Adapter for mySAP.com (SAP R/3 V. 3.x) User Guide · New in release 4.6.x v The connector supports invocation of the ABAP Debugger for the appropriate function module when the connector

WebSphere Business Integration Adapters

Adapter for mySAP.com (SAP R/3 V. 3.x)User GuideV5.3.x

��

WebSphere Business Integration Adapters

Adapter for mySAP.com (SAP R/3 V. 3.x)User GuideV5.3.x

��

Note!Before using this information and the product it supports, read the information in “Notices” on page 269.

18April2003

This edition of this document applies to IBM WebSphere Business Integration Adapter for mySAP.com (SAP R/3Version 4.x) and to all subsequent releases and modifications until otherwise indicated in new editions.

To send us your comments about this document, e-mail [email protected]. We look forward to hearingfrom you.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in anyway it believes appropriate without incurring any obligation to you.

© Copyright International Business Machines Corporation 1997, 2003. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiAudience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiRelated documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiTypographic conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiNaming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

New in this release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixNew in 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixNew in release 4.8.x. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixNew in release 4.7.x. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixNew in release 4.6.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xNew in release 4.5.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xConnector version 4.4.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xConnector version 4.3.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xConnector version 4.2.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiConnector version 4.1.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Part 1. Connector overview and setup . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. Overview of the connector . . . . . . . . . . . . . . . . . . . . . . . 3Connector components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3How the vision connector framework works. . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2. Installing and configuring the connector . . . . . . . . . . . . . . . . 11Prerequisites for installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Installing the connector component . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Configuring the connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Connector startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Starting multiple connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Upgrading the connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Upgrading to the Java-based connector . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Part 2. ABAP Extension module . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 3. Overview of the ABAP Extension module . . . . . . . . . . . . . . . . 29ABAP Extension module components . . . . . . . . . . . . . . . . . . . . . . . . . . 29How the ABAP Extension module works . . . . . . . . . . . . . . . . . . . . . . . . . 30

Chapter 4. Installing and customizing the ABAP Extension module. . . . . . . . . . 41Connector transport file installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Verifying the connector transport file installation . . . . . . . . . . . . . . . . . . . . . . . 44Enabling the SAP application for the connector . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 5. Business object processing in the ABAP Extension module . . . . . . . . 47Business object conversion to a flat structure . . . . . . . . . . . . . . . . . . . . . . . . 48Business object data routing to ABAP handlers . . . . . . . . . . . . . . . . . . . . . . . 51How ABAP handlers process business object data . . . . . . . . . . . . . . . . . . . . . . 53Flat structure conversion to a business object . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 6. Developing business objects for the ABAP Extension module . . . . . . . 59Background information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Developing business objects using dynamic retrieve . . . . . . . . . . . . . . . . . . . . . . 62Developing business objects using dynamic transaction. . . . . . . . . . . . . . . . . . . . . 65

© Copyright IBM Corp. 1997, 2003 iii

Developing business objects using IDocs . . . . . . . . . . . . . . . . . . . . . . . . . 70Calling the ABAP Extension module and ABAP handler . . . . . . . . . . . . . . . . . . . . 76

Chapter 7. Developing event detection for the ABAP Extension module. . . . . . . . 77Designing an event detection mechanism . . . . . . . . . . . . . . . . . . . . . . . . . 77Implementing an event detection mechanism . . . . . . . . . . . . . . . . . . . . . . . . 80

Chapter 8. Testing a business object for the ABAP Extension module . . . . . . . . 85Preparing to test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Unit test issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Testing an ABAP handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Chapter 9. Managing the ABAP Extension module . . . . . . . . . . . . . . . . . 89Managing the connector log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Monitoring the SAP gateway service connections . . . . . . . . . . . . . . . . . . . . . . . 91Shutting down the connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Maintaining the event queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Maintaining the archive table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Chapter 10. Upgrading the ABAP Extension module . . . . . . . . . . . . . . . . 95Upgrading within a new version of SAP R/3 . . . . . . . . . . . . . . . . . . . . . . . . 95Upgrading ABAP handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Upgrade considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Part 3. ALE module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Chapter 11. Overview of the ALE module . . . . . . . . . . . . . . . . . . . . 105ALE module components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105How the ALE module works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 12. Configuring the ALE module . . . . . . . . . . . . . . . . . . . . 119Prerequisites to running the ALE module . . . . . . . . . . . . . . . . . . . . . . . . . 119ALE module directories and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Configuring the ALE module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Checking the SAP configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Configuring SAP to update IDoc status. . . . . . . . . . . . . . . . . . . . . . . . . . 121

Chapter 13. Developing business objects for the ALE module . . . . . . . . . . . 123Generating the IDoc definition dile . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Business object structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Supported verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Processing multiple IDocs with a wrapper business object . . . . . . . . . . . . . . . . . . . 134

Part 4. BAPI module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Chapter 14. Overview of the BAPI module . . . . . . . . . . . . . . . . . . . . 139BAPI module components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139How the BAPI module works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Chapter 15. Configuring the BAPI module . . . . . . . . . . . . . . . . . . . . 143BAPI module directories and files . . . . . . . . . . . . . . . . . . . . . . . . . . . 143BAPI module configuration properties . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Chapter 16. Developing business objects for the BAPI module . . . . . . . . . . . 145Background information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Business object naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Business object structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

iv Adapter for mySAP.com (SAP R/3 V. 3.x) User Guide

Supported verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Business object attribute properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Business object application-specific information . . . . . . . . . . . . . . . . . . . . . . . 149Using generated business object definitions and business object handlers . . . . . . . . . . . . . . 152

Part 5. RFC Server module . . . . . . . . . . . . . . . . . . . . . . . . . 157

Chapter 17. Overview of the RFC Server module . . . . . . . . . . . . . . . . . 159RFC Server module components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159How the RFC Server module works . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Chapter 18. Configuring the RFC Server module . . . . . . . . . . . . . . . . . 165RFC Server module directories and files . . . . . . . . . . . . . . . . . . . . . . . . . 165RFC Server module configuration properties . . . . . . . . . . . . . . . . . . . . . . . . 165Registering the RFC Server module with the SAP Gateway . . . . . . . . . . . . . . . . . . . 165

Chapter 19. Developing business objects for the RFC Server module . . . . . . . . 167Background information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Business object naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Business object structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Supported verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Business object attribute properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Business object application-specific information . . . . . . . . . . . . . . . . . . . . . . . 172Using generated business objects and business object handlers . . . . . . . . . . . . . . . . . . 175

Part 6. Hierarchical Dynamic Retrieve module . . . . . . . . . . . . . . . . 179

Chapter 20. Overview of the Hierarchical Dynamic Retrieve module . . . . . . . . . 181Hierarchical Dynamic Retrieve module components . . . . . . . . . . . . . . . . . . . . . 181How the connector works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Chapter 21. Configuring the Hierarchical Dynamic Retrieve module . . . . . . . . . 183Hierarchical dynamic retrieve module directories and files . . . . . . . . . . . . . . . . . . . 183Hierarchical dynamic retrieve module configuration properties . . . . . . . . . . . . . . . . . . 183

Chapter 22. Developing business objects for the Hierarchical Dynamic Retrievemodule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Business object structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Business object attribute properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Business object application-specific information . . . . . . . . . . . . . . . . . . . . . . . 193

Part 7. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Appendix A. Standard configuration properties for connectors . . . . . . . . . . . 199New and deleted properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Configuring standard connector properties for WebSphere InterChange Server . . . . . . . . . . . . 200Configuring standard connector properties for WebSphere MQ Integrator . . . . . . . . . . . . . . 212

Appendix B. Connector configurator . . . . . . . . . . . . . . . . . . . . . . 221Using Connector Configurator in an internationalized environment . . . . . . . . . . . . . . . . 221Starting Connector Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Choosing your broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Using a connector-specific property template . . . . . . . . . . . . . . . . . . . . . . . . 224Using Connector Configurator with ICS as the broker . . . . . . . . . . . . . . . . . . . . . 227Setting the configuration file properties (ICS) . . . . . . . . . . . . . . . . . . . . . . . . 229Setting the configuration file properties (WebSphere MQ Integrator Broker) . . . . . . . . . . . . . 234Using standard and connector-specific properties with Connector Configurator . . . . . . . . . . . . 237

Contents v

Completing the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Appendix C. Generating business object definitions using SAPODA. . . . . . . . . 239Installation and usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Using SAPODA in Business Object Designer . . . . . . . . . . . . . . . . . . . . . . . . 243After using SAPODA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Appendix D. Connector feature list . . . . . . . . . . . . . . . . . . . . . . . 259Business object request handling features . . . . . . . . . . . . . . . . . . . . . . . . . 259Event notification features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261General features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Programming interface information . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Trademarks and service marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

vi Adapter for mySAP.com (SAP R/3 V. 3.x) User Guide

About this document

The IBM WebSphere InterChange Server system is a suite of software integrationproducts that includes prebuilt modules for common business integrationrequirements, and development and management tools. These products supplyconnectivity for leading e-business technologies and enterprise applications.

This document describes the IBM WebSphere InterChange Server connector forSAP including how to install, configure, develop business objects, test, and manageyour custom development.

AudienceThis document is for IBM WebSphere InterChange Server consultants andcustomers. You should be familiar with SAP and connector development.

Related documentsThe IBM WebSphere InterChange Server documentation describes the features andcomponents common to all installations, and includes reference material on specificcollaborations and connectors.

To access the documentation, go to the directory where you installed the IBMWebSphere InterChange Server product and open the documentation subdirectory.If a welcome.html file is present, open it for hyperlinked access to alldocumentation. If no documentation is present, you can install it or read it directlyfrom the IBM WebSphere InterChange Server documentation website,http://www.ibm.com/websphere/WebSphere InterChange Server/library.

Typographic conventionsThis document uses the following conventions:

courier font Indicates a literal value, such as a command name, filename, information that you type, or information that thesystem prints on the screen.

bold Indicates a new term the first time that it appears.italic, italic Indicates a variable name or a cross-reference.blue text Blue text, which is visible only when you view the manual

online, indicates a cross-reference hyperlink. Click any bluetext to jump to the object of the reference.

Naming conventionsIn this document the following naming conventions are used:v The IBM WebSphere InterChange Server connector for SAP is referred to simply

as the connector.v The “connector” refers to the combination of the vision connector framework

and a connector module.

© Copyright IBM Corp. 1997, 2003 vii

http://www.ibm.com/websphere/crossworlds/library

v All references to names of IBM WebSphere InterChange Server ABAP objects(such as function modules, programs, and tables) are valid for the connector thatsupports SAP R/3 version 3.x.

viii Adapter for mySAP.com (SAP R/3 V. 3.x) User Guide

New in this release

This release of this connector and document contains the following newinformation:

New in 5.0

Important: Because the connector has not been internationalized, do not run itagainst InterChange Server version 4.1.1 if you cannot guarantee thatonly ISO Latin-1 data will be processed.

Note: Patch releases refer to this connector as mySAP.com R/3 Connector.

New in release 4.8.xIBM WebSphere Business Integration Adapter for mySAP.com (SAP R/3 Version4.x) includes the connector for SAP. This adapter operates with both theInterChange Server (ICS) and WebSphere MQ Integrator (WMQI) integrationbrokers. An integration broker, which is an application that performs integration ofheterogeneous sets of applications, provides services that include data routing.

This adapter includes:v An application-component specific to SAP R/3 Version 4.xv SAPODAv A sample business object, which is located in \connectors\SAP\samples\v IBM WebSphere Adapter Framework, which consists of:

– Connector Framework– Development tools (including Business Object Designer and Connector

Configurator)– APIs (including ODK, JCDK, and CDK)

This manual provides information about using this adapter with both integrationbrokers: InterChange Server (ICS) and WebSphere MQ Integrator (WMQI).

Important: Because the connector has not been internationalized, do not run itagainst InterChange Server version 4.1.1 if you cannot guarantee thatonly ISO Latin-1 data will be processed.

New in release 4.7.x

Note: Patch releases refer to this connector as mySAP.com R/3 Connector.

The connector has replaced the CWSAPGEN utility with SAPODA. For moreinformation, see Appendix C, “Generating business object definitions usingSAPODA”, on page 239.

© Copyright IBM Corp. 1997, 2003 ix

New in release 4.6.xv The connector supports invocation of the ABAP Debugger for the appropriate

function module when the connector begins processing a business object. Formore information, see “ABAPDebug” on page 19.

v The connector supports updating the status of an ALE event. For moreinformation, see “Configuring SAP to update IDoc status” on page 121.

v This manual documents how to specify ALE Communication Partnerinformation in application-specific information. For more information, see“Parent wrapper business object” on page 127.

New in release 4.5.xv This version of the connector contains minor changes to the ALE module that

enabled the connector to be certified by SAP for integration. The changesmaintain backwards compatibility with objects generated for use with previousversions of the ALE module.

v When running the connector multi-threaded, one of the available threadsallocated with the MaxNumConnections property will be dedicated for pollingoperations.

Connector version 4.4.xv The modules configuration property has been simplified. The new configuration

values are shorter and more intuitive. However, for backward compatibility, theprevious values are still accepted. For the list of module names, see Table 4 onpage 17.

v The new Hierarchical Dynamic Retrieve module processes hierarchical or flatbusiness objects in response to requests from collaborations configured to workwith the connector. For information on this module, see Chapter 21,“Configuring the Hierarchical Dynamic Retrieve module”, on page 183.

v The ALE module provides non-invasive event processing. For more information,see Chapter 12, “Configuring the ALE module”, on page 119.

v The ALE module uses Transaction IDs (TIDs) to guarantee that each piece ofdata is delivered or processed once and only once. For more information, seeChapter 12, “Configuring the ALE module”, on page 119.

v The connector supports multi-threading. For more information, see“NumberOfListeners” on page 22.

Important: BAPI business object handlers generated before the IBM WebSphereInterChange Server Connector for SAP version 4.3.0 are notthread-safe. To guarantee data consistency and integrity when usingmulti-threading, you must regenerate these business object handlers.The business objects do no require any change.

v The connector running on Solaris now uses SAP’s Java API and fully supportsall connector modules. Because IBM WebSphere InterChange Server does notship the Java API, you must download it from SAP’s website. For moreinformation, see “Prerequisites for installation” on page 11.

v The connector no longer uses the CharacterEncoding configuration property.

Connector version 4.3.xThis document contains all patches from the 4.2.x releases.

x Adapter for mySAP.com (SAP R/3 V. 3.x) User Guide

Connector version 4.2.xv With the 4.2.7 release, the IBM WebSphere InterChange Server connector for SAP

uses SAP’s Java Connector (jCO) API. This is for Windows only. As of the 4.2.7release, SAP does not support the jCO for UNIX; therefore the 4.2.7 version ofthe connector does not support jCO for UNIX.

v With the 4.2.7 release, the “RefreshLogonCycle” on page 22 connector-specificconfiguration property has been changed so that the connector can either log offand then back on after every processed event, or not log off at all.

v The Guide to the IBM WebSphere InterChange Server Connector for SAP Version3.x contains new information supporting the three new connector modules. PartIII describes the ALE Module, Part IV describes the BAPI Module, and Part Vdescribes the RFC Server Module.The ALE Module provides a non-invasive solution to sending IDocs into an SAPapplication. The BAPI Module provides a non-invasive solution to calling BAPIsin an SAP application. The RFC Server Module enables RFC-enabled functions tocall the connector.The ALE Module enables consumes (service call requests) only. The BAPIModule enables service call requests and event notification. The RFC ServerModule enables real-time non-invasive event notification.

v In the ALE Module, simple attributes in a data record business object that useCxIgnore or CxBlank are now represented with a blank. Previously CxIgnore wasinterpreted as a forward slash (/). SAP handles forward slash (/) charactersdifferently depending on the function used. For more information see“Attributes: Data record business object” on page 129.

v New connector-specific configuration properties that support the new modulesare documented. For more information, see gwService, NumberOfListeners,PollQuantity, RefreshLogonCycle,RfcProgramId, and RfcTraceOn.

Connector version 4.1.xv Chapter 10, “Upgrading the ABAP Extension module”, on page 95 contains

upgrade information for the connector and objects. It provides information abouthow to upgrade to the IBM WebSphere InterChange Server SAP connector forSAP version 4.x, including upgrading to use the IBM WebSphere InterChangeServer namespace /CWLD/.

v New standard connector configuration properties Agent URL, AnonymousConnections, CA Certificate Location, GW Name, and Listener Port were added.

New in this release xi

xii Adapter for mySAP.com (SAP R/3 V. 3.x) User Guide

Part 1. Connector overview and setup

© Copyright IBM Corp. 1997, 2003 1

2 Adapter for mySAP.com (SAP R/3 V. 3.x) User Guide

Chapter 1. Overview of the connectorv “Connector components” on page 3v “How the vision connector framework works” on page 5

This chapter describes the connector component of the IBM WebSphere BusinessIntegration Adapter for mySAP.com (SAP R/3 Version 4.x). The connector enablesan integration broker to exchange business objects with SAP applications.

Connectors consist of an application-specific component and the connectorframework. The application-specific component contains code tailored to aparticular application. The connector framework, whose code is common to allconnectors, acts as an intermediary between the integration broker and theapplication-specific component. The connector framework provides the followingservices between the integration broker and the application-specific component:v Receives and sends business objectsv Manages the exchange of startup and administrative messages

This document contains information about the application-specific component andconnector framework. It refers to both of these components as the connector.

For more information about the relationship of the integration broker to theconnector, see the IBM CrossWorlds System Administration Guide (if InterChangeServer is the integration broker), or the WebSphere Business Integration AdaptersImplementation Guide for MQ Integrator (if WebSphere MQ Integrator is theintegration broker).

Connector componentsThe connector for SAP is written in Java and consists of two parts: the visionconnector framework and connector modules (the connector’s application-specificcomponent, the Connector Framework, and business object handlers). The visionconnector framework provides a meta-data-driven layer of abstraction to theConnector Framework used by all WebSphere business integration systemadapters.

The vision connector framework extends the methods in the system-wideConnector Framework. The connector modules extend the methods in the visionconnector framework and communicate with an SAP application.

Note: By default, the connector uses the ABAP Extension Module to support thevision connector framework. For more information on the ABAP ExtensionModule, see Chapter 3, “Overview of the ABAP Extension module”, onpage 29.

Figure 1 illustrates the architecture of the connector and the relationship of thesystem-wide and vision connector frameworks. The visionConnector class canimplement any number of connector modules.


Vision connector frameworkThe vision connector framework dynamically routes the initialization, poll, andtermination requests to connector modules. It also dynamically routes businessobjects to business object handlers. A business object handler is a connectormodule designed specifically to support business objects. To dynamically routerequests and business objects, the connector uses the verb application-specificinformation of a business object and values of certain application-specific connectorconfiguration properties.

The vision connector framework consists of two classes: visionConnector andvisionBOHandler.

Figure 2 illustrates the vision connector framework and its association withconnector modules.

Vision connector

pollForEvents()terminate()init()

System-wide connector framework

doVerbFor()pollForEvents()terminate()init()

Vision BO handler

doVerbFor()

Connector

Vision connector framework

Connector modules

Figure 1. Architecture of the connector for SAP


The vision connector framework provides the following capabilities for theconnector:v Calls any implementation of the init(), pollForEvents(), and terminate()

methods.v Routes business objects to specific business object handlers based on the verb

application-specific information of a business object.

Connector modulesThe connector modules are Java classes that extend the methods in the visionconnector framework. They support the vision connector framework by providingspecific functionality, such as logging in to the SAP application, processing eventsand business objects, and terminating the connection to the SAP application. Theconnector modules carry out requests between the vision connector framework andthe SAP application. By default, the vision connector framework uses theconnectors\SAP directory as the root directory for the connector modules.

Connector modules may not use all of the framework methods. For example, onemodule might use the init() and terminate() methods while another moduleuses only the pollForEvents() method. However, every method in thevisionConnector and visionBOHandler classes must be implemented for eachconnector module. Methods that a connector does not use must be implemented asdummy methods, that is, they do nothing but exit.

How the vision connector framework worksThe connector interacts with an SAP application using connector modules. Theconnector modules make calls to SAP’s Native Interfaces and pass data (businessobject or event data) to and from an SAP application. The connector’s flexibledesign enables different modules to be used for different tasks such as initializingthe connector with the SAP application or passing business object data.

Communication between the connector and an SAPapplication

The connector uses SAP’s Remote Function Call (RFC) library to communicate withan SAP application. SAP’s RFC API allows external programs to call ABAPfunction modules within an SAP application.

visionConnector


Connector

visionBOHandler

terminate()init()

Connector

doVerbFor()

Connector

doVerbFor()pollForEvents()


Figure 2. vision connector framework and connector modules

Chapter 1. Overview of the connector 5

Processing business objectsThe connector is meta-data driven. Meta-data, in the WebSphere businessintegration system, is application-specific data that is stored in business objects andthat assists a connector module in its interaction with the application. Ameta-data-driven connector module handles each business object that it supportsbased on meta-data encoded in the business object definition rather than oninstructions hard-coded in the connector module.

Business object meta-data includes the structure of a business object, the settings ofits attribute properties, and the content of its application-specific information.Because connector modules are meta-data driven, they can handle new or modifiedbusiness objects without requiring modifications to the connector-module code.

The vision connector framework uses the value of the verb application-specificinformation in the top-level business object to call the appropriate connectormodule to process the business object. The verb application-specific informationprovides the classname of the connector module.

The verb application-specific information of most top-level business objects mustidentify the classname of the connector module. The syntax of this verbapplication-specific information is:AppSpecificInfo = PartialPackageName.ClassName,

For example,AppSpecificInfo = sap.sapextensionmodule.VSapBOHandler,

In this example, sap.sapextensionmodule is the partial package name, andVSapBOHandler is the classname. The full package name includes thecom.crossworlds.connectors prefix, which the WebSphere business integrationsystem adds to the name automatically. In other words, the full text of the exampleis:com.crossworlds.connectors.sap.sapextensionmodule.VSapBOHandler

Note: The verb application-specific information of most top-level business objectsmust use a comma (,) delimiter after the connector classname. However, theServer verb, which is used by the RFC Server Module, is delimited insteadby a semi-colon (;). For information about the Server verb, see “How theRFC Server module works” on page 161 and “Supported verbs” on page170.

You need not specify the package name and classname for the verbapplication-specific information if the business object is used:v by the ALE module to process application events; however, when you use the

ALE module to process service call requests, you must specify the package nameand classname

v by the ABAP Extension module, which uses the default business object handler(sap.sapextensionmodule.VSapBOHandler)

Important: Customer-generated connector modules that process business objectsfor the BAPI and RFC Server modules must specify a full packagename, which must begin with bapi. For example,bapi.client.Bapi_customer_getdetails2. The full package name inthis example is bapi.client, and the classname isBapi_customer_getdetail2.


Most business object processing is specific to each connector module. By defaultthe connector uses the ABAP Extension Module. For more information on businessobject processing for the ABAP Extension Module, see “Business object processing”on page 31 and “Business object data routing to ABAP handlers” on page 51.

For more information on specifying verb application-specific information for theALE module, see “Event processing” on page 110 and “Processing multiple IDocswith a wrapper business object” on page 134.

Processing multiple concurrent interactionsThe system-wide Connector Framework can create separate threads for processingan application event and a business object request. When processing multiplerequests from the integration broker, it can create multiple threads to handlemultiple business object requests. For example, when InterChange System is theintegration broker, the connector can receive multiple business object requests frommultiple collaborations or from a multi-threaded collaboration.

Important: BAPI business object handlers generated before the connector for SAPversion 4.3.0 are not thread-safe. To guarantee data consistency andintegrity when using multi-threading, you must regenerate thesebusiness object handlers. The business objects do no require anychange.

Figure 3 illustrates the multi-threading architecture.


Event processingThe connector performs the following steps when handling a poll call:1. The system-wide Connector Framework creates a single dedicated thread to

handle poll calls. This thread calls the pollForEvents() method of the visionconnector framework at the frequency specified in the PollFrequencyconfiguration property.

2. The thread polls SAP, which uses a dialog process to locate and return theevent.

Note: If the connector’s MaxNumberOfConnections configuration propertyevaluates to a number greater than 1, the vision connector frameworkdedicates a connection to SAP for polling. If MaxNumberOfConnectionsevaluates to 1, event and service-call request processing share a singleconnection to SAP.


SAP gateway

WebSphere BusinessInterChange Server

SAP R/3

SAP R/3 system

SAP RFC library

Dialogprocess1

DialogprocessN

System-wide connector framework

doVerbFor()pollForEvents()terminate()init()

Dialogprocess2

Thread1pollForEvents()

Thread1doVerbFor()

ThreadNdoVerbFor()

visionConnector

Connection Pool

visionBOHandler

doVerbFor()

Connector modules

doVerbFor()



Connector

Figure 3. Multi-Threading Architecture of the Connector for SAP


The polling thread dies only when the connector shuts down.

Note: Because the RFC Server connector agent pushes events out of SAP instead ofpolling for events, it spawns its own threads instead of using threadscreated by the connector framework. Because the ALE connector agent usesthe RFC Server connector agent to access events, it also it spawns its ownthreads instead of using threads created by the connector framework whenit processes events.

Request processingIndependently of polling, the system-wide Connector Framework can createmultiple request-processing threads, one for each request business object. Eachrequest thread instantiates the appropriate business object handler.

For example, when processing business object requests from InterChange Server,the number and type of business object handlers depends on the number and typeof the collaborations sending the requests:v If multiple collaborations send business objects, each request thread instantiates

a business object handler of the appropriate type.v If a multi-threaded collaboration sends multiple business objects of the same

type, the request threads instantiate an equal number of business object handlersof that type.

If the connector’s MaxNumberOfConnections configuration property evaluates to anumber greater than 1, the vision connector framework dedicates one connectionto SAP for polling and allocates the remaining connections to a pool used only forrequest processing.

As illustrated in Figure 3, the connector performs the following steps whenhandling a business object request:1. The system-wide Connector Framework creates a separate thread for each

business object request. Each thread calls the doVerbFor() method of the Visionbusiness object handler.

2. If the connector’s MaxNumberOfConnections configuration property evaluates toa number greater than 1, the Vision business object handler checks the visionconnector framework’s connection pool to determine if a connection handle isavailable.v If the handle is available, the thread sends the request to SAP, which uses a

dialog process to handle the request.v If the handle is not available, the thread waits until one becomes available.

Thread sequencing determines the order in which each business objecthandler thread claims or waits for an available connection handle.

If the connector’s MaxNumberOfConnections configuration property evaluates to1, the Vision business object handler shares a connection with event processing.

3. SAP releases the dialog process after it completes processing and sends a returncode.

4. The connector releases the connection handle after it receives the return codefrom SAP.

Setting the number of available connectionsUse the “MaxNumberOfConnections” on page 21 configuration property to specifythe maximum number of connection handles available. The number of connectionscannot exceed the number of dialog processes.


SAP locks the dialog process while processing an interaction, releasing it onlywhen the interaction completes. Therefore, multiple concurrent requests lock anequal number of dialog processes until processing finishes.

Important: Before setting a value for MaxNumberOfConnections, contact your SAPBASIS administrator to determine an appropriate value to maximizethroughput without negatively affecting performance on theapplication server.

Setting multiple connectionsBy default the connector supports only single-threading. To cause the connector tosupport multiple threads, remove the following flag from your connector startupscript:

UNIX-tMAIN_SINGLE_THREADED

End of UNIX

Windows-tSINGLE_THREADED

End of Windows

For more information, see the Connector Development Guide for Java.


Chapter 2. Installing and configuring the connector

“Prerequisites for installation”

“Installing the connector component” on page 12

“Configuring the connector” on page 16

“Connector startup” on page 24

“Upgrading the connector” on page 25

“Upgrading to the Java-based connector” on page 26

This chapter describes the installation and configuration of the connectorcomponent of the IBM WebSphere Business Integration Adapter for mySAP.com(SAP R/3 Version 4.x). This chapter assumes that all the necessary files wereinstalled when the WebSphere business integration system was installed. Forinformation about installing these, see the WebSphere Business Integration AdaptersImplementation Guide for MQ Integrator, or, for the WebSphere Interchange Server,see the System Installation Guide for UNIX or for Windows.

After completing the connector installation procedure described in this chapter,you have the option of configuring the connector or installing the default ABAPExtension Module. You do not need to install the ABAP Extension Module beforeconfiguring the connector.

This chapter covers installation issues only for the connector component. Forinstallation information specific to one of the connector’s modules, see theconfiguration chapter specific to that module.

Important: If you are upgrading versions of the connector, you must replace theconnector Java Archive files (.jar). You also need to upgrade theconnector transport files as well as any business object transports thatyou have previously installed. Depending on changes made to theconnector, you may need to load a new copy of the CN_SAP.txt file intoyour repository. See the Release Notes for more information.

Prerequisites for installationAll of the components of the connector can be found in the \connectors\SAPdirectory.

Note: In this document backslashes (\) are used as the convention for directorypaths. For UNIX installations, substitute slashes (/) for backslashes (\). Allfile pathnames are relative to the directory where the product is installed onyour system.

Prior to installing the connector component of the IBM WebSphere BusinessIntegration Adapter for mySAP.com:v Download the SAP Java API. SAP calls their Java API the Java Connector (jCO).


Make sure that you download the jCO for the operating system that yourconnector is running on. The jCO is available for download from SAP’s websiteat http://service.sap.com/connectors. You must have a SAPNet account toaccess the jCO (if you do not already have one, contact your local SAP BASISadministrator).You will need to add these files to the \connectors\SAP directory after youinstall the connector. For steps on installing the connector, see “Installing SAP’sJava connector (jCO)” on page 14.

v It is recommended that you install the SAP client on the same machine on whichyou are installing the connector.

v It is recommended that you install the most recent SAP Support Package foryour version of SAP.SAP delivers for Support Packages: Basis, R/3 application, ABAP, and HR. Theyprovide bug fixes for the ABAP code in the SAP application. It is recommendedthat you use an updated SAP kernel. The kernel is the executables, written inC++, that carry out transports, interface with the operating system, communicatewith the database, and run the system.

v It is recommended that you set up a CPIC user account in the SAP application.Give this account privileges necessary to manipulate the data required by thebusiness objects supported by the connector.For example, if the connector must perform certain SAP business transactions,the connector’s account in the SAP application must have the permissions toperform to perform these transactions. You must set the connector-specificconfiguration properties ApplicationUserName and ApplicationPassword usingthis account information. For more information on how to set these properties,see “Configuring the connector” on page 16.

v Set up a user account in SAP with privileges to install and administer theconnector. The account should have the following characteristics:– Any valid SAP user name and password– ABAP developer access– Table configuration access– Administration access for transactions SM21 and SM50 to administer and

monitor the connector

Installing the connector componentAfter your WebSphere business integration system has been installed, you caninstall additional adapters from the product CD at any time. To do this, insert theproduct CD, run the installation program, and choose the adapters that you wantto install.

Note: Unless otherwise indicated, the remaining sections in this chapter apply toboth Windows and UNIX installations of the connector.

This section describes only the installation of the connector’s application-specificcomponent. By default, the connector uses the ABAP Extension Module, so youmust install the transport files that support that connector module. After you haveinstalled and configured the connector, you must install the ABAP ExtensionModule. For more information on installing the ABAP Extension Module, seeChapter 4, “Installing and customizing the ABAP Extension module”, on page 41.

The IBM WebSphere Business Integration Adapter for mySAP.com can be installedon a UNIX or Windows machine. The connector consists of three parts that need to


be installed: the connector’s application-specific component, SAP’s RFC library, andany SAP transport files delivered with the product and required to support theconnector.

After you have installed the required connector files, you must download andinstall the Java Connector (jCO) files. For more information on downloading thejCO files, see “Prerequisites for installation” on page 11. For more information oninstalling the jCO files, see “Installing SAP’s Java connector (jCO)” on page 14.

The connector files must be installed on a machine that is capable of acting as anSAP client. By default, the connector JAR files are installed with the integrationbroker.

Installing on a UNIX SystemTo install the connector on a UNIX system, run the Installer for IBM WebSphereBusiness Integration Adapter, and select the IBM WebSphere Business IntegrationAdapter for mySAP.com. Table 1 lists the files used by the connector that runs in aUNIX environment.

Table 1. IBM WebSphere Business Integration Adapter for mySAP.com: Files for UNIX

Directory/filename Description

connectors/SAP/bapi/client Directory containing the BAPI Module business object handler filesconnectors/SAP/bapi/server Directory containing the RFC Server Module business object handler filesconnectors/SAP/dependencies Directory containing all version-specific transport filesconnectors/SAP/messages Directory containing the SAPConnector.txt file.connectors/SAP/samples Directory containing sample ABAP objectsconnectors/SAP/utilities Directory containing the generatedfiles subdirectory, into which you can put

files generated by SAPODAconnectors/SAP/CWSAP.jar Connector class filesconnectors/SAP/start_SAP.sh System startup script for the connector.

This script is called from the generic connector manager script. The productinstaller creates a customized wrapper for this connector manager script.

When the connector works with ICS, use this customized wrapper to start andstop the connector. When the connector works with WMQI, use this customizedwrapper only to start the connector; use mqsiremotestopadapter to stop theconnector.

repository/SAP Directory containing the CN_SAP.txt file.

Before you can use the connector, you must configure the connector from theinstaller’s Connector Configuration screen. From this screen:v Choose SAP from the Select Connector Name list.v Click Install to have Installer generate the customized SAP wrapper,

connector_manager_Sap.

Note: For more information on installing the connector component, refer to theWebSphere Business Integration Adapters Implementation Guide for MQIntegrator, or, for ICS, the System Installation Guide for UNIX.

Installing on a Windows systemTo install the connector on a Windows system, run Installer for IBM WebSphereBusiness Integration Adapter, and select the IBM WebSphere Business IntegrationAdapter for mySAP.com. Installer installs standard files associated with the

Chapter 2. Installing and configuring the connector 13

connector. Table 2 lists the standard files installed in a Windows environment.

Table 2. IBM WebSphere Business Integration Adapter for mySAP.com: Files for Windows

Directory/filename Description

connectors\SAP\bapi\client Directory containing the BAPI Module business objecthandler files

connectors\SAP\bapi\server Directory containing the RFC Server Module businessobject handler files

connectors\SAP\dependencies Directory containing all version-specific transport filesconnectors\SAP\messages Directory containing the SAPConnector.txt file.connectors\SAP\samples Directory containing sample ABAP objectsconnectors\SAP\utilities Directory containing the files (cwsapgen.bat and

Cwsapgen.jar) and the directory (generatedfiles) for theCWSAPGen utility

connectors\SAP\CWSAP.jar Connector class fileconnectors\SAP\start_SAP.bat Batch file used to start the connectorrepository\SAP Directory containing the CN_SAP.txt file.

Installer adds a menu option for the connector’s application-specific component tothe IBM WebSphere Business Integration Adapters menu (if WMQI is theintegration broker) or to the IBM WebSphere InterChange Server menu (if ICS isthe integration broker). For a fast way to start the connector, create a shortcut tothis component on the desktop.

Note: For more information on installing the connector, see the WebSphere BusinessIntegration Adapters Implementation Guide for MQ Integrator, or, for ICS, theSystem Installation Guide for Windows.

Installing SAP’s Java connector (jCO)The IBM WebSphere Business Integration Adapter for mySAP.com requires the useof SAP’s Java Connector (jCO). SAP supports jCO for SAP R/3 3.1h and higher. Ifyou have already followed instructions for installing the connector component, youshould have already downloaded SAP’s Java Connector (jCO) as described in“Prerequisites for installation” on page 11. If you have not downloaded the jCO,download and unzip it now.

After you have installed the files delivered with SAPODA, copy the followingunzipped jCO files into your environment.

Important: Do not use versions of jCO older than 1.1.02.

UNIX

Copy the following files to the /connectors/SAP directory:v jCO.jar

v librfccm.o (AIX) or librfccm.so (Solaris)

v libjRFC11.so

v libjRFC12.so


End of UNIX

Windows

Copy the following files to the \connectors\SAP directory:v jCO.jar

v librfc32.dll

v jRFC11.dll

v jRFC12.dll

For Windows, the librfc32.dll requires an additional C runtime dll. The Cruntime dll required is msvcrt.dll version 5.00.7022 or newer. The dll msvcrt.dllshould be copied into C:\WINNT\system32 directory. This dll may already be presentand if not, can be found on the Presentation CD that contains the WindowsSAPGUI setup in the folder <cddrive>:\GUI\Windows\Win32\system. See SAP OSSnote number 0182805 for more information.

End of Windows

Installing connectors on remote machinesYou can install and run the connector on a remote machine. Install the integrationbroker on one machine and the connector on another machine. It is recommendedbut not required that both machines be on the same subnet. For more informationon installing the connector on a remote machine, see he WebSphere BusinessIntegration Adapters Implementation Guide for MQ Integrator, or, for ICS, see theSystem Installation Guide for UNIX or for Windows.

Installing multiple connectorsTo enable the integration broker to handle multiple business objects for SAP at thesame time, you may want to install and configure multiple connector componentsfor an SAP system and customize each connector to handle specific businessobjects.

Each connector component can subscribe to certain business objects depending ontheir type (such as Customer or Purchase Order). Because you can have multipleconnectors accessing the same SAP application, each connector can process eventsand pass them on to the integration broker. In addition, multiple connectors cansupport multiple business object requests at the same time. This increasesthroughput and speeds up the transfer of data into and out of the SAP application.

It is recommended that you choose a unique naming convention for each connectorcomponent. For example, if you are using two connectors you could name themSAP1_Connector and SAP2_Connector.

To install and set up multiple connector components, do the following:1. Install each of the connectors as described in this chapter. This includes the

connector shared library files. Give a unique name to each connector youinstall, and verify that you have the supporting connector files.If you are installing multiple connectors on the same machine, you need onlymake a copy of the shared library files and rename them. You do not need toinstall the transports again.

2. Create a copy of the startup script:


v On UNIX, make a copy of the existing connector_manager_sap file forstarting the connector, and rename the file to match the name of theconnector.

v On Windows, make a copy of the existing shortcut to the start_sap.bat file,and rename the shortcut file to match the name of the connector. Add thename of the connector as a parameter of the connector shortcut.

3. Make a copy of the connector definition file (CN_ConnectorName.txt), rename itto match the new connector name, and then copy it to the repository directory(if WMQI is the integration broker), or load it into the IBM WebSphereInterChange Server repository (if ICS is the integration broker).

4. Make a copy of the connector class file, CWSAP.jar.5. Initialize the connector configuration properties so that both connectors poll the

same SAP application for events.6. Only if ICS is the integration broker, add map references for each connector.7. Specify the business objects supported by each connector.8. Only if ICS is the integration broker, assign collaborations to the appropriate

connectors. Currently, a collaboration can be handled by only one connector. Ifcollaborations are already set up, you may need to stop them and then rebindthe ports.

9. If you are using the ABAP Extension Module for business object handing, setup the distribution of events to each connector that you install. Use the IBMWebSphere InterChange Server Connector Tools window (transaction YXR1).See “Setting up event distribution” on page 44 for instructions on setting upevent distribution for each combination of business object, integration broker,and connector.

Important: If a business object is not configured to go to a particular connector,the business object is sent to the next connector that polls for events. Ifa business object is configured to go to a particular connector, as forexample during the testing phase, but the connector is not used in theproduction phase, the event queue for the connector fills up. Toremedy this situation, delete the connector/business objectconfiguration in the Event Distribution window (Transaction YXRH).

Configuring the connectorYou must configure the connector’s standard and connector-specific connectorconfiguration properties before you can run it. To configure connector properties,use:v Connector Designer—if ICS is the integration broker

Access this tool from IBM WebSphere InterChange Server System Manager(CSM).

v Connector Configurator—if WMQI is the integration brokerAccess this tool by clicking its menu option in the IBM WebSphere BusinessIntegration Adapters submenu of the Windows Start menu.

As you enter configuration values, they are saved in the repository.

Standard connector configuration propertiesStandard configuration properties provide information that all connectors use. SeeAppendix A, “Standard configuration properties for connectors”, on page 199 fordocumentation of these properties.


Table 3 provides information specific to this connector about configurationproperties in the appendix.

Table 3. Property information specific to this connector

Property Note

CharacterEncoding The connector does not use this property.PollFrequency If using the RFC Server Module or the ALE Module for

event processing, do not set this property’s value to keyor to no. Setting the value to key or no prevents theconnector from instantiating these modules at startup.

You must provide a value for the ApplicationName configuration property beforerunning the connector.

Connector-specific configuration propertiesConnector-specific configuration properties provide information needed by theconnector at runtime. Connector-specific properties also provide a way of changingstatic information or logic within the connector framework and the connector’sapplication-specific component without having to recode and rebuild the connector.

Table 4 is a quick reference for the connector-specific configuration properties. TheModules column contains a list of the connector modules that use the associatedproperty.

Table 4. Quick reference for connector-specific configuration properties

Name Possible values Default value Modules

ABAPDebug true or false false ABAP Extension

BAPI

Dynamic RetrieveAleEventDir path ALEAleUpdateStatus true or false false ALEAleSelectiveUpdate IDocType:MessageType ALEAleStatusMsgCode MessageCode ALEAleSuccessCode 52 or 53 52 ALEAleFailureCode 68 or 58 68 ALEAleSuccessText SuccessText ALEAleFailureText FailureText ALEApplicationPassword SOFTWARE ABAP Extension

ALE

BAPIApplicationPassword CROSSWORLDS ABAP Extension

ALE

BAPIClient ABAP Extension

ALE

BAPIgwService Gateway server identifier sapgw00 RFC Server

ALE


Table 4. Quick reference for connector-specific configuration properties (continued)


Hostname IP-address orserver-name

All

Language E ABAP Extension

ALE

BAPIMaxNumberOfConnections 2 ABAP Extension

ALE (only for service call requests)

BAPIModules ModuleName AllNamespace true or false true ABAP ExtensionNumberOfListeners any positive integer 1 RFC Server

ALEPollQuantity any positive integer 20 ABAP Extension

ALERefreshLogonCycle true true ABAP Extension

ALE

BAPIRfcProgramId program ID CWLDSERVER RFC Server

ALERfcTraceOn true or false false AllSAPALE_Archive_Queue any valid MQ Series

queue nameALE (event processing only)

SAPALE_Event_Queue any valid MQ Seriesqueue name

ALE (event processing only)

SAPALE_Wip_Queue any valid MQ Seriesqueue name

ALE (event processing only)

SAPtid_MQChannel any valid MQ channel ALESAPtid_MQPort any valid MQ port ALESAPtid_QueueManager any valid MQ queue

manager nameALE

SAPtid_Queue any valid MQ queue name ALE (request processing only)SAPtid_QueueManager any valid MQ queue

manager nameALE

SAPtid_QueueManagerHost any valid MQ queuemanager host name

ALE

SAPtid_QueueManagerLogin any valid MQ queuemanager login name

ALE

SAPtid_QueueManagerPasswordany valid MQ queuemanager password

ALE

Sysnr system-number 00 ABAP Extension

ALE

BAPITransIdCollabName No longer supported.


Table 4. Quick reference for connector-specific configuration properties (continued)


ApplicationPassword true or false false ABAP Extension

ALE

BAPI

ABAPDebugSpecifies whether the connector invokes the ABAP Debugger for the appropriatefunction module when the connector begins processing a business object. Whenthis property is set to true, the connector opens the ABAP Debugger for thefollowing connector modules:v ABAP Extension—when processing events out of SAP and service call requests

into SAPv BAPI—only when processing service call requests into SAP

The connector invokes the ABAP Debugger only if you have:v Changed the default value of the “ApplicationPassword” on page 21

configuration property from WebSphere InterChange Server to a Dialog userwith proper user authorizations.

v Set the ABAPDebug property to true.

Note: You can add breakpoints only after the debugger opens.

Important: This property should always be set to false in a productionenvironment.

The default value is false.

AleEventDirSpecifies the location of the root directory (\ale) for the event directory used bythe ALE Module to log and recover events. When the connector starts for the firsttime, if it does not find the root directory in the directory from which theconnector is started, it creates it and the event subdirectory:v If the path is specified in this property, it uses that path to create the directory.v If no path is specified, it creates the root directory in the directory from which

the connector is started.

For example, if your connector is located in \connectors\SapConnector1 (within theproduct directory), the connector creates the following directory:\connectors\SapConnector1\ale

UNIX

If you are not in the connector’s directory when you start the connector for thefirst time, the connector creates the root directory in the directory from which youstart the connector regardless of the value of this property.

End of UNIX

For more information, see Chapter 12, “Configuring the ALE module”, on page 119.


The default value is:

UNIX$crossworlds/connectors/Sap/ale

End of UNIX

Windows%crossworlds%\connectors\Sap\ale

End of Windows

AleUpdateStatusSpecifies whether an audit trail is required for all message types. This propertymust be set to true to cause the connector to update a standard SAP status codeafter the ALE module has retrieved an IDoc object for event processing.

For more information, see Chapter 11, “Overview of the ALE module”, onpage 105.


AleSelectiveUpdateSpecifies which IDocType and MessageType combinations are to be updated whenthe connector is configured to update a standard SAP status code. You can definevalues for this property only if AleUpdateStatus has been set to true.

The syntax for this property is:IDocType:MessageType[,IDocType:MessageType [,...]]

where a colon (:) delimiter separates each IDocType and MessageType, and acomma (,) delimiter separates entries in a set. The example below illustrates twosets. In the example, MATMAS03 and DEBMAS03 are the IDocs, and MATMAS and DEBMASare the message types:MATMAS03:MATMAS,DEBMAS03:DEBMAS


AleStatusMsgCodeIf required, specifies the message code to use when the connector posts the ALEAUDMessage IDoc (ALEAUD01). Configure this message code in the receiving PartnerProfile. You can set a value for this property only if AleUpdateStatus has been setto true.

For more information, see “Configuring SAP to update IDoc status” on page 121.

AleSuccessCodeSpecifies the success status code for Application Document Posted. You mustspecify a value for this property (52 or 53) to cause the connector to update theSAP success status code after the ALE module has retrieved an IDoc object forevent processing. SAP converts this value to status 41 (Application DocumentCreated in Receiving System).



AleFailureCodeSpecifies the status code for dispatch failure. You must specify a value for thisproperty (68 or 58) to cause the connector to update the SAP failure status codeafter the ALE module has retrieved an IDoc object for event processing. SAPconverts this value to 40.


AleSuccessTextSpecifies the descriptive text for successful Application Document Posted.Specifying a value for this property is optional, even when you setAleUpdateStatus to true.


AleFailureTextSpecifies the descriptive text for dispatch failure. Specifying a value for thisproperty is optional, even when you set AleUpdateStatus to true.


ApplicationPasswordPassword for the connector’s user account on the SAP application. The default isSOFTWARE.

ApplicationUserNameName of the connector’s user account on the SAP application. The default iscrossworlds.

ClientClient number under which the connector logs in, often 100.

gwServiceGateway server identifier; often sapgw00. The 00 is the system number of the serverrunning the SAP Gateway (usually an application server) and may not be 00 if youhave more than one. The default is sapgw00.

HostnameIP address or the name of the application server that the connector logs in to.

LanguageLanguage in which the connector logs in. The default is E, for English.

MaxNumberOfConnectionsThe maximum number of concurrent interactions possible between the connectorand the SAP application. These interactions include polling for events andhandling service call requests. Only the ABAP Extension, BAPI, and ALE Modulesuse this property. The ALE Module uses this property only for service call requests.

Because each interaction uses a dialog process on the SAP application server, thenumber of connections cannot exceed the number of dialog processes available.


If no value is specified for this property, the connector uses the default value of 2.

ModulesIdentifies the module used by the connector to carry out the init(),pollForEvents(), and Terminate() requests. Specifically, it specifies the connectormodule used by the Vision Connector framework. Specify multiple connectormodules by separating each value with a comma. Do not add spaces.

The supported connector modules and the syntax to specify them is as follows:

ABAP Extension Module—Extension

ALE Module—ALE

BAPI Module—Bapi

RFC Server Module—RfcServer

NamespaceSpecifies whether or not the connector agent uses the ABAP components definedin the connector’s namespace /CWLD/. The value must be changed to false for anSAP 3.x application. The default is true.

NumberOfListenersSpecifies the number of listener threads that are created when the connector isinitialized. A listener thread can handle one request at a time. Each listener threadhandles a single event at a time; therefore, if you have multiple listener threads,the connector can handle multiple events concurrently. The default is 1.

It is recommended that you have no more listener threads than the available workprocesses in SAP.

PollQuantityDefines the maximum number of events picked up for a single poll. The default is20.

RefreshLogonCycleBecause SAP jCO 1.1 always refreshes the connector user’s global memory aftereach processed event for SAP R/3 version 4.x, the value of this property alwaysevaluates to true. The default is true.

RfcProgramIdIdentification that the connector registers in the SAP Gateway so that the listenerthreads can process events from RFC-enabled functions. This value must match theProgram ID registered in the SAP application (transaction SM59). The default isCWLDSERVER.

For more information on configuring the Program ID in the SAP application, see“Registering the RFC Server module with the SAP Gateway” on page 165.

RfcTraceOnSpecifies whether or not to generate a text file detailing the RFC activity for eachlistener thread. You can specify a value of true or false. A value of true activatestracing, which generates a text file. It is recommended that you use these text filesin a development environment only, because the files can grow rapidly. The defaultis false.


SAPALE_Archive_QueueSpecifies the MQ Series queue that archives TIDs and IDoc data after the ALEModule has finished processing events. For more information, see Chapter 11,“Overview of the ALE module”, on page 105.

There is no default value.

SAPALE_Event_QueueSpecifies the MQ Series queue that stores TIDs and IDoc data during the ALEModule’s processing of events. For more information, see Chapter 11, “Overview ofthe ALE module”, on page 105.


SAPALE_Wip_QueueSpecifies the MQ Series work-in-progress (wip) queue that holds TIDs and IDocdata while the ALE Module builds the MQ message for the event queue. After theconnector receives all data for an event, it moves the data in this queue to theSAPALE_Event_Queue. For more information, see Chapter 11, “Overview of theALE module”, on page 105.


SAPtid_MQChannelSpecifies the Client channel for the MQ Series queue manager. For moreinformation, see Chapter 11, “Overview of the ALE module”, on page 105.


SAPtid_MQPortSpecifies the port used to communicate with the MQ Series queue manager thathandles the queues for the ALE Module. For more information, see Chapter 11,“Overview of the ALE module”, on page 105.


SAPtid_QueueSpecifies the MQ Series queue on which messages containing the TID and TIDstatus reside. This property is used by the ALE Module only when processingrequests. For more information, see Chapter 11, “Overview of the ALE module”, onpage 105.


SAPtid_QueueManagerName of the MQ Series queue manager for the queues that store TIDs and IDocdata. This property is used by the ALE Module to process events and requests. Formore information, see Chapter 11, “Overview of the ALE module”, on page 105.


SAPtid_QueueManagerHostName of the host where the MQ Series queue manager resides. This property isused by the ALE Module to process events and requests. For more information, seeChapter 11, “Overview of the ALE module”, on page 105.



SAPtid_QueueManagerLoginUser name to log into the MQ Series queue manager. This property is used by theALE Module to process events and requests. For more information, see Chapter 11,“Overview of the ALE module”, on page 105.


SAPtid_QueueManagerPasswordPassword for the user who logs into the MQ Series queue manager. This propertyis used by the ALE Module to process events and requests. For more information,see Chapter 11, “Overview of the ALE module”, on page 105.


SysnrSystem number of the application server. The value is a two-digit number, often 00.The default is 00.

TransIdCollabName

Important: The connector no longer supports this property.

UseDefaultsOn a Create or Update operation, if UseDefaults is set to true, the AdapterFramework (WMQI) or Connector Framework (ICS) checks whether a valid valueor a default value is provided for each business object attribute marked asrequired. If a value is provided, the Create or Update operation succeeds. If theparameter is set to false, the connector checks only for a valid value and causesthe Create or Update operation to fail if it is not provided. The default is false.

Connector startupFor information on starting a connector, stopping a connector, and the connector’stemporary startup log file, see the WebSphere Business Integration AdaptersImplementation Guide for MQ Integrator, or, for ICS, see the IBM CrossWorlds SystemAdministration Guide.

Starting multiple connectorsTo start multiple connectors, follow these instructions:1. Copy the connector definition, giving the new definition an appropriate name.

For example, name the new definition SAP2_Connector.v If the connector uses WMQI as the integration broker, use a system

command to copy the definition file (by default,\repository\Sap\CN_SAP.txt) to CN_SAP2.txt. Then open the definition filewith a text editor and rename the definition to the name of your connector

v If the connector uses ICS as the integration broker, use CSM to copy andname the definition.

2. Make a copy of the entire \connectors\SAP directory, and change the name tomatch the new connector name, for example \connectors\SAP_Connector2.

3. In the new connector directory, make a copy of the CWSAP.jar file, and thenrename it to match the name of the new connector, for exampleCWSAP2_Connector.jar.

4. For Windows, create a connector shortcut and point it to the connector startupfile, start_SAP.bat, in the \connectors directory.


5. Copy the SAP.txt message file in the \connectors\messages\ directory, andrename it to match the new connector name, for exampleSAP2_ConnectorConnector.txt

Repeat these steps for each connector.

Upgrading the connectorThis section describes how to upgrade the connector:v “Upgrading the connector for the ALE Module’s management of TIDs”v “Upgrading to the Java-based connector” on page 26

Upgrading the connector for the ALE Module’s management ofTIDs

The ALE Module persistently stores IDoc objects and Transaction IDs (TIDs) forevery transaction it receives from the SAP application. In releases of the connectorprior to version 4.8.x, the connector used IBM WebSphere collaborations, businessobjects, and maps to store the data in the repository. Version 4.8.x of the connectorreplaces the previous way of TID management with the use of MQSeries queues.

Attention: To enable the ALE Module to process IDocs to and from the SAPapplication, you must upgrade the connector. However, it is imperative that youallow the current IDoc processing cycle to complete before upgrading theconnector.

Before you upgrade the connector to enable the ALE Module to process IDocs, youmust complete the processing of current files in the event and WIP directories.Also, check the archive directory for failed and unsubscribed events.

To complete the processing of current files in the event and WIP directories:v Temporarily halt the transmission of IDocs both to and from the connector.v Verify that there are no IDocs (files) in the following directories when you

upgrade:

UNIX$crossworlds/connectors/SAP/ale/events$crossworlds/connectors/SAP/ale/wip

End of UNIX

Windows%crossworlds%\connectors\SAP\ale\events%crossworlds%\connectors\SAP\ale\wip

End of Windows

To complete processing of any failed and unsubscribed events:v Temporarily halt the transmission of IDocs both to and from the connector.


v Verify the status of the IDocs (files) in the following directory when youupgrade:

UNIX$crossworlds/connectors/SAP/ale/archive

End of UNIX

Windows%crossworlds%\connectors\SAP\ale\archive

End of Windows

v Correct any errors to the failed or unsubscribed events.v Move the corrected file to the event directory for processing.

Note: If, when using transaction SM58, you find unsuccessfully processed IDocs inthe SAP system, wait until the connector is upgraded to resubmit theseIDocs. After you complete the upgrade of the connector, correct the errorsand resubmit the IDocs for processing through the MQSeries queues usingthe new TID management.

Once these directories are clear, apply the upgrade and follow the configurationinstructions in:v “Connector-specific configuration properties” on page 17v Chapter 11, “Overview of the ALE module”, on page 105v Chapter 12, “Configuring the ALE module”, on page 119

Upgrading to the Java-based connectorThe IBM WebSphere Business Integration Adapter for mySAP.com is delivered as aJava-based connector (connector version 4.0.0 and later). In previous releases, theconnector was written in C++. The directory structure is \connectors\SAP.

The following procedure is for upgrading a C++ version of the connector to theJava version of the connector.1. Rename the current connector directory.

For example, \connectors\SAP becomes connectors\SAP.old.2. Rename the connector message file.

For example, \connectors\messages\SAPconnector.txt becomes\connectors\messages\SAPconnector.txt.old.

3. Copy the new connector directory and files to the \connectors directory.4. Copy the new connector message file to the \connectors\messages directory.

Windows

Modify the connector shortcut to point to the start_SAP.bat file in the connectordirectory. For example, if you are using the connector that supports SAP R/3version 3.x, modify the shortcut to point to the connector startup file\connectors\SAP\start_SAP.bat.

End of Windows


Part 2. ABAP Extension module



Chapter 3. Overview of the ABAP Extension modulev “ABAP Extension module components”v “How the ABAP Extension module works” on page 30

This chapter describes the ABAP Extension Module of the IBM WebSphereBusiness Integration Adapter for mySAP.com (SAP R/3 Version 4.x). The ABAPExtension Module enables an integration broker to send business objects to andreceive events from SAP R/3 application version 3.1H or 3.1I.

ABAP Extension module componentsThe ABAP Extension Module consists of components written in Java and ABAP.The Java components consist of the connector module and the SAP RFC libraries.SAP delivers their RFC libraries in Java and C. The ABAP components consists ofvarious SAP application function modules, database tables, and programs. Some ofthese ABAP components are developed and delivered as part of the adapter andsome are native to every SAP installation

Figure 4 illustrates the overall architecture of the ABAP Extension Module.

SAP R/3

ABAP

doVerbFor()

Java

SAP RFC library

pollForEvents()

SAP gateway

EventRequest

EventReturn

Eventtable

Function Module:Y_XR_RFC_EVENT_RETURN

Function module:Y_XR_RFC_EVENT_REQUEST

Function module:Y_XR_RFC_DO_VERB_NEXTGEN

ABAP handlers

EventProcessing

pollForEvents()

Eventrequest

Eventreturn

Eventarchive

EventProcessing

Function module:Y_XR_ADD_TO_QUEUE

Init()

Function module:Y_XR_RFC_LOGON


Figure 4. ABAP Extension module architecture


Java componentsThe connector is delivered and run as a Java Archive (JAR) file. It handles theevent delivery and event business object request processes. The SAP RFC library isdelivered and run as a JAR file as well. It enables external programs to executeABAP function modules within an SAP application.

The Java components:v Open an RFC connection to the SAP application using the SAP RFC library and

the SAP Gateway.v Handle requests from the integration broker and pass the requests to an ABAP

component of the connector.v Poll the SAP application for events.

ABAP componentsThe ABAP components of the connector are function modules, programs, anddatabase tables. These elements handle the event delivery and business objectrequest processes initiated by the Java component. The ABAP components aredelivered in connector transport files to be loaded into an SAP application; onceloaded, they run as ABAP repository objects.

The ABAP components:v Handle business object requests from the Java component by calling the

appropriate function modules designed to handle a particular business objecttype and verb.

v Detect, trigger, and store events in the event table.v Handle event requests and their subsequent return (event status update) from

the Java component.

How the ABAP Extension module worksMost of the functionality provided by the ABAP Extension Module occurs inside ofthe SAP application. For most of the virtual functions that every connector mustimplement, there is a corresponding ABAP function module in the SAPapplication. However, SAP does not provide ABAP function modules that supportthe specific requirements of the init(), doVerbFor(), and pollForEvents()methods, so these function modules have been developed and delivered as part ofthe connector module. While the Java components provide some functionality, themajority of the processing for these methods is done by the ABAP components inthe SAP application.

Table 5 shows the virtual Java methods that the connector module implements andtheir corresponding ABAP components. Keep in mind that this table does notprovide a complete list of the ABAP components used by the connector.

Table 5. Java components and their corresponding ABAP components

Java components ABAP components

doVerbFor() Y_XR_RFC_DO_VERB_NEXTGENgetVersion() No implementation requiredgetBOHandlerForBO No implementation requiredinit() Y_XR_RFC_LOGONpollForEvents() Y_XR_RFC_EVENT_REQUEST

Y_XR_RFC_EVENT_RETURNterminate() No implementation required


Together, these ABAP function modules are the core of the ABAP ExtensionModule. The following sections describe connector initialization, business objectprocessing, and how the connector handles event notification.

The implemented functions are discussed in the rest of this chapter.

InitializationThe init() method calls the ABAP function module Y_XR_RFC_LOGON to validatethat the destination SAP application is running and that the RFC library can beused to execute ABAP function modules. If the function module does not executesuccessfully, the connector terminates.

Business object processingAll service call requests for SAP are initiated by the doVerbFor() method in theJava component of the connector module. The connector’s ABAP function moduleY_XR_RFC_DO_VERB_NEXTGEN and an ABAP handler in the ABAP component of theconnector module handle the requests.

Figure 5 illustrates business object processing.

SAP R/3

doVerbFor()doVerbFor()

EventRequest

EventReturn

EventProcessing

SAP RFC library

SAP gateway

ABAP handlers

Function module:Y_XR_RFC_DO_VERB_NEXTGEN

ABAP

Java


Figure 5. Business object processing of doVerbFor()

Chapter 3. Overview of the ABAP Extension module 31

doVerbFor()In the Java component of the connector module, the doVerbFor() method of asingle business object handler implementation handles all of the business objectrequests from the integration broker and all business object events from thepollForEvents() method. In either case, doVerbFor() executes in the followingmanner:1. Converts an instance of a WebSphere business object for SAP to a single,

predefined flat structure that contains the business object data.2. Calls the ABAP function module Y_XR_RFC_DO_VERB_NEXTGEN, passes the

business object data to it, and then waits for business object data to bereturned.

3. Converts the returned business object data back into a WebSphere businessobject.

The doVerbFor() method passes business object data to function moduleY_XR_RFC_DO_VERB_NEXTGEN and then creates an entirely new business objectstructure from the returned business object data.

Y_XR_RFC_DO_VERB_NEXTGENIn the ABAP component of the connector module, the connector’s ABAP functionmodule Y_XR_RFC_DO_VERB_NEXTGEN is responsible for handling all WebSpherebusiness object processing in the SAP application. Specifically, it routes businessobject data to the appropriate ABAP handler. In this sense, function moduleY_XR_RFC_DO_VERB_NEXTGEN can be thought of as a business object router. It alwaysexecutes in the following manner:1. Receives a business object.2. Dynamically calls an ABAP handler to process the business object data and

passes the business object data as a parameter.3. Receives business object data from an ABAP handler and returns it back to the

requesting call.

Y_XR_RFC_DO_VERB_NEXTGEN uses ABAP handlers to fulfill each object type andverb-specific request. Y_XR_RFC_DO_VERB_NEXTGEN uses the value in a businessobject’s verb application-specific information to determine which ABAP handler tocall. Y_XR_RFC_DO_VERB_NEXTGEN can be thought of as a router from the doVerbFor()method to an ABAP handler.

ABAP handlersABAP handlers are unique to the connector module in that they extend thebusiness object handler functionality from the Java component of the connectormodule. ABAP handlers reside in the SAP application as ABAP function modulesand communicate directly with Y_XR_RFC_DO_VERB_NEXTGEN. ABAP handlers areneeded to get business object data into or out of the SAP application database.

Figure 6 illustrates the business object processing components of the ABAPExtension Module and their relationship to one another. Notice that for a singlebusiness object handler (doVerbFor()) and business object router(Y_XR_DO_VERB_NEXTGEN) there are multiple ABAP handlers.


ABAP handlers are responsible for adding business object data into the SAPapplication database (Create, Update, Delete) or for using the business object dataas the keys to retrieving data from the SAP application database (Retrieve).

The adapter provides generic ABAP handlers. For example, function moduleY_XR_RFC_DYNAMIC_TRANSACTION supports flat business objects for Create, Update,Delete, and Retrieve operations.

The WebSphere business integration system provides a meta-data repository and ageneric ABAP handler to support flat business objects. The adapter also providesan ABAP handler (Y_XR_IDOC_HANDLER) to support hierarchical business objects;however, you must develop an additional business-object-specific ABAP handlerfor each hierarchical business object that you need to support.

The WebSphere business integration system provides tools that facilitate thedevelopment process. For more information on developing business objects andABAP handlers, see Chapter 6, “Developing business objects for the ABAPExtension module”, on page 59 and Appendix C, “Generating business objectdefinitions using SAPODA”, on page 239.

Event notificationEvent notification refers to the collection of processes that notify the connector ofSAP application object events. Notification includes, but is not limited to the typeof the event (object and verb) and the data key required for the external system toretrieve the associated data.


SAP R/3

SAP RFC library

SAP gateway

Business object router:Y_XR_RFC_DO_VERB_NEXTGEN

Java

ABAP

BOHandler:doVerbFor()

ABAP handler:Y_XR_DYNAMICTRANSACTION

ABAP handler:Y_XR_IDOC_

HANDLER

ABAP handler:Y_XR_BAPI_

HANDLER

ABAP handler:OBJECT

SPECIFIC IDOC

ABAP handler:Y_XR_DYNAMIC

RETRIEVE

Figure 6. Adapter-provided business object processing components


Figure 7 illustrates the event notification process, which uses the pollForEvents()method.

Event notification for the connector consists of two functions:v “Event polling”v “Event triggering” on page 37

Event pollingEvent polling consists of three functions that are carried out by thepollForEvents() method:v “Event Request”v “Event Processing” on page 36v “Event Return” on page 36

Note: The roles of these functions are distributed in the Java and ABAPcomponents. However, the Java component always initiates event polling.

Event Request: Event request is the process of polling and retrieving events fromthe event table in the SAP application. The event request mechanism of the Javacomponent has a counterpart function module in the SAP application,Y_XR_RFC_EVENT_REQUEST. This function retrieves events from the connector’s ABAPevent table, YXR_EVENTS.

r

SAP R/3

SAP RFC library

SAP gateway

pollForEvents()

Evequest

entr

Eventreturn

Eventprocessing

Eventtable

Function module:Y_XR_RFC_EVENT_RETURN

Function module:Y_XR_RFC_EVENT_REQUEST

Eventarchive

Function module:Y_XR_ADD_TO_QUEUE

Java

ABAP


Figure 7. Event notification process


Every triggered event enters the event table with an initial status of prequeued(status marked as P in the event table) and a default event priority of zero. Beforean event can be processed, its status must be changed to queued (Q in the eventtable). The priority of an event must be zero before the connector retrieves the fullobject that it represents. For more information on event priority, see “EventPriority” on page 39.

The status of an event changes from prequeued to queued if there are no databaselocks for the combination of the user who created the event and the event’s key. Iflocks exist, the status of the event is set to locked (L in the event table) and theevent is requeued. An ABAP constant, C_MAXIMUM_REQUEUE, defines of the numberof times that an event can be requeued. If the maximum number (defaulted to 100)is attained, then the event is archived to the event archive table.

Note: Every event with a prequeued or locked status is updated with every poll.You can run into performance issues when events are triggered in batches.You can configure the polling frequency using the PollFrequencyconfiguration property. For more information, see Appendix A, “Standardconfiguration properties for connectors”, on page 199.

After preprocessing all prequeued events, the ABAP function moduleY_XR_RFC_EVENT_REQUEST selects the events to return to the event request method inthe Java component of the connector module (only events with a status of queuedcan be selected). The connector-specific configuration property PollQuantity(defaulted to 20) determines the maximum number of events returned for a singlepoll. For more information, see Chapter 2, “Installing and configuring theconnector”, on page 11.

The event request mechanism performs the event selection process in two steps:1. Selects events dedicated to the connector and the integration broker.

Events are dedicated to a specific integration broker in the event distributiontable (/CWLD/EVT_DIS). The name of the integration broker specified in thistable must match the name specified in the shortcut that starts the connector.For example, the standard shortcut for an SAP connector running on Windowshas the format:...\start_SAP.bat SAPconnectorName integrationBrokerName -cConfigFileName

When WMQI is the integration broker, the WebSphere business integrationsystem identifies the integration broker specified in the event distribution tableby getting values from the connector’s startup command:v The value of the integrationBrokerName parameter links the broker instance

in the startup command to the broker specified in the event distributiontable.

Note: The product’s installation program uses the integration broker namespecified at installation as the value of the integrationBrokerNameparameter in the startup command.

v The value of the ConfigFileName parameter identifies the Queue Managerand queues configured for the specific WMQI instance.

2. If fewer than the maximum number of events have been selected, pulls thebalance from the events that are not configured for event distribution.


For example, if the connector-specific configuration property PollQuantity iskept at 20 and there are 8 events dedicated to the specific connector and theintegration broker, the mechanism selects 12 additional events that are notconfigured for event distribution.When WMQI is the integration broker and only one Queue Manager has beenconfigured, the names of the queues must be unique for each instance of theintegration broker. When WMQI is the integration broker and a cluster hasbeen configured, the names of the queues must be unique for each integrationbroker within the cluster.If desired, you can incorporate the name of the broker (as specified in theintegrationBrokerName parameter of the startup command) or the name of theconnector into the names of the queues. For example, if two brokers are namedWMQI1 and WMQI2, their respective ADMINOUTQUEUEs might be namedADMINOUTQUEUE_MQI1 and ADMINOUTQUEUE_MQI2, respectively.

Important: If you set up multiple connectors to poll, you must configure everyevent to be processed by only one connector. Otherwise theconnector may send duplicate events, or may archive events insteadof retrieving them.

Event Processing: The event request function produces an array of events to beprocessed from the YXR_EVENTS event table. It passes these events to the eventprocessing function, which handles them one at a time in the following manner:1. Evaluates if the event is in the connector subscription list using the object.verb

value.v If an event is not in the subscription list, sets the status of the event to not

subscribed.v If an event is in the subscription list, creates a parentObjectOnly.Retrieve

business object, and sets the value of the first key attribute with the eventkey value. Composite keys are treated as singletons and must be interpretedby the ABAP business object processing function modules

2. Invokes doVerbFor() and passes the business object data to it. Once thebusiness object is passed, event processing waits for business object data toreturn.

3. Updates the status of the event array based on the doVerbFor() processing.4. Delivers the business object data to the integration broker if the business object

data is successfully retrieved.

Event Return: After each event is processed by event request, it is returned to theSAP application using function module Y_XR_RFC_EVENT_RETURN. This functionmodule makes a copy of the processed event, adds it to the event archive table(YXR_ARCHIV), and then deletes the original entry from the event table.

Note: Events with their new status are all updated after each event is processed.

Archived events include successfully processed events, events that were processedbut terminated in an error, and unsubscribed events. Each event has a status thatcan indicate one of the following conditions:v The business object was successfully sent to the integration broker.v The event produced an unknown Java return code from the connector.v The event failed in attempting to retrieve data from the SAP application.v The event timed out because the business object was locked.


v No collaboration subscribes to the event—relevant only when InterChangeServer (ICS) is the integration broker.

Use the IBM (CROSSWORLDS Connector Tool in the SAP application toadminister the event archive table. Connector Tool enables an administrator todisplay and truncate the archive table and to resubmit events for processing. Formore information about maintaining the archive table and setting up logtruncation, see Chapter 9, “Managing the ABAP Extension module”, on page 89.

Event triggeringThe connector is event-driven. In order to get events out of the SAP application,you need to implement an event triggering mechanism for each IBMWebSphere-supported business object. Event triggering for the connector comprisesthree functions:v “Event Detection”v “Event Trigger” on page 37v “Event persistence” on page 39

Event Detection: Event detection is the process of identifying that an event wasgenerated in the SAP application. Typically, connectors use database triggers todetect an event. However, because the SAP application is tightly integrated withthe SAP database, SAP allows very limited access for direct modifications to itsdatabase. Therefore, the event detection mechanisms are implemented in theapplication transaction layer above the database.

The IBM WebSphere Business Integration Adapter for mySAP.com commonly usesthree mechanisms to detect an event in the SAP application:v Code enhancementsv Batch programsv Business Workflow

Note: Each event detection mechanism has advantages and disadvantages thatneed to be considered when designing and developing a business objecttrigger. For more information on implementing an event detectionmechanism, see Chapter 7, “Developing event detection for the ABAPExtension module”, on page 77.

Note: These are only a few examples of event detection mechanisms. There aremany different ways to detect events.

Event Trigger: Regardless of the detection mechanism used, all events aretriggered using the event trigger Y_XR_ADD_TO_QUEUE. Once an event is identified byone of the event detection mechanisms, it is passed to the event trigger. The IBMWebSphere Business Integration Adapter for mySAP.com includes an event trigger(Y_XR_ADD_TO_QUEUE) that commits events to the event table (YXR_EVENTS).Specifically, it adds a row of data for the object name, verb, and key that representsthe event.

All events are added to the current events table using Y_XR_ADD_TO_QUEUE. Inaddition to adding a row of data to YXR_EVENTS, Y_XR_ADD_TO_QUEUE can be set upfor:v Event filteringv Event distributionv Event priority


Event filtering, event distribution, and event priority are executed as part of theevent trigger and by no other program. They result in either the event’s restriction(filtering), or modification (event distribution and event prioritization).

Event filtering The event trigger can be used to filter out eventsthat you do not want added to the event table. Theadapter provides an ABAP include program(YXRRESTR) that enables you to restrict specificevents for this purpose.

Event distribution Load balancing can be used to distribute eventprocessing across multiple connectors allowing youto process multiple events at the same time. Theevent trigger provides this capability through theevent distribution table (YXR_EVTDIS). You candedicate business objects to be retrieved by aspecific connector. Also, event distribution can takea single event and replicate it one or more timesfor each subscribed combination of connector andthe integration broker.

Figure 8 illustrates the event triggering functionality inside the SAP application.The events E1, E2, and E3 are received by the event trigger Y_XR_ADD_TO_QUEUE. E1represents a Customer event and E3 represents an Order event. Event distributionis set up so that all Customer objects are handled by SAPconnector1 and all Orderobjects are handled by SAPconnector2. In this environment, both connectors usethe same integration broker. Because E1 is a Customer object, it is polled bySAPconnector1 and because E3 is an Order object, it is polled by SAPconnector2.E2 is an Inventory object that is filtered out by code in the restriction programYXRRESTR that restricts inventory objects from Plant 100.

Attention: If you are using multiple connectors to poll, you must dedicate everysubscribed event to a specific connector. Failure to do so may result in duplicateevents delivered. You must guarantee that there is no dependency between objectsdedicated to different connectors, because this may result in events being deliveredout of sequence.

For example, assume you have a single integration broker named CROSSWORLDS1that subscribes to two different business objects, BO_A and BO_B. The BO_Abusiness object is small and can be retrieved quickly whereas BO_B is large and

EventDistribution

Eventfiltering

Currenteventtable

Y_XR_ADD_TO_QUEUE

E1

E3

E1

E3

E1Event

detectionmechanism

E2

E3

SAP1connector

SAP2connector

Figure 8. Event triggering with function module Y_XR_ADD_TO_QUEUE


takes much longer to retrieve. With two connectors polling, SAPconnector1 andSAPconnector2, you can set up the event distribution table so that SAPconnector1retrieves BO_A and SAPconnector2 retrieves BO_B. SAPconnector1 cancontinuously poll small objects of type A, while SAPconnector2 focuses on thelarger type B objects.

Note: For information on how the WebSphere business integration systemidentifies each unique instance of a WMQI integration broker, see “EventRequest” on page 34.

Important: If the event distribution table is not configured for a specific object,then each event triggered for that object is available for anycombination of connector and integration broker.

Event priority You can set the event priority for each combination of businessobject, connector, and integration broker by delaying the retrievalof events. An event’s priority indicates the number of polls that areneeded before the event is picked up for delivery. For example, ifyou set the priority of an event to 10, then the connector polls theevent table ten times before the event is retrieved. Each time theconnector polls, the priority value is reduced by one until itreaches zero.

By default, all events are given a priority of zero. An object’spriority is configured in the same ABAP table as event distribution.

Event persistence: Once the event trigger inserts an event into the event table, theevent is committed to the database with its event distribution and event priorityvalues set. At this time, only polling can modify the event. When the event pollingprocesses is completed, meaning the event was retrieved from the SAP applicationand processed by the Java component of the connector, a copy o f the processedevent is added to the event archive table (YXR_ARCHIV). The original event is thendeleted from the event table.

Note: You can resubmit an event from the archive table. Keep in mind that theevent is simply moved to the event table and is not triggered again.Specifically, it does not pass back through event filtering, event distribution,and event priority.



Chapter 4. Installing and customizing the ABAP Extensionmodule

v “Connector transport file installation”v “Verifying the connector transport file installation” on page 44v “Enabling the SAP application for the connector” on page 44

This chapter describes the installation and customization of the ABAP ExtensionModule only and assumes that you have already installed and configured the IBMWebSphere Business Integration Adapter for mySAP.com. For more information oninstalling and configuring the connector, see Chapter 2, “Installing and configuringthe connector”, on page 11. Customizing the connector is optional, butrecommended.

All of the components of the connector can be found in the \connectors\SAPdirectory for Windows and the /lib directory for UNIX. The transports areinstalled on an SAP R/3 application or database server as described below in“Connector transport file installation” on page 41.

Note: In this document backslashes (\) are used as the convention for directorypaths. For UNIX installations, substitute backslashes with slashes (/). All filepathnames are relative to the directory where the product is installed onyour system.

Connector transport file installationThe connector’s transport files contain a variety of objects such as, table structures,functions, and data. These development objects need to be imported into your SAPinstallation to provide specific functionality required by the ABAP ExtensionModule.

Transport filesEach transport file is included in a .zip file. For example, the transport file for theSAP R/3 version 3.x Primary transport is located in the Primary.zip file. Thesefiles can be found in \connectors\SAP\dependencies\transports_3x.

Modifications required by IBM WebSphere Business Integration Adapter formySAP.com (SAP R/3 Version 4.x) are handled by a set of three required transportfiles along with one transport file for each business object. To ensure that allnecessary tables are created before the data for those tables is added, the transportfiles must be imported in the following order:1. Primary

2. Infrastructure_1

3. Infrastructure_2

Once the required transport files have been successfully loaded, the businessobject-specific transports can be loaded in any order. See the transport noteincluded in each transport .zip file for detailed information about the transportfile.

Primary This transport file contains the developmentobjects, which should only be loaded once into the


recipient system. It contains the number rangeobjects, the development class for YXR1 as well asthe restriction include, which can be used to makecustomer-specific changes to the triggering logic.Caution should be used when applying thistransport file to a system that already has theconnector running on it, because the contents ofthe transport file may overwrite changes that weremade to these objects.

Infrastructure_1 This transport file contains the programs and datadictionary objects associated with the connectorthat are not business object specific.

All of the objects begin with YXR with the followingexceptions:v The message class used in the connector’s

development environment is YX.v There are two set/get memory parameters YXD

and YXV, because set/get parameters are limitedto three characters.

v The programs behind the two product areamenus are MENUYXR0 and MENUYXR1, because SAPautomatically prefixes the string MENU before allarea menu programs. The area menusthemselves are within our name range.CAUTION:Any changes that are made to objects in thistransport file need to be well documentedoutside of SAP. Changes will be overwritten bythe next IBM WebSphere adapter infrastructuretransport and will need to be re-appliedmanually.

Infrastructure_2 This transport contains SAP customizing datanecessary for the connector log and for thetransaction to maintain the connector’s tables. Allof the keys begin with YXR. The customizing tableentries in the connector’s tables do not begin withYXR.

Installing connector transport filesThe connector transport files make all necessary modifications to SAP by importingprograms and other development objects included with the IBM WebSphereBusiness Integration Adapter for mySAP.com. They do not alter any SAP programsor modify user exits.

In the following instructions, SID refers to your SAP system ID andTransportFileName refers to the name of the transport file. However, the charactersthat make up the transport file name appear in a different order in the installationdirectory from the way the name is passed as a parameter to the various tpcommands. In the \usr\sap\trans\cofiles directory, the format of a transport filename is K9xxxxx.SID, but when the file name is passed as a parameter it has theformat SIDK9xxxxx. For example, the file name K912345.D30 would be passed as aparameter as D30K912345 if your SID is D30.


To install the transports:1. Log in as the SAP administrator, SIDadm.2. Copy the transports to the SAP database server.The transports consist of two

kinds of files and should be copied as described below:a. Copy files that have names beginning in K to the \usr\sap\trans\cofiles

directory.b. Copy the other files to the \usr\sap\trans data directory.

Check the connection to the database and determine the path of the tpparamfile by running the tp connect command:tp connect SID

If this command fails, try adding the path of the tpparam file as a secondparameter:tp connect SID pf = path_of_tpparamFor example, if the SID is P11 and the path of the tpparam file is\usr\sap\trans\bin\tpparam, the command would be:tp connect P11 pf = \usr\sap\trans\bin\tpparam

If tp connect succeeds when you specify the path of the tpparam file andfails when you do not, you should specify the optional tpparam path in thecommands described below in step 3.

3. The transports can be imported in one of the following two ways:v In \usr\sap\trans\bin, execute the following commands for each transport,

in the order specified:tp addtobuffer TransportFileName SID pf = path_of_tpparamtp import TransportFileName SID u023689 CLIENT=CLIENT# pf =path_of_tpparam

v In the Transport Management System (transaction STMS):a. Click the Import overview icon (F5).b. Double-click the appropriate queue to be updated.c. In the menu bar, click Extras, then Other requests, and then click Add.d. Populate the transport request field, and click the check mark to enter it.e. When the Add Transport Request confirmation window appears, click Yes

to attach the import to the queue.f. Place the cursor on the transport that was just added.g. In the menu bar, click Request, and then click Import.h. Populate the Target client field, and click the check mark to import it.

Important: Install the transports in order.4. When the transports are installed, change the development class to follow the

migration path of your development classes. In SAP R/3 versions 3.x thedevelopment class is YXR1

Using the IBM CrossWorlds Connector Tools window (transaction YXR1):a. From the Customizing menu, click Connector, and click Reassign Transp

Lyr.b. Select the appropriate Transport layer entry, and then click the Save button.

For additional configuration requirements of particular application-specificbusiness objects, see the reference page for that business object.

Chapter 4. Installing and customizing the ABAP Extension module 43

CAUTION:Any changes you make to development objects which were in the connectortransports, should be well documented outside of SAP. Changes could beoverwritten by the next release of the adapter’s transport files and would needto be re-applied manually. For more information on upgrade issues, seeChapter 10, “Upgrading the ABAP Extension module”, on page 95.

Verifying the connector transport file installationTo verify that the connector transport files were physically moved into the SAPapplication, examine the transport logs in one of the following two ways:v To verify that the connector transport files were physically moved into the SAP

application, examine the transport logs in one of the following ways:Using the Transport Organizer (transaction SE01):1. Populate the number field with the name of the transport file.2. Click Display to see the log.

Using the Transport Management System graphic interface (transaction STMS):1. Click the Import overview icon (F5).2. Double-click the appropriate queue.3. Right-click the transport number, and then select Logs.4. Examine the log to see if the installation was successful.

v To verify that SAP generated the objects successfully:1. Go to transaction SE382. Enter YXR_CNST as the program.3. Select Source Code, and then click Display.4. From the Program menu, click Generate.5. Click Select All, and then click Continue (F2).

This generates all of the adapter’s programs that include these programs.

If you get the response Programs successfully generated, you can assume thatthe transport was successful.

Enabling the SAP application for the connectorAfter installing the connector and configuring the standard and connector-specificconfiguration properties, you have the option of modifying the event handling andlogging capabilities for the connector from within the SAP application.

Setting up event distributionLoad balancing distributes event and business object request processing acrossmultiple connectors. The IBM WebSphere Business Integration Adapter formySAP.com can handle only one transaction at a time. Therefore, if you set upmultiple connectors to handle specific business objects, then multiple events andbusiness objects can be processed at the same time. For more information onsetting up multiple connectors, see “Installing multiple connectors” on page 15.

To set up event distribution for multiple connectors:1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).


2. From the Customizing menu, click Connector, and then click EventDistribution.

3. Click the New Entries button (F5), and in the New Entries window, enter thebusiness object name, connector name, and InterChange Server name.

4. Enter a number in the counter field for each business object. The combinationof the business object and counter provides a unique key for the eventdistribution table. The counter can be any number up to six digits in length.

Note: In a test environment, you may have multiple users testing the samebusiness object that is subscribed to by multiple connectors. If each userwants only a certain event for that business object, then you can specify auser name to differentiate between which event is passed to whichcombination of connector and integration broker. In the User (Event Trigger)field, enter the appropriate user name for the business objects.

Setting up event filteringThe configuration table in the SAP application cannot accommodate allmodifications, so the IBM WebSphere Business Integration Adapter for mySAP.comprovides an ABAP include program that can be modified to filter events. Thisprogram, YXRRESTR is called from within the event trigger Y_XR_ADD_TO_QUEUE toenable additional filtering of events.

Note: You must have developer privileges to make changes because the codeneeds to be recompiled.

To view or modify the include program YXRRESTR:1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).2. From the Customizing menu, click Event Triggering, and click Modify

Restrictions (transaction YXRS).

A number of possibilities for event filtering can be configured using this program.

Setting up event priorityYou can set the priority of an event to be processed based on its importance. Bysetting the priority of each combination of business object, connector, andintegration broker, you can delay a connector’s retrieval of an event. For example,if you set the priority of an event to 10, the connector polls the event table tentimes before retrieving the event. So, if the connector polls the event table every 5seconds, the connector picks up the event after 50 seconds. Each time the connectorpolls, the priority value is reduced by one until the event is retrieved andprocessed.

To set the priority of an event:1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).2. From the Customizing menu, click Connector, and click Event Distribution.3. Populate the Priority column, with a value between 1 and 99 for the

appropriate business object.

Increasing log tablespace sizeThe log tables for the IBM WebSphere Business Integration Adapter formySAP.com are located, by default, in the tablespace named PSAPUSER1D,and the

Chapter 4. Installing and customizing the ABAP Extension module 45

indexes are located in tablespace PSAPUSER1I. PSAPUSER1D and PSAPUSER1I are SAPapplication tablespaces reserved for customer use, but are typically small. Becauseof the default size, these tablespaces can fill up quickly, depending on the level ofactivity and the logging level of the adapter’s installation.

To view the current size of these tablespaces, go to transaction DB02, and thenclick the Current Sizes button. The volume of events captured by IBM WebSpherebusiness integration system determines the size needed for these tablespaces.

If the default sizes are too small, ask the SAP database administrator for theinstallation to modify them.

Verifying number ranges for transport objectsThere are three objects for the adapter that must have an adequate number rangewithin the SAP application. When the transports are installed, the following objectsand their default number ranges are set:v YXR_EVENTv YXR_IDOCv YXR_LOGv YXR_OBJARC

You should have to verify only that the associated number ranges are set correctly.To view the number ranges:1. Go to transaction SNRO.2. Populate the Object field with the object name (for example, YXR_EVENT).3. Click Number Ranges, and then click Intervals.

Note: If you reinstall the Primary connector transport in an installation whereevents have already been generated, new events may be created usingexisting event IDs. To prevent this problem, turn off logging (transactionYXRM), and then truncate the log completely before reimporting theconnector transport file. Once the connector transport file has beensuccessfully loaded, turn logging back on. For more information ontruncating the event log, see “Setting up truncation of the event log” onpage 90.


Chapter 5. Business object processing in the ABAP Extensionmodule

v “Business object conversion to a flat structure” on page 48v “Business object data routing to ABAP handlers” on page 51v “How ABAP handlers process business object data” on page 53v “Flat structure conversion to a business object” on page 57

This chapter discusses business object processing for the ABAP Extension Module.It provides a detailed description of how the connector processes business objects.The chapter is set up to show the progression of a business object through the Javaand ABAP components of the connector.

Note: All references to ABAP components of the connector use the SAP R/3version 3.x naming convention.

Business object processing for the Extension Module of the IBM WebSphereBusiness Integration Adapter for mySAP.com (SAP R/3 Version 4.x) is the same forall business objects regardless of the specific native SAP API that is used. Forexample, if you develop a business object based on a Call Transaction or an IDoc,the business object data is processed the same way. The processing is the samewhether a business object is sent into the SAP application as a retrieve performedas part of event notification or as a business object request. The business object’sverb also does not change the processing.

Figure 9 illustrates the conversion and processing of an application-specificbusiness object to a flat structure and then back to an application-specific businessobject. Note that the business object data that is passed out of the SAP applicationmust have the same structure as the data passed in, but the data might not havethe same values.


Business object processing consists of four steps. The four steps listed belowcorrespond to the numbers in Figure 9.1. The connector converts an application-specific business object into a flat

structure containing business object data and passes the data to the SAPapplication.

2. The connector’s function module Y_XR_RFC_DO_VERB_NEXTGEN dynamically routesthe business object data to an ABAP handler.

3. The ABAP handler processes the business object data, generates business objectresponse data, and returns new business object data to the connector backthrough Y_XR_RFC_DO_VERB_NEXTGEN.

4. The connector receives the new business object data, and uses it and thebusiness object definition of the application-specific business object to create anew business object to pass to the integration broker.

Business object conversion to a flat structureAs a first step in business object processing, the connector converts a businessobject into a flat structure that can be processed in the SAP application. The formatof the flat structure is the same for all types of business objects (such as CallTransaction-based or IDoc-based business objects). The flat structure is reformatteddata from an application-specific business object. The only difference between the

Business object router:Y_XR_RFC_DO_VERB_NEXTGEN

ABAP handlers

BOHandlerConnector

module

Flatstructure

Flatstructure

3

1

2

4

Application-specific

businessobject

Application-specific

businessobject

Connectormodule

WebSphere BusinessInterChange Serverr

SAP R/3

Figure 9. Business object processing


two forms of data is that the flat structure does not maintain parent and childbusiness object relationships. Therefore, the connector relies on a set of rules tocreate a flat structure.

When converting a business object into a flat structure, the connector creates astructure in memory and then populates it with data from the business object. Indoing so, it passes the following data into the SAP application from the businessobject:v Business object namev Business object application-specific informationv Business object verbv Business object verb application-specific informationv Attribute namev Attribute property IsKey

v Attribute property AppText

v Attribute value

Table 6 shows the generic flat structure of a business object. The connector usesthis flat structure when adding the business object data from a WebSphere businessobject.

Table 6. Generic Flat Structure Representation of a WebSphere Business Object for SAP

Field Name Data Type Length Description

ATTR_NAME CHAR 32 Attribute Name (example, CustomerId)BLANK1 CHAR 1 DelimiterATTR_VALUE CHAR 200 Attribute Value (example, 00000103)BLANK2 CHAR 1 DelimiterISKEY CHAR 1 1= true, 0 = false; attributes onlyBLANK3 CHAR 1 DelimiterISNEW CHAR 1 1 = BO; 0 = verb or attributeBLANK4 CHAR 1 DelimiterPEERS CHAR 6 Indicates number of peers of an array of business

objectsBLANK5 CHAR 1 DelimiterOBJ_NUMBER CHAR 6 Not usedBLANK6 CHAR 1 DelimiterAPPTEXT CHAR 120 Application-specific information of object, verb or

attributeBLANK7 CHAR 1 Delimiter

Note: The BLANKn field names always contain a single character (CHAR) spaceand should never be populated.

In order for the data conversion to work properly, the business object data in theflat structure must strictly adhere to a set of rules. These rules are defined in thisinitial data conversion step:v Each business object attribute is placed sequentially into a flat structure, where

one row corresponds to one attribute.v Hierarchical business objects are converted as depth and then breadth.

Chapter 5. Business object processing in the ABAP Extension module 49

When the connector populates the flat structure with business object data, theconnector loops through each business object twice, beginning with the top-levelbusiness object.1. In the first pass, it sets all simple attributes. Each attribute equals one row in

the flat structure.2. In the second pass, it recursively executes the same processing in step 1 for

each child business object.

Attributes that represent child business objects are not included in their parents.Instead, each child that contains data is created as a complete business object. Theresult is a single list of attributes ordered by depth, then breadth.

Figure 10 illustrates the data conversion of a WebSphere business object for SAPinto a flat data structure. The conversion of data always follows the rule of depthfirst and then breadth. In the example, the top-level parent business object,SAP_Order, has two children, SAP_LineItem (1) and SAP_LineItem (2), which areconsidered peers. SAP_LineItem (1) has one child business object,SAP_ScheduleLines.

It is important to understand the ordering of the business objects and theirattributes when designing a business object definition. The following tablesillustrate the result of the conversion of an WebSphere business object to a flatstructure. Table 7 represents a flat structure for a flat business object, SAP_Material,

Order Number

Parent business object

Customer Number

SAP_LineItem (2)

SAP_Order

Item number

Material

SAP_ScheduleLines (1)

SAP_LineItem (1)

Delivery datee

Quantity

SAP_ScheduleLines

Customer number

Item number

Material

Delivery Date

Quantity

Order numberChild business object

Child business object

SAP_Order

SAP_LineItem

SAP_ScheduleLines

Item number

Material

SAP_ScheduleLines (null)

SAP_LineItem (2)

Child business object Item number

Material

SAP_LineItem

Flat structure

SAP_ScheduleLines (null)

Figure 10. Conversion from a business object to a flat structure


whose key value is ItemID. In this example, there is no application-specificinformation for the business object or any of the attributes. Table 8 represents a flatstructure of a hierarchical business object based on an IDoc Sales Order.

Table 7. Flat business object SAP_Material

ATTR_NAME ATTR_VALUE ISKEY ISNEW PEERS OBJ_NUMBER

APPTEXT

BoName SAP_Material 0 1 1 (blank) (blank)BoVerb Retrieve 0 0 1 (blank) :Y_XR_DYNAMIC_RETRIEVEItemID 000000000000001179 1 0 1 (blank) (blank)ShortDesc CxIgnore 0 0 1 (blank) (blank)ObjectEventID SAP_124 0 0 1 (blank) (blank)

In this example, there is no application-specific information for the business objector any of the attributes.

Table 8. Hierarchical business object based on an IDoc sales order


APPTEXT

BoName SAP_Order 0 1 1 (blank) YXRV4B01BoVerb Create 0 0 1 (blank) [archive:methods]Currency USD 0 0 1 (blank) E1EDK01:CURCYOrderId CxIgnore 1 0 1 (blank) E1EDK01:BELNRObjectEventId SAP_124 0 0 1 (blank) E1EDK01:

ObjectEventIdBoName SAP_LineItem 0 1 2 (blank) Z1XRV40BoVerb Create 0 0 2 (blank) (blank)Createdby User1 1 2 (blank) Z1XRV40:ERNAMObjectEventId SAP_125 0 0 2 (blank) Z1XRV40:

ObjectEventIdBoName SAP_

ScheduleLines0 1 1 (blank) E1EDK14

BoVerb Create 0 0 1 (blank) (blank)Qualifier 001 1 0 1 (blank) Z1XRV40:QUALFOrganizationId 1000 0 0 1 (blank) E1EDK14:ORGIDObjectEventId SAP_126 0 0 1 (blank) E1EDK14:

ObjectEventIdBoName SAP_LineItem 0 1 2 (blank) Z1XRV40BoVerb Create 0 0 2 (blank) (blank)Createdby User1 1 0 2 (blank) Z1XRV40:ERNAMObjectEventId SAP_127 0 0 2 (blank) Z1XRV40:

ObjectEventId

The first two rows, BoName and BoVerb, are added by the connector for eachbusiness object. BoName and BoVerb are keywords that cannot be used as businessobject attributes.

Business object data routing to ABAP handlersOnce the business object data is converted into a flat structure, the business objectdata is passed into SAP memory by calling the adapter’s ABAP function moduleY_XR_RFC_DO_VERB_NEXTGEN. Y_XR_RFC_DO_VERB_NEXTGEN does not manipulate thebusiness object data; it simply routes it to the appropriate ABAP handler for


further processing. After Y_XR_RFC_DO_VERB_NEXTGEN passes the business object datato an ABAP handler, it waits for business object data to be returned.

Note: Remember that every business object retrieve and request is processedthrough Y_XR_RFC_DO_VERB_NEXTGEN.

Y_XR_RFC_DO_VERB_NEXTGEN uses a business object’s verb application-specificinformation to determine which ABAP handler processes the business object data.At runtime, Y_XR_RFC_DO_VERB_NEXTGEN reads the verb application-specificinformation and passes the business object data to the specified ABAP handler.

Every ABAP handler must reserve the use of verb application-specific informationfor the connector. The format for the verb application-specific information is::function1:function2:function3

where Y_XR_RFC_DO_VERB_NEXTGEN executes function1, passing function2 andfunction3 as parameters. For example, Customer Update and Material Retrieveexecute only function1:

For Create, Update or Delete verbs, specify:Y_XR_RFC_DYNAMIC_TRANSACTION

For the Retrieve verb, specify :Y_XR_RFC_DYNAMIC_RETRIEVE

One of the ABAP handlers provided by the adapter is function moduleY_XR_IDOC_HANDLER. This ABAP handler reformats the data of the flat structure intoan instance of an IDoc definition and passes that reformatted data to anotherABAP handler written to handle that specific type of IDoc. The following examplesillustrate the use of the IDoc handler API:

Sales Order Update = :Y_XR_IDOC_HANDLER:Y_XR_ORDER_C2

Sales Order Retrieve = :Y_XR_IDOC_HANDLER:Y_XR_ORDER_C4

In the examples, Y_XR_IDOC_HANDLER is executed and passes the second functionmodule name as well as the business object data. Y_XR_IDOC_HANDLER executes thecall to the second ABAP handler to pass the business object data in an IDoc formatto the Y_XR_ORDER function module written specifically to handle Order objects. Forsteps on setting up verb support for the IDoc handler, see “Developing businessobjects using IDocs” on page 70.

Note: Y_XR_RFC_DO_VERB_NEXTGEN uses the value of function1 only. function2 andfunction3 may be used by the ABAP handler.

To dynamically call an ABAP handler, Y_XR_RFC_DO_VERB_NEXTGEN requires theinterface of every ABAP handler to be exactly the same. This enablesY_XR_RFC_DO_VERB_NEXTGEN to send and receive business object data, as well as areturn code and a return text message to any ABAP handler. For more informationon the functional module interface, see “IBM WebSphere function moduleinterface” on page 61.


How ABAP handlers process business object dataThe function of an ABAP handler is to get business object data into or out of theSAP application database. When processing business object data, ABAP handlers:1. Interpret business object data.2. Integrate data with SAP native APIs.3. Reformat all data returned from native APIs.

business object data and ABAP handlersEvery ABAP handler receives business object data in the same format (flatstructure). However, each ABAP handler has specific requirements for businessobjects that are determined by the complexity of the WebSphere business objectdefinition, the native API that SAP provides, and the level of functionality that theABAP handler provides. For these reasons, ABAP handlers may interpret businessobject data by parsing it into a structure specific to the business object. Thisenables the ABAP handler to more easily manipulate the data.

Note: Parsing the data is not required. However, it simplifies the ABAP handler’sprocessing of a business object.

The adapter provides several ABAP handlers, such as an IDoc handler. The IDochandler leverages SAP’s IDoc technology by providing an ABAP handler tointerpret business object data by reformatting it into an IDoc-based structure forthe ABAP handler to use.

Business object data and SAP native APIsOnce the ABAP handler interprets the business object data, the ABAP handlermust integrate it with the SAP application database. It must manipulate thebusiness object data to use SAP native APIs such as Call Transaction, BAPI, orABAP SQL to get data into or out of the application database.

Create, update, and delete processingThe intent of a Create, Update, or Delete operation is to modify the SAPapplication database. While the SAP application database schema for a givenbusiness object defines the structure of the data, the transactions provided by SAPthat modify that data have a much broader scope of influence. As a result, directlymodifying the application database tables of an SAP application can havedisastrous results to the applications’s data integrity.

Instead of directly modifying the database tables, SAP provides a flexible ABAPAPI (Call Transaction) for Create, Update, and Delete operations. Call Transactionis SAP-provided functionality for entering data into an SAP application. Itguarantees that the data adheres to SAP’s data model by using the same screens anonline user would use in a transaction. This process is commonly referred to asscreen scraping.

Retrieve ProcessingIf the verb is Retrieve, then the connector uses ABAP SQL statements to retrievedata from the SAP application database. The business object data provides the keysfor the where clause when pulling data. The difficulty in this methodology ofretrieving data is that the retrieved data must be represented in a format thatrepresents the business object structure. This is done in the ABAP handler ABAPcode.


Returned business object data reformattingRegardless of the verb of the business object, the connector waits for two types ofconfirmations:v Return codev Returned business object data (for success only, return code = 0)

If the ABAP handler returns a non-zero code, then no business object is returned tothe connector. If ABAP handler processing is successful, then the connector expectsnew business object data that reflects the operation performed. For example, after asuccessful Create, the returned business object is an exact copy of the businessobject initially sent in, except that the keys are updated. Similarly, a successfulRetrieve results in a fully formed instance of the business object. However, Create,Update, and Delete operations have different requirements for returned businessobjects than do Retrieve operations.

When InterChange Server (ICS) is the integration broker, the difference inrequirements comes from how the WebSphere business integration system handlesbusiness objects, specifically dynamic cross-referencing of object IDs duringmapping. When the connector returns a business object to InterChange Server aftera Create or Update operation, the mapping infrastructure attempts to update thecross-reference tables with the newly acquired object ID. This is accomplished bylooking up the value of the business object’s ObjectEventId attribute that was setwhen the business object was originally sent to the connector.

To the ABAP handlers, this is significant because the ABAP handlers areresponsible for “stitching” the object IDs into the business object that is returned tothe connector. Typically, this is not an issue for Retrieve operations because there isno corresponding dynamic cross-referencing. Retrieve operations generate anentirely new business object that is returned to the connector. This business objectdoes not have any direct relationship to the structure of the business objectoriginally sent in.

The business object data returned by the ABAP handler must be in the same flatstructure format as when it was initially passed in to function moduleY_XR_RFC_DO_VERB_NEXTGEN. The ABAP handler needs to send out only simple typeattributes with the following information for each:v Valuev Peer relationshipv Application-specific information

The attribute name is not required at this point, because the connector uses onlythe application-specific information to create a business object from this data.Identifiers for the beginning and ending of business objects or object typeattributes are not used and should not be added. For example, the BoName andBoVerb rows are not used in the business object returned from the ABAP handler.They are initially passed into the ABAP handler only to facilitate processing.

The ABAP handler must adhere to the following set of rules when populating aflat structure with business object response data representing an WebSpherebusiness object:v Send only simple attributes, not object types.v All attributes must exist in the WebSphere business object definition.


v All attributes must be sent in the order they are listed in the WebSpherebusiness object definition.

v No attribute of a child business object can be sent unless at least one attribute issent for its parent business object.

v Contained business objects must communicate the number of peers they have.v Attribute name (field ATTR_NAME) is not required.

Figure 11 illustrates a flat business object (no object type attributes).

Table 9 represents the structure of a flat business object, SAP_Material, whose keyvalue is ItemID. Notice that field ATTR_NAME is not required, APPTEXT is unique foreach attribute, and because this business object is flat, the PEERS field can be leftblank.

Table 9. Flat business object SAP_Material


APPTEXT

(blank) 000000000000001179 (blank) (blank) (blank) (blank) ItemId(blank) Toaster 6000 (blank) (blank) (blank) (blank) ShortDesc(blank) SAP_124 (blank) (blank) (blank) (blank) ObjectEventId

Figure 12 illustrates a hierarchical business object (containing object types).

ItemId

ShortDesc

ObjectEventId

SAP_Material

Figure 11. Flat business object SAP_Material


Table 10 shows a representation of a flat structure of a hierarchical business objectbased on an IDoc Sales Order. Notice that field ATTR_NAME is not required, APPTEXTis unique for each attribute, and because this business object is hierarchical, thePEERS field lists the appropriate relationship.

Table 10. Hierarchical business object based on an IDoc sales order


APPTEXT

(blank) USD 0 0 1 (blank) E1EDK01:CURCY(blank) 0000000101 0 0 1 (blank) E1EDK01:BELNR(blank) SAP_124 0 0 1 (blank) E1EDK01:

ObjectEventId(blank) User1 0 0 2 (blank) Z1XRV40:ERNAM(blank) SAP_125 0 0 2 (blank) Z1XRV40:

ObjectEventId(blank) 001 0 0 1 (blank) Z1XRV40:QUALF(blank) 1000 0 0 1 (blank) E1EDK14:ORGID(blank) SAP_126 0 0 1 (blank) E1EDK14:

ObjectEventId(blank) User1 0 0 2 (blank) Z1XRV40:ERNAM(blank) SAP_127 0 0 2 (blank) Z1XRV40:

ObjectEventId

Createdby

SAP_Organization (1)

ObjectEventId

SAP_LineItem (1)

Qualifier

Organization

ObjectEventId

SAP_Organization

Createdby

SAP_Organization (1)

ObjectEventId

SAP_LineItem (1)

Order number

Customer number

SAP LineItem (2)

SAP_Sales Order

ObjectEventId

Parent business object




Figure 12. Hierarchical business object SAP sales order (IDoc)


Flat structure conversion to a business objectOnce the flat structure has been repopulated with new business object data,Y_XR_RFC_DO_VERB_NEXTGEN returns the business object data to the calling connector.Remember that the connector is single-threaded; therefore, it passes only onebusiness object at a time. The connector must now convert the business object datafrom the flat structure into a business object. When processing data in a flatstructure into a business object, the connector must:1. Initialize the original business object.2. Transfer the business object data from the flat structure to the business object.3. Deliver the business object to the connector infrastructure.

Business object initializationThe connector initializes the original business object that it received from theintegration broker before it populates it. When initializing the business object, theconnector sets every attribute in the top-level business object to null. For objecttype attributes, this action recursively deletes every contained business object,leaving only the top-level business object.

How the connector rebuilds a business objectAfter the connector initializes the original business object, what remains is thetop-level business object containing the business object name and business objectverb, but no attribute value data. The attribute value data must be transferred fromthe flat structure from the ABAP handler. The logic for transferring the returneddata is simple, but the data must be transferred in the exact order that theconnector expects it.

The connector matches the application-specific information in the returned data toan attribute’s application-specific information in the business object definition. Theconnector attempts to set every attribute that is in the returned business objectdata. If any attribute cannot be set, the connector returns FAIL to the connectorinfrastructure.

In order for the returned data transfer to execute successfully, the connectorexpects the following to be true of the returned data:v It contains only simple attributes, where one row equals one attribute.v Attributes must exist in the WebSphere business object definition.v Attributes must be ordered as they are in the WebSphere business object

definition (depth and then breadth).v An attribute’s application-specific information links its object’s

application-specific information with another value that uniquely identifies theattribute within the business object’s definition.

v Child attributes must occur after their parent object’s attributes (never beforetheir parents and never after their grandparents).

v An attribute must communicate its business object’s number of peers.

When the connector rebuilds the application-specific business object, the connectorloops through the business object twice, beginning with the top-level businessobject.1. In the first pass, it sets all simple attributes.


2. In the second pass, it checks if the flat attribute exists in a child object. If itexists the connector recursively executes the same processing for the childobject.

Attention: If the conversion of a flat structure to a business object fails, theconnector reports a failure to the integration broker. However, the data is alreadyposted in the SAP application and, therefore, cannot be rolled back at this stage.While the rules are simple, implementing a complex, hierarchical business objectwith many attributes can be difficult to manage.

Once the business object is successfully rebuilt with new business object data, theconnector returns it to the integration broker.


Chapter 6. Developing business objects for the ABAPExtension module

v “Background information”v “Developing business objects using dynamic retrieve” on page 62v “Developing business objects using dynamic transaction” on page 65v “Developing business objects using IDocs” on page 70v “Calling the ABAP Extension module and ABAP handler” on page 76

This chapter discusses business object development for the IBM WebSphereBusiness Integration Adapter for mySAP.com (SAP R/3 Version 4.x). It providesbackground information as well as steps for developing business objects and ABAPhandlers. In general, the contents of this chapter should be used as guidelines forbusiness object development. You should be familiar with how the connectorprocesses business objects.


Background informationBusiness object development for the ABAP Extension Module consists of creatingan application-specific business object definition and an associated ABAP handlerfor each verb that you want to support.

To develop an application-specific business object, you must create a businessobject definition that supports your business needs. The IBM WebSphere BusinessIntegration Adapter for mySAP.com (SAP R/3 Version 4.x) includes tools thatfacilitate the process of developing business object definitions in the SAPapplication. Although you can use Business Object Designer or a text editor tocreate business object definitions for the ABAP Extension Module, it isrecommended that you initially use the adapter’s business object developmenttools. These tools use the SAP application’s native definitions as a template.

For each application-specific business object definition that you develop, you mustsupport it by using an adapter-provided ABAP handler or by developing a customABAP handler. The ABAP handler is the mechanism that gets data into and out ofthe SAP application database.

Note: The application-specific business object and the ABAP handler rely on eachother’s consistency to pass data into and out of the SAP application;therefore, if you change the business object definition, then you must changethe ABAP handler to support it.

The adapter’s ABAP handler is implemented as an ABAP function module. ABAPhandlers are one or more function modules that work together to fulfill a businessobject retrieve or request from the business object routerY_XR_RFC_DO_VERB_NEXTGEN. ABAP handlers are responsible for passing businessobject data into and out of the SAP application.


Note: SAP supports many verbs other than those (Create, Retrieve, Update, andDelete) supported by the WebSphere business integration system. You candevelop an ABAP handler to support any verb.

To develop an ABAP handler, you must understand how the connector gets datainto and out of the SAP application and what form that data takes during thisprocess. For a high level description of business object processing, see Chapter 3,“Overview of the ABAP Extension module”, on page 29. For a detailed descriptionof business object processing, see Chapter 5, “Business object processing in theABAP Extension module”, on page 47.

Note: When you develop business objects, you must make sure that the objects areadded to the connector’s YXROBJ table in the SAP R/3 application. If theyare not, you will not be able to access the for customization (for example,setting up the object for event distribution).

SAP native APIsAdapter-provided ABAP handlers use SAP native APIs, which enable ABAPhandlers to pass data into and out of the SAP application. The WebSphere businessintegration system has implemented the following native APIs:v “ABAP SQL”v “Call transaction”v “Batch data communication (BDC)” on page 61

ABAP SQLABAP SQL is SAP’s proprietary version of SQL. It is database and platformindependent, so that whatever SQL code you write, you can run it on any databaseand platform combination that SAP supports. ABAP SQL is similar in syntax toother versions of SQL and supports all of the basic database table commands suchas update, insert, modify, select and delete. For a complete description of ABAPSQL, its use, syntax and functionality, see your SAP documentation.

Using ABAP SQL, an ABAP handler can modify SAP database tables with businessobject data for create, update and delete operations and similarly can use thebusiness object data in the “where” clause of an ABAP select statement as the keys.

Note: The WebSphere business integration system never uses ABAP SQL tomodify SAP tables, because this may corrupt the integrity of the database.The connector uses ABAP SQL only to retrieve data and to modifyadapter-delivered database tables.

Call transactionCall transaction is SAP-provided functionality for entering data into an SAPsystem. Call Transaction guarantees that the data adheres to SAP’s data model byusing the same screens an online user sees in a transaction. This process iscommonly referred to as screen scraping. To use Call Transaction, specify thefollowing types of instructions:v Initiation—transaction to callv Navigation—sequence of screens to processv Mapping—input data that should go into each field on a screen

Initiation is passed as a single value parameter in the Call Transaction call.Navigation and Mapping instructions are passed in together in a table with a


specific format; this format is usable for invoking Call Transaction for any SAPtransaction. In this format, these instructions are referred to as the BDC data, BDCtable, or BDC session.

Batch data communication (BDC)Batch data communication (BDC) is an instruction set that SAP can follow toexecute a transaction without user intervention. The instructions dictate thesequence in which a transaction’s screens are processed and which fields should bepopulated with data on which screens. All of the elements of an SAP transactionthat are exposed to an online user have identifications that can be used in a BDC.The elements are as follows:v Screens—identified by a program name and screen number.v Input fields—typically identified by the database table and field name to which

it refers.v Commands in the transaction—commands such as save, new items, details, and

exit (identified by a one- to eight-character code)

To get a screen’s BDC identity, place the cursor in any field on the screen. Press F1for help and then F9 for technical information. The program name and screennumber are listed under Screen Data.

To get an input field’s BDC identity, place the cursor in each field on the screen inwhich you want to input data. Press F1 for help and then F9 for technicalinformation. If there is a box named Field Description for Batch Input, then use theinformation in the Screen Field field. If this box does not exist, from the Field Databox, concatenate the Table Name and Field Name together with a hyphen.

To get a command’s BDC identity, highlight the command in the menu and pressF1 for help. Use the value in the Function field.

IBM WebSphere function module interfaceEvery ABAP handler must implement the same function module interface. Thefunction module interface guarantees that the business object routerY_XR_RFC_DO_VERB_NEXTGEN can pass business object data to and from ABAPhandlers. The interface is:*"*"Local interface:*" IMPORTING*" VALUE(PROC_FUNC_1) LIKE RS38L-NAME OPTIONAL*" VALUE(PROC_FUNC_2) LIKE RS38L-NAME OPTIONAL*" VALUE(OBJECT_NAME) LIKE YXR_LOG_H-OBJ_NAME OPTIONAL*" VALUE(OBJECT_VERB) LIKE YXR_CHANGE-OBJ_VERB OPTIONAL*" VALUE(ARCHIVE) OPTIONAL*" VALUE(TEXT) LIKE T100-TEXT OPTIONAL*" EXPORTING*" VALUE(RETURN_TEXT) LIKE YXR_EVENT-OBJ_KEY*" VALUE(RFCRC) LIKE YXR_RFCRC-YXR_RFCRC*" TABLES*" RFC_STRUCTURE STRUCTURE YXR_RFC_S*" EXCEPTIONS*" NOT_FOUND*" ERROR_PROCESSING

In the importing section of the interface, you can communicate values such as theABAP handler name, business object name, and business object.

Chapter 6. Developing business objects for the ABAP Extension module 61

The exporting section of the interface is used to communicate the results of theABAP handler processing. The return code RFCRC parameter is a single field usedto determine the code a connector returns. The possible values are:

RC = 0 (success, VALCHANGE)

RC = 1 (failure, FAIL)

The RETURN_TEXT parameter is a 120-character free text field that is written to bythe connector or logged as an error message in the return status descriptor. If theABAP handler does not provide a value for this parameter, thenY_XR_RFC_DO_VERB_NEXTGEN supplies default text depending on the return code.

Note: The exceptions section of the interface defines two exceptions. It isrecommended that you use the exporting parameters instead.

IBM WebSphere ABAP handler APIsThe adapter includes several APIs that facilitate the development of ABAPhandlers that support WebSphere business objects for SAP. These APIs weredeveloped as “generic” ABAP handlers, because they only require meta-data tosupport additional business objects of any type. The adapter includes the followingABAP handler APIs:v Dynamic Retrieve—Y_XR_DYNAMIC_RETRIEVEv Dynamic Transaction—Y_XR_DYNAMIC_TRANSACTIONv IDoc Handler—Y_XR_IDOC_HANDLER

The adapter includes a set of tools that support these APIs. The tools can be foundin IBM WebSphere InterChange Server Connector Tool (transaction YXR1). Thefollowing sections discuss the adapter-provided APIs and gives you steps on howto use the IBM WebSphere InterChange Server Connector Tool (transaction YXR1)to develop business objects for them.

Developing business objects using dynamic retrieveThe Dynamic Retrieve function module is a mapping tool and dynamic SQLstatement generator. This function module uses the meta-data stored in theYXR_DISPLY table to generate SQL select statements at runtime. Dynamic Retrievetakes the resulting fields of these SQL statements and fills the attributes of theWebSphere business object. When the Dynamic Retrieve function module is called,the following steps are performed:1. All entries are retrieved from YXR_DISPLY, where,

object name = objectName

2. For each new table specified in YXR_DISPLY, a SQL where clause is generatedbased on the fields marked as key. The corresponding Field Name in businessobject attributes is used to populate the value in the where clause. If a defaultvalue is specified in YXR_DISPLY, this default is used.

3. The SQL select statement is executed. The resulting fields are copied into thecorresponding Field Name in business object attributes.

Note: Before you can generate a business object definition, you must create aWebSphere business object using the IBM WebSphere InterChange ServerConnector Tools Window (YXR1).


Tipsv Entries in YXR_DISPLY must be grouped by table name. All relevant key values

must appear first.v If data from a specific table is optional, all non-key fields for that table must be

marked as optional.v The default operand for the where clause is equals. Other operands can be

specified in the Rel column. Use the F4 drop-down list for possible operands.v System fields such as system language (LANGU), current date (DATUM) or current

time (UZEIT), can be specified in the System column. Press the F4 key for moreoptions. This applies only to key fields.

v If you want to do an existence check, specify at least one non-key field even ifyou are only interested in the success or failure of the select statement.

v Data read from one table can be used in the where clause of a later table.

Table 11 shows table entries for the Dynamic Retrieve table.

Table 11. Table Entries for Dynamic Retrieve

Field Name Description When Used Technical Name

Object Name WebSphere businessobject name

Always OBJ_NAME

Counter Counter Always POSNRTable Table to read Always TABNAMEField Name Field name in table Always NAME_FELDKey Specifies a key field of a

tableFirst field of each table.Used to build the whereclause of the selectstatement.

KEYFLAG

Optional Free text description ofscreen, field or command

Used for non-key fields. Ifall non-key fields aremarked as optional and ifthe select statement fails,the results will be awarning, not an error.

OPTIONAL

Rel Operand (relation) Used to determinerelationships in whereclause. By default, theoperands in the whereclause are ’equal’ but canbe changed by entering avalue in this field.

YXR_OPERND

Field Name in businessobject

Attribute in theWebSphere businessobject to supply the inputvalue

v Key fields: to build thewhere clause.

v Non-key fields: toreturn database fieldsto attributes in thebusiness object

SOURCEFLD

Default Value A static default value touse if no entry isprovided in theWebSphere businessobject

Key fields DEFLT_VAL

SY Field A dynamic system field tobe used as a default value(for example: DATUM)

Key fields SYFIELD


Table 11. Table Entries for Dynamic Retrieve (continued)


Length Character length from the0 or offset position of theattribute value thatshould be used whenbuilding the where clause.

Key fields. Only relevantwhen using an attributethat contains a compositevalue.

LENGTH

Offset Character offset from the0 position of the attributevalue that should be usedwhen building the whereclause.

Key fields. Only relevantwhen using an attributethat contains a compositevalue.

YXR_OFFSET

To access adapter’s table-driven connector table for Display:1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).2. From the Customizing menu, click Dynamic Read, and then click Modify

Retrieve.

Figure 13 shows the Dynamic Retrieve table with a nested SQL select statement.Results from a previous select statement are used to build the key on subsequentselect statements.

Using the Counter column as a line number for discussion, you can step throughthe SAP_FuncLocation example of a functional location object in the DynamicRetrieve table.

100 Table IFLOT has only one key field. The value in the CustomerId attributesin the where clause. If the value in CustomerId is 4711, then the whereclause is:

where TPLNR = ’4711’

310 This is the first non-key field. At this point, the actual select statement isexecuted. The select statement is:

Select * from IFLOT where TPLNR = ’4711’

Figure 13. Dynamic retrieve with a nested SQL select statement


The resulting value of ILOAN is then copied into the ObjectLocationattribute, which is ’5678’ for this example.

320 Since this is a new table and a key field, the where clause is built again.Once again the where clause is:

where TPLNR = ’4711’

330 Another key for table TFLOTX. The where clause is extended with:

and SPRAS = ’E’

If the value of Language2 is CxIgnore, then the E is taken from the DefaultValue field.

340 This is the first non-key field for table IFLOTX. The select statement isexecuted. The statement is:

Select * from IFLOTX where TPLNR = ’4711’ and SPRAS = ’E’

The resulting value of PLTXT is copied into the CustomerName attribute. Ifthe select statement fails, a warning is issued, because all the non-keyfields for table IFLOTX are marked as optional.

350 The value of KZLTX from the previous select statement is copied into theTextIndicator attribute.

360 Since this is a new table and key field, the where clause is built again. Thevalue of the where clause is taken from the attribute ObjectLocation, whichwas filled by an earlier select statement. If ’5678’ is the value in theattribute ObjectLocation, the where clause is:

where ILOAN = ’5678’

370 This is the first non-key field. The select statement is executed. Thestatement is:

Select * from ILOA where ILOAN = ’5678’

The resulting value of ADRNR will be copied into the AddressId attribute.

This completes the building of the SAP_FuncLocation function module forDynamic Retrieve support.

Developing business objects using dynamic transactionThe Dynamic Transaction function module is a mapping tool and dynamic codegenerator. It uses SAP’s Call Transaction API to get data into an SAP application.Also, it stores static definitions of Batch Data Communication (BDC) sessions byobject/verb combinations. Before the BDC data is passed to a Call Transaction, thebusiness object attribute values are mapped into the BDC session. At thecompletion of the call transaction, the resulting key value is set in the appropriatevalue of the business object, and all messages from the call transaction are logged.

Note: If the Call Transaction fails, the connector does not store a BDC session inSAP for reprocessing. Obsolete versions of the connector agent did store aBDC session; however, using the stored session led to inconsistencies incross-referencing and request processing.

The Dynamic Transaction function module builds a BDC session to do a calltransaction by combining the BDC defined in the Dynamic Transaction table,YXR_CHANGE, and the values from the incoming business object. When the DynamicTransaction function module is called, the following steps are performed:


1. All entries are retrieved from YXR_CHANGE, where:object name = objectName and verb = objectVerb

2. Field input values are mapped from the business object into the BDC sessionbased on the attribute name.

3. BDC sessions are processed using Call Transaction.4. Key values are captured, Call Transaction messages are logged, and the key is

set in the business object.

Note: Before you can generate a business object definition, you must create aWebSphere business object using the IBM WebSphere InterChange ServerConnector Tools Window (YXR1).

Tipsv Data entered on an initial screen may default for all line items and reduce

required line item input.v Line item overview screens may provide enough input rather than drilling down

to a details screen which may require additional input.v Confirmation messages usually do not need to be answered in BDC; for

example, Are you sure you want to save?

v The counter renumbers in increments of 10, for each object and verbcombination, every time you enter and exit the table maintenance in changemode.

v During execution, the Call Transaction uses the user’s settings for dateformatting. Be sure the connector user is set up to use a variation of YYYY-MM-DDdate format. This is the standard date format used by the WebSphere businessintegration system. Similarly, change your own user settings if you want toreprocess the business objects by stepping through the transaction.

Composing a BDC session for a business objectComposing a BDC session requires an understanding of an SAP transaction’sdesign. An SAP transaction allows the same data to be input in various sequencesand on different screens. Typically each sequence or flow exposes additionalfunctionality. As a result, certain data validation and input field requirements occuron some screens, but not on others. The challenge is to find the sequence that doeswhat you need with the least amount of effort. A simple BDC session is morestable than a complex BDC session.

An SAP transaction may behave differently when accessed using the CallTransaction method in a background process instead of executing online. Forexample, different or additional screens may appear or input fields may reside ondifferent screens than your online investigation revealed. The discrepancy occursbecause the transaction’s controlling code may dictate different behavior whenexecuted in the background instead of executing online. As a result, your onlinetest may work when reprocessing a failed object event as you step through thetransaction, however, the connector consistently fails when processing the sameobject. If this occurs, modify the BDC so that it processes in the background. If youmodify the BDC, you may encounter cases where the BDC processes in thebackground, but now fails when processed online.

The BDC you define in the Dynamic Transaction table is static. It cannot reactduring the transaction if certain input data causes other screens to pop-up or otherfields become mandatory during runtime. Proper investigation of a transaction’s


configuration is important to be able to predict consistent behavior. Experimentseveral times with the transaction; repeated behavior can become your guideline.

Once you have determined the screen flow, follow the steps below and documentthe information you gather in a spreadsheet.1. Go to the transaction that supports your object and identify the transaction

code.2. Identify the BDC elements for the screen and input fields you require.3. Identify the menu command you need to continue processing to the next

screen.4. Repeat steps 2 and 3 for each screen required.5. Conclude by noting the command to save the transaction.

Table 12 describes the column names for Dynamic Transaction table YXR_CHANGE.

Table 12. YXR_CHANGE Table Entries for Dynamic Retrieve


Object Name WebSphere businessobject name

Always OBJ_NAME

Verb Verb (Create, Update,Delete, or Retrieve)

Always OBJ_VERB

Counter Counter Always POSNRProgram Program associated with

a screenBDC screen identification PROG_NAME

ScNo Screen number associatedwith a screen

BDC screen identification DYNPRO

Start Specifies a new screen BDC screen identification DYNBEGINBDC field name BDC input field name BDC input fields FNAMDefault Value A static default value to

use if no entry isprovided in theWebSphere businessobject, or if usingBDC_OKCODE, becauseit is the command value

A value might not alwaysbe passed in and it ismandatory for thetransaction

DEFLT_VAL

SY Field A dynamic system field tobe used as a default value(for example: DATUM)

A value is not passed inor should be determinedby SAP system fields

SYFIELD

Return A numeric, 1-4, thatidentifies which systemmessage field returns thekey value at transactioncompletion (sy-msgv#)

A business object keyattribute that shouldreceive the key value

RETURNFLD

Field Name in businessobject

Attribute in theWebSphere businessobject to supply the inputvalue

BDC input fields SOURCEFLD

Length Character length from thezero position of theattribute value thatshould be used for input

Only relevant when usingan attribute that containsa composite value

LENGTH

To define or modify a business object’s meta-data (transferring information toYXR_CHANGE):


1. Go to the IBM WebSphere InterChange Server Connector Tools window(transaction YXR1).

2. From the Customizing menu, click Call Transaction, and click Modify Create,Update.

Defining the meta-data for the business object is simple. For each screen, the firstentry identifies the screen, the following entries identify the input fields, and thelast entry must be a command. This grouping repeats for each screen.

Figure 14 shows the Dynamic Transaction table for an SAP CustomerMasterbusiness object to create a customer (transaction XD01).

Using the Counter column as a line number for discussion, step through the SAPCustomerMaster example.

100 Begin with screen number 100 of program SAPMF02D. This is a newscreen, the first, so it is flagged in the Start column.

110 On screen 110, use the value from the Customer_account_groupattribute in the business object, and add it to the BDC field namecolumn (the value is RF02D-KT0KD). Specify the default value as0001. If the Customer_account_group attribute contains CxIgnore,then the BDC field name column receives the default value 0001

120 The Customer_Account_Number attribute is the key value, so it is

Figure 14. Dynamic transaction for SAP CustomerMaster business object


not set during the Call Transaction. SAP assigns the key valueinternally and makes it available only after the transaction issuccessfully posted. For this reason, leave the BDC field namecolumn blank, but include an entry in the table because theCustomer_Account_Number attribute must be set with this keyvalue when it is returned at the conclusion of the Call Transaction.Also enter the word RETURN in the Program column forCustomerNumber.

Depending on the transaction, SAP returns the key value in one offour possible fields: SY-MSGV1, SY-MSGV2, SY-MSGV3 or SY-MSGV4. Tospecify that you want the return value set in a particular attribute,enter a number, 1-4, in the Return column. This numbercorresponds to the SY-MSGV# field containing the key value. Forexample, Figure 14 illustrates a 1 in the Return column, whichindicates that SY-MSGV1 contains the Customer Number.

130 You are finished entering the necessary values for the first screen,so enter a command, /00, in the Default Value column to simulatepressing the Enter key. This takes you to the next transactionscreen. Commands are entered in the screen input field,BDC_OKCODE, which is where you enter in a transaction code.

140 At this point, you are at the next transaction screen. Enter theaddress information. Since it is a new screen, flag it in the Startcolumn. In this example, the second screen is associated with thesame program as the initial screen, and only the screen numberchanged from 100 to 110. This is not always the case.

150 -210 use the values from the Name_1, Sort_field, City,P_0_Box_postal_code, Country_key, Language_keys, andPost_office_box attributes in the business object, and addcorresponding values to the BDC field name column.

220 Similar to line 130, processing for this screen is complete. However,rather than simply simulating the Enter key, enter the commandvalue UPDA to save the transaction. This takes you to the nexttransaction screen.

230 At this point, you are at the third transaction screen, so flag it inthe Start column. Because your business object does not requiredata from this screen, you will complete processing for this screenin the next line.

240 Similar to line 130, processing for this screen is complete. Enter thecommand value /00 to simulate pressing the Enter key. This takesyou to the final transaction screen.

250 At this point, you are at the final transaction screen. Flag it in theStart column.

260 Similar to lines 150-210. Use the value from the business objectattribute, Transport_zone_to_which_or_from_which_the_goods_are_delivered, and add its corresponding value (KNA1-LZONE) tothe BDC field name column.

270 Similar to line 220, processing for this screen is complete and thetransaction is complete, so enter the command value to save, UPDA.This is the last action the Call Transaction API receives.

280 The final entry for any business object is always the specification of


the transaction code. The keyword TCODE goes in the Programcolumn and the transaction code goes in the BDC field namecolumn.

This completes the definition of the BDC Session for the SAP4_CustomerMasterbusiness object.

If a Call Transaction returns an error message when it fails, you could have one ofthe common errors described below.v The SAP application has called a screen that the BDC did not expect, so the SAP

application returns the message, No input available for program XX and screenYY. If this occurs, add the appropriate entries to the Dynamic Transaction table tohandle the input screen for program XX and screen YY.

v The SAP application is instructed by the BDC to set a field that does not exist.Most likely, the SAP application executed its own instruction that you did notexplicitly set. As a result, you are on a different screen than you intended. If thisoccurs, repeat the instruction and add only the piece that sends you to theappropriate screen.

Developing business objects using IDocsWebSphere business objects for the ABAP Extension Module can be defined in SAPas an IDoc. IDocs are part of SAP’s EDI solution known as ALE (Application LinkEnabling). Their definitions are stored in SAP’s BOR (Business Object Repository)and can be accessed globally within an SAP system. The IBM WebSphere BusinessIntegration Adapter for mySAP.com leverages the definition part of ALE tointerpret and parse WebSphere business objects in the SAP application inpreparation for use with an SAP native API. The adapter provides an IDoc handlerthat supports business objects developed using IDocs.

IDoc handler is made up of two function modules. Other ABAP handlers such asDynamic Retrieve and Dynamic Transaction are only a single function module.

Y_XR_DO_VERB_NEXTGEN passes business object data to IDoc handler,Y_XR_IDOC_HANDLER. Based on the application-specific information,Y_XR_IDOC_HANDLER reformats the business object data into the structure of the IDocspecified by the application-specific information. After reformatting, the businessobject data is passed to an object-specific IDoc handler (based on the object/verbcombination of the business object) that handles the integration with an SAP nativeAPI. Once the object-specific IDoc handler finishes processing the business objectdata, it returns the business object data in IDoc format to Y_XR_IDOC_HANDLER. Thebusiness object data is now converted back to its original format and returned toY_XR_DO_VERB_NEXTGEN.

Figure 15 illustrates the basic architecture of an IDoc handler.


To use the adapter-provided IDoc handler, you must have an IDoc defined in theSAP application. Either SAP-delivered or customer-built IDocs can be used.Because an IDoc definition must mirror the definition of the WebSphere businessobject for SAP, the adapter provides a tool in IBM WebSphere InterChange ServerConnector Tool (transaction YXR1) that you can use to generate the WebSpherebusiness object definition based on the IDoc.

Before you can generate a business object definition, you must have alreadycreated a WebSphere business object in the SAP application. To create a businessobject definition based on an IDoc:1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).2. From the Customizing menu, click Maintain Objects.3. Create the new object name.

For more information on how the application-specific information is used for theverb functions, see “Business object data routing to ABAP handlers” on page 51.

After defining the IDoc, create a function module for each verb the business objectmust support. Each function should have the following interface to ensure thatY_XR_IDOC_HANDLER can call it:*" IMPORTING*" VALUE(OBJECT_KEY_IN) LIKE YXR_EVENT-OBJ_KEY OPTIONAL*" VALUE(INPUT_METHOD) LIKE BDWFAP_PAR-INPUTMETHD*" OPTIONAL*" VALUE(LOG_NUMBER) LIKE YXR_LOG_H-LOG_NR OPTIONAL*" EXPORTING*" VALUE(OBJECT_KEY_OUT) LIKE YXR_EVENT-OBJ_KEY*" VALUE(RETURN_CODE) LIKE YXR_RFCRC-YXR_RFCRC*" VALUE(RETURN_TEXT) LIKE YXR_EVENT-OBJ_KEY*" TABLES*" IDOC_DATA STRUCTURE EDIDD

IDoc handlers and create, update, and delete verbsIDoc handlers that support Create, Update and Delete operations receive businessobject data formatted as an IDoc. The role of these operations is to integrate thebusiness object data with SAP’s Call Transaction API and generate an object key.Only the object key is passed back to Y_XR_IDOC_HANDLER, not the business objectdata. Y_XR_IDOC_HANDLER stores the business object data in memory and inserts the

Business object router:Y_XR_RFC_DO_VERB_NEXTGE

IDoc handler:object specific IDoc

IDoc handler:Y_XR_IDOC_HANDLER

IDoc handler architecture

Figure 15. IDoc handler architecture


object key into the first attribute marked isKey in the parent business object. Then,Y_XR_IDOC_HANDLER passes the business object data back to the connector.

Note: When InterChange Server (ICS) is the integration broker, it is critical tomaintain the business object data because the mapping infrastructurerequires the preservation of the ObjectEventId for dynamiccross-referencing.

The sample code below represents the following flow:1. Initializes global data.2. Deconstructs the IDoc into working tables.

v Initializes the target structure with ’/’ (CxIgnore) because not all objects aresent into the SAP application. Uses the form in YXRIFRM0.

v Uses the forms in YXRIFRM0 to transfer data from the IDoc into internal tablesfor consistent behavior across objects.

3. Builds the BDC. Uses the forms in YXRIFRM0 to transfer data from the internaltables into the BDC table for consistent behavior across objects.

4. Creates a Call Transaction.5. Captures the object key.

The following sample code supports SAP Sales Quote Create:*- Initialize working variables and internal tables

PERFORM INITIALIZE_IN.

*- I01(MF): Begin IDoc interpretationPERFORM LOG_UPDATE(SAPLYXR1) USING C_INFORMATION_LOG TEXT-I01

SPACE SPACE SPACE.

*- Interpret IDoc data structureIF NOT IDOC_DATA[] IS INITIAL.

*- Move IDoc to internal tablesPERFORM INTERPRET_IDOC.

*- Check some of the input fieldsPERFORM CHECK_INPUT.

*- If key values were missing, exit functionIF RETURN_CODE NE 0.

EXIT.ENDIF.

*- E01(MF): No Idoc data lines sent for processing.ELSE.

RETURN_CODE = 2.RETURN_TEXT = TEXT-E01.EXIT.

ENDIF.

*- Build the BDC session for transaction VA21.PERFORM BUILD_BDC_VA21.

*- Call TransactionPERFORM LOG_UPDATE(SAPLYXR1) USING C_INFORMATION_LOG TEXT-I02

’VA21’ C_BLANK C_BLANK.

CALL TRANSACTION ’VA21’ USING BDCDATAMODE INPUT_METHOD

UPDATE ’S’


MESSAGES INTO BDC_MESSAGES.

*- Capture return code and object key from transactionPERFORM PREPARE_RETURNED_MESSAGE.

ENDFUNCTION.

The Create logic has two main functions:v Translates the IDoc Data into manageable data structuresv Executes a Call Transaction

Translating IDOC structureThe first part of the Create logic is the task of translating data in the IDoc structureinto working data structures. To do this, you need to create code similar to thefollowing:loop at idoc_data.

case idoc_data-segnam.when ’ZSQVBAK’. " Header Data

move idoc_data-sdata to zsqvbak.

when ’ZSQVBUK’. " Status Segmentmove idoc_data-sdata to zsqvbuk.

when ’ZSQVBP0’. " Partner Header Levelmove idoc_data-sdata to zsqvbp0.

when ’ZSQVBAP’. " Item Detailmove idoc_data-sdata to zsqvbap.

when ’ZSQVBA2’. " Item Detail Part 2move idoc_data-sdata to zsqvba2.

when ’ZSQVBUP’. " Item Statusmove idoc_data-sdata to zsqvbup.

when ’ZSQVBKD’. " Commerical datamove idoc_data-sdata to zsqvbkd.

when ’ZSQKONV’. " Conditionmove idoc_data-sdata to zsqkonv.

when ’ZSQVBPA’. " Partner Item Levelmove idoc_data-sdata to zsqvbpa.

endcase.

endloop.

IDoc handlers and the retrieve verbObject-specific IDoc handlers that support the Retrieve verb do not receivebusiness object data from the initial IDoc handler. Y_XR_IDOC_HANDLER passes thevalue of the first attribute marked isKey in the business object data using theparameter OBJECT_KEY_IN. It is the IDoc handlers responsibility to use this key toretrieve all information relevant to this instance of the object using ABAP SQL andformat that data in the appropriate IDoc structure.

The following code supports the Sales Quote example. The Sales Quote object mustretrieve data from tables VBAK, VBUK, VBPO, VBAP, VBUP, VBKD, KNOV, and VBPA. Thetables follow the hierarchy and cardinality of IDoc type ZSLSQUOT. The code doesthe following:


1. Initializes global data.2. Returns business object data from the SAP application database.3. Builds an IDoc from the returned data and returns that data to

Y_XR_IDOC_HANDLER.

The code for IDoc type ZSLSQUOT is:*- Clear the interface structures.

clear: g_text, object_key_out, return_code, return_text, idoc_data.refresh: idoc_data.

* If no key value is specified, log it as an error and exit.if object_key_in is initial or

object_key_in = c_cxignore_const.perform log_update(saplyxr1) using c_error_log text-e02

space space space.return_code = 1.return_text = text-e02.exit.

endif.

perform initialize_global_structures.

perform fill_internal_tables.if not return_code is initial.

exit.endif.

* Build Idoc segments from internal tablesperform fill_idoc_inttab.

return_code = 0.return_text = text-s01.

perform log_update(saplyxr1) using c_information_log text-s01space space space.

endfunction.

The two most important parameters are OBJECT_KEY_IN for the inbound key andIDOC_DATA for the outbound data. Note that OBJECT_KEY_IN may even be a multiplekey depending on the conventions you have defined.

The VBAK table drives the selection criteria for the child tables, so each table isloaded into working tables. Using the VBAK table, you can retrieve the child tableswith additional keys. So, for the Sales Quote example, the code is as follows:form fill_internal_tables.

* Get information from VBAK, VBUK, VBAP, VBKD, KONV, VBPA

select single * from vbakwhere vbeln = object_key_in.

if sy-subrc <> 0.perform log_update(saplyxr1) using c_error_log text-e01

object_key_out c_blank c_blank.return_code = ’1’.g_text = text-e01.replace ’&’ with order_number into g_text.return_text = g_text.

exit.endif.

select single * from vbuk


where vbeln = vbak-vbeln.

select * from vbap into table t_vbapwhere vbeln = vbak-vbeln.

* Continue for other tables

The following code is used to copy the requested data from the applicationdatabase into internal tables and working variables. Then it creates segments thatdirectly correspond to the WebSphere business object definition and puts it into theSAP segment structure.

In some cases for close matches on fields between the IDoc type and the workingstructure, you can do an ABAP move-corresponding command. In other cases, it ismore preferable to do manual moves from the working table to the IDoc type tablebecause of the relatively few fields to move in comparison to the overall number offields in the structure. Simply, it is used to transfer data from the working datastructures into the IDoc structures and then in the flat data field.

The code is:form fill_idoc_inttab.

perform fill_zsqvbak." Fill the Sales Quote Headerperform fill_zsqvbuk." Fill the Sales Quote Statusperform fill_zsqvbap." Fill Sales Quote Lines

endform." FILL_IDOC_INTTAB

*-- fill the Sales Quote Headerform fill_zsqvbak.

clear idoc_data.clear zsqvbak.idoc_data-segnam = ’ZSQVBAK’.

move-corresponding vbak to zsqvbak.move zsqvbak to idoc_data-sdata.append idoc_data.

endform." FILL_ZSQVBAK

*-- fill the Sales Quote Header Statusform fill_zsqvbuk.

clear idoc_data.clear zsqvbuk.idoc_data-segnam = ’ZSQVBUK’.

move-corresponding vbuk to zsqvbuk.move zsqvbuk to idoc_data-sdata.append idoc_data.

endform." FILL_ZSQVBAK

*-- fill the Sales Quote Line and the Line Child segmentsform fill_zsqvbap.

loop at t_vbap.clear idoc_data.clear zsqvbap.idoc_data-segnam = ’ZSQVBAP’.

move-corresponding t_vbap to zsqvbap.move zsqvbap to idoc_data-sdata.


append idoc_data.

perform fill_zsqvba2.perform fill_zsqvbup.perform fill_zsqvbkd.perform fill_zsqkonv.perform fill_zsqvbpa.

endloop.

endform.

*-- fill second part of vbapform fill_zsqvba2." etc.

Calling the ABAP Extension module and ABAP handlerThe connector uses the value of the verb application-specific information in abusiness object to call the appropriate ABAP handler in the ABAP ExtensionModule. To call the appropriate ABAP handler in the ABAP Extension Module,you must specify the classname for the ABAP Extension Module and the ABAPhandler function module use by the business object. For example, the verbapplication-specific information for the Dynamic Retrieve ABAP handler is:AppSpecificInfo = sap.sapextensionmodule.VSapBOHandler,:Y_XR_DYNAMIC_RETRIEVE

Note: You must uses a comma delimiter between the connector module(classname) and ABAP handler.

For more information on business object processing for the ABAP ExtensionModule, see “Business object processing” on page 31.


Chapter 7. Developing event detection for the ABAPExtension module

v “Designing an event detection mechanism”v “Implementing an event detection mechanism” on page 80

Event detection is part of the event triggering process in the ABAP component ofthe ABAP Extension Module. Every event detection mechanism must call an eventtrigger, which takes the detected event and adds it to an event table. For moreinformation on triggering events, see “Event triggering” on page 37.


Designing an event detection mechanismYou can use many different mechanisms to detect events in the SAP application.An event detection mechanism should have the ability to make a function modulecall. The three event detection mechanisms that the IBM WebSphere BusinessIntegration Adapter for mySAP.com (SAP R/3 Version 4.x) has implemented are:v Code Enhancement—implemented for a business process (normally a single SAP

transaction) by inserting event detection code at an appropriate point within theSAP transaction

v Batch Program—involves developing an ABAP program containing the criteriafor detecting an event

v Business Workflow—uses SAP’s own object-oriented event detection capabilities

It is important that you determine the appropriate event detection mechanism toimplement for each business object that you develop, because some may not beavailable for a particular business process. Technical and functional knowledge of aparticular business process is necessary for each transaction for which you want toimplement event detection.

Review the following implementation considerations when determining whichevent detection mechanism to implement for your business process.

Availability Which event detection mechanisms are availablefor this business process? This should be one of thefirst questions that you consider. CodeEnhancement and Batch Program have highavailability, whereas Business Workflow does not.

Real-time integration Do events need to be detected synchronously? Doyou need to detect a large number of events at onetime? All mechanisms except Batch Program aresuitable for real-time integration.

Reliability Are all data changes for this business processdetected when generating an event? CodeEnhancement and Batch Program, provide the bestcontrol of capturing all events of an object.Business Workflow provides limited reliability. For


example, Business Workflow does not detect anaddress change during a Vendor transactionupdate.

Flexibility Do certain criteria need to be evaluated before anevent is triggered? Does an event need to bedetected at a certain point in the transaction? CodeEnhancement is the most flexible, because you caninsert code at a specific point before event data iscommitted. Batch Program is moderately flexible,while Business Workflow has very little flexibilityin its implementation.

Upgrade dependency Does an upgrade to the SAP application change theway an event is detected for this business process?Typically, this is not known, but Business Workflowis affected by application changes the most becauseit is under SAP’s control.

Difficulty Is time or level of difficulty an issue? Eachmechanism has its own level of implementationdifficulty. In general, Batch Program is the easiest.Code Enhancement and Business Workflow aremoderately more difficult.

At this point, you should have an idea of the event detection mechanisms that youneed to consider. Use Table 13 as a general guideline in determining whichmechanism can be used for each business process you need to support.

Table 13. Event Detection Mechanism Decision Table

CodeEnhancement

Batch Program BusinessWorkflow

Availability High High LowReal-time integration Yes No YesReliability High High LowFlexibility High Medium LowUpgrade dependency Low Low MediumDifficulty Medium Low Medium

A final consideration to note is the development methodology of your site. Perhapsevent detection using only Business Workflow is the preferred method and CodeEnhancement cannot be used at all.

Using Code Enhancement is the recommended approach for event detectionbecause it is reliable, highly flexible, synchronous, and has high availability. Incontrast, the Business Workflow mechanism is not generally available for allbusiness processes. Batch Program is typically used when real-time integration isnot desired.

Each event detection mechanism has advantages and disadvantages for detectingan event in a business process. The following sections give more detail about eachof the event detection mechanisms, including the main advantages anddisadvantages of each.


Code enhancementCode Enhancement is implemented at specific points in the code of an SAPtransaction. By making use of user exits, you can insert event detection code at themost logical point in a transaction. The event detection code allows for evaluationof criteria to determine whether an event is generated.

The general strategy of this mechanism is to insert your event detection code whenthe data for a transaction is about to be committed to the database.

Advantagesv Has access to SAP transactional information for the event detection processv Allows the insertion of event detection code at an appropriate point of a

transactionv Provides synchronous event detectionv Limits the reliance on SAP functionality, so maintenance and enhancements are

easier

Disadvantagesv User exits may not always be in the appropriate location in the transaction.v SAP modification features may be necessary.

Batch programBatch program is useful when a large number of events of the same type (such ascustomer orders) need to be triggered or a business process requires a largeamount of processing time. This mechanism does not require any modifications toSAP delivered code; however, you need to use (write) an ABAP program thatevaluates criteria for detecting events.

Advantagesv Can be implemented for most business processesv Accurately detects eventsv Is easy to implementv Can be scheduled to run at a specific time if runtime resources are an issue

Disadvantagesv It does not provide synchronous event detection.v SAP transactional information is not available.v State (create, update, or delete) or status changes cannot be detected or may not

be easily detected.v If a background job is created to automate a batch program, an additional task

needs to be maintained and monitored.

Business workflowBusiness workflow is a cross-application tool within the SAP application thatenables you to integrate business tasks between applications. This toolsupplements the existing business functions of the SAP application. The standardfunctions of SAP can be adapted using Business Workflow to meet the specificrequirements of the desired business function. Business Workflow uses theBusiness Object Repository (BOR), which stores the definitions for each SAP objectin the application.

Chapter 7. Developing event detection for the ABAP Extension module 79

Advantagesv Provides synchronous event detectionv Makes use of SAP’s object-oriented business object capability to link the

detection of events to ABAP function modulesv Is easy to implement

Disadvantagesv An SAP object does not exist in the SAP BOR for every business process.v The SAP event (such as created or deleted) may not exist for the SAP object.v It may not detect all changes in a business process.v It does not always provide the flexibility for detecting events at the proper time.v It depends on SAP-provided functionality, which may change between versions

of SAP.

Implementing an event detection mechanismOnce you determine the business process to support (for example, sales quotes orsales orders), and determine the preferred event detection mechanism, implementthe mechanism for your business process.

Note: When implementing an event detection mechanism, it is a good idea tosupport all of the functionality for a business process in one mechanism.This limits the impact in the SAP application and makes event detectioneasier to manage.

The following sections describe the implementation process for the four eventdetection mechanisms implemented by the IBM WebSphere Business IntegrationAdapter for mySAP.com. Whenever applicable, an example is provided along withsample code.

Code enhancementCode enhancement requires encapsulating a portion of ABAP code in a customfunction module. The event detection code is written as a function module toensure that the processing remains separate from the transaction. Any tables orvariables used from the transaction need to be passed to the function module byvalue and not by reference.

To minimize the effects of locking a business object when retrieving an event, thefunction module typically executes in an update-task mode. To avoidinconsistencies, do not use update task if the function module is already beingcalled within a process that is in an update -task mode.

To minimize the impact in the transaction, place the function module withinanother include program. Using an include program allows you to make changesto custom code rather than to SAP code.

The event detection code contains logic that identifies the object for the event. Forexample, the sales order transaction handles many types of orders, but only oneorder type is required. This logic is in the event detection code. The generalstrategy for placing this event detection code is to insert it just before the data iscommitted to the database. The function module containing the event detectioncode is typically created as a part of the function group for the business object.

To implement Code Enhancement for event detection:


v Determine which verbs to support: Create, Update, or Delete. This helps definewhich transactions to investigate.

v Determine the business object key for the transaction. This key must be uniqueto allow the connector to retrieve the business object from the database. Acomposite key may be required.

v Check that an SAP-provided user exit in the transaction has all of theinformation needed to detect an event. For example, a user exit may not be ableto implement a Delete verb because the business object is removed from thedatabase prior to that point.

v If a user exit cannot be used, determine the appropriate location for the eventdetection code, and then add the event detection code using an SAPmodification. Select a location that has access to the business object key andother variables used to make the decision.Research a business process by looking for a “commit work statement” in thecode executed by the transaction for the business process. You can use the ABAPdebugger to investigate the value of different attributes at that point.

v Determine the criteria for detecting an event.v Create the function module containing the event detection code.v Create the include program and then add it to the transaction’s code. Test all of

the scenarios designed to detect an event.

The following steps describe the process of creating an example SAP sales quoteusing the Code Enhancement event detection mechanism. The code that follows itis a result of this process.1. Upon investigation of the SAP sales quote transaction, transaction VA21 is found

to support the desired sales quote creation business process.2. The sales quote number is determined to be the unique key. The Sales quote

number is stored in table/field VBAK-VBELN.3. Transaction VA21 has a user exit in the transaction flow as part of the document

save process (Form Userexit_save_document). At this point in the transaction,the quote number is available when the user exit is executed.

4. The user exit belongs to other business processes, so additional coding isneeded to differentiate a sales quote from other categories of documents.VBAK-VBTYP is available to determine the document category. A sales quote issaved in the SAP database with a document category of B.

5. An include statement is added to the user exit that points to the includeprogram.

6. At this time, the include program and a function module need to be created.

The new function module contains the following code:If VBAK-VBTYP = ‘B’.

C_OBJ_ORDER = ‘SAP_SalesQuote’.TMP_OBJKEY = XVBAK-VBELN.

TMP_EVENT = ‘Create’.TMP_OBJTYPE = Space.

CALL FUNCTION ’Y_XR_ADD_TO_QUEUE’EXPORTING

OBJTYPE = TMP_OBJTYPEOBJNAME = C_OBJ_ORDEROBJKEY = TMP_OBJKEYEVENT = TMP_EVENTGENERIC_RECTYPE = ’’IMPORTINGRECTYPE = TMP_RECTYPE


TABLESEVENT_CONTAINER = TMP_EVENT_CONTAINER

EXCEPTIONSOTHERS = 1.

Endif.

Batch programTo implement batch program as an event detection mechanism, you must write anABAP program that evaluates database information. If the criteria in the ABAPprogram is fulfilled when the program executes, then an event is triggered.

To implement Batch Program for event detection:v Determine which verb to support: Create, Update, or Delete.v Determine the business object key for the transaction. The business object key

must be unique so that the business object can be retrieved from the database. Acomposite key may be required. For example, implementing a batch program forinventory levels of materials at different plants requires the key Material_key +Plant_key.

v Determine the criteria for detecting an event. You should have knowledge of thedatabase tables associated with a business object.

v Create an ABAP program containing the criteria for generating an event.v Determine if a background job is required to automate the batch program. A

background job is useful if there is an impact on system resources, which makesit necessary to run the batch program during off-peak hours.

The following steps describe the process of creating a batch program that detectsevents for all sales quotes created on today’s date. The code that follows it is aresult of this process.1. Create is determined to be the supported verb.2. The quote number is determined to be the unique key used to retrieve the

events.3. The creation date (VBAK-ERDAT) and the document category (VBAK-VBTYP)

need to be checked.

The following sample code supports the SAP Sales Quote as a batch program:REPORT ZSALESORDERBATCH.

tables: vbak.

parameter: d_date like sy-datum default sy-datum.

data: tmp_key like YXR_EVENT-OBJ_KEY,tmp_event_container like swcont occurs 0.

" retrieve all sales quotes for today’s date" sales quotes have vbtyp = Bselect * from vbak where erdat = d_date

and vbtyp = ’B’.

tmp_key = vbak-vbeln.TMP_OBJTYPE = space.

CALL FUNCTION ’Y_XR_ADD_TO_QUEUE’EXPORTING

OBJTYPE = TMP_OBJTYPEOBJNAME = ’SAP_SalesQuote’OBJKEY = tmp_key


EVENT = ’Create’GENERIC_RECTYPE = ’’IMPORTINGRECTYPE = r_rectypeTABLES

EVENT_CONTAINER = tmp_event_container.

write: / vbak-vbeln.endselect.

Business workflowBusiness workflow is a set or sequence of logically related business operations. Theprocessing logic within a workflow detects events. The Business Workflow eventdetection mechanism relies on the SAP Business Object Repository (BOR), whichcontains the directory of objects along with their related attributes, methods, andevents.

To implement business workflow for event detection:v Determine which business object represents the functionality that you need.

Check if the events trigger, start, or end a workflow. You can use the BusinessObject Builder (transaction SWO1) to search for the appropriate business object.

v Create a subtype of this business object. A subtype inherits the properties of thesupertype and can be customized for use.

v Activate the events (such as CREATED, CHANGED, and DELETED) for thebusiness object by customizing the subtype.

The following example of SAP sales quote can be used to implement an eventtrigger using business workflow:1. Search the BOR for the appropriate sales quote business object. A search can be

done using the short description field and the string ’*quot*’. BUS2031(Customer Quotes) is one of the business objects returned.

2. Upon further investigation of BUS2031, it is determined that the key field isCustomerQuotation.SalesDocument (VBAK-VBELN).

3. A subtype for BUS2031 is created using the following entries:Object type—ZMYQUOTEEvent—SAP_SalesQuoteName—SAP Sales QuoteDescription—Example of an SAP Sales Quote SubtypeProgram—ZMYSALESQUOTE

Application—V

4. The event detection mechanism is activated by adding an entry to the EventLinkage table (transaction SWE3). The create event is activated using thefollowing entries:Object type—ZMYQUOTE

Event—SAP_SalesQuote

Receiver FM—Y_XR_ADD_TO_QUEUE_DUMMY

Receiver type FM—Y_XR_ADD_TO_QUEUE_WF

Note: The Receiver and Receiver type function modules (FM) both point toY_XR_ADD_TO_QUEUE. The DUMMY function module is used only becausesometimes the SAP application requires that both fields be populated. TheWF function module translates the SAP standard interface to the one used byY_XR_ADD_TO_QUEUE.


The business workflow event detection mechanism is created and active. It is setup to detect all SAP Customer Quotes that are created.


Chapter 8. Testing a business object for the ABAP Extensionmodule

v “Preparing to test”v “Unit test issues” on page 86v “Testing an ABAP handler” on page 87

Once you have developed an application-specific business object and a supportingABAP handler, you must unit test to make sure they support the desiredfunctionality. The IBM WebSphere Business Integration Adapter for mySAP.com(SAP R/3 Version 4.x). provides unit test tools to facilitate this testing. These toolsoperate independently from your IBM WebSphere business integration system,which means that you do not need to have this system running to test yourbusiness object.

Note: These tools do not replace full end-to-end testing through the IBMWebSphere business integration system. They are meant only to be used forunit testing of individual business objects and ABAP handlers.

Preparing to testAll business object processing originates from the Java component of the connector.This is for all objects and all possible verbs. To unit test, the adapter includes anABAP program that simulates the connector’s action of sending in a businessobject request.

Specifically, the program simulates the doVerbFor() processing in the Javacomponent of the connector by calling the ABAP function moduleY_XR_RFC_DO_VERB_NEXTGEN. Like doVerbFor(), the test program requires a businessobject as an input to pass to the ABAP function module n. The ABAP test programuses a text file as its input.

All input test files have the same ASCII text format. From this file format, the testprogram restructures the data to resemble the business object passed toY_XR_RFC_DO_VERB_NEXTGEN. The following rules apply to business object input files:v Business object must have only one parent business object in a file.v Child business objects are ordered first in depth, then in breadthv Attributes and objects must be ordered in the exact sequence as they occur in

the business object repository definition.v For each attribute, the information described in Table 14 must be provided in the

described format and in the sequence shown (leading spaces after the “=” areignored):

Table 14. Attribute Properties and Values

Attribute Property Description or Possible Values

Name name of the attributeValue value of the attribute or CxIgnore =

‘CxIgnore’or CxBlank = ‘ ‘IsKey value that specifies whether the attribute is a

key:0 = no 1 = yes


Table 14. Attribute Properties and Values (continued)

Attribute Property Description or Possible Values

Peers NumberOfPeers value expressed an integer thatrepresents the total number of child businessobjects at the same level For example, if an Itembusiness object contains two line items, eachline item would have the value ‘2’.

AppInfo application-specific information that is specificto each business object

The test program provides a Quick Retrieve function to help generate a test inputfile. For more information, see “Testing an ABAP handler” on page 87.

Unit test issuesThe unit tools test all SAP development work that handles business objectprocessing for the connector. Also, the unit test tools enable you to test theinteraction of your work with the ABAP components of the connector. The testtools allow you to test your development work as an online user (real-time) only.

Note: It is important to understand the differences between testing the connectoras an online user and testing the connector as if operating as a backgrounduser.

The differences between testing the connector as an online user or as a backgrounduser are described as follows:v Memory—When testing a business object, the connector must log into the SAP

application.The connector runs as a background user, so it processes in a single memoryspace that is never implicitly refreshed until the connector is stopped and thenrestarted (therefore it is critical in business object development to clear memoryafter processing is complete). Since you are an online user, memory is typicallyrefreshed after each transaction you execute.For more information, see Chapter 6, “Developing business objects for the ABAPExtension module”, on page 59. Any problems that may occur because of this(for example, return codes never being initialized) are not detected using the testtool; only testing with the connector will reveal these issues.

v Screen flow behavior—Screen flow behavior is relevant only when using the CallTransaction API. The precise screen and sequence of screens that a user interactswith is usually determined at runtime by the transaction’s code. For example, ifa user chooses to extend a material master record to include a sales view bychecking the Sales view checkbox, SAP queries the user for the specific SalesOrganization information by presenting an additional input field. In this way,the transaction source code at runtime determines the specific screen and itsrequirements based on the data input by the user. While the test tool doeshandle this type of test scenario, there is a related scenario that the test toolcannot handle.SAP’s transaction code may present different screens to online users versusbackground users (usually for usability versus performance). The test tool onlyoperates as an online user. The connector only operates as a background user.Despite this difference, unit testing should get through most of the testingsituations.


Testing an ABAP handlerTo test, you must first generate a business object input file. At this point, you mayneed to modify it to contain attribute values and appropriate application-specificinformation. The last step is to execute the test program, pointing to your test fileas an input.

Creating a test fileTo create a test file:1. Go to WebSphere InterChange Server Connector Tools (transaction YXR1).2. Select Test g Test Program.3. Perform a Quick Retrieve for the required business object:

v Enter the name of an output file.v Select either an IDoc Retrieve or a Dynamic Retrieve.v Enter the business object’s name and object key.v If you selected an IDoc Retrieve, enter the IDoc Type, enter

Y_XR_IDOC_HANDLER in the Method 1 field, and enter the name of yourRetrieve function module in the Method 2 field.

v If you selected a Dynamic Retrieve, enter Y_XR_DYNAMIC_RETRIEVE in theMethod 1 field.

4. Click execute to save the test business object in the output file you specified.5. Edit the test file in any text editor. You must:

v Modify the verb application specific information to point to your ABAPhandler See “Business object data routing to ABAP handlers” on page 51 forthe syntax. For example,:function1:function2.

v Verify that the appropriate attribute on the parent is marked isKey.v Add input values for the attributes, as required.

Using the test fileTo use the test file:1. Go to WebSphere InterChange Server Connector Tools (transaction YXR1).2. Select Test g Test Program.3. Enter the location and file name of your input file in the input file field.4. (Optional) Enter a file name and location for the output data (can be the same

as the input, but it will overwrite the input).5. Click the execute button.

When finished, the program will display the last message that was raised duringprocessing. In addition, the processed data is displayed on the screen forverification. This is the same information that would be generated in the outputfile of step 4.

Also, you can look in the IBM WebSphere InterChange Server ABAP Log foradditional details.

Chapter 8. Testing a business object for the ABAP Extension module 87


Chapter 9. Managing the ABAP Extension modulev “Managing the connector log file”v “Monitoring the SAP gateway service connections” on page 91v “Shutting down the connector” on page 91v “Maintaining the event queue” on page 92v “Maintaining the archive table” on page 92

The IBM CrossWorlds Connector Tool (transaction YXR1) enables you to maintainthe IBM WebSphere Business Integration Adapter for mySAP.com (SAP R/3Version 4.x) event processing. You can also use this tool to maintain the connectionto the SAP application. You can view the connector log file and the SAP GatewayService connections. Also, you can reprocess archived objects from the connectorlog, view events waiting to be processed, and resubmit and delete events from thearchive table.

Managing the connector log fileThe connector log in the SAP application displays in reverse chronological order allevents and errors that relate to the connector, such as Create or Update operationsor events that arrive in the event queue. The log file lists the date, time, and eventfor each log entry. The log file is a good source to start troubleshooting problems.

Setting log optionsYou can set the global and user settings to the level of detail you want logged inthe connector log file, as well as the number of entries and type of data you wantdisplayed. To set the connector logging levels:1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1)2. From the Customizing menu, click Log, and then click Logging Options.3. Under Logging Level, select from the levels 0 - 3. The four levels of logging are

as follows:v 0 — Offv 1 — Log only warnings and errorsv 2 — Log every event with minimal informationv 3 — Log each event in detail, including every attribute of every business

object

Note: Logging level 0 is not recommended. Logging level 1 is recommendedfor a production system. Logging level 3 is recommended for adevelopment or debugging system.

Displaying the logTo view recently processed objects and details associated with them, display theconnector log. To display the connector log in the SAP application:1. Go to IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).2. Click the Display Log button, or from the Tools menu, click Display Log (F8).

Log entries display the date, time, and event. Entries are color-coded:


green—indicates a successful event

yellow—indicates a warning message

red—indicates an error

white— indicates an archived object

Magenta entries provide information on the beginning and end of the event. Youcan click on any arrow to link to SAP’s display transaction for that business object.

You can change the amount of detail that is displayed about each event. To changethe display level, click the More Details or Fewer Details button depending on thelevel of detail desired.

Filtering log detailsYou can change the amount of detail that is displayed about each event. If theamount of data displayed is more than you currently need, narrow the informationdisplayed. For example, you can view business objects by user, name, date, orevent number.1. Click the Filter Data button.2. Populate the appropriate fields to filter the log file.3. Click Filter.

In the Logging Options screen, you can set user settings for the number of logentries to display at one time and the default logging display level.

Setting up truncation of the event logSAP keeps an event log of the connector’s activity. This log can, over time, take upa lot of disk space. To save disk space, you can set this log to automaticallytruncate. When you set automatic truncation, by default SAP prints the truncatedentries to the default printer of the user who sets up the job. Therefore, you mayalso want to control the print options.

To set up truncation options:1. Go to IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).2. Click the Display Log button, or from the Tools menu, click Display Log (F8).3. Click the Log Options button or from the Goto menu, click Log Options (F7).4. Under Global Settings (for all users), enter the number of log entries you want

kept in the log after each truncation. For example, if you specify 1000, then oneach log truncation, all entries in the log except for the newest 1000 will betruncated.

5. To truncate the log immediately, click the Truncate Log button.

Important: Set up automatic truncation of the event log by scheduling reportYXRLOGT. It is recommended that you run this report on a regularbasis.

To schedule the YXRLOGT report:1. From the System menu, click Services, click Jobs, and then click Define Job

(transaction SM36).


2. Name the job, and specify the class (priority). The target host needs to be filledin only if you have multiple application servers accessing a single databaseserver.

3. Specify the start date and frequency of the job by clicking the Start Date button.4. Specify the frequency with which you would like to run the job. Select the

Periodic job check box, click the Period values button, and then select theappropriate button by clicking the Period Values button.

5. Click the save button twice to get back to the first screen. Define whichprogram is to be run by clicking the Steps button. Schedule ABAP programYXRLOGT. No Variant is needed.

6. By default, SAP will print the truncated entries in the log to the default printerof the user who sets up the job. If logging is turned high and many events areprocessed, this printout could be very long (several hundred pages). You cancontrol where the entries will be printed (or whether they are printed at all) byclicking on the Print specifications button.

7. To deactivate the automatic printing of the truncated log, uncheck the Printimmed. check box. This way the printout will be spooled and kept for a defaultof 8 days, where it could be referenced if necessary, without wasting paper.Now click the Save button twice.

8. Click the green back arrow.9. Click the save button, and then click the green back arrow. Your job is now

scheduled.

To view your truncation job:1. From the System menu, click Services, click Jobs, and then click Job Overview

(transaction SM37).2. Type the job name, and then press Enter. If the job is in Released state, it is

fine.

Note: You can access the connector log file by clicking the Connector Log button.

Monitoring the SAP gateway service connectionsYou can monitor the SAP Gateway Service connections between the connector andthe SAP application. Each entry displays information such as connector host name,user name, and connection status.

To monitor the SAP Gateway Service connections:1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).2. From the Tools menu, click Monitor Gateway.3. Click on a Server Name to view more details.

Shutting down the connectorIt is recommended that you shut down your connector using:v IBM WebSphere InterChange Server System Manager (when InterChange Server

is the integration broker)v The mqsiremotestopadapter command (when WebSphere MQ Integrator is the

integration broker).

Chapter 9. Managing the ABAP Extension module 91

Important: Do not use the Gateway monitor window. If you use the Gatewaymonitor window, your connector may not shut down properly.

Maintaining the event queueYou can check the outgoing current event queue for events that have not beenprocessed by the connector.1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).2. From the Tools menu, click Outgoing Queue, and then click Display Queue.3. Click Execute or press the F8 key to display the event queue.

To limit the number of event entries that are displayed, populate the applicablefields in the Current Event Selection section. For example, to limit the displayedentries for a particular business object, enter a business object name in the ObjectName field. If you do not know the exact syntax for the business object name, clickthe Object Name field, click the arrow button (F4), and then select the appropriatebusiness object name.

To see more information about an event, double-click an event field. Under normalconditions, events are picked up every few seconds. If an event is displayed, it hasnot been processed by the connector. This may indicate that the connector is notrunning.

The following is a list of the possible event status values for the event queue:

P — Prequeued When an event is triggered, the status is initially set to prequeue (P),because it has not yet been determined whether the business object islocked.

L — Locked When a user creates or updates a business object in SAP, a lock isplaced against that business object. Once the business object has beencommitted to the database, SAP removes the lock. If an event istriggered while a business object is locked, the event remains in theevent queue with status locked (L) until the lock has been removed.

R — Retrieved When the connector retrieves an event, the status changes to retrieved(R). This is a temporary status. Once event processing finishes, theconnector updates the status and moves the event to the archive table.If the status remains retrieved for an extended period of time, itindicates that the connection between the connector and SAP R/3 mayhave been lost during processing of that event.

Q — Queued When the business object is no longer locked, the status changes toqueued (Q), and the event is ready to be picked up by the connector.The event remains in this status until a confirmation of a retrieval isreceived.

Maintaining the archive tableUsing the IBM WebSphere InterChange Server Connector Tool (transaction YXR1),you can display the archive table and determine the status of archived events. Inthe table, you can identify events that need to be resubmitted for polling when anintegration broker subscribes to them.

To display the archive table:1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).


2. From the Tools menu, click Outgoing Queue, and then click Display Archive.3. Click Execute or press the F8 key to display the archive queue.

To limit the number of archive entries that are displayed, populate the applicablefields in the Archived Event Selection section. For example, to limit the displayedentries for a particular business object, enter a business object name in the ObjectName field. If you do not know the exact syntax for the business object, click theObject Name field, click the arrow button, and then select the appropriate businessobject name.

To see more information about an event, double-click an event field.

The following is a list of the possible event status values for the archive table:

0 — Success The connector successfully processed the event and sent thebusiness object to the integration broker.

1 — Error in SAP The connector encountered an error while retrieving thebusiness object within SAP for this event.

2— Not Subscribed No integration broker was subscribed to the combination of thebusiness object and verb for this event.

3— Error in Java The connector encountered an error during one of the following:

v Receiving the business object from SAP

v Converting the SAP business object to a WebSphere businessobject for SAP

v Inserting the business object into the message queue4 — Max requeued The event was requeued more than the maximum times

specified by the requeued constant, c_maximum_requeue (usually100). An event is requeued if its business object is locked.

5 — Multiple Event Some business objects have single events in the event table thatcause multiple events to be created at the time of retrieval. Theoriginal single event does not create a business object and istherefore archived using this event status.

6— Event Deleted A user manually deleted the event from the event table.

Resubmitting events from the archive tableYou can resubmit events from the archive table to the event queue for reprocessing.Depending on how you want to handle the events in the archive table, you havethe option of resubmitting a single event or multiple events. Keep in mind thatresubmitting events only moves the events from the archive table to the event tableand therefore the events do not pass through event distribution, event restriction,or event priority. Follow these steps from the Archived Events window:1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).2. From the Tools menu, click Outgoing Queue, and then click Resubmit Events.3. Choose the event or events to be resubmitted.4. Click the Execute button, or from the Program menu, click Execute (F8).

A status message displays. You can display the connector log to view the eventand its new status.

Deleting events from the archive tableYou can delete archive events manually or schedule them to be deletedautomatically.

Chapter 9. Managing the ABAP Extension module 93

To delete Archive Events manually:1. Go to the IBM WebSphere InterChange Server Connector Tools window

(transaction YXR1).2. From the Tools menu, click Outgoing Queue, and click Truncate Archive.3. Populate the applicable fields.4. Click the Execute button (F8).


Chapter 10. Upgrading the ABAP Extension modulev “Upgrading within a new version of SAP R/3”v “Upgrading ABAP handlers” on page 96v “Upgrade considerations” on page 98

This chapter describes the upgrade process for the ABAP Extension Module. Itassumes that you are not modifying the repository definitions for the connector orany objects unless explicitly stated to do so. This chapter focuses on the ABAPcomponents of ABAP Extension Module of the IBM WebSphere BusinessIntegration Adapter for mySAP.com.

When upgrading, you must have the latest ABAP Extension Module componentsfor your version of SAP R/3 version. The goal of the upgrade process is to getyour ABAP handler development to work with the latest ABAP Extension Modulecomponents.

Upgrading the ABAP Extension Module can be described in two distinct scenarios:v Upgrading an SAP R/3 system that contains adapter-provided ABAP handlers

For example, you may be running an SAP R/3 version 3.1 system that you wantto upgrade to SAP R/3 version 4.6. After you upgrade the SAP R/3 system, youmust upgrade the adapter environment. For details on upgrading the adapterenvironment in a new version of SAP R/3, see “Upgrading within a new versionof SAP R/3” on page 95.

v Implementing an adapter-provided ABAP handler for an object that supports anolder version of SAP R/3For example, you may be using the connector that supports the SAP R/3 version4.6 application and want to use the Material object that supports SAP R/3version 4.0 or 4.5. To use this Material object, you need to upgrade it to yourSAP R/3 version 4.6 system. For details on how to upgrade an object to a newerversion of SAP R/3, see “Upgrading ABAP handlers” on page 96.

Upgrading within a new version of SAP R/3The upgrade process for the SAP R/3 application does not modify any of theadapter’s ABAP development, but it may modify the SAP R/3 application so thatsome of the adapter’s ABAP development does not work properly.

This section describes how to upgrade the adapter’s ABAP development in anupgraded SAP R/3 application. Before you can upgrade the adapter, you musthave already upgraded your SAP R/3 application.

To upgrade the adapter’s ABAP development:1. Install the latest ABAP Extension Module transport files for the correct version

of the SAP R/3 application.You must install the correct version-specific transport files. For details oninstalling these transport files, see “Connector transport file installation” onpage 41.

2. Compile all programs and resolve syntax errors associated with the ABAPdevelopment.


The easiest way to find syntax errors is to generate each function groupassociated with each object and fix the errors one at time. Repeat this processuntil all function groups compile successfully. Be sure to generate any otherprograms such as triggering programs that are not associated with a functiongroup.If you are upgrading to SAP R/3 version 4.x, note that the 4.x ABAP handlersuse the product namespace /CWLD/. For special considerations for upgrading tothe connector supporting SAP R/3 version 4.x, see “Connector for SAP R/3” onpage 98.

3. Test the new environment and make modifications as needed.Only a full system test enables you to work out any problems with theupgrade. Test your event detection mechanisms by running the appropriatetransaction or program and sending business objects to the SAP system. Usethe adapter’s log within the SAP system to help identify other issues.For information on testing business objects, see Chapter 8, “Testing a businessobject for the ABAP Extension module”, on page 85.

Upgrading ABAP handlersUpgrading ABAP handlers has two steps.1. Resolve any compilation errors that may arise when introducing your ABAP

handlers into an environment with a different version of the ABAP ExtensionModule.

2. Evaluate the functionality that the business object provides in the newer SAPR/3 version. For example, the business object may operate properly but maynot return the right information; or maybe the business object no longerfunctions because SAP has changed the screens for the Call Transaction.

This section details the processes of the first step, such as packaging the businessobject’s ABAP handler and providing guidelines for possible compilation conflictpoints. The second step is not addressed in this section. See Chapter 6,“Developing business objects for the ABAP Extension module”, on page 59 formore information on extending the functionality of your objects.

Attention: Once you upgrade an object, it is considered custom work even if itwas originally developed by IBM.

Upgrade ABAP handlers when:v You want to use a previously implemented IBM-delivered SAP R/3 business

object in a later version of SAP R/3. For example, you may have alreadyimplemented a Customer business object in your SAP R/3 version 3.x systemthat does not exist in the 4.6 system.

v You want to use an adapter-provided SAP R/3 object that supports an SAP R/3version other than the version that you need. For example, you may want to usethe adapter-provided Material business object for SAP R/3 version 3.x in yourSAP R/3 version 4.6 system.

Essentially the upgrade procedure is the same. The only difference is thatupgrading a previously implemented business object requires you to package thebusiness object into a transport file as the second step.

Note: If you have objects in SAP R/3 version 4.6 that do not take advantage of theIBM product namespace, you need to upgrade those objects to thenamespace.


To upgrade an adapter-provide ABAP handler from one SAP R/3 version toanother:1. Verify that the latest version of the ABAP Extension Module transport files for

your version of SAP R/3 are installed.2. Package existing business objects into transport files. Note that if you are

upgrading an business object that has not been modified for yourimplementation, skip to step 3, because you should be able to use the originaltransport that was loaded.Use the adapter-delivered transport files as templates for what should beincluded for each business object. This may include function groups, IDocdefinitions, and Dynamic Retrieve and Dynamic Transaction data.v Include any additional programs and custom work.

Custom work done in the ABAP component of the connector needs to bemanually applied to the new SAP R/3 ABAP component of the connector.For example, you need to manually apply any changes to adapter-providedABAP handlers such as IDoc Handler or Dynamic Transaction.

v Check to see if changes were made to program YXRRESTR. This program isintended for customer modification.If changes were made, you can avoid conflicts by downloading the customwork as text files, not as transport files. Use the corresponding old programas a reference for updating /CWLD/TRIGGERING_RESTRICTIONS.

v Release the transports and note the transport numbers. The BASISadministrator needs this information to load the objects in the new SAP R/3system.

3. For IDocs (that define ABAP handler business objects) in an SAP R/3 version3.x system only, capture the structure and segment definitions of the IDocs andthen manually re-create them in the new system.If you do not have an SAP R/3 version 3.x environment and IDocs, then skipthis step.

4. Install the business object transport files. You should have your local BASISadministrator install the transports for the business objects you packaged instep 1.The BASIS administrator should use all of the override codes available for thetransport. This forces the business objects into the environment even if there arecompilation errors. Before importing the business objects, the BASISadministrator should know that you may encounter inconsistencies during theimport process.v If you packaged existing business objects in step 2, then install these

transport files.v If you are using non-implemented business objects, then simply install the

latest transport file for the business object that you want to use. You mustinstall the correct version-specific transport files.

For more information on installing these transport files, see “Connectortransport file installation” on page 41.

5. Compile all programs and resolve syntax errors associated with the ABAPdevelopment.The easiest way to find syntax errors is to generate each function groupassociated with each business object and fix the errors one at time. Repeat thisprocess until all function groups compile successfully. Be sure to generate anyother programs, such as triggering programs, that are not associated with afunction group.

Chapter 10. Upgrading the ABAP Extension module 97

If you are upgrading to SAP R/3 version 4.x, note that the 4.x ABAP handlersuse the product namespace /CWLD/. For special considerations for upgrading tothe connector supporting SAP R/3 version 4.x, see “Connector for SAP R/3” onpage 98.

6. Apply the event detection mechanisms.For user exits, the precise location may be different now. Search for key SAPlines of code to make a best approximation.

7. Test the new environment and make modifications as needed.Only a full system test enables you to work out any problems with theupgrade. Test your event detection mechanisms by running the appropriatetransaction or program and sending business objects to the SAP system. Usethe connector’s log within the SAP system to help identify other issues.For information on testing business objects, seeChapter 8, “Testing a businessobject for the ABAP Extension module”, on page 85.

Upgrade considerationsThe following sections provide reference information for the upgrade scenarios.This reference information is provided to help with the upgrade process for theconnector for SAP R/3 version 4.6 and IDocs.

Connector for SAP R/3The connector for SAP R/3 version 4.x uses the product namespace /CWLD/; thefollowing guidelines facilitate the effort to make your ABAP handlers work in thisrenamed environment. See Chapter 5, “Business object processing in the ABAPExtension module”, on page 47 for more information on how objects are processedand for background information for developing objects.

Business objects that use dynamic retrieve or dynamictransactionThe functionality for converting transaction-based (Dynamic Retrieve and DynamicTransaction) type business objects is provided through the new IBM WebSphereInterChange Server Station. The business object can be downloaded to a text filefrom transactions YXDY (Dynamic Retrieve) and YXTD (Dynamic Transaction) inthe old system and then uploaded to the new tables using IBM WebSphereInterChange Server Station in the new system. Do this from the Tools tab using theObject MetaData option.

Keep the following in mind:v The Long Text Declarations for transaction-based Dynamic Retrieve need to be

manually entered into the new table.v The Table Declarations for transaction based Dynamic Retrieve need to be

manually ported from the old include program to the new tables declarationinclude program.

Business objects that use IDoc or BAPI handlers, and customworkYou must redirect SAP R/3 version 3.x business objects that begin with Y* to theproduct /CWLD/ namespace. Only the names have changed. SAP’s “where used list”functionality greatly facilitates the search for all of the references that need to bechanged. Following is a list of the most common references that need to bechanged. Test to ensure your search is complete.


Table 15 shows the changes for the /CWLD/ namespace naming convention. Theparameter lists do not require changes.

Table 15. Namespace object name changes

Old name New name

Interface parameters of the function modulesYXR_EVENT-OBJ_KEY /CWLD/LOG_HEADER-OBJ_KEY (in three places)YXR_LOG_H-LOG_NR /CWLD/LOG_HEADER-LOG_NRYXR_RFCRC-YXR_RFCRC /CWLD/RFCRC_STRU-RFCRCChanges normally in the TOP include of the business object function groupYXR_CNST /CWLD/CONSTANTSYXRIFRM0 /CWLD/INBIDOC_FRMS0Data elementsYXR_VERB /CWLD/OBJ_VERBTable structuresYXR_CONFIG /CWLD/CONF_VALYXR_EVENTS /CWLD/EVT_CURYXR_LOG_I /CWLD/LOG_ITEMYXR_RFC_S /CWLD/OBJ_STRUProgram referenced in the LOG_UPDATE perform statementSAPLYXR1 /CWLD/SAPLLOGTriggering function modules (the parameter lists do not require changes)Y_XR_COMMIT_IDOC_RAISE_DELETE /CWLD/ COMMIT_IDOC_RAISE_DELETEY_XR_/ADD_TO_QUEUE /CWLD/ADD_TO_QUEUE

Additional IBM ABAP componentsIn addition to upgrading the custom objects and custom work, you must:v Upgrade any ABAP code from the old event restriction program to the new

event restriction program.v Manually upgrade all configuration objects and configuration values from the

old tables to the new tables.v Upgrade any event distribution entries from the old table to the new table.v Upgrade the log object links from the old table to the new table.

Give special consideration to production sites that already have events in theexisting SAP R/3 version 4.x event tables. The transfer of these events from theexisting event table to the new event table should be coordinated with IBMTechnical Support.

Packaging and re-creating IDocsThis section applies to IBM WebSphere SAP R/3 version 3.x objects only.

Because you cannot transport IDoc objects from SAP R/3 version 3.x, you mustmanually re-create them in the new SAP R/3 system. To do this, you need to:v Capture the IDoc structure and segment definitionsv Manually re-create the IDocs

Capture the IDoc structure and segment definitionsTo capture the most useful representation of an IDoc, capture the overall structurethat identifies all of the segments, and then capture business object definitions foreach segment. Once you have a clear representation of the IDoc, you can us it tomanually re-create it in the new system.


If you have access to the old and new systems, you can simply copy and paste thebusiness objects between the systems. However, if both systems are not available,then you should record the IDoc and segment definitions outside of the SAPsystem for reference. Although this is optional, it is strongly recommended thatyou record the definitions.

To download the most useful representations of the IDocs and the segmentdefinitions, first download the overall structure of the IDoc, and then downloadthe IDoc segment definitions.

Downloading the overall IDoc structure: To download the overall IDoc structure:1. Go to the Develop IDocs Type screen (transaction WE30).2. Enter an IDoc object name, and then click Display (F7).3. Expand the IDoc structure so that all segments are visible.

a. Download a text version of the structure.b. From the System menu, click List, click Save, and then click Local File.c. Accept the default option unconverted, and then click Enter.

The file is downloaded as a text file and can be viewed in any text editor.d. Specify the location to download the file, and then click Transfer.

Downloading the segment definitions: You can download only one segmentdefinition at a time. Repeat the following steps for each segment. To download asegment definition:1. Go to transaction SE11 and enter the segment name.2. From the Dictionary Object menu, click Print.

Make sure the Table Structure box is checked.3. Deselect the Print immediately checkbox, check the new spool request check

box, and then click Continue.4. Go to the Spool Request Selection screen (transaction SP01) to view the print

request.5. Click Execute, select the checkbox next to the request, and then click Display

comments.6. Convert the data to a downloadable format.

a. From the Goto menu, click List Display.b. Download a text version of the segment. From the System menu, point to

List, point to Save, and then click Local File.c. Accept the default option unconverted, and click Enter.

The file is downloaded as a text file and can be viewed in any text editor.d. Specify the location to download the file, and then click Transfer.

Once you have represented the object using text files, you can import them into aspreadsheet application to set up the object hierarchy. This facilitates the creation ofIDoc segments, because you can cut and paste the fields directly into the segmenteditor in the SAP application.

Manually re-create the IDocsOnce you have a representation of the IDoc, you must manually re-create it in thenew system. The SAP R/3 version 4.x environment uses different tables to storeIDoc type and segment definitions than does SAP R/3 version 3.x. As a result, youmust use SAP’s tools to redefine the IDoc definitions to update the proper tables.There are two steps to this process:


v Re-create the segment definitions using the Develop Segments screen(transaction WE31).

v Re-create the IDoc type and assign all of the segments to it.

A common error message encountered when re-creating segments by assigning theSAP R/3 version 3.x data element to the new segment field is Invalid dataelement. SAP replaced many of the SAP R/3 version 3.x data elements with dataelements that have an underscore followed by the letter D (_D) at the end of theSAP R/3 version 3.x name. For example, CHARG in SAP R/3 version 3.x is BatchNumber for the data element and is replaced in SAP R/3 version 4.x withCHARG_D.

If a data element does not exist in the new form, find a new form in the SAP R/3version 4.x system. The data element must have the same type and length as theoriginal in SAP R/3 version 3.x system. The description does not affect processingand is visible only in the log.

Attention: Do not rename the IDoc, segments, or segment fields because there isa direct relationship between the IDoc definition and the IBM WebSphere businessobject repository. In addition, the ABAP functions used to process the IDoc alsorely on these names.



Part 3. ALE module



Chapter 11. Overview of the ALE modulev “ALE module components”v “How the ALE module works” on page 109

This chapter describes the ALE (Application Link Enabling) Module of the IBMWebSphere Business Integration Adapter for mySAP.com (SAP R/3 Version 4.x)The ALE Module allows an integration broker to send business objects to andreceive events from SAP R/3 application version 3.1H or 3.1I.

ALE is an SAP interface that allows systems to communicate asynchronously withthe R/3 system:v The integration broker sends a WebSphere Business Integration Adapter business

object for SAP. The business object’s data represents a processing request to theconnector. The connector converts the business object to a table formatcompatible with the SAP Intermediate Document (IDoc) format. In other words,the connector converts the data to IDoc format of the desired function moduleinterface. The connector uses Remote Function Calls (RFCs) to the ALE interfaceto pass the IDoc data to the SAP R/3 system.

v The connector receives data representing an application event from SAP in IDoctable format. It converts the data to a WebSphere Business Integration Adapterbusiness object for SAP before sending it to the integration broker. The connectoruses RFCs to the ALE Module to receive the data from the ALE interface.

Important: In releases of the connector prior to version 4.8.x, the connector usedcollaborations, business objects, and maps to store Transaction IDs(TIDs) and their status in the repository, and used the local file systemto store IDoc data. Version 4.8.x of the connector replaces the previousmanagement of TIDs and IDoc data with the use of MQSeries queues.

Note: Because the ALE Module uses asynchronous communication, it cannot beused when cross-referencing is required.

ALE module componentsThe ALE module is written in Java and extends the Vision Connector Framework.The module consists of:v the connector frameworkv the connector’s application-specific component for ALEv two ALE business object handler classes (one for event processing and one for

request processing)v the SAP RFC librariesv the SAP jCO connectorv the connector’s application-specific component for the RFC Server (used for

event processing only).The ALE Module uses the RFC Server connector component because of thesimilarities for event processing—both support RFC calls directly from the SAPapplication.

SAP delivers the RFC libraries in Java and C. The connector is delivered and runas a Java archive (JAR) file.


Figure 16 illustrates the architecture of the ALE Module.

Event processing componentsWhen processing events from SAP, the connector uses the components illustratedin Figure 16 in the following ways:v The Vision connector framework starts the RFC Server connector component,

which spawns listener threads. Each listener thread uses the RFC library and theSAP gateway to register a single handle to the SAP application.

v The listener thread processes events from the SAP application.An event is the execution of an ABAP function that transfers data to the listener.The event data sent by SAP may represent one or more such heterogeneousexecutions.Each event from SAP is considered a transaction. The connector uses a two-stepprocess with a Transaction ID (TID) to handle each event, guaranteeingonce-only delivery of data from SAP to the connector.

v MQSeries queues persistently store a JMS-MQ message for each event. EachJMS-MQ message stores the TID identifying the event, the status of the TID, theIDoc data associated with the event, and the processing status of the IDoc.

v The connector’s polling process creates WebSphere business objects from thestored event message, and sends the business objects to the integration broker.

v The business integration system tracks unprocessed events to handle theirrecovery in case the integration broker or the connector goes down. When theintegration broker or the connector is restored, the connector automaticallyresubmits these events.



SAP gateway

terminate()

ALErequest-

processingBO handler

doVerbFor()

SAP R/3 System

SAP RFC library

pollForEvents()init()terminate()

RFC serverconnector

init()

Function modules:idoc_inbound_asynchronous

Function modules:idoc_inbound_asynchronous

Listener threads

Main thread

ALEevent-

processingBO handler

process()

MQ seriesqueues

JMS interfacefor MQ series

Connector framework andALE connector component

Figure 16. ALE module architecture


For more information, see “Event processing” on page 110.

Request processing componentsWhen processing requests from the integration broker, the connector uses thecomponents illustrated in Figure 16 in the following ways:v The ALE Module uses the SAP RFC library and the SAP Gateway to open an

RFC connection to the SAP R/3 application.v The ALE request-processing business object handler processes requests from the

integration broker, converting them from business object format to IDoc databased on the SAP IDoc format.

v For every request sent to the application, the ALE Module persistently storesTransaction IDs (TIDs) in a TID queue as a JMS-MQ message. The TIDguarantees that event is delivered once and only once.

v The ALE Module releases the connection to the SAP R/3 application.

For more information, see “Request processing” on page 115.

Listener threadsListener threads handle all of the ALE-specific RFC calls between the ALE Moduleand the SAP application. When the connector starts up, the init() method of theRFC Server Module creates a main thread that spawns a configurable number oflistener threads. Each listener thread opens a handle to the SAP Gateway.

The listener threads do the following:v Use a program identifier to register with the SAP Gateway.v Identify to the SAP Gateway the ALE-specific RFC-enabled functions that they

support. These functions are idoc_inbound_asynchronous andinbound_idoc_process.

v Receive events from the ALE-specific function.v Instantiate the event-processing ALE business object handler.

A thread listens continuously in a synchronous manner for events from theALE-specific functions that it supports.

Transaction IDsSAP uses a transaction and its corresponding ID to frame an event, guaranteeingthat each piece of data is delivered once and only once from SAP. SAP sends aTransaction ID (TID) with the event data. To manage the TIDs centrally for eventand request processing, the connector stores each TID as a JMS-MQ message on anMQSeries queue. When processing events, it also stores the associated IDoc data asthe message body. The connector stores the TID, TID status, and the IDoc’sprocessing status in the message header.

ALE-specific business object handlersTwo ALE-specific business object handlers are provided, one for event processingand one for request processing.

Event-processing business object handlerA listener thread instantiates the event-processing business object handler, whichdoes the following:v Retrieves the RFC event data from SAP.

Chapter 11. Overview of the ALE module 107

v Creates a JMS-MQ message to persistently store and manage the transaction IDthat SAP sends with the event.

v Stores the data of the one or more IDocs received from SAP in the JMS-MQmessage.

v Returns a response to the ALE-specific function through the SAP Gateway. Theresponse indicates that the transaction has been completed.

Request-processing business object handlerThe Vision connector framework instantiates the ALE request-processing businessobject handler, which checks for the existence of the TransactionId attribute in theWebSphere business object for SAP. If this attribute exists, it continues with thefollowing steps.1. Obtains a TID either from the JMS-MQ message or from SAP.2. Converts the business object data to the IDoc data format defined by the

desired function module interface for the RFC call into SAP.3. Makes the RFC call to the ALE interface.4. Updates the status of the TID for this request in its JMS-MQ message.5. Returns a success response to the integration broker.

Structure of the business object for SAPA WebSphere business object for SAP represents each IDoc as a parent wrapperbusiness object that contains two child business objects: a control record businessobject and a data record business object. The control record business objectcontains the meta-data required by the connector to process the business object.The data record business object contains the actual business object data to beprocessed by the SAP application, and the meta-data required for the connector toconvert it to an IDoc structure for the RFC call.

IBM WebSphere Business Integration Adapter for mySAP.com includes a businessobject definition for the control record. The definition file, BO_SAPIDocControl.txt,is located in the \repository\SAP directory. The ALE Module uses the samebusiness object definition for 3.X and 4.X versions of SAP.

The TABNAM attribute in the control record business object indicates which SAPfunction module the parent wrapper business object calls:v A value of EDI_DC40 indicates the idoc_inbound_asynchronous function module,

which the connector uses only for SAP 4x.v A value of EDI_DC indicates the inbound_idoc_process function module, which is

provided for backward compatibility with SAP 3x.

In addition, the following attributes must have values for SAP to properly processthe object in ALE. These values are based on your ALE configuration:v Name_of_table_structure

v Client

v Name_of_basic_type

v Logical_message_type

v Partner_type_of_sender

v Partner_number_of_sender

v Partner_type_of_recipient

v Partner_number_of_recipient


The DOCNUM attribute in both business objects establishes the relationship betweenthe data record business object and the control record business object.

When processing service call requests, the ALE Module can handle multiple IDocsin a single business object. Before it can do so, however, you must add anothermultiple-IDoc wrapper business object around two or more parent wrapperbusiness objects. This top-level multiple IDoc wrapper business object contains anattribute that represents an array of parent wrapper business objects. For moreinformation, see “Parent wrapper business object” on page 127.

IBM WebSphere Business Integration Adapter for mySAP.com includes a businessobject generation tool, SAPODA. This tool uses an IDoc definition text file togenerate business object definitions for the ALE Module. For more information ondeveloping business objects for the ALE Module, see Chapter 13, “Developingbusiness objects for the ALE module”, on page 123 and Appendix C, “Generatingbusiness object definitions using SAPODA”, on page 239.

How the ALE module worksWhen processing application events, the ALE Module acts as a server to the SAPapplication. In this capacity, the ALE Module receives events that the SAPapplication ″pushes″, or sends, to the connector. When processing requests, theALE Module receives business object requests from the integration broker andsends them to the SAP application.

This section documents the following processes:v “Initialization and termination” on page 109v “Business object processing” on page 110

Initialization and terminationThe init() method opens an RFC connection to the SAP R/3 application throughthe SAP Gateway. If the connector fails to initialize, it terminates the connectionusing the terminate() method. The connector terminates by disconnecting fromthe SAP Gateway.

When processing application events or business object requests, the connector’sinitialization process does the following:1. Registers with the SAP Gateway the Program ID specified in the RfcProgramId

connector configuration property. For information on setting the Program ID asa TCP/IP port see “Registering the RFC Server module with the SAP Gateway”on page 165.

2. Opens an MQSeries session to the queues configured for the connector.3. Verifies that the required MQSeries queues for event and request processing

have been created. If they have not been created, terminates the connector.

For more information, see Chapter 12, “Configuring the ALE module”, on page 119.

Because the connector supports multi-threading, when the ALE Module processesrequests from the integration broker, it does not use the module’s init() methodto create a connection handle. Instead, it uses the Vision connector framework’sconnection pool of such handles.

Important: When you use this module to process application events, connectorpolling is required to properly initialize the module (to install the RFC


functions on the server), and for it to properly manage errors.Therefore, do not set the value of the PollFrequency property to key orto no. Do not allow the SAP application to trigger events to theconnector until you have verified that the connector’s log displays theinstallation of the required RFC functions.

Business object processingThe ALE Module’s processing of WebSphere business objects for SAP is initiatedeither through event processing or request processing.

This section describes:v “Event processing”v “Request processing” on page 115

Note: When business object data is returned from SAP’s Java Connector (jCO) API,the ALE Module receives values for DATS and TIMS fields in the followingformats: YYYY-MM-DD (the hyphens are included) for the DATS data element,and HH:mm:ss (the colons are included) for the TIMS data element. Thecapitalized HH denotes 24-hour time, and not 12-hour time. When processingevents, the ALE Module changes these formats to fit the 8-character and6-character maximum size of their corresponding business object attributes.The connector shortens the length of the value by removing the hyphensfrom the date data and the colons from the time data.

Event processingTwo RFC-enabled functions in an SAP application initiate all event processing forthe ALE Module. The ALE’s business object handler for event processing supportsthe functions idoc_inbound_asynchronous and inbound_idoc_process.

When processing events, this business object handler persistently stores thebusiness objects in an MQSeries queue. The connector maintains the TransactionIDs (TIDs) associated with the RFC call to guarantee that each piece of data isdelivered once and only once.

Important: A single RFC call can send the data for one or more IDocs. Therefore,an MQSeries queue may contain a JMS-MQ message that representsmultiple IDocs, each of which represents a business object. Each RFCcall is associated with a single TID.

This section describes the following:v “Processing Events in the MQSeries Queue”v “Creating Archive Messages” on page 112v “Structure of JMS-MQ Message for Event and Archive Processing” on page 113v “Updating the IDoc Status in SAP” on page 115

Processing Events in the MQSeries Queue: Figure 17 illustrates how the ALEModule processes the MQSeries queue.


Business-object event processing for the ALE Module executes in the followingmanner:1. An RFC function pushes event data to the SAP Gateway, where a listener

thread picks up events. The thread checks the TID associated with the event todetermine whether a JMS-MQ message exists for the TID (that is, whether theTID has been sent previously):v If the TID has not been sent previously, the connector continues to 2.v If the TID has been sent previously, the connector’s behavior depends on the

state of the previous transaction. If TidStatus is CREATED, the connectorremoves the IDoc data from the message. If the status is ROLLBACK, theconnector changes the status to CREATED, and, if IDoc data exists in themessage, the connector removes the IDoc data from the message. If the statusis EXECUTED, the connector returns control to SAP.

2. The listener thread instantiates the ALE event-processing business objecthandler, which retrieves the RFC-interface data from the SAP Gateway.

3. The business object handler formats each transaction into a JMS-MQ message,which it stores persistently in the queue specified by the SAPALE_Wip_Queueconfiguration property.Each JMS-MQ message represents a single RFC call. Each RFC call canrepresent one or more business objects associated with a single TID. Theconnector stores the TID in the message’s CorrelationID property, sets theTidStatus to CREATED, and sets the IDocProcessStatus to unknown. The connectoruses the message body to store IDoc data.

4. After each transaction completes, the connector changes the value of TidStatusand sends a confirmation back to SAP indicating that the transaction iscomplete. After SAP receives the confirmation, it removes the TID and itsassociated data from the SAP application.

SAP gateway

SAP application

SAP RFC library

ALEevent-processingBO handler

ALE-specificfunction

Listener thread

2

4

1

3

5

pollForEvents()

integrationbroker

ALEdata handler

6

8

7

WebSphere MQqueue

JMS interfacefor WebSphere MQ

Figure 17. Business object event processing


If the AleUpdateStatus configuration property evaluates to true, the connectorupdates the status of the IDoc in SAP. If it retrieves a packet of IDocs, itupdates the status of all IDocs in the packet. For more information, see“Updating the IDoc Status in SAP” on page 115.

5. The connector moves the JMS-MQ message from the Wip queue to the queuespecified by the SAPALE_Event_Queue configuration property.

6. The ALE Module’s polling thread picks up the event message from the Eventqueue.

7. The connector instantiates an ALE data handler, which creates a WebSpherebusiness object for SAP based on the message’s meta-data.

8. The connector checks for subscribed events:v It posts subscribed business objects to the integration broker. If a JMS-MQ

message contains more than one IDoc, the connector posts each one as aseparate business object.

v For all unsubscribed business objects, the connector changes the value of themessage’s IDocProcessStatus property to unsubscribed, and moves themessage to the MQSeries queue specified by the SAPALE_Archive_Queueconfiguration property.For more information see, “Creating Archive Messages”.

The Ale Module uses FIFO (First In, First Out) to maintain the processing orderwhen reading the messages from the Event queue.

Important: Connector polling is required for this module to manage errorsproperly when it processes application events. Therefore, do not set thevalue of the connector’s PollFrequency property to key or to no. Do notallow the SAP application to trigger events to the connector until youhave verified that the connector’s log displays the installation of therequired RFC functions.

Creating Archive Messages: A single event message may contain multiple IDocs,each of which represents a business object. As it processes each IDoc in the eventmessage, the connector creates corresponding messages in the Archive queue. Thenumber and types of archive messages depends on the processing status of eachIDoc.

For example, assume the connector processes an event message with four IDocs,each of which it transforms or attempts to transform into a business object, withthe results illustrated in Table 16:

Table 16. Archive Message Creation

Status of IDoc or business object Resulting Archive Message

Successfully transforms the first IDoc, andposts the business object to the integrationbroker

Creates an archive message with the sameCorrelationID as the event message, and anIDocProcessStatus of success—the messagecontains the data in the first IDoc

Fails to transform the second IDoc into abusiness object

v Creates an archive message with the sameCorrelationID as the event message, andan IDocProcessStatus of fail—the messagecontains the data in the second IDoc

v Changes the IDocProcessStatus of the firstarchive message from success to partial(because not all business objects in theevent message processed successfully)


Table 16. Archive Message Creation (continued)

Status of IDoc or business object Resulting Archive Message

Successfully transforms the third IDoc, andposts the business object to the integrationbroker

Writes the data from the third IDoc to themessage with the IDocProcessStatus ofpartial

Successfully transforms the fourth IDoc, butthe business object created is not subscribedin the integration broker

v Creates an archive message with anIDocProcessStatus of unsubscribed—themessage contains the data in the fourthIDoc

v After processing the last IDoc, moves themessage from the Event queue to theArchive queue and gives itIDocProcessStatus of original

The connector handles the event message from the Event queue in either of thefollowing scenarios:v If the connector has successfully posted to the integration broker each business

object associated with all IDocs in the event message, the archive message withthe IDocProcessStatus of success contains all the data from all IDocs in theevent message. The connector deletes the event message.

v If the connector does not successfully post to the integration broker eachbusiness object associated with all IDocs in the event message, it moves themessage to the Archive queue and changes the IDocProcessStatus to original.

Note: If connector goes down after processing the last IDoc in the event messagebut before archiving the event message, it archives the event message withan IDocProcessStatus of recovery. For more information, see “ALE moduledirectories and files” on page 119.

Structure of JMS-MQ Message for Event and Archive Processing: Table 17describes the structure of the message that the connector sends to the Event andArchive queues.

Table 17. Structure of JMS-MQ Message for Event and Archive Processing

Property Name Description

CorrelationId The JMS message header property—the connector sets thevalue of this property from the Transaction ID (TID) sent bySAP

TidStatus The JMS message header property that maintains the statusof the TID

IDocProcessStatus The JMS message header property that maintains the statusof the IDoc object during event processing

As the connector processes each IDoc in an event message, it moves the IDoc intoa message in the Archive queue. The archive message has the same CorrelationIdas the event message. Depending on the processing status of each IDoc, theconnector may create up to four different archive messages that correspond to thesame event message.

Table 18 describes the possible values for the IDocProcessStatus property after asingle business object’s events are moved to the Archive queue.


Table 18. Archive Queue Values for the IDocProcessStatus Message Property

IDocProcessStatusProperty Value

Event Status Description

success Success When all IDocs in a single event messageprocess successfully, the corresponding archivemessage contains all IDocs. In this case, thereis a single archive message.

partial Success When some of the IDocs in a single eventmessage fail processing, this archive messagecontains only the successfully processed IDocs.In this case, there are multiple archivemessages.

unsubscribed Unsubscribed When some of the IDocs in a single eventmessage are unsubscribed, this archivemessage contains all the unsubscribed IDocs.In this case, there are multiple archivemessages.

original N/A v If any IDoc in a single event message failsprocessing or is unsubscribed, this archivemessage contains the entire original eventmessage. The message is created even whenthe event message contains a single IDoc. Inthis case, there are multiple archivemessages.

v If the connector dies after successfullyprocessing every IDoc in a single eventmessage but before it moves the eventmessage out of the event queue into thearchive queue, the recovery process movesthe event message to the archive queue withstatus of original and changes the status ofthe existing archive message from success torecovery. In this case, there are two archivemessages: one with status original and onewith status recovery.

fail Fail When any IDoc in a single event message failsprocessing, this archive message contains allthe IDocs that failed formatting or were notsent successfully to the integration broker. Inthis case, there are multiple archive messages.

recovery Possible failure When event message processing does notfinish properly, that is, the connector hassuccessfully processed all IDocs in the eventmessage but the event message has not beenmoved out of the event queue, the recoveryprocess does the following:

v changes the status of the archive messagefrom success to recovery

v moves the entire original event message tothe archive queue with a status of original

This situation may occur if the connector diesbefore it moves the event message out of theevent queue. In this case, there are multiplearchive messages.


Updating the IDoc Status in SAP: To cause the connector to update a standardSAP status code after the ALE Module has retrieved an IDoc for event processing,you must:v Set the AleUpdateStatus configuration property to true and set the value of the

AleSuccessCode and AleFailureCode configuration properties.v Configure the inbound parameters of the Partner Profile of the Logical System in

SAP to receive the ALEAUD message type.

If AleUpdateStatus evaluates to true, the connector sends the ALEAUD IDoc to SAPwith status code information and, optionally, descriptive text. The ALEAUD IDoc callsthe IDOC_INPUT_ALEAUD function module. The connector supports sending thefollowing status codes to this function module:v IDoc has been completely posted in the business integration system.

The AleSuccessCode connector-specific configuration property can have a valueof 52 or 53. SAP converts this value to 41.

v IDoc cannot be processed in the business integration system.The AleFailureCode connector-specific configuration property can have a valueof 68. SAP converts this value to 40.

In both of the cases above, the business integration system does not send furtherstatus codes that would indicate further processing.

For information on setting the connector-specific configuration properties that arerequired to return IDoc status, see:v “AleUpdateStatus” on page 20v “AleSuccessCode” on page 20v “AleFailureCode” on page 21

For information on setting the connector-specific configuration properties that areoptional to return IDoc status, see:v “AleSelectiveUpdate” on page 20v “AleStatusMsgCode” on page 20v “AleSuccessText” on page 21v “AleFailureText” on page 21

Request processingThe Vision connector framework uses the value of the verb AppSpecificInfoproperty of the top-level business object to instantiate the ALE request-processingbusiness object handler. The doVerbFor() method in the request-processingbusiness object handler initiates all business object requests.

The business object handler converts the business object data into two tables thatrepresent the IDoc format and its meta-data component, the control record. Oncethe data is in IDoc format, the business object handler makes an RFC call to theappropriate SAP function module: either idoc_inbound_asynchronous orinbound_idoc_process. Because ALE is asynchronous, the connector does not waitfor a return response.

Important: By default, parent wrapper business objects generated by SAPODAcontain a TransactionId attribute. The existence of this attribute causesthe connector to manage TIDs when processing service call requests. Ifyou do not want TID management for request processing, you must


manually remove this attribute from the generated business object. Formore information, see “Parent wrapper business object” on page 127.

Note: The value of the TransactionId attribute is a unique identifier populated bythe integration broker. The value is not the equivalent of a TID in the SAPapplication.

If the TransactionId attribute does not exist, the ALE Module sends the requestdirectly to SAP. If the TransactionId attribute exists, the ALE Module does thefollowing:1. The connector checks whether the business object’s TransactionId attribute has

a value:v If the attribute has a value, the connector uses this value as the CorrelationID

of a JMS-MQ message.v If the attribute is empty, the connector generates the CorrelationID value by

concatenating the business object’s name (for example, sap_CustomerMaster)with the value of all key attributes and a timestamp.

2. The connector checks whether a JMS-MQ message with the same CorrelationIDexists in the queue specified by the SAPtid_Queue configuration property.v If the value of the business object’s TransactionId attribute does not match

any message’s CorrelationID, the connector creates a new JMS-MQ message.It sets the value of the message’s CorrelationID property to the value of thebusiness object’s TransactionId attribute. Then the connector retrieves a newTID from SAP and uses it to set the value of the message’s TransactionIdproperty. The connector sets the value of the TidStatus property to CREATED.Table 19 illustrates the relationship between the business object attribute, theJMS-MQ message properties, and the SAP application’s TID. Processingcontinues to 3.

Table 19. Relationship of business object attribute, JMS-MQ message properties, and SAPapplication TIDs

Business Object AttributeName

JMS-MQ Message PropertyName

SAP Application

TransactionID CorrelationIdTransactionID TID

v If the value of the business object’s TransactionId attribute does match amessage’s CorrelationID, the connector’s behavior depends upon themessage’s TidStatus. If TidStatus is CREATED, the connector continues to 3. IfTidStatus is ROLLBACK, the connector changes the value to CREATED, andcontinues to 3. If TidStatus is EXECUTED, the connector updates the value toResubmitted and returns success to the integration broker without processingthe business object.

3. The connector converts the business object to RFC tables and makes an RFCcall to SAP.v If the call posts successfully, the connector updates the message’s TidStatus

to EXECUTED.v If the call fails to post to SAP or raises an exception, the connector updates

the message’s TidStatus to ROLLBACK.4. After SAP acknowledges receipt of the RFC call, the connector informs SAP

that it can delete the TID, and returns a success status to the integration broker.


Structure of MQSeries Message for Request Processing: Table 20 describes thestructure of the JMS-MQSeries message that the connector gets from the Requestqueue:

Table 20. Structure of JMS-MQ Message for Request Processing


CorrelationId The connector gets the value of this property from theTransactionId attribute of the request business object sentby the integration broker. If the TransactionId attributecontains no value, the connector constructs a value for thisproperty from:BOName + BOKeyAttributes + TimeStampThetimestamp includes hour, minute, second, and millisecondof the system time. Forexample:sapCustomerMasterAttr1keyAttr2key150713882

TransactionId TID received from SAP. The value of this property serves asthe unique identifier of the MQSeries message

TidStatus Status of the transaction



Chapter 12. Configuring the ALE modulev “Prerequisites to running the ALE module”v “ALE module directories and files”v “ALE module directories and files”v “Configuring the ALE module” on page 120v “Checking the SAP configuration” on page 121v “Configuring SAP to update IDoc status” on page 121

This chapter describes the configuration of the ALE Module. The connectorcomponent of the IBM WebSphere Business Integration Adapter for mySAP.com(SAP R/3 Version 4.x) should be installed before performing the configurationtasks described in this chapter.

For more information on installing the connector, see Chapter 2, “Installing andconfiguring the connector”, on page 11.

Prerequisites to running the ALE moduleTo enable the connector to store the TID and IDoc data persistently during eventprocessing, and to store the TIDs persistently during request processing, you mustdo the following:v Verify that the following are running on your system:

– MQSeries– TCP/IP

v Create the following MQSeries queues, whose names are specified by thecorresponding connector-specific configuration properties:– For event processing: Archive queue (SAPALE_Archive_Queue property), Event

queue (SAPALE_Event_Queue property), Work-in-Progress (Wip) queue(SAPALE_Wip_Queue property)

– For request processing—the connector requires a single MQSeries queuewhose name is specified by the SAPtid_Queue configuration property.

For information about how the connector uses these queues, see “How the ALEmodule works” on page 109.

ALE module directories and filesTable 21 lists the directories and files used by the ALE Module.

Table 21. ALE module directories and files

Filename Events Requests Description

CWSAP.jar Yes Yes Program file for the ALE Module. Located inthe \connectors\SAP directory.

BO_SAPIDocControl.txt Yes Yes Control record business object definition file.Located in the \repository\SAP directory.

%crossworlds%/MA_88 or$crossworlds/MA_88

MQSeries patch directory


Table 21. ALE module directories and files (continued)

Filename Events Requests Description

EventState.log file Yes No Located in the directory specified in theAleEventDir configuration property, theconnector logs information to this file aboutsuccessfully processed IDocs in a JMS-MQevent message. Note: The connector doesnot create the log file automatically the firsttime it processes an event. You must createthis file for before you run the connector forthe first time.


Configuring the ALE moduleBefore you can use the ALE Module, you must:v Add the module name for the ALE Module to the Modules property. The

module name is ALE.v To enable TID management, you must configure the appropriate

connector-specific properties.– “SAPALE_Archive_Queue” on page 23 (event-processing only)– “SAPALE_Event_Queue” on page 23 (event-processing only)– “SAPALE_Wip_Queue” on page 23 (event-processing only)– “SAPtid_Queue” on page 23 (request-processing only)

v To cause the connector to update a standard SAP status code after the ALEModule has retrieved an IDoc for event processing, you must configure specificproperties and configure the inbound parameters of the Partner Profile of theLogical System in SAP to receive the ALEAUD message type. For more informationand a full listing of relevant properties, see “Configuring SAP to update IDocstatus” on page 121.

v Set the remaining required standard and connector-specific configurationproperties.To set the connector configuration properties, use Connector Configurator (if theconnector uses WMQI as the integration broker) or Connector Designer (if theconnector uses ICS as the integration broker). For more information on settingthe connector configuration properties, see “Configuring the connector” on page16 and Appendix A, “Standard configuration properties for connectors”, onpage 199.

Important: Connector polling is required for this module to manage errorsproperly when it processes application events. Therefore, do not set thevalue of the connector’s PollFrequency property to key or to no. Do notallow the SAP application to trigger events to the connector until youhave verified that the connector’s log displays the installation of therequired RFC functions.


Checking the SAP configurationBefore running the ALE Module, verify that the SAP system is properly configuredto process business objects:v Check that the logical systems are defined and assigned for the SAP system and

external system (transaction code SALE).v Check that the distribution model has been maintained, and that the required

message types have been added to the model (transaction code BD64).v Check that there are partner profiles for the logical system or distribution model

(transaction code WE20).v For event processing:

– Check that the SAP application (transaction code SM59) matches the programID specified in the RfcProgramId configuration property. For moreinformation on setting up a TCP/IP port see “Registering the RFC Servermodule with the SAP Gateway” on page 165.

– Check that the Wip, Event, and Archive queues (specified by SAP_Wip_Queue,SAP_Event_Queue, and SAP_Archive_Queue, respectively) are defined andrunning in MQSeries

v For request processing, check that the request queue (specified by SAPtid_Queue)is defined and running in MQSeries

Configuring SAP to update IDoc statusTo cause the connector to update a standard SAP status code after the ALE Modulehas retrieved an IDoc for event processing, you must:v Set the AleUpdateStatus configuration property to true and set the value of the

AleSuccessCode and AleFailureCode configuration properties.v Configure the inbound parameters of the Partner Profile of the Logical System in

SAP to receive the ALEAUD message type.

For more information, see “Updating the IDoc Status in SAP” on page 115.

Configuring SAPConfigure the inbound parameters of the Partner Profile of the Logical System toreceive the ALEAUD message type. Set the following properties to the specifiedvalues:

Table 22. Configuring SAP to receive IDoc status

SAP property Value

Basic Type ALEAUD01Logical Message Type ALEAUDFunction Module IDOC_INPUT_ALEAUDProcess Code AUD1

Setting connector-specific configuration propertiesSet the following connector-specific configuration properties, which are required toreturn IDoc status:v “AleUpdateStatus” on page 20v “AleSuccessCode” on page 20v “AleFailureCode” on page 21

Chapter 12. Configuring the ALE module 121

You may also set the following optional connector-specific configuration properties:v “AleSelectiveUpdate” on page 20v “AleStatusMsgCode” on page 20v “AleSuccessText” on page 21v “AleFailureText” on page 21

Set the following connector-specific configuration properties, which are required toprocess events and requests:v “SAPtid_MQChannel” on page 23v “SAPtid_MQPort” on page 23v “SAPtid_QueueManager” on page 23v “SAPtid_QueueManagerHost” on page 23v “SAPtid_QueueManagerLogin” on page 24v “SAPtid_QueueManagerPassword” on page 24


Chapter 13. Developing business objects for the ALE modulev “Generating the IDoc definition dile”v “Business object structure”v “Supported verbs” on page 132v “Processing multiple IDocs with a wrapper business object” on page 134

This chapter describes the business objects required for the ALE Module. It alsodiscusses how the business object generation utility, SAPODA, generates thedefinitions. The chapter assumes you are familiar with how the connectorprocesses business objects. For more information on the ALE Module, seeChapter 11, “Overview of the ALE module”, on page 105.

Business object development for the ALE Module consists of creating a businessobject definition for each IDoc (Intermediate Document) type that you want tosupport. IDocs must adhere to a specific format for SAP to process them correctly.Therefore, when developing a business object for the ALE Module, the businessobject definition is dictated by the IDoc Structure as defined in SAP.

Use SAPODA to generate business object definitions for the of the IBM WebSphereBusiness Integration Adapter for mySAP.com (SAP R/3 Version 4.x). SAPODA usesthe SAP application’s native IDoc definitions as templates for business objectdefinitions for the ALE Module. After creating the definitions, you can useBusiness Object Designer or a text editor to modify them. For information on usingSAPODA, see Appendix C, “Generating business object definitions usingSAPODA”, on page 239.

Generating the IDoc definition dileBefore using SAPODA to generate a business object definition for the ALE Module,you must create the IDoc definition file for each IDoc you want to support.SAPODA uses this file as input. Use transaction WE63 in SAP to create the IDocdefinition file.

To generate the IDoc definition file:1. In SAP, select transaction WE63 by entering /oWE63.2. Deselect the Output IDoc record’s Output IDoc recordscheck box.3. Select the Output IDoc type’s Output IDoc types check box.4. In the IDoc type IDoc types’s field, enter the basic IDoc type or the custom

IDoc type.5. Select the Output Segment Fields’ checkbox.6. Click the Execute icon at the top of the screen. The IDoc definition is displayed

on the screen.7. Save the definition to a local directory.

Business object structureThe WebSphere business object for SAP for the ALE Module is made up of atop-level parent wrapper object and two child objects: the control record object andthe data record object. This section describes the following:v “Illustration of business object structure” on page 124


v “Business object naming conventions” on page 125v “Parent wrapper business object” on page 127v “Control record business object” on page 127v “Data record business object” on page 128

Illustration of business object structureFigure 18 illustrates the structure of a WebSphere business object for the ALEModule.


Business object naming conventionsThis section describes the following:v “Standard naming conventions” on page 126v “Using IDoc extensions/types” on page 126

[BusinessObjectDefinition]Name = sap_alereq01Version = 1.1.0AppSpecificInfo = ALEREQ01

[Attribute]Name = Dummy_KeyIsKey = true

[Attribute]Name = TransactionId

[Attribute]Name = Control_recordType = sap_idoccontrolCardinality = 1

[Attribute]Name = Data_recordType = sap_alereq01_cwdataCardinality = 1

[Verb]Name = CreateAppSpecificInfo = sap .sapalemodule.VSapALEBOHandler,MsgType=MATFET;MsgCode=;MsgFunction=[End]. . .[Verb]Name = AleOutboundVerbsAppSpecificInfo = Create, Update[End]

sap_alereq01

Name = Name_of_table_structureAppSpecificInfo = TABNAM

Name = IDoc_numberAppSpecificInfo = DOCNUM. . .

sap_idoccontrol

sap_alereq01_cwdata

Name = sap_alereq01_e2aler1001Type = sap_alereq01_e2aler1001Cardinality = 1. . .

Parent wrapper business object

Child business objects

sap_alereq01_e2aler1001

Name = Logical_message_typeMaxLength = 6AppSpecificInfo = 0+MESTYP

Name = Message_typeMaxLength = 30AppSpecificInfo = 6+MESTYP40. . .

Figure 18. Relationship of WebSphere business objects for SAP and an IDoc

Chapter 13. Developing business objects for the ALE module 125

Standard naming conventionsThe ALE Module requires its business objects to follow the naming conventionsdescribed in Table 23. SAPODA, which generates all but the control record businessobject, derives the business object and attribute names from the IDoc definition inaccordance with these conventions.

Table 23. IBM WebSphere SAP business object naming conventions

IBM WebSphere Business Objector Attribute

Name Type

Parent wrapper business object BOprefix_BasicIDocTypeNote: Theillustrations in this chapter use SAP_or sap_ as the business object prefix.You can specify your ownmeaningful prefix when you createyour business object definitions.

n/a

Control Record business object Control_record sap_idoccontrolData Record business object Data_record BOprefix_BasicIDocType_cwdataData Record child business object BOprefix_BasicIDocType_IDocSegmentNameBOprefix_BasicIDocType_IDocSegmentNameData Record attribute IDocFieldText String

Because WebSphere business integration system component names support onlyalphanumeric characters and the underscore character (_), SAPODA replacesspecial characters in the IDoc segment field descriptions with underscorecharacters in the business object definition. For example, SAPODA changes thespaces, parentheses, and periods in the following SAP description to underscoresin the corresponding attribute name:Partner function (e.g. sold-to party, ship-to party)

SAPODA represents the above description in the generated business objectdefinition as:Partner_function__e_g__sold_to_party__ship_to_party__

SAPODA guarantees that all attribute names in the business object definition areunique. If an IDoc has multiple fields with the same field name, then SAPODAadds a counter suffix to the generated attribute name.

You can modify attribute names at any time after you generate the business object.However, when you modify an attribute name, ensure that you do not modify itsapplication-specific information. The connector uses this text to identify the IDocattribute to which the attribute corresponds. For more information, see“Application-Specific Information in Simple Attributes” on page 130.

Using IDoc extensions/typesYou can generate a business object definition based on a custom IDoc type that hasbeen created from the combination of a basic IDoc type and an Extension type.SAPODA names the parent wrapper business object that it generates in thefollowing format:sap_IDocType

Important: When loading a business object definition for an IDoc extension intothe repository, you might encounter conflicts if a business objectdefinition for the basic IDoc Type already exists in the repository andits name matches the basic IDoc Type plus extension. You mustmanually resolve these conflicts.


Parent wrapper business objectThe name of the parent wrapper business object is the basic IDoc type prefixed bya user-defined prefix followed by an underscore (_), for example sap_. The parentwrapper business object contains four attributes: Dummy_key, Control_record,Data_record, and TransactionId.

The Control_record and Data_record attributes represent single-cardinality childbusiness objects.

The Type of the Control_record attribute is sap_idoccontrol, and this businessobject definition is provided with the ALE Module.

The Type of the Data_record attribute is BOprefix_BasicIDocType_cwdata. Thisbusiness object definition contains one or more child business objects, dependingon the IDoc segment definition of a basic IDoc type from the SAP application.

The existence of the TransactionId attribute determines whether the connectormanages TIDs when processing service call requests. If you do not want TIDmanagement for request processing, you must manually remove this attribute fromthe generated business object.

The application-specific information of the parent wrapper business objectindicates:v The type of IDoc to be createdv ALE Communication Partner information—Set only if your data requires more

than one Partner type, Partner number, or Partner function.

SyntaxThe AppSpecificInfo property of the parent wrapper object has the followingsyntax:BasicIDocType[,Pn=PartnerNumberOfRecipient[,Pt=PartnerTypeOfRecipient[,Pf=PartnerFunctionOfRecipient]]

Explanation of syntaxBasicIDocType

Specifies the basic IDoc type

Pn Specifies the Partner number of the recipient

Pt Specifies the Partner type of the recipient

Pf Specifies the Partner function of the recipient

ExampleAppSpecificInfo = ALEREQ01,Pn=ALESYS2,Pt=LS,Pf=EL

Control record business objectThe ALE Module uses a generic control record business object definition for allIDocs. It contains a superset of attributes that are present in the 3.x version (SAPstructure EDI_DC) and the 4.x version (SAP structure EDI_DC40) of the controlrecord. The control record business object definition is provided with the ALEModule, and must be loaded into the business object repository. Use BusinessObject Designer to load the business object into the repository.


Note: Alternatively, if InterChange Server (ICS) is the integration broker, you canuse the repos_copy command. For more information on repos_copy, see theIBM CrossWorlds System Administration Guide.

Table 24 lists the simple attribute properties of the control record business object.

Table 24. Properties of simple attributes in the control record business object

Property name Description

Name The value of the Name property is the modified value of theTEXT field in the IDoc definition. SAPODA replaces specialcharacters (such as periods, slashes, and spaces) withunderscores so that the name contains only alphanumericcharacters and the underscore character (_), as described in“Business object naming conventions” on page 125

Type Specifies the type of data. SAPODA sets the value to String.MaxLength SAPODA derives the value of MaxLength from the LENGTH

field in the IDoc definition.IsKey SAPODA sets this property to true on the first attribute of a

business object.IsForeignKey SAPODA sets the value to false.IsRequired The IsRequired property specifies whether an attribute must

contain a value. SAPODA set this property to true only onthe Name_of_table_structure attribute in the control recordobject.

AppSpecificInfo SAPODA derives the value from the NAME field in the IDocdefinition.

DefaultValue Specifies the value to assign to this attribute if there is norun-time value. SAPODA does not set a value for thisproperty.

Important: Attributes set to either CxIgnore or CxBlank in the control recordbusiness object are interpreted as a blank space for the IDoc controlrecord.

Data record business objectAn IDoc definition file has information about the structure of the IDoc, the IDocsegment hierarchy, and the fields that make up the segments. SAPODA uses theIDoc as input to generate the data record business object and its child businessobjects. The number of children depends on the IDoc segment definition of thebasic IDoc type from the SAP application.

The top level of the data record business object corresponds to the basic IDoc type.This top-level business object contains an attribute that represents a child businessobject or an array of child business objects (one for each IDoc segment). Thestructure and hierarchy of the child business objects match that of the IDocsegments in the basic IDoc type.

The cardinality of the attribute that represents child business objects depends onthe value of the LOOPMAX field in the IDoc definition:v If the value of LOOPMAX is 1 for a segment, this attribute represents a

single-cardinality child business object.v If the value of LOOPMAX is greater than 1, this attribute represents an array of

child business objects.

This section describes:


v “Attributes: Data record business object”v “Application-specific information: Data record business object” on page 130v “Illustration of the relationship between business object and IDoc” on page 131

Attributes: Data record business objectTable 25 describes the properties of each simple attribute in the data recordbusiness object. SAPODA generates the properties described below.

Table 25. Simple attributes: Data record business object


Name The value of the Name property is the modified value of theTEXT field in the IDoc definition. SAPODA replaces specialcharacters (such as periods, slashes, and spaces) withunderscores so that the name contains only alphanumericcharacters and the underscore character (_), as described in“Business object naming conventions” on page 125.

Type Specifies the type of data. SAPODA sets the value to String.MaxLength SAPODA derives the value of MaxLength from the LENGTH

field in the IDoc definition.IsKey SAPODA sets this property to true on the first attribute in

each business object. For every other attribute, SAPODA setsthe value to false.

IsForeignKey SAPODA sets the value to false.IsRequired Specifies whether an attribute must contain a value. SAPODA

sets the value to false.AppSpecificInfo SAPODA sets the value of the AppSpecificInfo property to

the value of the Name field in the IDoc definition prependedby the offset value and the + character; for example, for asegment field named SIGN with an offset of 40, it sets thefollowing value for AppSpecificInfo: 40+SIGNFor moreinformation, see “Application-Specific Information in SimpleAttributes” on page 130.

DefaultValue Specifies the value to assign to this attribute if there is norun-time value. SAPODA does not set a value for thisproperty.

Important: Simple attributes in the data record business object can have twospecial values: CxIgnore and CxBlank. Simple attributes set to CxIgnoreor CxBlank are represented by blank spaces in the segment data string.SAP processes these attributes by placing one space character in theapplication field.

Table 26 describes the properties of each attribute in the data record business objectthat represents a child or array of child business objects. SAPODA generates theproperties described below

Table 26. Attributes that represent child business objects


Name SAPODA sets the value of the name property toBOprefix_BasicIDocTypeIdocSegmentName; for example,SAP_E2ALER1001

Type SAPODA sets the value is the type of child business objectto: BOprefix_BasicIDocTypeIdocSegmentName

ContainedObjectVersion SAPODA sets the value to 1.0.0.Relationship SAPODA sets the value to containment.IsKey SAPODA sets the value to false.


Table 26. Attributes that represent child business objects (continued)


IsForeignKey SAPODA sets the value to false.IsRequired The IsRequired property specifies whether a child business

object must exist. SAPODA sets the value to false if thevalue of the STATUS field for the corresponding segment inthe IDoc definition has a value of OPTIONAL. SAPODA setsthis property to true if the STATUS field in the IDocdefinition has a value of MANDATORY.

AppSpecificInfo The AppSpecificInfo property contains information on thehierarchy level and minimum and maximum number ofallowed occurrences of a segment. For more information, see“Application-Specific Information in Attributes ThatRepresent Children” on page 131.

Cardinality If the value of the LOOPMAX field in the IDoc definition is 1,SAPODA sets the value to 1. If the value of LOOPMAX isgreater than 1, SAPODA sets the value to n.

Application-specific information: Data record business objectThis section describes how connector uses the value of the AppSpecificInfoproperty:v “Application-specific information at the bhusiness-object level”v “Application-Specific Information in Simple Attributes”v “Application-Specific Information in Attributes That Represent Children” on

page 131

Application-specific information at the bhusiness-object level: The connectoruses the value of the AppSpecificInfo property at the business-object level of thedata record and each of its children to obtain the name of the associated Idoc andits segments:v The syntax of the application-specific information on the data record business

object is:IDocType_CWDATA

For example, given an IDoc named ALERQ01, SAPODA creates the value of theAppSpecificInfo property as ALERQ01_CWDATA.

v The value of the application-specific information on the children of the datarecord business object is the corresponding segment name. For example, givenIDoc ALERQ01 with two segments named E2ALER1001 and E2ALEQ1, SAPODAautomatically creates the value of the AppSpecificInfo property for the twochild business objects as:– First child: E2ALER1001– Second child: E2ALEQ1

Application-Specific Information in Simple Attributes: The connector uses thevalue of the AppSpecificInfo property of simple attributes to obtain the field namein SAP and its position (offset) in the data string.

The offset value is the position of the first character of the attribute value in thedata string. The offset value is calculated by subtracting the value in theBYTE_FIRST value of the first field in the IDoc definition from the BYTE_FIRSTvalue of the given attribute. This value is used with the MaxLength property tobuild the data string for the IDoc segment.


The syntax of the AppSpecificInfo property of simple attributes is:

OffsetNumber+IDocFieldName

For example, a segment field named SIGN with an offset of 40 has the followingvalue for AppSpecificInfo:40+SIGN

Application-Specific Information in Attributes That Represent Children: Theconnector uses the value of the AppSpecificInfo property of attributes thatrepresent a child or array of child business objects to obtain information on thehierarchy level and minimum and maximum number of allowed occurrences of asegment. SAPODA sets the AppSpecificInfo property for these attributes byobtaining information from the LEVEL, LOOPMIN and LOOPMAX fields in the IDocdefinition.

Illustration of the relationship between business object and IDocFigure 19 illustrates the relationship between the WebSphere data record businessobject and the IDoc definition from an SAP application.


Supported verbsVerb support for the ALE module is limited by the verbs that SAP supportsthrough its ALE interface. SAPODA generates the Create, Update, Delete, andRetrieve verbs in the business object definition. Implementation of each verbrequires knowledge of the ALE configuration within SAP.

SAPODA generates the AppSpecificInfo for the verbs and the AleOutboundVerbsmeta-verb on the parent wrapper business object. However, it populates only oneof the parameters of the AppSpecificInfo with values: it specifies the businessobject handler to use for service-call request processing. For all other processing,you must manually modify the business object definition to add or remove specificinformation:

Name = Data_recordType = sap_e2alereq01_cwdataCardinality = 1. . .

sap_alereq01

Name = sap_e2aler1001AppSpecificInfo = E2ALER1001

Name = Logical_message_typeAppSpecificInfo = 0+MESTYP. . .MaxLength = 6. . .Name = sap_e2aleq1AppSpecificInfo = 03,1,9999IsRequired = trueRelationship = ContainmentCardinality = n

Parent wrapper business object

. . .

Data record business objects

IDoc definition

. . .BEGIN_IDOC ALEREQ01BEGIN_GROUP. . .

Begin_Segment E2ALER1001

Level 02Begin_FieldsText Logical message typeName MESTYPByte_First 000064Length 0006. . .

. . .End_SegmentBegin_Segment E2ALEQ1

Level 03Status MANDATORYLoopmin 0001Loopmax 9999. . .End_Segment

Name = sap_e2aleq1AppSpecificInfo = E2ALEQ1

Name = sap_e2alereq01_cwdataAppSpecificInfo=ALEREQ01_CWDATA

Name = sap_e2aler1001Type = sap_e2aler1001Cardinality = n. . .

Figure 19. Relationship between data record business object and IDoc definition Fields


v When using the business object for event processing, you must specify valuesfor the following the AppSpecificInfo properties:– Parent wrapper business object’s verb—specify a value for those parameters

that uniquely identify the verb. Depending on the requirements of your ALEconfiguration, specify the message type, message code, and message function.Make these changes after you import the business object definition into yourrepository. For information on this syntax, see “AppSpecificInfo property:Parent wrapper verb” on page 133.

Important: SAPODA inserts the AppSpecificInfo value that specifies thebusiness object handler, which the connector uses only for requestprocessing. SAPODA does not insert values for the messageparameters. If you are using the ALE Module for eventprocessing, you must manually add the values for the messageparameters.

– Parent wrapper business object’s AleOutboundVerbs meta-verb—acomma-separated list of verbs supported for event processing. Forinformation on this syntax, see “AppSpecificInfo property: Parent wrappermeta-verb” on page 134.

v When using the business object for request processing, you must specify a valuefor the following the AppSpecificInfo properties:– Parent wrapper business object’s verb—specify the package and classname of

the business object handler so that the connector can determine theappropriate business object handler. SAPODA inserts the following value intothe AppSpecificInfo property of each standard verb: AppSpecificInfo =sap.sapalemodule.VSapALEBOHandler. For information on this syntax, see“AppSpecificInfo property: Parent wrapper verb” on page 133.

– When using a wrapper business object to process multiple IDoc parentbusiness objects, you must add the package and classname of the businessobject handler to the AppSpecificInfo property of each verb in the multipleIDoc wrapper business object. See “Processing multiple IDocs with a wrapperbusiness object” on page 134 for more information.

AppSpecificInfo property: Parent wrapper verbThe syntax of the AppSpecificInfo property of the parent wrapper businessobject’s verb differs depending on whether the business object represents anapplication event or a service call request:

Application event syntax[BOHandler],MsgType=messageType;MsgCode=[messageCode];MsgFunction=[messageFunction]

Note: The connector matches the values in the control record with the valuesspecified in the verb’s AppSpecificInfo property to determine the verb.

Service call request syntaxBOHandler[,MsgType=messageType;MsgCode=[messageCode];MsgFunction=[messageFunction]]

Explanation of syntaxBOHandler Specifies the request-processing business object handler; the value

defaults to the following: sap.sapalemodule.VSapALEBOHandler

MsgType Specifies the message type configured for the IDoc in ALE

MsgCode Specifies the message code configured for the IDoc in ALE; the


connector requires a value only if MsgType does not uniquelyidentify the verb; however, specify a value if required by your ALEconfiguration

MsgFunction Specifies the message function configured for the IDoc in ALE; theconnector requires a value only if MsgType and MsgCode do notuniquely identify the verb; however, specify a value if required byyour ALE configuration

AppSpecificInfo property: Parent wrapper meta-verbIn the AppSpecificInfo property of the parent wrapper business object’sAleOutboundVerbs verb, specify those verbs the connector should support forapplication-event processing, separating verbs with a comma.

Important: SAPODA generates values for the Create, Retrieve, Update, and Deleteverbs. After the definition has been generated, you must manuallydelete those verbs that you do not want the connector to support.

The following example instructs the connector to support the Create and Updateverbs for processing application events:[Verb]

Name = AleOutboundVerbs

AppSpecificInfo = Create, Update

[End]

Processing multiple IDocs with a wrapper business object

Note: This section is applicable only to service-call request processing.

When processing multiple IDocs, the ALE Module requires a wrapper businessobject as the top-level business object. The multiple IDoc wrapper business objectcontains an attribute that represents an array of IDoc parent wrapper businessobjects.

For each parent wrapper business object, SAPODA generates the Create, Retrieve,Update, and Delete verbs. For each of these verbs, it generates the followingAppSpecificInfo values:sap.sapalemodule.VSapALEBOHandler,MsgType=;MsgCode=;MsgFunction=

Figure 20 illustrates the relationship between a top-level wrapper object and it’schild IDoc business objects.


Multiple IDoc wrapper object exampleThe following is a sample definition of a multiple IDoc wrapper business object:[BusinessObjectDefinition]Name = sap_alereq01_wrapperVersion = 1.0.0AppSpecificInfo =

[Attribute]Name = Dummy_keyType = StringCardinality = 1MaxLength = 1IsKey = trueIsForeignKey = falseIsRequired = trueAppSpecificInfo = DummyKeyDefaultValue =[End]

[Attribute]Name = TransactionIdType = StringCardinality = 1MaxLength = 1IsKey = falseIsForeignKey = falseIsRequired = falseAppSpecificInfo = CrossWorlds TIDDefaultValue =[End]

Name = Dummy_keyIsKey = trueAppSpecificInfo = DummyKey

Name = TransactionIdAppSpecificInfo = CrossWorlds TID

Name = sap_alereq01Type = sap_alereq01Cardinality = n

sap_alereq01_wrapper

Name =AppSpecificInfo =

sap_alereq01

sap_alereq01

Name =AppSpecificInfo =

Multiple IDoc wrapper business objects

Parent wrapper business objects

Figure 20. Wrapper business object containing child business objects


[Attribute]Name = sap_alereq01Type = sap_alereq01ContainedObjectVersion = 1.0.0Relationship = ContainmentCardinality = nMaxLength = 255IsKey = falseIsForeignKey = falseIsRequired = falseAppSpecificInfo =DefaultValue =[End]

[Verb]Name = CreateAppSpecificInfo = sap.sapalemodule.VSapALEBOHandler,MsgType=;MsgCode=;MsgFunction=[End]

[Verb]Name = RetrieveAppSpecificInfo = sap.sapalemodule.VSapALEBOHandler,MsgType=;MsgCode=;MsgFunction=[End]

[Verb]Name = UpdateAppSpecificInfo = sap.sapalemodule.VSapALEBOHandler,MsgType=;MsgCode=;MsgFunction=[End]

[Verb]Name = DeleteAppSpecificInfo = sap.sapalemodule.VSapALEBOHandler,MsgType=;MsgCode=;MsgFunction=[End]

Multiple IDoc wrapper: Attribute that represents the childbusiness object

Table 27 lists and describes the properties of the attribute that represents the childbusiness object in the multiple IDoc wrapper business object.

Table 27. Multiple IDoc wrapper: Attribute that represents child business object


Name Set the value to the name of the parent business objectgenerated by SAPODA.

Type Set the value to the name of the parent business objectgenerated by SAPODA.

ContainedObjectVersion Set the value to 1.0.0.Relationship A child business object is contained by a parent business

object; therefore, the value is containment.IsKey Set the value to false.IsForeignKey Set the value to false.IsRequired Set the value to false.AppSpecificInfo This property is not used for the attribute that represents

child business objects in the ALE Module.Cardinality Set the value of the attribute in the top-level wrapper

business object that represents the IDoc parent businessobject to cardinality n.


Part 4. BAPI module



Chapter 14. Overview of the BAPI modulev “BAPI module components”v “How the BAPI module works” on page 140

This chapter introduces the BAPI module of the IBM WebSphere BusinessIntegration Adapter for mySAP.com. The BAPI module enables an integrationbroker to send business objects to SAP R/3 application versions 3.1H or 3.1I usingBAPIs.

BAPIs are SAP’s standardized Business Application Programming Interfaces thatenable third parties to interact with SAP R/3 applications. They are implementedas RFC-enabled function modules for an SAP business object’s methods.

Note: A BAPI is simply an RFC-enabled function in an SAP application. Inaddition to BAPIs, the BAPI module can be used to support anyRFC-enabled function.

BAPI module componentsThe BAPI module is a connector module written in Java that supports native BAPIcalls directly to an SAP R/3 application. It extends the Vision ConnectorFramework by implementing the VisionConnectorAgent and VisionBOHandlerclasses. The BAPI module uses the SAP RFC libraries written in Java and C, whichenables external programs to communicate with an SAP R/3 application.

Figure 21 illustrates the overall architecture of the BAPI module. The BAPI moduleis made up of the connector framework, the connector’s application-specificcomponent for BAPI, and BAPI-specific business object handler connector modules,as well as the SAP RFC Library.


The BAPI module components:v Open an RFC connection to the SAP R/3 application using the SAP RFC library

and the SAP Gateway.v Handle requests from the integration broker and call BAPIs in an SAP R/3

application.v Terminate connections to the SAP R/3 application.

How the BAPI module worksThe BAPI module implements the init(), terminate(), pollForEvents(), anddoVerbFor() methods. However, the pollForEvents() method is not used becausethe BAPI module supports request operations only.

Initialization and terminationThe init() method opens an RFC connection with the SAP R/3 applicationthrough the SAP Gateway. If the connector fails to initialize, it terminates using theterminate() method. The connector terminates by disconnecting the connection tothe SAP Gateway.

Business object processingA single implementation of the doVerbFor() method in the Vision ConnectorFramework’s business object handler initiates all business object requests. TheVision business object handler processes all of the business objects passed betweenthe BAPI module and the integration broker. In the BAPI module, a BAPI-specific

SAP R/3 application


SAP gateway

SAP RFC library

SAP R/3

BAPI


Connector framework andBAPI connector component

BAPI

BAPI

doVerbFor()

BAPI-SpecificBOHandler

doVerbFor()

BAPI-SpecificBOHandler

doVerbFor()

BAPI-specificBO handler


Figure 21. BAPI module Architecture


business object handler supports only one BAPI; therefore, for each supportedBAPI in the SAP R/3 application, you must have an associated BAPI-specificbusiness object handler.

The Vision business object handler uses the verb application-specific information ofa business object to invoke the appropriate BAPI-specific business object handler.The BAPI parameter names and formats are hard-coded in the BAPI-specificbusiness object handler so that the business object handler can make an RFC call tothe appropriate BAPI.

Note: When business object data is returned from SAP’s Java Connector (jCO) API,the BAPI module receives values for DATS and TIMS fields in the followingformats: YYYY-MM-DD (the hyphen is included) for the DATS data element,and HH:mm:ss (the colon is included) for the TIMS data element. Thecapitalized HH denotes 24-hour time, and not 12-hour time. The BAPImodule does not change these formats.

Figure 22 illustrates business object processing for the BAPI module.

Once invoked by the Vision business object handler, the BAPI-specific businessobject handler executes in the following manner:1. Receives the WebSphere business object for SAP from the Vision business object

handler.2. Populates the BAPI parameters with business object data.


SAP R/3

SAP R/3 application

Vision business object handler

SAP gateway

BAPIBAPI

SAP RFC library

BAPI

doVerbFor()

doVerbFor()


doVerbFor()


doVerbFor()


Figure 22. Business object processing for the BAPI module

Chapter 14. Overview of the BAPI module 141

3. Executes a BAPI call using RFC and passes the BAPI parameters to the SAPR/3 application. The business object handler waits for the business object datato be returned.

4. Receives the business object data (BAPI parameters).5. Converts the BAPI parameters back to WebSphere business object data.6. Passes the business object to the Vision business object handler and ultimately

to the integration broker.

Note: If a BAPI module has a Return Structure or Return Table, the connectorchecks for the message types A (abort) and E (error) to determine if the eventprocessed successfully. A message type A or E indicates that the event failedto process. If a BAPI does not have a Return Structure or Return Table, youmust implement your own error handling. When WebSphere MQ Integrator(WMQI) is the integration broker, events that fail in the ConnectorFramework are moved to the fault queue; events that fail in the WMQIenvironment are handled by the MQ message flow. When InterChangeServer (ICS) is the integration broker, you can resubmit failed events usingWebSphere InterChange Server System Manager (CSM).

Supporting BAPIsIBM WebSphere Business Integration Adapter for mySAP.com includes a tool,SAPODA, that generates business object definitions that support BAPIs. SAPODAinterprets the interface of a BAPI, maps its parameters to the business objectattributes, and adds the application-specific information for each attribute.

Also, for each WebSphere business object definition, you must generate anassociated BAPI-specific business object handler using SAPODA. For moreinformation on Developing business objects and BAPI-specific business objecthandlers, see Chapter 16, “Developing business objects for the BAPI module”, onpage 145.

Note: Some BAPIs do not have single field parameters that correspond to simpleattributes in the WebSphere business object. The connector requires everytop-level business object to have a simple attribute that serves as the keyattribute. Therefore, when generating a business object and business objecthandler from a BAPI without a single field parameter, SAPODA creates akey attribute named Dummy_key in the top-level business object, marks itas the key attribute, and adds dummy_key as the application-specificinformation of this attribute. Dummy_key provides the connector with a keyattribute so that it can process the business object. However, the connectorignores the value of the Dummy_key attribute when modifying applicationdata.


Chapter 15. Configuring the BAPI modulev “BAPI module directories and files”v “BAPI module configuration properties”

This chapter describes the configuration of the BAPI module and assumes that allof the necessary files were installed when the IBM WebSphere Business IntegrationAdapter for mySAP.com was installed. For more information on installing theconnector, see Chapter 2, “Installing and configuring the connector”, on page 11.

BAPI module directories and filesThe BAPI module directory and files are contained in the \connectors\SAP\directory. Table 28 lists the directory and file used by the BAPI module.

Table 28. BAPI module directory and file

Directory/Filename Description

\bapi\client Directory containing the runtime files for theconnector. All BAPI-specific BOHandler class filesmust be copied into this directory.

CWSAP.jar Connector class file

BAPI module configuration propertiesYou must configure the BAPI module before it can start operating. To configure theBAPI module, set the standard and connector-specific connector configurationproperties. For more information on configuring the connector configurationproperties, see “Configuring the connector” on page 16 and Appendix A,“Standard configuration properties for connectors”, on page 199.



Chapter 16. Developing business objects for the BAPI modulev “Background information”v “Business object structure” on page 146v “Business object structure” on page 146v “Supported verbs” on page 147v “Business object attribute properties” on page 147v “Business object application-specific information” on page 149v “Using generated business object definitions and business object handlers” on

page 152

This chapter describes business objects required for the BAPI module. It alsodiscusses how the business object generation utility, SAPODA, generates thedefinitions. The chapter assumes you understand how the connector processesbusiness objects. For more information on business object processing in the BAPImodule, see Chapter 14, “Overview of the BAPI module”, on page 139.

Note: This chapter describes business objects that support BAPIs; however, theBAPI module can be used to support any RFC-enabled function.

Background informationBusiness object development for the BAPI module requires creation of thefollowing for each supported BAPI:v An application-specific business objectv An associated BAPI-specific business object handler

SAPODA facilitates the process of developing business objects and BAPI-specificbusiness object handlers. SAPODA uses the SAP application’s native definitions asa template when generating business object definitions for the IBM WebSphereBusiness Integration Adapter for mySAP.com.

Important: SAPODA must have access to the BAPI in an SAP R/3 system toretrieve the BAPI interface.

Note: SAP supports many methods that can be mapped to the standard verbs(Create, Update, Delete, and Retrieve) that the connector supports. You candevelop business objects and BAPI-specific business object handlers tosupport any method used by BAPIs.

Business object naming conventionsA BAPI interface consists of importing, exporting, and table parameters, where:v Importing parameters are passed to the BAPI.v Exporting parameters are returned from the BAPI.v Table parameters are passed in either direction.

Some BAPIs may not have all of the types of parameters. For example, a BAPImay have importing and table parameters only.


SAPODA automatically maps the BAPI importing, exporting, and table parametersto attributes in WebSphere business objects for SAP as described in Table 29.

Table 29. Naming Conventions: WebSphere business objects for SAP

Business Object BAPI Interface

Top-level business object BOprefix_BAPInameNote: The illustrations inthis chapter use SAP_ or sap_ as the businessobject prefix. You can specify your ownmeaningful prefix when you create yourbusiness object definitions.

Attribute FieldDescriptionChild business object BOprefix_BAPIParameterName

SAPODA guarantees that all attribute names in the business object definition areunique. If a BAPI has multiple parameters with the same field description,SAPODA adds a counter as the suffix to the generated attribute name.

You can modify the attribute names at any time after you generate the businessobject definition. However, when you modify an attribute name, ensure that youdo not modify the application-specific information. The connector uses thisinformation to identify the BAPI parameter to which the attribute corresponds. Formore information on the application-specific information, see “AppSpecificInfo forattributes” on page 150.

Business object structureThe connector uses a BAPI-specific business object handler to map each businessobject attribute to a BAPI parameter. The connector, each business object, and eachBAPI-specific business object handler are meta-data-driven. The application-specificinformation provided in the meta-data of each business object and business objecthandler allows you to add connector support for a new business object and itshandler without modifying connector code. Instead:v The connector uses the verb application-specific information of the top-level

business object to instantiate the appropriate BAPI-specific business objecthandler.

v The business object handler uses the attribute application-specific information ofeach business object to map between each attribute and its parameter.

Each BAPI-specific business object handler supports both single- andmultiple-cardinality relationships between business objects.

A business object based on a BAPI can contain no more than two levels ofhierarchy. Therefore, all BAPI simple parameters correspond to attributes of thetop-level business object, and BAPI structure and table parameters correspond tochild business objects.

Table 30. Correspondence between BAPIs and WebSphere Business Objects for SAP

BAPI Interface Parameter WebSphere Business Object for SAP

Simple field Attribute of the top-level business objectStructure Single-cardinality child business objectTable Multiple-cardinality child business objects


Note: Importing and exporting parameters can be simple field or structureparameters.

Figure 23 illustrates the association between a business object and a BAPI. Thefigure illustrates a fragment of the sap_bapi_salesorder_createfromdat2 businessobject, which corresponds to the BAPI_SALESORDER_CREATEFROMDAT2 BAPI.

Supported verbsThe BAPI module supports the standard verbs (Create, Update, Delete, andRetrieve) used by the WebSphere business integration system. For each supportedverb, a BAPI can have an associated method. Most BAPIs support one of thefollowing operations: create, retrieve, update, and delete.

Business object attribute propertiesThe properties of the attributes of a top-level business object differ depending onwhether the attribute represents a simple value, or a child or an array of childbusiness objects.

Name = SAP_ORDER_ITEMS_INCardinality = nAppSpecificInfo =IORDER_ITEMS_IN:EORDER_ITEMS_IN

SALESDOCUMENT (simple field)

ORDER_HEADER_IN (structure)

ORDER_ITEMS_IN (table)

BAPI_SALESORDER_CREATEFROMDAT2

[Attribute]Name = SALES_DOCUMENT_NUMBERAppSpecificInfo = ISALESDOCUMENT:

Name = sap_order_header_inType = sap_order_header_inCardinality = 1

Name = sap_order_items_inType = sap_order_items_inCardinality = n

[Verb]Name = CreateAppSpecificInfo = sap.bapi.client.BAPI_SALESORDER_CREATEFROMDAT2

sap_bapi_salesorder_createfromdat2

Name = sap_order_header_inAppSpecificInfo = IORDER_HEADER_IN:

sap_order_header_in

sap_order_items_in

SAP sales order BAPITop-level business object

Child business objects

Name = sap_order_items_inAppSpecificInfo =IORDER_ITEMS_IN:EORDER_ITEMS_IN

Figure 23. Mapping between a business object and a BAPI

Chapter 16. Developing business objects for the BAPI module 147

v Table 31 lists and describes the properties of simple attributes of a top-levelbusiness object.

v Table 32 lists and describes the attributes that represent a child or array of childbusiness objects.

SAPODA generates the attribute properties as described in each table.

Table 31. Simple attributes properties: Top-level business object


Name Derived from the description of the BAPI parameter. SAPODAreplaces special characters (such as periods, slashes, and spaces)with underscores.

Type Specifies the type of data. SAPODA sets the value to String.MaxLength Specifies the field length of the BAPI parameter.IsKey Specifies whether the attribute is the key. The first simple

attribute of a business object defaults to the key attribute. Theconnector does not support using an attribute that represents achild business object or an array of a child business objects as akey attribute. Therefore, if the BAPI provides only structure andtable parameters, you must insert a simple attribute as the firstattribute. SAPODA inserts the Dummy_key attribute as the firstattribute, marks it as the key attribute, and sets appropriatevalues. Do not modify those values. For more information, see“Supporting BAPIs” on page 142.

IsForeignKey SAPODA sets the value to false.IsRequired Specifies whether an attribute must contain a value. SAPODA

sets the value to false.AppSpecificInfo Contains the name of the BAPI parameter that corresponds to

the associated attribute. The format is:IABAPFieldName:EABAPFieldNameFor more information on theapplication-specific information, see “Business objectapplication-specific information” on page 149.

DefaultValue Specifies the value to assign to this attribute if there is norun-time value. SAPODA does not set a value for this property.

Table 32 lists and describes the attributes that represent a child or array of childbusiness objects. SAPODA generates the properties described below.

Table 32. Properties of an Attribute that Represents a Child or Children


Name The value is the name of the structure or table parameter. Theformat is: BOprefix_BAPIParameterName.

Type The value is the type of child business object; in other words,the type is BOprefix_BAPIParameterName.

ContainedObjectVersion SAPODA sets the value to 1.0.0.Relationship SAPODA sets the value to containment.IsKey SAPODA sets the value to false.IsForeignKey SAPODA sets the value to false.IsRequired Specifies whether an attribute must contain a value. SAPODA

sets the value to false.AppSpecificInfo Contains the name of the BAPI parameter that corresponds to

the associated attribute. The format is:IBAPIParameterName:EBAPIParameterNameFor moreinformation on the application-specific information, see“AppSpecificInfo for attributes” on page 150.


Table 32. Properties of an Attribute that Represents a Child or Children (continued)


Cardinality BAPI structure parameters have single cardinality (1) andBAPI table parameters have multiple cardinality (n).

Important: Simple attributes can have two special values: CxIgnore and CxBlank.When a business object is sent to the BAPI module as a service callrequest and the business object has simple attributes set to CxIgnore orCxBlank, it is as if those attributes are invisible to the BAPI module.However, the SAP application initializes such an attribute to its ABAPdata type. The BAPI module converts all returned blank values toCxIgnore.

Initializing Attribute ValuesEvery field in SAP has an initial value. When the connector receives a service callrequest, the BAPI-specific business object handler populates most of the BAPIinterface parameters with the values listed in Table 33. The one exception is thecharacter data type. The business object handler converts a CxIgnore in thebusiness object attribute to a space in the SAP field. If you want any other value tobe converted to CxIgnore, the component that creates the business object mustperform the conversion. For example, when ICS is the integration broker, modifythe map to handle this conversion.

Table 33 provides initial values set by the business object handler.

Table 33. Initial Field Values in SAP

Data Type Description Initial Value Set by BusinessObject Handler

C Character spaceN Numeric string 000...D Date (YYYMMDD) 00000000T Time (HHMMSS) 000000X Byte (hexadecimal) X00I Integer 0P Packed number 0F Floating point number 0.0

Business object application-specific informationApplication-specific information in business object definitions provides the BAPImodule with application-dependent instructions on how to process businessobjects. These instructions are specified at the business-object level, at the attributelevel (both for simple attributes and for attributes that represent a child or array ofchild business objects), and for verbs.

AppSpecificInfo for the verb of the top-level business objectThe connector uses the value of the verb application-specific information in thetop-level business object to call the appropriate BAPI-specific business objecthandler. The value of the AppSpecificInfo property specifies the package andclassname for the BAPI-specific business object handler. The format is as follows:

AppSpecificInfo = bapi.client.BOHandler


where BOHandler is the name of the class. By default, SAPODA uses the name ofthe BAPI as the name of the class. SAPODA automatically adds theapplication-specific information to the top-level business object.

Important: You must include the value client before the business object handlername to identify that the BAPI-specific business object handler acts asa client.

For example, if you are supporting the SALES_ORDER_CREATEFROMDAT2 BAPI, then theapplication-specific information is as follows:

AppSpecificInfo = bapi.client.sales_order_createfrom dat2

AppSpecificInfo for attributesThe connector uses the value of an attribute’s application-specific information todetermine which importing, exporting, and table parameters to use. The value ofthis property contains the prefix I (for importing parameters) or E (for importingparameters). The prefix indicates whether the attribute value is used to pass datainto or out from the SAP application.

Because structure parameters can be either importing or exporting, they use eitheran I or an E before the parameter value. Because table parameters can pass data toand return data from a BAPI, they can have both I and E parameter values.

Important: Always use a colon (:) separator when you specify parameter valueswith I and E. If specifying only an importing value, the colon mustfollow the value. If specifying only an exporting value, the colon mustprecede the value. If specifying both values, the colon follows theimporting value and precedes the exporting value.

Figure 24 illustrates the correspondence between a business object and an exampleBAPI named BAPI_EXAMPLE. In the example, the simple attributes (Attribute_1,Attribute_2, and Attribute_3) specify only an importing or exporting parameter.The attribute that represents a child business object (Child_1) corresponds to anexporting structure parameter. The attribute that represents an array of childbusiness objects (Child_2) corresponds to a table parameter.

Each child business object has a simple attribute that corresponds to a field of thecorresponding structure or table (Attribute_11 and Attribute_14, respectively). Youcan find these fields by looking at the details of the BAPI.


Table 34 identifies the format of the application-specific information for specifickinds of attributes.

Table 34. AppSpecificInfo Format for Specific Kinds of Attributes

AppSpecificInfo Format Attribute Type

IParameterName:EParameterName SimpleITableName:ETableName Represents a child business object mapped to a table

parameterIStructureName:EStructureName Represents a child business object mapped to a structure

parameter

BAPI_EXAMPLE

[BusinessObjectDefinition]Name = Top_Level_BusObjAppSpecificInfo =

[Attribute]Name = Attribute_1AppSpecificInfo = IField_1:

Name = Attribute_2AppSpecificInfo = :EField_2

Name = Attribute_3AppSpecificInfo = IField_3:

Name =Child_1Type =Child_1Cardinality = 1AppSpecificInfo = :EReturn

Name = Child_2Type = Child_2Cardinality = nAppSpecificInfo = ITable_7:ETable_7

Top_Level_BusObj

WebSphere BAPI business object

Child_2 (1)

[BusinessObjectDefinition]Name = Child_1AppSpecificInfo = :EReturn

[Attribute]Name = Attribute_11AppSpecificInfo = IField_11:EField_11

FUNCTION BAPI_EXAMPLE.*"---------------------------------------------------*"*"

*" IMPORTING*" Field_1 ...*" Field_3 ...*" EXPORTING*" Field_2 ...*" Return ...*" TABLES*" Table_7 ...

ENDFUNCTION.

Child_1

[BusinessObjectDefinition]Name = Child_2AppSpecificInfo = ITable_7:ETable_7


Child_2

Figure 24. Correspondence between a business object and an example BAPI


Table 34. AppSpecificInfo Format for Specific Kinds of Attributes (continued)


IFieldName:EFieldName Represents an attribute of a child business object mapped to afield in a table or structure parameter

SAPODA automatically generates the appropriate application-specific informationfor the business object definition. It is recommended that you do not change theparameter names of the generated application-specific information.

Using generated business object definitions and business objecthandlers

Use SAPODA to generate business object definitions and business object handlersfor each RFC-enabled function that you want to support. You can use thegenerated objects without any modifications. However, you can manually editthese objects to refine the functionality.

After the objects are generated, you must add the business object definition and itscorresponding BAPI-specific business object handler to your WebSphere businessintegration system’s runtime environment.v Use Business Object Designer to copy the business object definition into your

repository.

Note: Alternatively, if InterChange Server (ICS) is the integration broker, youcan use the repos_copy command to load the definition into therepository.

v Use a system command to copy the BAPI-specific business object handler files tothe following directory under the product directory:

\connectors\SAP\bapi\client

The BAPI-specific business object handler files are:– BAPI Name.java

– BAPI Name.class

For example, given the BAPI_SALESORDER_CREATEFROMDAT2 BAPI and auser-specified prefix of sap_, SAPODA generates the following:– sap_bapi_salesorder_createfromdat2 (business object definition that includes

all child business objects)– Bapi_salesorder_createfromdat2.java

– Bapi_salesorder_createfromdat2.class

Important: You can modify the name of the generated business object as well asthe name of its child business objects. To do so, you must edit thedefinition as a text file rather than in Business Object Designer. If youdo change a business object’s name, ensure that you also modify allreferences to the names that you change. Also, if you modify thenames of the generated.class file for the business object handler, youmust maintain the changes for the application-specific information forthe associated business object.


Tips and tricksThis section describes the following tips and tricks for developing business objectsand BAPI-specific business object handlers:v “Multiple business objects contain the same return business object”v “Generated business object definition contains unnecessary attributes and child

business objects”v “Generated business object names are too long or fail your naming conventions”

on page 154v “Generated AppSpecificInfo for table parameters specify unnecessary

parameters” on page 154

Multiple business objects contain the same return businessobjectMost BAPIs use the same name for the return object. When SAPODA generates abusiness object definition, it creates a child business object to represent this returnobject. If multiple business object definitions contain an identically named childbusiness object, you can add that child business object into the repository onlyonce, or copy only a single definition file into the repository directory.

To enable multiple business objects to contain the return business object, you mustmodify the name of the return business object to be unique for each businessobject.

To rename the return business object, modify the definition of each business objectdefinition that contains it. The definition of the child business object is contained inthe same definition file as its parent.

To rename the child, do the following:1. Open the definition file for the top-level business object in a text editor.2. Locate the definition of the BOprefix_return child business object.3. Change the child’s name to be unique. For example, append a number to the

text (sap_return_2).4. Change all references in the definition to refer to the newly named child. For

example, change the value of the Type property for every attribute thatrepresents the child business object.

5. Save the changed definition file.6. Use Business Object Designer to load the newly named child business object

into the repository.

Note: Alternatively, if ICS is the integration broker, you can use the repos_copycommand to load the definition into the repository.

Generated business object definition contains unnecessaryattributes and child business objectsSAPODA interprets all BAPI interface parameters and, for each one, it creates acorresponding business object attribute or child business object. To increaseperformance of business object processing, remove all unrequired attributes andbusiness objects from the business object definition.

Note: SAPODA facilitates graphically removing all optional attributes and childbusiness objects before definition generation. For more information, see“Provide additional information” on page 250.


To increase performance of business object processing, you can also remove allunrequired importing and exporting table parameter values from theapplication-specific information.

After definition generation, you can use Business Object Designer to manually editthe business object definition if you require other changes. However, be carefulthat you remove only attributes that you absolutely will not be using.

Generated business object names are too long or fail yournaming conventionsSAPODA uses the name of the BAPI function module to generate the name of thebusiness object definition. You can use a text editor to modify a business object’sname.

Important: If you do change the name, ensure that you modify all references tothe name as well. However, do not modify the parameter names of thegenerated application-specific information.

To change a generated business object’s name:1. Save the definition to a file.2. Use a text editor to shorten or change the name.3. Use Business Object Designer to load the newly named child business object



Generated AppSpecificInfo for table parameters specifyunnecessary parametersTable parameters can be both importing and exporting parameters. If you do notrequire importing or exporting of values for a table parameter, you can remove itfrom the application-specific information.

For example, for a create operation, if you do not need to return the table datafrom the SAP application after the create operation has completed, you can removethe exporting parameter value (such as Etable name).

For a retrieve operation, you do not need to specify any importing tableparameters. Therefore, you can remove the importing parameter value (such asItable name).

Note: You must remove the unrequired value from the AppSpecificInfo of theattribute in the parent that represents the child as well as from theAppSpecificInfo at the business-object level of the child business object. Donot remove the colon (:).

For example, to remove the ETable_7 exporting parameter in Figure 24 on page151, you would do the following:1. In the Child_2 attribute of the Top_Level_BusObj business object, change the

attribute’s AppSpecificInfo value to:ITable_7:

2. In the AppSpecificInfo at the business-object level of the Child_2 businessobject, change the value to:ITable_7:


3. In the AppSpecificInfo for each attribute of the child business object, usingAttribute_14 as an example, change the value to:IField_14:



Part 5. RFC Server module



Chapter 17. Overview of the RFC Server modulev “RFC Server module components”v “How the RFC Server module works” on page 161

This chapter introduces the RFC Server module of the IBM WebSphere BusinessIntegration Adapter for mySAP.com (SAP R/3 Version 4.x). The RFC Servermodule enables the integration broker to receive business objects from SAP R/3application version 3.1H or 3.1I applications that support RFC calls. It supports allSAP applications that use RFC-enabled functions by acting as a server to thoseapplications.

RFC Server module componentsThe RFC Server module is a connector module written in Java that supports RFCcalls directly from an SAP application. It extends the Vision Connector Frameworkby implementing the VisionConnectorAgent class. The RFC Server module uses theSAP RFC libraries that are written in Java and C, which enables external programsto communicate with an SAP application.

Figure 25 illustrates the overall architecture of the RFC Server module. The RFCServer module is made up of the connector framework, the connector’sapplication-specific component for RFC Server, RFC Server-specific business objecthandlers, listener threads, and the SAP RFC Library.


SAP R/3

SAP gateway

SAP application


SAP RFC library

pollForEvents()terminate()init()RFC server-

specificBO handler

RFC-enabledfunction

Listener threads

Main thread

Connector framework andRFC server connector component

r

Figure 25. RFC Server module Architecture


The RFC Server module components:v Spawn listener threads that open handles to the SAP application using the SAP

RFC library and the SAP Gateway. Each listener thread opens a single handle tothe SAP application.

v Process requests from RFC-enabled functions in the SAP application.v Terminate connections to the SAP application.

Listener ThreadsListener threads handle all of the RFC calls between the RFC Server module andthe SAP application. When the connector starts up, the init() method creates amain thread that spawns a configurable number of listener threads. Each listenerthread opens a handle to the SAP Gateway.

The listener threads:v Register with the SAP Gateway using a program identifier.v Identify to the SAP Gateway the RFC-enabled functions that they support.v Use the first available thread to pick up an event from a supported RFC-enabled

function.v Instantiate an RFC Server-specific business object handler based on the server

verb in the corresponding business object, and then retrieve the event data fromthe SAP Gateway.

v Populate business objects with RFC event data, and then convert returnedbusiness object data to RFC event data.

v Return a response to the RFC-enabled function through the SAP Gateway.

Note: A thread listens continuously in a synchronous manner for events fromRFC-enabled functions that it supports.

RFC Server-specific business object handlersThe RFC Server-specific business object handlers are unique to each RFC-enabledfunction in the SAP application. Each business object handler is instantiated by alistener thread and invokes an associated business object.

Because the RFC Server module acts as a server to the SAP application, it “pushes”or sends events from the SAP application to the integration broker. This behavior isvery different from other modules, which poll the application for events. Becauseof this difference, RFC Server-specific business object handlers perform differenttasks from other business object handlers.

Once instantiated, the RFC Server-specific business object handler:v Retrieves the RFC event data and populates the associated WebSphere business

object for SAP.v Passes the business object to the integration broker and receives a business

object in return.The business object handler uses the application-specific information of thebusiness object’s server verb to determine which collaboration should processthe business object data.– When InterChange server (ICS) is the integration broker, the business object’s

server verb must specify a valid collaboration. Because a collaboration cannotexplicitly subscribe to an event that is pushed to the connector, the RFCServer-specific business object handler must determine the appropriatecollaboration, and then instantiate it


– When WebSphere MQ Integrator (WMQI) is the integration broker, thebusiness object’s server verb must contain a dummy value.

v Converts the returned business object data back to RFC event data.v Returns the RFC event data back to the SAP application.

How the RFC Server module worksThe RFC Server module implements the init(), terminate(), pollForEvents(),and process() methods.

This section describes:v “Initialization and termination”v “Business object processing” on page 161v “Supporting RFC-Enabled Functions” on page 162

Initialization and terminationThe init() method creates a main thread that spawns a configurable number oflistener threads which open a handle to the SAP Gateway. If the connector fails toinitialize, it terminates using the terminate() method. The connector terminates bydisconnecting the connection to the SAP Gateway.

During the initialization process, the RFC Server module registers with the SAPGateway using a specified Program ID. This Program ID must be set using theRfcProgramID connector configuration property and set up as a TCP/IP port in theSAP application. For more information on setting up a TCP/IP port, see“Registering the RFC Server module with the SAP Gateway” on page 165.

Business object processingAll processing of WebSphere business objects for the RFC Server module isinitiated by an RFC-enabled function in an SAP application. In the RFC Servermodule, an RFC Server-specific business object handler supports only oneRFC-enabled function; therefore, for each supported function in the SAPapplication, you must have an associated RFC Server-specific business objecthandler. In addition, you must have an associated business object for each RFCServer-specific business object handler.

Figure 26 illustrates business object processing for the RFC Server module.

Chapter 17. Overview of the RFC Server module 161

Business object processing for the RFC Server module executes in the followingmanner:1. A listener thread picks up a subscribed event from the SAP Gateway and

matches the name of the corresponding RFC-enabled function with an RFCServer-specific business object handler.

2. The listener thread instantiates the appropriate RFC Server-specific businessobject handler based on data from the RFC event on the SAP Gateway, andthen creates an instance of the corresponding business object.

3. The RFC Server-specific business object handler retrieves the RFC interface datafrom the SAP Gateway and populates the WebSphere business object for SAP.

4. The RFC Server-specific business object handler passes the business object tothe integration broker.

5. The business object handler receives the returned business object from theintegration broker, converts it back to the RFC interface, and then returns it tothe SAP Gateway.

The RFC Server module uses the SAP Gateway to maintain the processing order ofevents and to maintain the status of events. Since the listener threads makesynchronous calls, an event must return to the SAP Gateway before it can beconsidered successfully processed.

Note: If an RFC-enabled function module has a Return Structure or Return Table,the connector checks for the message types A (abort) and E (error) todetermine if the event processed successfully. A message type A or Eindicates that the event failed to process. If an RFC-enabled function moduledoes not have a Return Structure or Return Table, you must implement yourown error handling.

Supporting RFC-Enabled FunctionsIBM WebSphere Business Integration Adapter for mySAP.com includes a tool,SAPODA, that generates business object definitions based on an RFC-enabled

SAP gateway

SAP Application

SAP RFC library

RFCserver-specific

BO handler

RFC-enabledfunction

Listener thread

2

4

1

3

5

Integrationbroker

Figure 26. Business object processing


function. SAPODA interprets the interface of an RFC-enabled function, maps itsinterface parameters to the business object attributes, and adds theapplication-specific information for each attribute.

For each business object definition, you must generate an associated RFCServer-specific business object handler, which invokes the corresponding businessobject. For more information on developing business objects and RFCServer-specific business object handlers, see Chapter 19, “Developing businessobjects for the RFC Server module”, on page 167.

Note: Some RFC-enabled functions do not have single field parameters thatcorrespond to simple attributes in the WebSphere business object. Theconnector requires every top-level business object to have a simple attributethat serves as the key attribute. Therefore, when generating a business objectand business object handler from a RFC-enabled function without a singlefield parameter, SAPODA creates a key attribute named Dummy_key in thetop-level business object, marks it as the key attribute, and adds dummy_keyas the application-specific information of this attribute. Dummy_keyprovides the connector with a key attribute so that it can process thebusiness object. However, the connector ignores the value of theDummy_key attribute when modifying application data.

Chapter 17. Overview of the RFC Server module 163


Chapter 18. Configuring the RFC Server modulev “RFC Server module directories and files”v “RFC Server module configuration properties”v “Registering the RFC Server module with the SAP Gateway”

This chapter describes the configuration of the RFC Server module and assumesthat all of the necessary files were installed when the IBM WebSphere BusinessIntegration Adapter for mySAP.com (SAP R/3 Version 4.x) was installed. For moreinformation on installing the connector, see Chapter 2, “Installing and configuringthe connector”, on page 11.

RFC Server module directories and filesThe RFC Server module directory and files are contained in the \connectors\SAP\directory. Table 35 lists the directory and file used by the RFC Server module.

Table 35. RFC Server module directory and file

Directory/Filename Description

\bapi\server Directory containing the runtime files for theconnector. All RFC Server-specific BOHandler classfiles must be copied into this directory.


RFC Server module configuration propertiesYou must configure the RFC Server module before it can start operating. Toconfigure the RFC Server module, set the standard and connector-specificconnector configuration properties. For more information on configuring theconnector configuration properties, see “Configuring the connector” on page 16and Appendix A, “Standard configuration properties for connectors”, on page 199.

Registering the RFC Server module with the SAP GatewayDuring initialization, the RFC Server module registers with the SAP Gateway. Ituses the value set for the RfcProgramId connector-specific configuration property.This value must match the value set in the SAP application. You must configurethe SAP application so that the RFC Server module can create a handle to it.

To register the RFC Server module as an RFC destination:1. In the SAP application, go to transaction SM59.2. Expand the TCP/IP connections directory.3. Click Create (F8).4. In the RFC destination field, enter the name of the RFC destination system. It is

recommended that you use RFCSERVER.5. Set the connection type to T (Start an external program via TCP/IP).6. Enter a description for the new RFC destination, and then click Save.7. Click the Registration button for the Activation Type.8. Set the Program ID. It is recommended that you use the same value as the RFC

destination (RFCSERVER), and then click Enter.


Important: Ensure that the connector-specific configuration property RfcProgramIDis set to the same value as the Program ID value in the SAPapplication. If the values do not match, business object processing willfail.


Chapter 19. Developing business objects for the RFC Servermodule

v “Background information”v “Business object naming conventions”v “Business object structure” on page 168v “Supported verbs” on page 170v “Business object attribute properties” on page 170v “Business object application-specific information” on page 172v “Using generated business objects and business object handlers” on page 175

This chapter describes business objects and business object handlers required forthe RFC Server module. It provides background information and discusses howthe business object generation utility, SAPODA, generates the definitions.Thechapter assumes you are familiar with how the connector processes businessobjects. For more information on business object processing in the RFC Servermodule, see Chapter 17, “Overview of the RFC Server module”, on page 159.

Note: Once you have created business objects and RFC Server-specific businessobject handlers, you must make sure that you register the RFC Servermodule with the SAP Gateway. For more information, see “Registering theRFC Server module with the SAP Gateway” on page 165.

Background informationBusiness object development for the RFC Server module consists of creating anapplication-specific business object definition and an associated RFC Server-specificbusiness object handler for each RFC-enabled function that you want to support.Because SAPODA uses the SAP application’s native definitions as a template whengenerating definitions for each of these, it is recommended that you use SAPODAto generate these definitions.

Note: SAP supports many methods that can be mapped to the standard verbs(Create, Update, Delete, and Retrieve) that the connector supports. You candevelop business objects and RFC Server-specific business object handlers tosupport any method used by RFC-enabled functions.

Business object naming conventionsAn RFC-enabled function interface consists of importing, exporting, and tableparameters, where:v Importing parameters are passed to the RFC-enabled function.v Exporting parameters are returned from the RFC-enabled function.v Table parameters are passed in either direction.

Some RFC-enabled functions may not have all of the types of parameters. Forexample, an RFC-enabled function may have importing and table parameters only.

SAPODA automatically maps the RFC-enabled function importing, exporting, andtable parameters to IBM WebSphere attributes as described in Table 36.


Table 36. Naming Conventions: WebSphere Business Objects for SAP

Business object Rfc-Enabled Function Interface

Top-level business object BOprefix_FunctionNameNote: The illustrations inthis chapter use SAP_ or sap_ as the business objectprefix. You can specify your own meaningful prefixwhen you create your business object definitions.

Attribute Field DescriptionChild business object BOprefix_FunctionParameterName

SAPODA guarantees that all attribute names in the business object definition areunique. If an RFC-enabled function has multiple parameters with the same fielddescription, SAPODA adds a counter as the suffix to the generated attribute name.

You can modify the attribute names at any time after you generate the businessobject definition. However, when you modify an attribute name, ensure that youdo not modify the application-specific information. The connector uses thisinformation to identify the RFC-enabled function parameter to which the attributecorresponds. For more information on the application-specific information, see“AppSpecificInfo for attributes” on page 173.

Business object structureThe connector uses an RFC Server-specific business object handler to map eachbusiness object attribute to an RFC-enabled function’s parameter. The connector,each business object, and each RFC Server-specific business object handler aremeta-data-driven. The application-specific information provided in the meta-dataof each business object and business object handler allows you to add connectorsupport for a new business object and its handler without modifying connectorcode. Instead:v The connector uses the verb application-specific information of the top-level

business object to instantiate the appropriate RFC Server-specific business objecthandler.

Important: The RFC Server module differs from other modules in that it doesnot poll SAP for events. Instead, SAP pushes event data to theconnector. Because this module does not use standard pollingprocedures, the RFC Server-specific business object handler checksevery business object that represents an event for the name of thecollaboration that will process it. When InterChange Server (ICS) isthe integration broker, the RFC Server-specific business objecthandler uses the value obtained to instantiate the appropriatecollaboration. When WebSphere MQ Integrator (WMQI) is theintegration broker, a dummy value must be provided for the RFCServer-specific business object handler to process the eventsuccessfully.

v The business object handler uses the attribute application-specific information ofeach business object to map between each attribute and its parameter.

Each RFC Server-specific business object handler supports both single- andmultiple-cardinality relationships between business objects.

A WebSphere business object based on an RFC-enabled function can contain nomore than two levels of hierarchy. Therefore, all simple parameters correspond toattributes of the top-level business object, and structure and table parameters


correspond to child business objects.

Table 37. Correspondence between RFC-Enabled Functions and Business Objects

RFC-enabled function InterfaceParameter

WebSphere Business Object for SAP

Simple field Attribute of the top-level business objectStructure Single-cardinality child business objectTable Multiple-cardinality child business objects

Note: Importing and exporting parameters can be simple field or structureparameters.

Figure 27 illustrates the association between a WebSphere business object and anRFC-enabled function (BAPI). The figure illustrates a fragment of a user-definedsap_bapi_po_create business object, which corresponds to the BAPI_PO_CREATEBAPI.

Chapter 19. Developing business objects for the RFC Server module 169

Supported verbsThe RFC Server module supports the standard verbs (Create, Update, Delete, andRetrieve) used by the WebSphere business integration system. For each supportedverb, an RFC-enabled function can have an associated method. Most RFC-enabledfunctions support one of the following operations: create, retrieve, update, anddelete.

Business object attribute propertiesThe properties of the attributes of a top-level business object differ depending onwhether the attribute represents a simple value, or a child or an array of childbusiness objects.

PURCHASEORDER (simple field)

PO_HEADER (structure)

PO_ITEMS (table)

BAPI_PO_CREATE

[Attribute]Name = Purchasing_document_numberAppSpecificInfo = :EPURCHASEORDER

Name = sap_po_headerType = sap_po_headerCardinality = 1

Name = sap_po_itemsType = sap_po_itemsCardinality = n

[Verb]Name = ServerAppSpecificInfo = sap.bapi.server.Bapi_po_create;Collab=POCollab

sap_bapi_po_create

Name = sap_po_headerAppSpecificInfo = IPO_HEADER:

sap_po_header

sap_po_items

Name = sap_po_itemsAppSpecificInfo = IPO_ITEMS:EPO_ITEMS

SAP sales order BAPITop-level business object

Child Business Objects

Figure 27. Mapping between a business object and a BAPI


v Table 38 lists and describes the properties of simple attributes of a top-levelbusiness object.

v Table 39 lists and describes the attributes that represent a child or array of childbusiness objects.

SAPODA generates the attribute properties as described in each table.

Table 38. Simple Attributes: Top-Level Business Object


Name Derived from the description of the RFC-enabled functionparameter. SAPODA replaces special characters (such asperiods, slashes, and spaces) with underscores.

Type Specifies the type of data. SAPODA sets the value to String.MaxLength Specifies the field length of the RFC-enabled function

parameter.IsKey Specifies whether the attribute is the key. The first simple

attribute of a business object defaults to the key attribute.The connector does not support using an attribute thatrepresents a child business object or an array of a childbusiness objects as a key attribute. Therefore, if the functionprovides only structure and table parameters, you mustinsert a simple attribute as the first attribute. SAPODAinserts the Dummy_key attribute as the first attribute, marksit as the key attribute, and sets appropriate values. Do notmodify those values. For more information, see “SupportingBAPIs” on page 142.

IsForeignKey SAPODA sets the value to false.IsRequired Specifies whether an attribute must contain a value.

SAPODA sets the value to false.AppSpecificInfo Contains the name of the RFC-enabled function that

corresponds to the associated attribute. The format is:IRFCFunctionParameterName:ERFCFunctionParameterNameFormore information on the application-specific information, see“Business object application-specific information” on page172.

Default Value Specifies the value to assign to this attribute if there is norun-time value. SAPODA does not set a value for thisproperty.

Table 39 lists and describes the attributes that represent a child or an array of childbusiness objects. SAPODA generates the properties described in the table below.

Table 39. Properties of an Attribute that Represents a Child or Children


Name The value is the name of the structure or table parametername. The format is: BOprefix_FunctionParameterName

Type The value is the type of child business object; in other words,the type is BOprefix_FunctionParameterName

ContainedObjectVersion SAPODA sets the value to 1.0.0.Relationship SAPODA sets the value to containment.IsKey SAPODA sets the value to false.IsForeignKey SAPODA sets the value to false.IsRequired Specifies whether an attribute must contain a value. SAPODA

sets the value to false.


Table 39. Properties of an Attribute that Represents a Child or Children (continued)


AppSpecificInfo Contains the name of the BAPI parameter that corresponds tothe associated attribute. The format is:IFieldName:EFieldNameFor more information on theapplication-specific information, see “Business objectapplication-specific information” on page 172.

Cardinality Structure parameters have single cardinality (1) and tableparameters have multiple cardinality (n).

Initializing attribute valuesEvery field in SAP has an initial value, as listed in Table 40. When the connectorreceives an event, the RFC Server-specific business object handler moves thesevalues from each SAP field to its corresponding business object attribute. Thebusiness object handler retains initial values from SAP with one exception: thecharacter data type. The business object handler converts a space in the SAP fieldto CxIgnore in the business object attribute. If you want any other value to beconverted to CxIgnore, the component that creates the business object mustperform the conversion. For example, when ICS is the integration broker, modifythe map to handle this conversion.

Table 40. Initial Field Values in SAP

Data Type Description Initial Value Set by BusinessObject Handler

C Character spaceN Numeric string 000...D Date (YYYMMDD) 00000000T Time (HHMMSS) 000000X Byte (hexadecimal) X00I Integer 0P Packed number 0F Floating point number 0.0

Business object application-specific informationApplication-specific information in business object definitions provides the RFCServer module with application-dependent instructions on how to process businessobjects. These instructions are specified at the business-object level, at the attributelevel (both for simple attributes and for attributes that represent a child or array ofchild business objects), and for verbs.

AppSpecificInfo for the server verb of the top-level businessobject

The connector uses the value of the server verb’s application-specific informationin the top-level business object to call the appropriate RFC Server-specific businessobject handler and to determine the destination collaboration for event processing.The value of the AppSpecificInfo property for the server verb specifies:v the package and classname for the RFC Server-specific business object handlerv the destination collaboration

The format is as follows:


AppSpecificInfo = bapi.server.BOHandler;Collab=CollaborationName

where BOHandler is the name of the class and CollaborationName is the name of thedestination collaboration.

SAPODA automatically adds the application-specific information for the serververb in top-level business object. For the value of the business object handler’sclassname, it uses the name of the RFC-enabled function. It does not provide avalue for the collaboration name parameter. Therefore, you must manually add thename of the collaboration.

Important: When WebSphere MQ Integrator (WMQI) is the integration broker, adummy value must be provided for the collaboration name parameter.The RFC Server-specific business object handler requires a value forthis parameter to process the event successfully.

Note: There is a one-to-one relationship between the WebSphere business objectfor SAP and the RFC Server-specific business object handler. The businessobject handler class files must exist in the \connectors\SAP\bapi\serverdirectory.

Important: You must include the value server before the business object handlername to identify that the RFC Server-specific business object handleracts as a server.

For example if you are supporting the BAPI_PO_CREATE RFC-enabled function andthe destination collaboration is called POCollab, then the verb application-specificinformation is as follows:AppSpecificInfo =bapi.server.Bapi_po_create;Collab=POCollab

AppSpecificInfo for attributesThe connector uses the value of an attribute’s application-specific information todetermine which importing, exporting, and table parameters to use. The value ofthis property contains the prefix I (for importing parameters) or E (for importingparameters). The prefix indicates whether the attribute value is used to pass datainto or out from the SAP application.

Because structure parameters can be either importing or exporting, they use eitheran I or an E before the parameter value. Because table parameters can pass data toand return data from a RFC-enabled function, they can have both I and Eparameter values.

Important: Always use a colon (:) separator when you specify parameter valueswith I and E. If specifying only an importing value, the colon mustfollow the value. If specifying only an exporting value, the colon mustprecede the value. If specifying both values, the colon follows theimporting value and precedes the exporting value.

Figure 28 illustrates the mapping between a business object and an exampleRFC-enabled function named BAPI_EXAMPLE. In the example, the simple attributes(Attribute_1, Attribute_2, and Attribute_3) specify only an importing or exportingparameter. The attribute that represents a child business object (Child_1) maps toan exporting structure parameter. The attribute that represents an array of childbusiness objects (Child_2) maps to a table parameter.


Each child business object has a simple attribute that maps to a field of thecorresponding structure or table (Attribute_11 and Attribute_14, respectively). Youcan find these fields by looking at the details of the BAPI.

Table 41 identifies the format of the application-specific information for specifickinds of attributes.

Table 41. AppSpecificInfo format for specific kinds of attributes


IParameterName:EParameterName SimpleITableName:ETableName Represents a child business object mapped to a table parameter

BAPI_EXAMPLE

[BusinessObjectDefinition]Name = Top_Level_BusObjAppSpecificInfo =

[Attribute]Name = Attribute_1AppSpecificInfo = IField_1:

Name = Attribute_2AppSpecificInfo = :EField_2

Name = Attribute_3AppSpecificInfo = IField_3:

Name =Child_1Type =Child_1Cardinality = 1AppSpecificInfo = :EReturn

Name = Child_2Type = Child_2Cardinality = nAppSpecificInfo = ITable_7:ETable_7

Top_Level_BusObj

IBM WebSphere BAPI business object

Child_2 (1)

[BusinessObjectDefinition]Name = Child_1AppSpecificInfo = :EReturn


FUNCTION BAPI_EXAMPLE.*"---------------------------------------------------*"*"

*" IMPORTING*" Field_1 ...*" Field_3 ...*" EXPORTING*" Field_2 ...*" Return ...*" TABLES*" Table_7 ...

ENDFUNCTION.

Child_1

[BusinessObjectDefinition]Name = Child_2AppSpecificInfo = ITable_7:ETable_7


Child_2

Figure 28. Mapping between a business object and an example BAPI


Table 41. AppSpecificInfo format for specific kinds of attributes (continued)


IStructureName:EStructureName Represents a child business object mapped to a structureparameter

IFieldName:EFieldName Represents an attribute of a child business object mapped to afield in a table or structure parameter

SAPODA automatically generates the appropriate application-specific informationfor your business object definition. It is recommended that you do not change theparameter names of the generated application-specific information.

Using generated business objects and business object handlersUse SAPODA to generate RFC-enabled function-specific business object definitionsand RFC Server-specific business object handlers for each RFC-enabled functionyou want to support. You can use the generated files with minimal modifications.

The only edit you must make is specifying the name of the destinationcollaboration in the verb application-specific information of the server verb.v When InterChange server (ICS) is the integration broker, this information is

required because a collaboration cannot explicitly subscribe to an event that ispushed to the connector. Therefore, the RFC Server-specific business objecthandler must determine the appropriate destination collaboration from thebusiness object’s meta-data, and then instantiate the collaboration.

v When WebSphere MQ Integrator (WMQI) is the integration broker, a dummyvalue is required for the RFC Server-specific business object handler to processthe event correctly.

Important: If the RFC-enabled function that you are using does not contain asimple field attribute, and SAPODA has created a Dummy_keyattribute as the key attribute, do not modify the values of this attribute.

After the business object definition and its corresponding RFC Server-specificbusiness object handler are generated, you must add the business object definitionto your WebSphere business integration system’s runtime environment.v Use Business Object Designer to load the business object definition into your

repository.

Note: Alternatively, if InterChange server (ICS) is the integration broker, you canuse the repos_copy command to load the definition into the repository.

v Use a system command to copy the RFC Server-specific business object handlerfiles to the following directory under the product directory:\connectors\SAP\bapi\server

The RFC Server-specific business object handler files are:v RFC-EnabledFunctionName.java

v RFC-EnabledFunctionName.class

For example, given the BAPI_PO_CREATE RFC-enabled function and a user-specifiedprefix of sap_, SAPODA generates the following:v sap_bapi_po_create (business object definition that includes all child business

objects)


v Bapi_po_create.java

v Bapi_po_create.class

Important: You can modify the name of the generated business object as well asthe name of its child business objects. To do so, you must edit thedefinition as a text file rather than in Business Object Designer. If youdo change a business object’s name, ensure that you also modify allreferences to the names that you change. Also, if you modify thenames of the generated.class file for the business object handler, youmust maintain the changes for the server verb application-specificinformation for the associated business object.

Tips and tricksThe following are tips and tricks for developing business objects and RFCServer-specific business object handlers.v “Multiple business objects contain the same return business object”v “Generated business object definition contains unnecessary attributes and child

business objects” on page 177v “Generated business object names are too long or fail your naming conventions”

on page 177v “Generated AppSpecificInfo for table parameters specify unnecessary

parameters” on page 177

Multiple business objects contain the same return businessobjectMost RFC-enabled functions use the same name for the return object. WhenSAPODA generates a business object definition, it creates a child business object torepresent this return object. If multiple business object definitions contain anidentically named child business object, you can add the definition for childbusiness object into the repository only once.

To enable multiple business objects to contain the return business object, you mustmodify the name of the return business object to be unique for each businessobject.

To rename the return business object, modify the definition of each business objectdefinition that contains it. The definition of the child business object is contained inthe same definition file as its parent.

To rename the child, do the following:1. Open the definition file for the top-level business object in a text editor.2. Locate the definition of the BOprefix_return child business object.3. Change the child’s name to be unique. For example, append a number to the

text (sap_return_2).4. Change all references in the definition to refer to the newly named child. For

example, change the value of the Type property for every attribute thatrepresents the child business object.

5. Save the changed definition file.6. Use Business Object Designer to load the newly named child business object




Generated business object definition contains unnecessaryattributes and child business objectsSAPODA interprets all RFC-enabled function interface parameters and, for eachone, it creates a corresponding WebSphere business object attribute or childbusiness object. To increase performance of business object processing, remove allunrequired attributes and business objects from the business object definition.

Note: SAPODA facilitates graphically removing all optional attributes and childbusiness objects before definition generation. For more information, see“Provide additional information” on page 250.

To increase performance of business object processing, you can also remove allunrequired importing and exporting table parameter values from theapplication-specific information.

After definition generation, you can use Business Object Designer to manually editthe business object definition if you require other changes. However, be carefulthat you remove only attributes that you absolutely will not be using.

Generated business object names are too long or fail yournaming conventionsSAPODA uses the name of the RFC-enabled function module to name thegenerated business object. You can use a text editor to modify a business object’sname.

Important: If you do change the name, ensure that you modify all references tothe name as well. However, do not modify the parameter names of thegenerated application-specific information.

To change a generated business object’s name:1. Save the definition to a file.2. Use a text editor to shorten or change the name.3. Use Business Object Designer to copy the newly named child business object



Generated AppSpecificInfo for table parameters specifyunnecessary parametersTable parameters can be both importing and exporting parameters. If you do notrequire importing or exporting of values for a table parameter, you can remove itfrom the application-specific information.

For example, for a create operation, if you do not need to return the table datafrom the SAP application after the create operation has completed, you can removethe exporting parameter value (such as Etable name).

For a retrieve operation, you do not need to specify any importing tableparameters. Therefore, you can remove the importing parameter value (such asItable name).

Note: You must remove the unrequired value from the AppSpecificInfo of theattribute in the parent that represents the child as well as from theAppSpecificInfo at the business-object level of the child business object. Donot remove the colon (:).


For example, to remove the ETable_7 exporting parameter in Figure 28 on page174, you would do the following:1. In the Child_2 attribute of the Top_Level_BusObj business object, change the

attribute’s AppSpecificInfo value to:ITable_7:

2. In the AppSpecificInfo at the business-object level of the Child_2 businessobject, change the value to:ITable_7:

3. In the AppSpecificInfo for each attribute of the child business object, usingAttribute_14 as an example, change the value to:IField_14:


Part 6. Hierarchical Dynamic Retrieve module



Chapter 20. Overview of the Hierarchical Dynamic Retrievemodule

v “Hierarchical Dynamic Retrieve module components”v “How the connector works” on page 182

This chapter describes the Hierarchical Dynamic Retrieve module of the IBMWebSphere Business Integration Adapter for mySAP.com (SAP R/3 Version 4.x).The Hierarchical Dynamic Retrieve module processes hierarchical or flat businessobjects. To process these requests, the connector retrieves data from the SAP R/3application version 3.1H or 3.1I.

Hierarchical Dynamic Retrieve module componentsThe Hierarchical Dynamic Retrieve module is written in Java and extends theVision Connector Framework. Because the module does not have its ownapplication-specific component, it uses the application-specific component forBAPI. Therefore, the module consists of the connector framework, theapplication-specific component for BAPI, the vDynRetBOH business object handler,and the SAP RFC libraries. SAP delivers the RFC libraries in Java and C. Theconnector is delivered and run as a Java archive (JAR) file.

Figure 29 illustrates the architecture of the Hierarchical Dynamic Retrieve module.

SAP R/3


SAP gateway

terminate()init()Hierarchical dynamicretrieve BO handler

doVerbFor()

SAP R/3 system

SAP RFC library

RFC_READ_TABLE

Connector framework andBAPI connector component


Figure 29. Hierarchical Dynamic Retrieve module architecture


How the connector worksThe connector gets a business object’s processing information from meta-dataspecified in the business object rather than from information hard-coded into theconnector. To obtain processing information from the business object, the connectormakes assumptions about the following:v The business object structurev The relationships between parent and child business objectsv The possible database representations of business objects

For information, see “Processing business objects” on page 6, and Chapter 22,“Developing business objects for the Hierarchical Dynamic Retrieve module”, onpage 185.

When the connector receives a request from the integration broker to perform anapplication operation, it obtains processing information from the verb specified forthe top-level business object.

The connector processes hierarchical business objects recursively; that is, itperforms the same steps for each child business object until it has processed allindividual business objects.

Note: The term hierarchical business object refers to a complete business object,including all the child business objects that it contains at any level. The termindividual business object refers to a single business object, independent ofany child business objects it might contain or that contain it. The termtop-level business object refers to the individual business object at the top ofthe hierarchy that does not itself have a parent business object.

When the integration broker sends a hierarchical business object with a Retrieveverb, the connector attempts to return a business object to the integration brokerthat exactly matches the current database representation of that business object. Inother words, the value of each simple attribute of every individual business objectthat the connector returns matches the value of its corresponding field in thedatabase. Also, the number of individual business objects in each array of thereturned business object match the number of children in the database for thatarray (unless the application-specific information limits the children to a subset).

To perform such a retrieval, the connector uses the primary key values in thetop-level business object to recursively descend through the corresponding data inthe database.


Chapter 21. Configuring the Hierarchical Dynamic Retrievemodule

v “Hierarchical dynamic retrieve module directories and files”v “Hierarchical dynamic retrieve module configuration properties”

This chapter describes the configuration of the Hierarchical Dynamic Retrievemodule of the IBM WebSphere Business Integration Adapter for mySAP.com (SAPR/3 Version 4.x). The SAP connector should be installed before performing theconfiguration tasks described in this chapter. For more information on installingthe connector, see Chapter 2, “Installing and configuring the connector”, onpage 11.

Hierarchical dynamic retrieve module directories and filesTable 42 lists the directories and files used by the Hierarchical dynamic Retrievemodule.

Table 42. Hierarchical dynamic retrieve module directories and files

File name Description



Hierarchical dynamic retrieve module configuration propertiesBefore you can run the Hierarchical dynamic Retrieve module, you must set thestandard and connector-specific configuration properties. At a minimum, you mustadd the class name for the BAPI module to the modules property. The classname issap.bapimodule.VBapiAgent.

For more information on configuring the connector configuration properties, see“Configuring the connector” on page 16 and Appendix A, “Standard configurationproperties for connectors”, on page 199.



Chapter 22. Developing business objects for the HierarchicalDynamic Retrieve module

v “Business object structure”v “Business object attribute properties” on page 192v “Business object application-specific information” on page 193

This chapter describes how the Hierarchical Dynamic Retrieve module processesbusiness objects and describes the assumptions the connector makes whenretrieving data. You can use this information as a guide to modifying existingbusiness objects or as suggestions for implementing new ones.

For a description of the Hierarchical Dynamic Retrieve module, see Chapter 20,“Overview of the Hierarchical Dynamic Retrieve module”, on page 181.

Business object structureThe connector assumes that every individual business object is represented by oneor more database tables, and that each simple attribute (that is, an attribute thatrepresents a single value, such as a String or Integer or Date) within the businessobject is represented by a column in one of those tables. The following situationsare valid:v The database tables might have more columns than the corresponding

individual business object has simple attributes (that is, some columns in thedatabase are not represented in the business object). Include in your design onlythose columns needed for the business object processing.

v The individual business object might have more simple attributes than thecorresponding database tables have columns (that is, some attributes in thebusiness object are not represented in the database). The attributes that do nothave a representation in the database have no application-specific information.

v Due to a restriction in the SAP API, the total number of characters for all of thedesired columns in each table represented by a single a business object cannotexceed 512. For more information, see “Handling long data rows” on page 188.

WebSphere business objects for SAP can be flat or hierarchical. All the attributes ofa flat business object are simple and represent a single value.

A hierarchical business object has attributes that represent a single child businessobject, an array of child business objects, or a combination of both. In turn, eachchild business object can contain a single child business object or an array ofbusiness objects, and so on.

Business object relationshipsThe Cardinality property of the attribute that represents the child or arraydetermines the type of relationship between parent and child:v A single-cardinality relationship occurs when the attribute in the parent

business object represents a child business object with cardinality 1.v A multiple-cardinality relationship occurs when an attribute in the parent

business object represents an array of child business objects with cardinality n.


The connector does not process a single-cardinality relationship differently from amultiple-cardinality relationship. However, there is a structural difference inforeign-key relationships when database tables have single-cardinality ormultiple-cardinality relationships. This difference is important when AdvancedOutbound Wizard generates a business object definition from an SAP DisplayTransaction:v In a single-cardinality relationship, the foreign key is determined by the primary

key in the child referencing a non- key attribute in the parent as its foreign key.Each child has at least one simple attribute that references a non-primary keyattribute in its parent as a foreign key. Figure 30 provides an example.

v In a multiple-cardinality relationship, the foreign key is determined by theprimary key in the child referencing the primary key attribute in the parent.Each child has at least one simple attribute that contains the parent’s primarykey as a foreign key. The child has as many foreign-key attributes as the parenthas primary-key attributes. Figure 32 provides an example.

In each case, the foreign-key relationship between the parent and child businessobjects is specified by the application-specific information of the key attributes ofthe child business object. For more information, see “Business object attributeproperties” on page 192 and “Application-specific information for simpleattributes” on page 194.

The next sections describe the following relationships among business objects:v “Single-cardinality relationship example”v “Multiple-cardinality relationship example” on page 187

Single-cardinality relationship exampleFigure 30 provides an example of a simple WebSphere business object developed toprocess customer objects in SAP. This example SAP_Customer has asingle-cardinality relationship to the example address object that it contains (theaddr_data[1] attribute has cardinality 1). The primary key attribute (address_id) inthe child business object references a non-primary key (address_id) in the parentbusiness object.

The following SELECT statements and their output illustrate retrieval of data fromthe tables represented by the business objects above:SELECT * FROM KNA1

KUNNR NAME1 ADRNR----- ------------- ----------

SAP_Customer

customer_id

Retrieve

address_id SAP_Address

Retrieve

address_id

.

.

.customer_name

..

addr_data[1]

citystate

Figure 30. Example customer and address relationship


10254 JOE’S PIZZA 220810255 LARRY’S HARDWARE 2209

SELECT * FROM ADRC

ADDRNUMBER CITY1 REGION---------- ---- -----2208 BURLINGAME CA2209 SAN FRANCISCO CA

In the example above, each customer (Joe’s Pizza and Larry’s Hardware) has asingle address. If the KUNNR and ADDRNUMBER columns are defined asprimary key constraints for their respective tables, the above structure ensures thateach customer can have only one associated address.

Note: For the sake of simplicity, the illustrations in this document do not displaythe application-specific information used by the connector to determine thetables and fields in the SAP application’s database.

Multiple-cardinality relationship exampleFigure 31 illustrates a multiple-cardinality relationship. In the example, ID=ABC isthe simple attribute with the parent’s primary key, and child[n] is the attributethat represents the array of child business objects.

Figure 32 provides an example of a different WebSphere business object developedto process customer objects in SAP. This example SAP_Customer has amultiple-cardinality relationship to the example sales view object that it contains(the sales_view_data[n] attribute has cardinality n). The primary key attribute(customer_id) in the child business object references the primary key (customer_id)in the parent business object.

Verb

Verb

ID..

ParentBOName

ID=ABC

Verb

..

child[n]

ID..

ChildBOName

Verb

ID..

..

OName

OName

Figure 31. Multiple-cardinality business object relationship

Chapter 22. Developing business objects for the Hierarchical Dynamic Retrieve module 187

The following SELECT statements and their output illustrate retrieval of data fromeach of these tables:SELECT * FROM KNA1

KUNNR NAME1----- -------------10254 JOE’S PIZZA10255 LARRY’S HARDWARE

SELECT * FROM KNVV

KUNNR VKORG VTWEG SPART---------- ----- ----- -----10254 EURP 01 1210255 EURP 01 0910255 USA 01 1310255 USA 01 14

In this example, Joe’s Pizza has one associated sales view record, whereas Larry’sHardware has three associated sales view records. The above structure allows eachcustomer to have zero or more associated sales view records.

Handling long data rowsSAP’s RFC_READ_TABLE function limits data retrieval to 512 bytes per row ofdata. Many SAP tables have more than 512 bytes of data per row. However, mostbusiness objects represent a small subset of all the database fields. Therefore, thetotal length of all attributes in a business object rarely exceeds the 512 bytemaximum.

In those cases that require the connector to retrieve more than 512 bytes of datafrom a single database table, the additional fields must be represented in separatesingle-cardinality child business objects. For example, if a business object mustrepresent 1500 bytes of data from a single table, the top-level business objectcontains at least two single-cardinality child business objects. Neither the parentnor either child has attributes whose total length (that is, the sum of theirmaximum length) exceeds 512 bytes.

Note: If a business object represents more than one database table, the total lengthof the values in the attributes that represent each table cannot exceed 512bytes. However, this limit does not pertain to the total length of the valuesof all attributes. For example, if a business object represents data from thetables that store information about Customers and CustomerPartners, the

SAP_Customer

customer_id

Retrieve

SAP_SalesView

Retrieve

customer_id

.

.

.customer_name

..

sales_view_data[n]

sales_orgdisti_channel

..

Figure 32. Example customer and sales view relationship


value of those attributes representing Customers cannot exceed 512 bytes,and the value of those attributes representing CustomerPartners cannotexceed 512 bytes, but the combined value of these attributes can exceed 512bytes.

Important: When you use Advanced Outbound Wizard to create business objectdefinitions, and it encounters an object that represents more than 512bytes of data from a single table, it stops adding attributes to the childbusiness object when the length exceeds 512 bytes. If your businessprocessing requires a business object to represent more than 512 bytesof data from a single table, you must manually create the additionalchild business objects.

Business object verb processingThis section outlines the steps the connector takes to handle a business objectrequest with the Retrieve verb. The connector processes hierarchical businessobjects recursively; that is, it performs the same steps for each child business objectuntil it has processed all individual business objects.

Business object comparisonWhen processing a retrieval request from the integration broker, the connector triesto return a business object that matches the current database representation of thatobject. In other words:v The value of each simple attribute in all individual business objects returned to

the integration broker matches the value of its corresponding field in thedatabase.

v The number of individual business objects in each array of the returned businessobject matches the corresponding number of children in the database.

Therefore, when the Hierarchical Dynamic Retrieve module receives a businessobject request with the Retrieve verb, it creates a response business object byrecursively descending the entire object in the application and retrieving thecurrent database representation. To perform the retrieval, the connector uses thespecified key values in the top-level request business object. Therefore, theresponse business object, which contains all the children of that top-level parent,may have different values for simple attributes and different child business objectsfrom the request business object.


For example, assume the integration broker passed the following SAP_Customerbusiness object to the Hierarchical Dynamic Retrieve module:

SAP_Customer

customer_id=2345

Retrieve

sales_view_data[n]

address_idaddress_data[1]

SAP_Address

SAP_SalesView

customer_id=2345sales_org=A

SAP_SalesView

customer_id=2345sales_org=B

SAP_SalesView

customer_id=2345sales_org=C

If, in the current database representation, the array of SAP_SalesView childbusiness objects contained by SAP_Customer 2345 does not include sales_org A,the connector’s response business object does not contain that child. Moreover, ifthe current database representation of SAP_Customer 2345 includes sales_org Dand sales_org E, the connector includes those children in the response businessobject. The business object that the SAP Hierarchical Dynamic Retrieve modulereturns to the integration broker at the end of retrieval is:

SAP_Customer

customer_id=2345

Retrieve

sales_view_data[n]

address_idaddress_data[1]

SAP_Address

SAP_SalesView

customer_id=2345sales_org=B

SAP_SalesView

customer_id=2345sales_org=C

SAP_SalesView

customer_id=2345sales_org=D

SAP_SalesView

customer_id=2345sales_org=E

Note: If the connector reads from multiple tables when creating a particularresponse business object, the business object does not match a singledatabase object. Instead, it matches selected fields from the specified tables.


Retrieve operationWhen retrieving a business object, the connector returns a status of eitherVALCHANGE if the operation was successful (regardless of whether the operationcaused changes to the business object), or FAIL if the operation failed.

The connector performs the following steps when retrieving a hierarchical businessobject:1. Removes all child business objects from the top-level business object that it

received from the integration broker.2. Calls the RFC_READ_TABLE function to retrieve the top-level business object

from the database.The connector uses key values in the request business object to build the SELECTstatement’s WHERE clause. The result of the retrieval causes one of the followingactions:v If the SELECT statement returns one record, the connector continues

processing the children and returns VALCHANGE (regardless of whether anyattribute changed value).

v If the SELECT statement returns no records, indicating that the top-levelbusiness object does not exist in the database, the connector returnsBO_DOES_NOT_EXIST.

v If the SELECT statement returns more than one record, the connectorcontinues processing the children and returns VALCHANGE.

3. Recursively retrieves all child business objects (single-cardinality andmultiple-cardinality).The connector calls the RFC_READ_TABLE function, which uses theappropriate foreign-key values to build the SELECT statement’s WHERE clause.The connector handles attributes marked as required in the following way:v If the business object‘s definition specifies that the child is required, the

retrieval must return a record. If not, the connector returns FAIL.v If the child is not required and the retrieval returns no records, indicating

that the child does not exist in the application, the connector leaves theparent’s attribute empty.

For each record returned, the connector performs the following actions:a. Creates a new individual business object of the correct type.b. Sets all of the current business object’s attributes based on the values in the

returned row.c. Recursively retrieves all of the current business object’s children.

Attention: If the retrieval of a single-cardinality child returns more thanone record, the connector returns only the first record.

d. Inserts the current business object with all of its children into theappropriate single-cardinality attribute or array attribute of the parent.

Note: A business object can have attributes that do not correspond to any databasecolumn, such as placeholder attributes. During retrieval, the connector doesnot change such attributes in the top-level business object; they remain set tothe values received from the integration broker. The application-specificinformation for these attributes must be blank.


Business object attribute propertiesBusiness object architecture defines various properties that apply to attributes. Thissection describes how the connector interprets these properties and describes howto set them when modifying a business object.

Name propertyEach business object attribute must have a unique name.

Type propertyEach business object attribute must be of type String, or the type of a childbusiness object or an array of child business objects.

Cardinality propertyEach business object attribute has the value of 1 or n in this property. All attributesthat represent a child business object or an array of child business objects also havea ContainedObjectVersion property (which specifies the child’s version number)and a Relationship property (which specifies the value Containment).

Max length propertyThe connector does not use this property. Although Advanced Outbound Wizardpopulates this property when it generates the business object, it does so only toprovide information.

Key propertyAt least one simple attribute in each business object must be specified as the key.To define an attribute as a key, set this property to true.

Important: The connector does not support specifying an attribute that representsa child business object or an array of child business objects as a keyattribute.

If the key property is set to true for a simple attribute, the connector adds thatattribute to the WHERE clause of the SELECT SQL statement that it generates whileprocessing the business object.

To maximize performance, it is recommended that you provide data for as manykey fields as possible.

To retrieve a child business object or children from an array of business objects, theconnector uses foreign keys in the WHERE clause of the SELECT statement. It does notuse the Key property of attributes in child business objects. For information onhow to specify an attribute in a child business object as a foreign key, see“Application-specific information for simple attributes” on page 194.

Foreign key propertyThe connector does not use this property. The connector obtains foreign-keyinformation from application-specific information. For more information, see“Application-specific information for simple attributes” on page 194.

Required propertyThe Required property specifies whether an attribute must contain a value.


v If an attribute that represents a child business object or an array of childbusiness objects is marked as required and the connector fails to retrieve anychild from the application, the retrieve operation fails.

v If a simple attribute is marked as required and the connector fails to retrieve thecorresponding row from the database, the retrieve operation fails. For example,if the connector reads from multiple tables for a business object and it fails toretrieve a row for a required simple attribute that represents a value in one ofthe tables, the entire retrieve fails.

AppSpecificInfoFor information on this property, see “Application-specific information for simpleattributes” on page 194.

Default value propertyThis property specifies a default value that the connector uses when generating theWHERE clause of a SELECT statement. This property is relevant only to simpleattributes that have been specified as key. For example, to cause the connector touse the default value specified for the Language attribute, you must specify theLanguage attribute as key.

Special value for simple attributesSimple attributes in business objects can have the special value, CxIgnore. When itreceives a business object from the integration broker, the connector ignores allattributes with a value of CxIgnore. It is as if those attributes were invisible to theconnector.

When the connector retrieves data from the database and the SELECT statementreturns a blank value for an attribute, the connector sets the value of that attributeto CxBlank by default.

Because the connector requires every business object to have at least one keyattribute, make sure that business objects passed to the connector have at least oneprimary or foreign key that is not set to CxIgnore.

Business object application-specific informationApplication-specific information in business object definitions provides theconnector with application-dependent instructions on how to process businessobjects. This information includes:v The class for the vDynRetBOH business object handler, which is provided in the

application-specific information for the verb of the top-level business object. Thisvalue is identical for all business objects that this module processes.

v Database and query information, which is provided in the application-specificinformation for simple attributes. The connector parses this information togenerate SELECT queries.

If you extend or modify an application-specific business object, make sure that theapplication-specific information in the business object definition matches the syntaxthat the connector expects.

The following sections discuss this functionality in more detail.


Application-specific information for the top-level businessobject’s verb

The verb of the top-level business object specifies the class for the vDynRetBOHbusiness object handler. This application-specific information should always be thefollowing:sap.bapi.vDynRetBOH

Application-specific information for simple attributesThe application-specific information for attributes specifies the followinginformation:v The name of the corresponding database tablev The name of the corresponding database columnv The foreign key relationship between an attribute in the current business object

and a parent or child business objectv The operand

The application-specific information format consists of four name-valueparameters, each of which includes the parameter name and its value. Eachparameter set is delimited from the next by a colon (:).

The format of attribute application-specific information is shown below. Squarebrackets ([ ]) surround an optional parameter. A vertical bar (|) separates themembers of a set of options. Reserve the colon as a delimiter.

TN=TableName:CN=ColumnName:[FK=[..]fk_attributeName]:[OP=GT|GE|EQ|NE|LE|LT|LIKE]

Figure 30 describes each name-value parameter.

Table 43. Name-Value Parameters in Attribute Application-Specific Information

Parameter Description

TN=TableName The name of the database tableCN=ColumnName The name of the database table column (field)FK=[..]fk_attribute Name The value of this property depends on whether the foreign-key relationship is

stored in the parent business object or the current business object:

v attributeName—specifies an attribute in the current business object; for moreinformation, see “Example: Current business object stores the foreign key” onpage 195

v ..attributeName—specifies an attribute in the parent business object

If an attribute is not a foreign key, do not include this parameter in theapplication-specific information.

OP=GT|GE|EQ|NE|LE|LT| LIKE The operand options are:

v GT—Greater Than

v GE—Greater than or Equal to

v EQ—EQual to (default option)

v NE—Not Equal to

v LE—Less than or Equal to

v LT—Less Than

v LIKE—Like

It is recommended that you specify EQ to maximize performance. If no operandis specified, the connector uses EQ.


The required parameters for each simple attribute are the table name and columnname. The operand defaults to EQ (equals). The following example illustrates thebasic format:TN=KNA1:CN=KUNNR

Important: Case is significant when specifying values for these parameters.

It is permissible for simple attributes within a business object to have no valuespecified (that is, zero length) for application-specific information fields. Theconnector ignores such attributes. This is a convenient way to ensure that theconnector does not process placeholder attributes used to separate adjacent arraysof child business objects.

If none of the application-specific information in any of a business object’sattributes provide sufficient information for the connector to build or execute aquery, the connector returns a failure.

Example: Current business object stores the foreign keyFigure 33 provides an example of a WebSphere business object with two foreignkeys that reference attributes within the business object. In this case, the businessobject represents data in two tables, one containing address data and the othercontaining lookup data for state/province and country abbreviations. To processthis data, the connector performs two table reads.

Attribute Information: Table 44 documents the table name, column name, key,and foreign-key for each attribute in the example SAP_Address:

Table 44. Description of example business object attributes

Attribute Table name Column name Key Foreign key Default

address_id ADRC ADDRNUMBER truecity ADRC CITY1 falsestate ADRC REGION falsecountry ADRC LAND1 falselanguage T005U SPRAS true Efk_country T005U LAND1 false FK=countryfk_state T005U BLAND false FK=statestate_description T005U BEZEI false

Attribute Application-Specific Information: Given the information in Table 44,the application-specific information for the fk_state attribute is:TN=T005U:CN=BLAND:FK=state

SAP_Address

Retrieve

address_id

.

.

city=Burlingamestate=CAcountry=USA

fk_statefk_country

state_description

Figure 33. Example: Current business object stores the foreign key


The application-specific information for the fk_country attribute is:TN=T005U:CN=LAND1:FK=country

SQL Queries: The following SELECT statements illustrate the WHERE clause that theconnector builds to retrieve data from the tables represented by SAP_Address:SELECT * FROM ADRC WHERE ADDRNUMBER = address_idValueSELECT * FROM T005U WHERE SPRAS = ‘E‘ AND LAND1 = countryValueAND BLAND = stateValue


Part 7. Appendixes



Appendix A. Standard configuration properties for connectors

New and deleted properties . . . . . . . . 199Configuring standard connector properties forWebSphere InterChange Server . . . . . . . 200

AdminInQueue. . . . . . . . . . . . 203AdminOutQueue . . . . . . . . . . . 203AgentConnections . . . . . . . . . . . 203AgentTraceLevel . . . . . . . . . . . 204ApplicationName . . . . . . . . . . . 204BrokerType . . . . . . . . . . . . . 204CharacterEncoding . . . . . . . . . . 204ConcurrentEventTriggeredFlows . . . . . . 205ContainerManagedEvents . . . . . . . . 205ControllerStoreAndForwardMode . . . . . 206ControllerTraceLevel . . . . . . . . . . 206DeliveryQueue . . . . . . . . . . . . 206DeliveryTransport . . . . . . . . . . . 206DuplicateEventElimination . . . . . . . . 207FaultQueue . . . . . . . . . . . . . 208JvmMaxHeapSize . . . . . . . . . . . 208JvmMaxNativeStackSize . . . . . . . . . 208JvmMinHeapSize . . . . . . . . . . . 208jms.FactoryClassName . . . . . . . . . 208jms.MessageBrokerName . . . . . . . . 208jms.NumConcurrentRequests . . . . . . . 208jms.Password . . . . . . . . . . . . 208

jms.UserName . . . . . . . . . . . . 209Locale . . . . . . . . . . . . . . . 209LogAtInterchangeEnd . . . . . . . . . 209MaxEventCapacity . . . . . . . . . . 209MessageFileName . . . . . . . . . . . 210OADAutoRestartAgent . . . . . . . . . 210OADMaxNumRetry . . . . . . . . . . 210OADRetryTimeInterval . . . . . . . . . 210PollEndTime. . . . . . . . . . . . . 210PollFrequency . . . . . . . . . . . . 210PollStartTime . . . . . . . . . . . . 211RequestQueue . . . . . . . . . . . . 211RepositoryDirectory . . . . . . . . . . 211ResponseQueue . . . . . . . . . . . 211RestartRetryCount . . . . . . . . . . . 211RestartRetryInterval . . . . . . . . . . 211SourceQueue . . . . . . . . . . . . 212SynchronousRequestQueue . . . . . . . . 212SynchronousResponseQueue . . . . . . . 212SynchronousRequestTimeout . . . . . . . 212TraceFileName . . . . . . . . . . . . 212WireFormat . . . . . . . . . . . . . 212

Configuring standard connector properties forWebSphere MQ Integrator . . . . . . . . . 212

Standard connector properties . . . . . . . 213

Connectors have two types of configuration properties:v Standard configuration propertiesv Connector-specific configuration properties

This chapter describes standard configuration properties, applicable to allconnectors. For information about properties specific to the connector, see theinstalling and configuring chapter of its adapter guide.

The connector uses the following order to determine a property’s value (where thehighest numbers override the value of those that precede):1. Default2. Repository (relevant only if InterChange Server is the integration broker)3. Local configuration file4. Command line

Note: In this document backslashes (\) are used as the convention for directorypaths. For UNIX installations, substitute slashes (/) for backslashes and obeythe appropriate operating system-specific conventions.

New and deleted propertiesThe following are the standard properties that have been either added or deletedin the 2.2 release of the adapters.v New properties

CharacterEncoding


LocalJVMMinHeapSizeJVMMaxHeapSizeJVMMaxStackSizeWireFormatMaxEventCapacityDuplicateEventEliminationjms.NumConcurrentRequestsContainerManagedEventsjms.Messagebrokername (replaces jms.BrokerName)

v Deleted properties

RequestTransportPingFrequencyTraceLevelAgentProxyTypeMaxThreadPoolSizeAnonymous ConnectionsGW NameAgent URLListener PortCertificate LocationLogFileNameTraceFileNamejms.BrokerName

Configuring standard connector properties for WebSphere InterChangeServer

This section describes standard configuration properties applicable to connectorswhose integration broker is WebSphere InterChange Server (ICS). Standardconfiguration properties provide information that is used by a configurablecomponent of InterChange Server called the connector controller. Like theconnector framework, the code for the connector controller is common to allconnectors. However, you configure a separate instance of the controller for eachconnector.

A connector, which consists of the connector framework and theapplication-specific component, has been referred to historically as the connectoragent. When a standard configuration property refers to the agent, it is referring toboth the connector framework and the application-specific component.

For general information about how connectors work with InterChange Server, seethe Technical Introduction to IBM WebSphere InterChange Server.

Important: Not all properties are applicable to all connectors that use InterChangeServer. For information specific to an connector, see its adapter guide.

You configure connector properties from Connector Configurator, which you accessfrom System Manager.


Note: Connector Configurator and System Manager run only on the Windowssystem. Even if you are running the connector on a UNIX system, you muststill have a Windows machine with these tools installed. Therefore, to setconnector properties for a connector that runs on UNIX, you must start upSystem Manager on the Windows machine, connect to the UNIXInterChange Server, and bring up Connector Configurator for the connector.

A connector obtains its configuration values at startup. If you change the value ofone or more connector properties during a runtime session, the property’s updatesemantics determine how and when the change takes effect. There are fourdifferent types of update semantics for standard connector properties:v Dynamic—The change takes effect immediately after it is saved.v Component restart—The change takes effect only after the connector is stopped

and then restarted in System Manager. This does not require stopping andrestarting the application-specific component or InterChange Server.

v Server restart—The change takes effect only after you stop and restart theapplication-specific component and InterChange Server.

v Agent restart—The change takes effect only after you stop and restart theapplication-specific component.

To determine the update semantics for a specific property, refer to the UpdateMethod column in the Connector Configurator window, or see the Update Methodcolumn of the table below.

The following table provides a quick reference to the standard connectorconfiguration properties. You must set the values of some of these propertiesbefore running the connector. See the sections that follow for explanations of theproperties.

Property Name Possiblevalues

Defaultvalue

Updatemethod

Notes

AdminInQueue valid JMS queue name CONNECTORNAME /ADMININQUEUE

AdminOutQueue valid JMS queue name CONNECTORNAME/ADMINOUTQUEUE

AgentConnections 1-4 1 server restart multi-threadedconnector only

AgentTraceLevel 0-5 0 dynamic

ApplicationName application name the value that is specified for theconnector name

componentrestart

value required

BrokerType ICS, WMQI ICS is requiredif your broker isICS

CharacterEncoding ascii7, ascii8,SJIS, Cp949, GBK,Big5,Cp297,Cp273,Cp280,Cp284,Cp037, Cp437

ascii7 componentrestart

ConcurrentEventTriggeredFlows 1 to 32,767 no value componentrestart

ContainerManagedEvents JMS or no value JMS guaranteedevent delivery

ControllerStoreAndForwardMode true or false true dynamicControllerTraceLevel 0-5 0 dynamicDeliveryQueue CONNECTORNAME/DELIVERYQUEUE component

restartJMS transportonly

DeliveryTransport MQ, IDL, or JMS IDL componentrestart

Appendix A. Standard configuration properties for connectors 201


Defaultvalue

Updatemethod

Notes

FaultQueue CONNECTORNAME/FAULTQUEUE componentrestart

DuplicateEventElimination True/False False componentrestart

JMS transportonly, ContainerManagedEvents must be<NONE>

JvmMaxHeapSize heap size inmegabytes

128m componentrestart

JvmMaxNativeHeapSize size of stack inkilobytes

128k componentrestart

JvmMinHeapSize heap size inmegabytes

1m componentrestart

jms.MessageBrokerName If FactoryClassNameis IBM, usecrossworlds.queue.manager.If FactoryClassNameis Sonic, uselocalhost:2506.

crossworlds.queue.manager server restart JMS transportonly

jms.FactoryClassName CxCommon.Messaging.jms.IBMMQSeriesFactoryorCxCommon.Messaging.jms.SonicMQFactory orany Java class name

CxCommon.Messaging.jms.IBMMQSeriesFactory

server restart JMS transportonly

jms.NumConcurrentRequests positive integer 10 componentrestart

JMS transportonly

jms.Password Any valid password server restart JMS transportonly

jms.UserName Any valid name server restart JMS transportonly

Locale en_US , ja_JP, ko_KR,zh_C, zh_T, fr_F, de_D,it_I, es_E, pt_BRNote: These are onlya subset of supportedlocales.

en_US componentrestart

LogAtInterchangeEnd true or false false componentrestart

MaxEventCapacity 1-2147483647 2147483647 dynamic RepositoryDirectory valuemust be<REMOTE>

MessageFileName path/filename Connectorname.txt orInterchangeSystem.txt

componentrestart

MonitorQueue any valid queue name CONNECTORNAME/MONITORQUEUE componentrestart

JMS transportonly,DuplicateEventEliminationmust be True

OADAutoRestartAgent true or false false dynamicOADMaxNumRetry a positive number 1000 dynamicOADRetryTimeInterval a positive number in

minutes10 dynamic

PollEndTime HH:MM HH:MM componentrestart



Defaultvalue

Updatemethod

Notes

PollFrequency a positive integer inmilliseconds

no (to disable polling)key (to poll only whenthe letter p is enteredin the connector’sCommand Promptwindow)

10000 dynamic

PollQuantity 1-500 1 componentrestart

Number ofitems to pollfrom application

PollStartTime HH:MM(HH is 0-23, MMis 0-59)

HH:MM componentrestart

RepositoryDirectory location whererepository is located

<REMOTE> componentrestart

<REMOTE> forICS broker

RequestQueue valid JMS queue name CONNECTORNAME/REQUESTQUEUE componentrestart

ResponseQueue valid JMS queue name CONNECTORNAME/RESPONSEQUEUE componentrestart

RestartRetryCount 0-99 3 dynamicRestartRetryInterval a sensible positive value

in minutes1 dynamic

SourceQueue valid MQSeries queuename

CONNECTORNAME/SOURCEQUEUE componentrestart

Valid only ifdeliverytransport is JMSand ContainerManagedEvents isspecified.

SynchronousRequestQueue CONNECTORNAME/SYNCHRONOUSREQUESTQUEUE

componentrestart

“SynchronousResponseQueue” onpage 219

CONNECTORNAME/SYNCHRONOUSRESPONSEQUEUE

componentrestart

SynchronousRequestTimeout 0 componentrestart

“WireFormat” on page 219 CwXML, CwBO cwxml agent restart CwXML fornon-ICS broker;CwBO ifRepositoryDirectory is<REMOTE>

AdminInQueueThe queue that is used by the integration broker to send administrative messagesto the connector.

The default value is CONNECTORNAME/ADMININQUEUE.

AdminOutQueueThe queue that is used by the connector to send administrative messages to theintegration broker.

The default value is CONNECTORNAME/ADMINOUTQUEUE.

AgentConnectionsThe AgentConnections property controls the number of IIOP connections openedfor request transport between an application-specific component and its connector


controller. By default, the value of this property is set to 1, which causesInterChange Server to open a single IIOP connection.

This property enhances performance for a multi-threaded connector by allowingmultiple connections between the connector controller and application-specificcomponent. When there is a large request/response workload for a particularconnection, the IBM WebSphere administrator can increase this value to enhanceperformance. Recommended values are in the range of 2 to 4. Increasing the valueof this property increases the scalability of the Visigenic software, which establishesthe IIOP connections. You must restart the application-specific component and theserver for a change in property value to take effect.

Important: If a connector is single-threaded, it cannot take advantage of themultiple connections. Increasing the value of this property causes therequest transport to bottleneck at the application-specific component.To determine whether a specific connector is single- or multi-threaded,see the installing and configuring chapter of its adapter guide.

AgentTraceLevelLevel of trace messages for the application-specific component. The default is 0.The connector delivers all trace messages applicable at the tracing level set orlower.

ApplicationNameName that uniquely identifies the connector’s application. This name is used bythe system administrator to monitor the WebSphere business integration systemenvironment. This property must have a value before you can run the connector.

BrokerTypeIdentifies the integration broker type that you are using. If you are using an ICSconnector, this setting must be ICS.

CharacterEncodingSpecifies the character code set used to map from a character (such as a letter ofthe alphabet, a numeric representation, or a punctuation mark) to a numeric value.

Note: Java-based connectors do not use this property. A C++ connector currentlyuses the value ASCII for this property. If you previously configured thevalue of this property to ascii7 or ascii8, you must reconfigure theconnector to use either ASCII or one of the other supported values. Todetermine whether a specific connector is written in Java or C++, see theinstalling and configuring chapter of its adapter guide.

Important: By default only a subset of supported character encodings display inthe drop list. To add other supported values to the drop list, you mustmanually modify the \Data\Std\stdConnProps.xml file in the productdirectory. For more information, see the appendix on ConnectorConfigurator.

Attention: Do not run a non-internationalized connector against InterChangeServer version 4.1.1 if you cannot guarantee that only ISO Latin-1 data will beprocessed.

The default value is ascii.


ConcurrentEventTriggeredFlowsDetermines how many business objects can be concurrently processed by theconnector controller for event delivery. Set the value of this attribute to the numberof business objects you want concurrently mapped and delivered. For example, setthe value of this property to 5 to cause five business objects to be concurrentlyprocessed. The default value is 1.

Setting this property to a value greater than 1 allows a connector controller for asource application to simultaneously map multiple event business objects, and tosimultaneously deliver them to multiple collaboration instances. Setting thisproperty to enable concurrent mapping of multiple business objects can speeddelivery of business objects to a collaboration, particularly if the business objectsuse complex maps. Increasing the arrival rate of business objects to collaborationscan improve overall performance in the system.

Note: To implement concurrent processing for an entire flow (from a sourceapplication to a destination application) also requires that the collaborationbe configured to use multiple threads and that the destination application’sapplication-specific component be able to process requests concurrently. Toconfigure the collaboration, set its Maximum number of concurrent eventsproperty high enough to use multiple threads. For an application-specificcomponent to process requests concurrently, it must be eithermulti-threaded, or be capable of using Connector Agent Parallelism and beconfigured for multiple processes (setting the Parallel Process Degreeconfiguration property greater than 1).

Important: To determine whether a specific connector is single- or multi-threaded,see the installing and configuring chapter of its adapter guide.

The ConcurrentEventTriggeredFlows property has no effect on connector polling,which is single-threaded and performed serially.

ContainerManagedEventsSetting this property to JMS allows a JMS-enabled connector with a JMS eventstore to provide guaranteed event delivery, in which an event is removed from thesource queue and placed on the destination queue as a single JMS transaction. Thisproperty can also be set to no value.

Notes:

1. When ContainerManagedEvents is set to JMS, you must also configure thefollowing properties to enable guaranteed event delivery: PollQuantity = 1 to500, SourceQueue = SOURCEQUEUE. In addition, you must configure a datahandler with the MimeType, DHClass, and DataHandlerConfigMOName(optional) properties. To set those values, use the Data Handler tab ofConnector Configurator. The fields for the values under the Data Handler tabwill be displayed only if you have set ContainerManagedEvents to JMS.

2. When ContainerManagedEvents is set to JMS, the connector does not call itspollForEvents() method, thereby disabling that method’s functionality.

The default value is JMS.

This property only appears if the DeliveryTransport property is set to the valueJMS.


ControllerStoreAndForwardModeSets the behavior of the connector controller after it detects that the destinationapplication-specific component is unavailable. If this property is set to true and thedestination application-specific component is unavailable when an event reachesInterChange Server, the connector controller blocks the request to theapplication-specific component. When the application-specific component becomesoperational, the controller forward the request to it.

Important: If the destination application’s application-specific component becomesunavailable after the connector controller forwards a service callrequest to it, the connector controller fails the request.

If this property is set to false, the connector controller begins failing all servicecall requests as soon as it detects that the destination application-specificcomponent is unavailable.

The default is true.

ControllerTraceLevelLevel of trace messages for the connector controller. The default is 0.

DeliveryQueueThe queue that is used by the connector to send business objects to the integrationbroker.

The default value is DELIVERYQUEUE.

DeliveryTransportSpecifies the transport mechanism for the delivery of events. Possible values are MQfor WebSphere MQ, IDL for CORBA IIOP, or JMS for Java Messaging Service.

If ICS is the broker type, the value of the DeliveryTransport property can be MQ,IDL, or JMS, and the default is IDL.

If WMQI is the broker type, JMS is the only possible Delivery Transport value.

The connector sends service call requests and administrative messages overCORBA IIOP if the value configured for the DeliveryTransport property is MQ orIDL.

WebSphere MQ and IDLUse WebSphere MQ rather than IDL for event delivery transport, unless you havecompelling reasons not to license and maintain two separate products. WebSphereMQ offers the following advantages over IDL:v Asynchronous communication – WebSphere MQ allows the application-specific

component to poll and persistently store events even when the server is notavailable.

v Server side performance – WebSphere MQ provides faster performance on theserver side. In optimized mode, WebSphere MQ stores only the pointer to anevent in the repository database, while the actual event remains in theWebSphere MQ queue. This saves the overhead of having to write potentiallylarge events to the repository database.


v Agent side performance – WebSphere MQ provides faster performance on theapplication-specific component side. Using WebSphere MQ, the connector’spolling thread picks up an event, places it in the connector’s queue, then picksup the next event. This is faster than IDL, which requires the connector’s pollingthread to pick up an event, go over the network into the server process, storethe event persistently in the repository database, then pick up the next event.

JMSEnables communication between the connector controller and client connectorframework using Java Messaging Service (JMS).

If you select JMS as the delivery transport, additional JMS properties such as″jms.MessageBrokerName,″ ″jms.FactoryClassName,″ ″jms.Password,″ and″jms.UserName,″ display in Connector Configurator. The first two of theseproperties are required for this transport.

Important: There may be a memory limitation if you use the JMS transportmechanism for a connector in the following environment:

v AIX 5.0v WebSphere MQ 5.3.0.1v InterChange Server (ICS) as the Integration broker

In this environment, you may experience difficulty starting the both the connectorcontroller (on the server side) and the connector (on the client side) due to memoryuse within the WebSphere MQ client. If your installation uses less than 768M ofprocess heap size, IBM recommends that you set:v The LDR_CNTRL environment variable in the CWSharedEnv.sh script.

This script resides in the \bin directory below the product directory. With a texteditor, add the following line as the first line in the CWSharedEnv.sh script:export LDR_CNTRL=MAXDATA=0x30000000

This line restricts heap memory usage to a maximum of 768 MB (3 segments *256 MB). If the process memory grows more than this limit, page swapping canoccur, which can adversely affect the performance of your system.

v The IPCCBaseAddress property to a value of 11 or 12. For more information onthis property, see the System Installation Guide for UNIX.

Notes:

v If your installation uses more than 768M of process heap size, this resolutionwould adversely affect product performance.

v If you run on AIX 4.3.3, you do not need to set the LDR_CNTRL environmentvariable. However, you must set IPCCBaseAddress to a value of 11 or 12.

DuplicateEventEliminationSetting this property to true enables a JMS-enabled connector with a non-JMSevent store to ensure that duplicate events are not delivered to the delivery queue.To make use of this feature, during connector development a unique eventidentifier must be set as the business object’s ObjectEventId attribute in theapplication specific code.

This property can also be set to false.

Note: When DuplicateEventElimination is set to true, you must also configure theMonitorQueue property to enable guaranteed event delivery.


FaultQueueIf the connector experiences an error while processing a message then theconnector moves the message to the queue specified in this property, along with astatus indicator and a description of the problem.

The default value is CONNECTORNAME/FAULTQUEUE.

JvmMaxHeapSizeThe maximum heap size for the agent (in megabytes). This property is applicableonly if the RepositoryDirectory value is <REMOTE>.

The default value is 128m.

JvmMaxNativeStackSizeThe maximum native stack size for the agent (in kilobytes). This property isapplicable only if the RepositoryDirectory value is <REMOTE>.

The default value is 128k.

JvmMinHeapSizeThe minimum heap size for the agent (in megabytes). This property is applicableonly if the RepositoryDirectory value is <REMOTE>.

The default value is 1m.

jms.FactoryClassNameSpecifies the class name to instantiate for a JMS provider. You must set thisconnector property when you choose JMS as your delivery transport mechanism(DeliveryTransport).

The default is CxCommon.Messaging.jms.IBMMQSeriesFactory.

jms.MessageBrokerNameSpecifies the broker name to use for the JMS provider. You must set this connectorproperty when you choose JMS as your delivery transport mechanism(DeliveryTransport).

The default is crossworlds.queue.manager.

jms.NumConcurrentRequestsSpecifies the maximum number of concurrent service call requests that can be sentto a connector at the same time. Once that maximum is reached, new service callsblock and wait for another request to complete before proceeding.

The default value is 10.

jms.PasswordSpecifies the password for the JMS provider. A value for this property is optional.

There is no default.


jms.UserNameSpecifies the user name for the JMS provider. A value for this property is optional.


LocaleSpecifies the language code, country or territory, and, optionally, the associatedcharacter code set. The value of this property determines such cultural conventionsas collation and sort order of data, date and time formats, and the symbols used inmonetary specifications. For more information, see the overview chapter of theconnector guide for an internationalized connector.

A locale name has the following format:ll_TT.codeset

where:

ll a two-character language code (usually in lowercase)

TT a two-letter country or territory code (usually inupper case)

codeset the name of the associated character code set; thisportion of the name is often optional.

The default is en_US.

Important: By default only a subset of supported locales display in the drop list.To add other supported values to the drop list, you must manuallymodify the \Data\Std\stdConnProps.xml file in the product directory.For more information, see the appendix on Connector Configurator.

Attention: If the connector has not been internationalized, the only valid valuefor this property is en_US. Do not run a non-internationalized C++ connectoragainst InterChange Server version 4.1.1 if you cannot guarantee that only ISOLatin-1 data will be processed. To determine whether a specific connector has beeninternationalized, see the installing and configuring chapter of its connector guide.

LogAtInterchangeEndSpecifies whether to log errors to InterChange Server’s log destination, in additionto the location specified in the LogFileName property. Logging to the server’s logdestination also turns on email notification, which generates email messages forthe MESSAGE_RECIPIENT specified in the InterchangeSystem.cfg file when errors orfatal errors occur. As an example, when a connector loses its connection to itsapplication, if LogAtInterChangeEnd is set to true, an email message is sent to thespecified message recipient. The default is false.

MaxEventCapacityThe maximum number of events in the controller buffer. This property is used byflow control and is applicable only if the value of the RepositoryDirectory propertyis <REMOTE>.

The value can be a positive integer between 1 and 2147483647. The default value is2147483647.


MessageFileNameThe name of the connector message file. The standard location for the message fileis \connectors\messages. Specify the message filename in an absolute path if themessage file is not located in the standard location.

If a connector message file does not exist, the connector usesInterchangeSystem.txt as the message file. This file is located in the productdirectory.

Important: To determine whether a specific connector has its own message file, seethe installing and configuring chapter of its adapter guide.

OADAutoRestartAgentSpecifies whether the Object Activation Daemon (OAD) automatically attempts torestart the application-specific component after an abnormal shutdown. Theproperties “OADMaxNumRetry” and “OADRetryTimeInterval” are related to thisproperty. This property is required for automatic restart.


OADMaxNumRetrySpecifies the maximum number of times that the OAD automatically attempts torestart the application-specific component after an abnormal shutdown.


OADRetryTimeIntervalSpecifies the number of minutes of the retry time interval that the OADautomatically attempts to restart the application-specific component after anabnormal shutdown. If the application-specific component does not start within thespecified interval, the OAD repeats the attempt as many times as specified in“OADMaxNumRetry”.

The default is 10.

PollEndTimeTime to stop polling the event queue. The format is HH:MM, where HH represents0-23 hours, and MM represents 0-59 seconds.

You must provide a valid value for this property. The default value is HH:MM, butmust be changed.

PollFrequencyThe amount of time between polling actions. Set PollFrequency to one of thefollowing values:v The number of milliseconds between polling actions.v The word key, which causes the connector to poll only when you type the letter

p in the connector’s Command Prompt window. Enter the word in lowercase.v The word no, which causes the connector not to poll. Enter the word in

lowercase.


The default is 10000.

Important: Some connectors have restrictions on the use of this property. Todetermine whether a specific connector does, see the installing andconfiguring chapter of its adapter guide.

PollStartTimeThe time to start polling the event queue. The format is HH:MM, where HH represents0-23 hours, and MM represents 0-59 seconds.


RequestQueueThe queue that is used by the integration broker to send business objects to theconnector.

The default value is REQUESTQUEUE.

RepositoryDirectoryThe location of the repository from which the connector reads the XML schemadocuments that store the meta-data of business object definitions.

When the integration broker is ICS, this value must be set to <REMOTE> becausethe connector uses the InterChange Server repository to obtain itsconnector-definition information

ResponseQueueDesignates the JMS response queue, which delivers a response message from theconnector framework to the integration broker. When the integration broker isInterChange Server, InterChange Server sends the request and waits for a responsemessage in the JMS response queue.

RestartRetryCountSpecifies the number of times the connector attempts to restart itself. When usedfor a parallel connector, specifies the number of times the master connectorapplication-specific component attempts to restart the slave connectorapplication-specific component.

The default is 3.

RestartRetryIntervalSpecifies the interval in minutes at which the connector attempts to restart itself.When used for a parallel connector, specifies the interval at which the masterconnector application-specific component attempts to restart the slave connectorapplication-specific component.

The default is 1.


SourceQueueDesignates the JMS source queue for the connector framework in support ofguaranteed event delivery for JMS-enabled connectors that use a JMS event store.For further information, see “ContainerManagedEvents” on page 205.

The default value is SOURCEQUEUE.

SynchronousRequestQueueDelivers request messages that require a synchronous response from the connectorframework to the broker. This queue is necessary only if the connector usessynchronous execution. With synchronous execution, the connector frameworksends a message to the SynchronousRequestQueue and waits for a response backfrom the broker on the SynchronousResponseQueue. The response message sent tothe connector bears a correlation ID that matches the ID of the original message.

SynchronousResponseQueueDelivers response messages sent in reply to a synchronous request from the brokerto the connector framework. This queue is necessary only if the connector usessynchronous execution.

SynchronousRequestTimeoutSpecifies the time in minutes that the connector waits for a response to asynchronous request. If the response is not received within the specified time thenthe connector moves the original synchronous request message into the fault queuealong with an error message.


TraceFileNameThe name of the file where the application-specific component writes tracemessages. Specify the filename in an absolute path. The default is STDOUT.

WireFormatMessage format on the transport.

Possible values are:v CwXMLif the broker is not ICS.v CwBOif the value of RepositoryDirectory is <REMOTE>.

Configuring standard connector properties for WebSphere MQIntegrator

This section describes standard configuration properties applicable to adapterswhose integration broker is WebSphere MQ Integrator Broker. For information onusing WebSphere Integrator Broker, see the Implementation Guide for WebSphere MQIntegrator Broker.

Important: Not all properties are applicable to all connectors that use WebSphereMQ Integrator Broker. For information specific to a connector, see itsadapter user guide.

You configure connector properties from Connector Configurator.


Note: Connector Configurator runs only on the Windows system. Even if you arerunning the connector on a UNIX system, you must still have a Windowsmachine with this tool installed. Therefore, to set connector properties for aconnector that runs on UNIX, you must run Connector Configurator on theWindows computer and copy the configuration files to the UNIX computerusing FTP or some other file transfer mechanism. For more informationabout Connector Configurator, see Appendix B, ″Connector Configurator.″

A connector obtains its configuration values at startup. If you change the value ofone or more connector properties during a runtime session, you must restart theconnector. Standard configuration properties provide information that is used bythe adapter framework and connector framework, and is common to allconnectors.

Standard connector propertiesThe following table provides a quick reference for standard connectorconfiguration properties. See the sections that follow for explanations of theproperties.

Name Possible values Default value

AdminInQueue valid JMS queue name CONNECTORNAME/ADMININQUEUEAdminOutQueue valid WebSphere MQ

queue nameCONNECTORNAME/ADMINOUTQUEUE

AgentTraceLevel 0-5 0ApplicationName application name AppNameConnectorBrokerType WMQI WMQICharacterEncoding ASCII, SJIS, Cp949, GBK,

Big5, Cp297, Cp273,Cp280, Cp284, Cp037,Cp437Note: These are only asubset of supportedvalues.

ASCII

ContainerManagedEvents JMS or no value JMSDeliveryQueue valid WebSphere MQ

queue nameCONNECTORNAME/DELIVERYQUEUE

DeliveryTransport JMS JMSDuplicateEventElimination true, falseFaultQueue valid WebSphere MQ

queue nameCONNECTORNAME/FAULTQUEUE

jms.FactoryClassName CxCommon.Messaging.jms.IBMMQSeriesFactory

jms.MessageBrokerName If FactoryClassName isIBM, usecrossworlds.queue.manager.If FactoryClassName isSonic, uselocalhost:2506.

crossworlds.queue.manager

jms.NumConcurrentRequests 10jms.Passwordjms.UserNameLocale en_US , ja_JP, ko_KR,

zh_C, zh_T, fr_F, de_D,it_I, es_E, pt_BRNote: These are only asubset of supportedlocales.

en_US


Name Possible values Default value

MessageFileName path/filename InterchangeSystem.txtPollEndTime HH:MM HH:MMPollFrequency milliseconds/key/no 10000PollStartTime HH:MM HH:MMRepositoryDirectory path/directory name Note:

Typically you mustchange this value fromthe default to whateverpath and directory namewas actually used whenyou installed the theconnector files.

C:\crossworlds\Repository

RequestQueue valid WebSphere MQqueue name

CONNECTORNAME/REQUESTQUEUE

ResponseQueue RESPONSEQUEUERestartRetryCount 0-99 3RestartRetryInterval an appropriate integer

indicating the number ofminutes between restartattempts

1

SourceQueue valid WebSphere MQqueue name

CONNECTORNAME/SOURCEQUEUE

SynchronousRequestQueue valid WebSphere MQqueue name

SynchronousResponseQueue valid WebSphere MQqueue name

SynchronousTimeout an appropriate integerindicating the number ofminutes the connectorwaits for a response to asynchronous request

0

WireFormat CwXML CwXML

AdminInQueueThe queue that is used by the integration broker to send administrative messagesto the connector.

The default value is CONNECTORNAME/ADMININQUEUE.

AdminOutQueueThe queue that is used by the connector to send administrative messages to theintegration broker.

AgentTraceLevelLevel of trace messages for the connector’s application-specific component. Thedefault is 0. The connector delivers all trace messages applicable at the tracinglevel set or lower.

ApplicationNameName that uniquely identifies the connection to the application. This name is usedby the system administrator to monitor the connector’s environment. When youcreate a new connector definition, this property defaults to the name of theconnector; when you work with the definition for an IBM WebSphere-deliveredconnector, the property is also likely to be set to the name of the connector. Set theproperty to a value that suggests the program with which the connector is


interfacing, such as the name of an application, or something that identifies a filesystem or website in the case of technology connectors.

BrokerTypeThis property is set to the value WMQI for connectors that are configured to useWebSphere MQ Integrator Broker as the integration broker.

CharacterEncodingSpecifies the character code set used to map from a character (such as a letter ofthe alphabet, a numeric representation, or a punctuation mark) to a numeric value.

Note: Java-based connectors do not use this property. A C++ connector currentlyuses the value ASCII for this property. If you previously configured thevalue of this property to ascii7 or ascii8, you must reconfigure theconnector to use either ASCII or one of the other supported values. Todetermine whether a specific connector is written in Java or C++, see theinstalling and configuring chapter of its adapter guide.

Important: By default only a subset of supported character encodings display inthe drop list. To add other supported values to the drop list, you mustmanually modify the \Data\Std\stdConnProps.xml file in the productdirectory. For more information, see the appendix on ConnectorConfigurator.

Attention: Do not run a non-internationalized connector against InterChangeServer version 4.1.1 if you cannot guarantee that only ISO Latin-1 data will beprocessed.

The default value is ascii.

ContainerManagedEventsSetting this property to JMS enables a JMS-enabled connector with a JMS eventstore to provide guaranteed event delivery, in which an event is removed from thesource queue and placed on the destination queue as a single JMS transaction. Thisproperty can also be set to no value.

Notes:

1. When ContainerManagedEvents is set to JMS, you must also configure thefollowing properties to enable guaranteed event delivery: PollQuantity = 1 to500, SourceQueue = SOURCEQUEUE. In addition, you must configure a datahandler with the MimeType, DHClass, and DataHandlerConfigMOName(optional) properties.

2. When ContainerManagedEvents is set to JMS, the connector does not call itspollForEvents() method, thereby disabling that method’s functionality.

The default value is JMS.

DeliveryQueueThe queue that is used by the connector to send business objects to the integrationbroker.

The default value is CONNECTORNAME/DELIVERYQUEUE.

DeliveryTransportSpecifies the transport mechanism for the delivery of events. The property defaultsto the value JMS, indicating that the Java Messaging Service (JMS) is used for


communication with WebSphere MQ Integrator. This property must be set to JMSwhen WebSphere MQ Integrator Broker is the integration broker. Otherwise, theconnector cannot start.

DuplicateEventEliminationSetting this property to true enables a JMS-enabled connector with a non-JMSevent store to ensure that duplicate events are not delivered to the delivery queue.To make use of this feature, during connector development a unique eventidentifier must be set as the business object’s ObjectEventId attribute in theapplication specific code.

This property can also be set to false.

Note: When DuplicateEventElimination is set to true, you must also configure theMonitorQueue property to enable guaranteed event delivery.

FaultQueueIf the connector experiences an error while processing a message then theconnector moves the message to the queue specified in this property, along with astatus indicator and a description of the problem.

The default value is CONNECTORNAME/FAULTQUEUE.

jms.FactoryClassNameSpecifies the class name to instantiate for a JMS provider.

The default is CxCommon.Messaging.jms.IBMMQSeriesFactory.

jms.MessageBrokerNameSpecifies the broker name to use for the JMS provider.

The default is crossworlds.queue.manager.

jms.NumConcurrentRequestsSpecifies the maximum number of concurrent service call requests that can be sentto a connector at the same time. Once that maximum is reached, new service callsblock and wait for another request to complete before proceeding.


jms.PasswordSpecifies the password for the JMS provider. A value for this property is optional.


jms.UserNameSpecifies the user name for the JMS provider. A value for this property is optional.


LocaleSpecifies the language code, country or territory, and, optionally, the associatedcharacter code set. The value of this property determines such cultural conventionsas collation and sort order of data, date and time formats, and the symbols used inmonetary specifications. For more information, see the overview chapter of theconnector guide for an internationalized connector.

A locale name has the following format:


ll_TT.codeset

where:

ll a two-character language code (usually in lowercase)

TT a two-letter country or territory code (usually inupper case)

codeset the name of the associated character code set; thisportion of the name is often optional.

The default is en_US.

Important: By default only a subset of supported locales display in the drop list.To add other supported values to the drop list, you must manuallymodify the \Data\Std\stdConnProps.xml file in the product directory.

Attention:

v WebSphere MQ Integrator supports only one locale at a time. Ensure that everycomponent of the installation (for example, all adapters, applications, and theintegration broker itself) is set to the same locale.

v If the connector has not been internationalized, the only valid value for thisproperty is en_US. Do not run a non-internationalized C++ connector againstInterChange Server version 4.1.1 if you cannot guarantee that only ISO Latin-1data will be processed. To determine whether a specific connector has beeninternationalized, see the installing and configuring chapter of its connectorguide.

MessageFileNameThe name of the connector message file. The standard location for the message fileis \connectors\messages. Specify the message filename in an absolute path if themessage file is not located in the standard location. This property defaults to thevalue InterchangeSystem.txt for new connector definitions and should be changedto the name of the message file for the specific connector.

PollEndTimeTime to stop polling the event queue. The format is HH:MM, where HH represents0-23 hours, and MM represents 0-59 seconds.


PollFrequencyThe amount of time between polling actions. Set the PollFrequency to one of thefollowing values:v The number of milliseconds between polling actions.v The word key, which causes the connector to poll only when you type the letter

p in the connector’s Command Prompt window. Enter the word in lowercase.v The word no, which causes the connector not to poll. Enter the word in

lowercase.

The default is 10000.


Important: Some connectors have restrictions on the use of this property. Todetermine whether a specific connector does, see the installing andconfiguring chapter of its adapter guide.

PollStartTimeThe time to start polling the event queue. The format is HH:MM, where HH represents0-23 hours, and MM represents 0-59 seconds.


RepositoryDirectoryThe path and name of the directory from which the connector reads the XMLschema documents that store the meta-data of business object definitions.

The default value is C:\crossworlds\repository. You must change this to thedirectory path that you are using for the \repository directory for your connector.Typically that path is established when you install the adapter product; forexample, C:\WebSphereAdapters\repository. The value must be a directory path.Do not use <REMOTE> as the RepositoryDirectory value for a connector that isnot using ICS as the broker.

RequestQueueThe queue that is used by the integration broker to send business objects to theconnector.

The default value is CONNECTORNAME/REQUESTQUEUE.

ResponseQueueDesignates the JMS response queue, which delivers a response message from theconnector framework to the integration broker.

RestartRetryCountSpecifies the number of times the connector attempts to restart itself. The defaultvalue is 3, indicating that the connector tries to restart 3 times. For instance, if aconnector is unable to log in to an application it fails to start, but with thisproperty set to the value 3 the connector tries a total of three times to start. Whenused in conjunction with the “RestartRetryInterval” property, this behavior enablesa connector to make several attempts at communicating with an application thatmight not reliably have a connection available all the time.

RestartRetryIntervalSpecifies the interval in minutes at which the connector attempts to restart itself.The default value is 1, indicating that the connector waits 1 minute in between itsrestart attempts.

SourceQueueDesignates the JMS source queue for the connector framework in support ofguaranteed event delivery for JMS-enabled connectors that use a JMS event store.For further information, see “ContainerManagedEvents” on page 205.

The default is CONNECTORNAME/SOURCEQUEUE.

SynchronousRequestQueueDelivers request messages that require a synchronous response from the connectorframework to WebSphere MQ Integrator Broker. This queue is necessary only if theconnector uses synchronous execution. With synchronous execution, the connectorframework sends a message to the SynchronousRequestQueue and waits for a


response back from WebSphere MQ Integrator Broker on theSynchronousResponseQueue. The response message sent to the connector bears acorrelation ID that matches the ID of the original message.

SynchronousResponseQueueDelivers response messages sent in reply to a synchronous request fromWebSphere MQ Integrator Broker to the connector framework. This queue isnecessary only if the connector uses synchronous execution.

SynchronousTimeoutSpecifies the time in minutes that the connector waits for a response to asynchronous request. If the response is not received within the specified time thenthe connector moves the original synchronous request message into the fault queuealong with an error message.


WireFormatThe data format for messages exchanged by the connector. The default value CwXMLis the only valid value, and directs the connector to compose the messages in XML.



Appendix B. Connector configurator

Before you can use a connector, you must create a connector configuration file thatsets the properties for the connector, designates the business objects and anymeta-objects that it supports, and sets logging and tracing values that theconnector will use at runtime. The configuration file may also contain propertiesfor the use of messaging and data handlers required by your connector.

Use Connector Configurator to create and modify the configuration file for yourconnector. If a configuration file has previously been created for your connector,you can use Connector Configurator to open the file and modify its settings. If noconfiguration file has yet been created for your connector, you can use ConnectorConfigurator to both create the file and set its properties.

When you complete a connector configuration file, the file is saved as an XMLdocument. You will save the XML document either as a project in System Manager(if ICS is your broker) or as a file with a *.cfg extension in a directory folder (ifWebSphere MQ Integrator Broker is your broker, or if you are using the file as alocal configuration file for ICS).

This appendix describes how to use Connector Configurator to:v Create a connector-specific property template for configuring your connectorv Create a configuration filev Set properties in a configuration file

Connector Configurator runs only in a Windows environment. If you are runningthe connector itself in a UNIX environment, use Connector Configurator in theWindows system in the network to modify the configuration file. Then copy thefile to your UNIX environment.

Note: Some properties in the connector configuration file use directory paths, andthese paths default to the Windows convention for directory paths. If youuse the connector configuration file in a UNIX environment, revise anydirectory path constructs in the configuration properties to match the UNIXconvention for directory paths.

Using Connector Configurator in an internationalized environmentConnector Configurator is internationalized and handles character conversionbetween the configuration file and the integration broker. Connector Configuratoruses native encoding. When it writes to the configuration file, it uses UTF-8encoding.

Connector Configurator supports non-English characters in:v All value fieldsv Log file and trace file path (specified in the Trace/Log files tab)

The drop list for the CharacterEncoding and Locale standard configurationproperties displays only a subset of supported values. To add other values to thedrop list, you must manually modify the \Data\Std\stdConnProps.xml file in theproduct directory.


For example, to add the locale en_GB to the list of values for the Locale property,open the stdConnProps.xml file and add the line in boldface type below:<Property name="Locale" isRequired="true" updateMethod="component restart">

<ValidType>String</ValidType><ValidValues>

<Value>ja_JP</Value><Value>ko_KR</Value><Value>zh_CN</Value><Value>zh_TW</Value><Value>fr_FR</Value><Value>de_DE</Value><Value>it_IT</Value><Value>es_ES</Value><Value>pt_BR</Value><Value>en_US</Value><Value>en_GB</Value>

<DefaultValue>en_US</DefaultValue></ValidValues>

</Property>

Starting Connector ConfiguratorConnector Configurator can be started and run in either of two modes:v Launched from System Managerv Independent of System Manager (stand-alone mode)

Running Configurator from System ManagerWhen you run Connector Configurator in conjunction with System Manager, youcanv Save connector configuration files (XML documents with the extension *.cfg) to a

directory that you specify, andv Save connector configuration files as components of System Manager projects. If

you are using ICS as your broker, this is a mandatory step before you deployyour configuration into the ICS.

Note: When you save a configuration file as a component of a System Managerproject, the file is stored in the designated project as an XML document filewith the extension *.con. It is not advisable to open the *.con file and edit itdirectly; instead, make any changes by opening the component in SystemManager.

To run Connector Configurator with System Manager, do any of the following:v In System Manager, right-click on the Connector folder of the Integration

Components Library (to create a new configuration), or right-click on aconnector configuration component within the Connector folder (to edit anexisting configuration), or

v From the System Manager menu, choose Tools>Connector Configurator, orv With System Manager already running, from Start>Programs choose IBM

WebSphere InterChange Server>IBM WebSphere Business IntegrationToolset>Development>Connector Configurator.

For details about using projects in System Manager and deploying to InterChangeServer, see the Implementation Guide for WebSphere InterChange Server.


Running Configurator independently of System ManagerWhen you run Connector Configurator without connecting to System Manager,you can save a connector configuration file (an XML document with the extension*.cfg) to a directory that you specify, but you cannot save or open a SystemManager project.

When you are creating a connector for use with a broker other than ICS, you donot need to connect to System Manager at any point in order to use the file. If youare creating a connector configuration for use with ICS as the broker, you may stillfind it useful on occasion to run Connector Configurator independently, and thenconnect to System Manager when you are ready to save the configuration file as acomponent of a System Manager project.

Choosing your brokerConnector Configurator can be used to configure connectors either for use withICS as the broker, or with WebSphere MQ Integrator Broker (also referred to asWMQI) as the broker.

Before you begin to configure the connector, you must choose the mode ofConnector Configurator that is appropriate for your broker. The mode that youchoose determines the properties that Connector Configurator will include in theconfiguration file. Choosing a broker is a mandatory step when you begin theprocess of creating a completely new configuration file. After a configuration filehas been created, you can optionally change the designated broker mode, using astandard configuration property. (This makes it possible to use an existingconfiguration file as a starting point for creating a configuration file that will beused with a different broker. However, be aware that revising a configuration filefor use with a different broker typically involves changing other configurationproperties as well, and not just the broker mode property.)

To choose a broker when you create a new configuration file (mandatory):v In the Connector Configurator home menu, choose File>New>Connector

Configuration. The New Connector Dialog displays.v In the Integration Broker field, choose either WMQI connectivity (for WebSphere

Integrator Broker) or ICS connectivity, according to the broker you are using.v Complete the remaining fields of the New Connector dialog, as described later

in this chapter for your specific broker.

To change your broker selection within an existing configuration file (optional):v Open the existing configuration file in Connector Configurator.v Select the Standard Properties tab.v In the Broker Type field of the Standard Properties tab, choose the value that is

appropriate for your broker. If you change the existing value, the available tabsand field selections of the properties screen will immediately refresh, to showonly those tabs and fields that appropriate for a configuration using the brokeryou have selected.

After you have chosen your broker type, you can complete the remainingConnector Configurator tasks for configuring your connector. When you save theconnector configuration file, Connector Configurator will save it in the brokermode that you have already selected. The title bar of Connector Configuratoralways displays the broker mode (such as ICS or WMQI) that ConnectorConfigurator is currently using.

Appendix B. Connector configurator 223

After you have completed the configuration file and set its properties, it will needto be deployed to the appropriate location for your connector.v If you are using ICS as your broker, save the configuration in a System Manager

project, and use System Manager to load the file into InterChange Server.v If you are using WebSphere MQ Integrator Broker as your broker, manually

copy the configuration file to its appropriate location, which must match exactlythe configuration file location specified in the startup file for your connector.

For further information about deployment, see the Implementation Guide forWebSphere InterChange Server (for using the connector with ICS as the broker), orthe Implementation Guide for WebSphere MQ Integrator Broker (for using the connectorwith MQ Integrator as the broker).

Using a connector-specific property templateTo create a configuration file for your connector, you can start with a previouslycreated connector configuration file (*.cfg), a connector definition file (*.txt) or arepository file (*.in or *.out), if any of these already exists for your connector. Forinstructions on using such existing files, see “Using an existing file” on page 228.

If none of those files exist, or if they are too dissimilar to the configurationrequirements of your connector, you can start instead by creating a template forthe connector-specific properties of your connector. You’ll create properties in thetemplate, define general characteristics and values for those properties, and specifyany dependencies between the properties. Then you’ll save the template and use itas the base for creating a new connector configuration file.

Creating a template of connector-specific propertiesTo create a template:1. Choose File>New>Connector-Specific Property Template.2. The Connector-Specific Property Template dialog appears, with the following

fieldsv Name

Enter a unique name that identifies the connector, or type of connector, forwhich this template will be used. You will see this name again when youopen the dialog for creating a new configuration file from a template.

v Find Template, and Template NameThe names of all currently available templates are displayed in the TemplateName display. Look for an existing template that would make a goodstarting point for your new connector template (such as a template whoseproperty definitions are a subset of the properties used by your connector).To see the connector-specific property definitions that are contained in anytemplate, select that template’s name in the Template Name display. A list ofthe property definitions contained in that template will appear in theTemplate Preview display.If you do not see any template that displays the connector-specific propertiesthat are used by your connector, you will need to create one. ConnectorConfigurator provides a template named None, containing no propertydefinitions, as a default choice.Choose a template from the Template Name display, enter that templatename in the Find Name field (or highlight your choice in Template Name),and choose Next.


Specifying general characteristicsThe Properties - Connector-Specific Property Template dialog appears. The dialoghas tabs for General characteristics of the defined properties and for Valuerestrictions. The General display has the following fields:v Edit properties

Use the buttons provided (or right-click within the Edit properties display) toadd a new property to the template, to edit or delete an existing property, or toadd a child property to an existing property.A child property is a property that is an attribute of another property--the″parent″ property. The parent property can obtain values, or child properties, orboth. These property relationships are commonly referred to as ″hierarchical″properties. Later, when you create a configuration file from these properties,Connector Configurator will identify hierarchical property sets with a plus signin a box at the left of any parent property.

v Property typeChoose one of these property types: Boolean, String, Integer, or Time.

v FlagsYou can set Standard Flags (IsRequired, IsDepracated, IsOverridden) or CustomFlags (for Boolean operators) to apply to this property

After you have made selections for the general characteristics of the property,choose the Value tab.

Specifying valuesThe Value tab enables you to set the maximum length, the maximum multiplevalues, a default value, or a value range for the property. To do so:1. Choose the Value tab. The display panel for Value replaces the display panel

for General.2. Select the name of the property in the Edit properties display.3. In the fields for Max Length and Max Multiple Values, make any necessary

changes. Note that the changes will not be accepted until and unless you alsoopen the Property Value dialog for the property, described in the next step.

4. Right-click the box in the left-hand corner of the Value display panel. AProperty Value dialog displays. Depending on the type of the property, thedialog allows you to enter either a value, or both a value and range. Enter theappropriate value or range, and click OK.

5. The Value panel refreshes to display any changes you made in Max Length andMax Multiple Values, and it displays a table with three columns:The Value column shows the value that you entered in the Property Valuedialog, and any previous values that you created.The Default Value column allows you to designate any of the values as thedefault.The Value Range shows the range that you entered in the Property Valuedialog.After a value has been created and appears in the grid, it can be edited fromwithin the table display. To make a change in an existing value in the table,select an entire row by clicking on the row number. Then right-click in theValue field and choose EditValue.


Setting dependenciesAfter you have finished making changes in both the General and the Value tabs,choose Next. The Dependencies dialog appears.

A dependent property is a property that is included in the template and used inthe configuration file only if the value of another property meets a specificcondition. To designate a property as being dependent and set the condition uponwhich it depends, do this:1. In the Available Properties display, select the property that will be made

dependent.2. In the Select Property field, use the drop-down menu to select the property that

will hold the conditional value.3. In the Condition Operator field, choose one of the following:

== (equal to)/= (not equal to)> (greater than)< (less than)>= (greater than or equal to)<=(less than or equal to)

4. In the Conditional Value field, enter the value that is required in order for thedependent property to be included in the template.

5. With the dependent property highlighted in the Available Properties display,click an arrow to move it to the Dependent Property display.

6. Click Finish. Connector Configurator stores the information you have enteredas an XML document, under \data\app in the\bin directory where you haveinstalled Connector Configurator.

Creating a configuration file from a connector-specifictemplate

After a connector-specific template has been created, you can use it to create aconfiguration file:1. Choose File > New>Connector Configuration.2. The New Connector dialog appears, with the following fields:

v NameEnter the name of the connector. Names are case-sensitive. The name youenter must be unique, must end with the word “connector”, and must beconsistent with the file name for a connector that is installed on the system;for example, enter PeopleSoftConnector if the connector file name isPeopleSoft.jar.

Important: Connector Configurator does not check the spelling of the namethat you enter. You must ensure that the name is correct.

v System ConnectivityChoose ICS or choose WMQI (for WebSphere MQ Integrator Broker)connectivity.

v Select Connector-Specific Property TemplateType the name of the template that has been designed for your connector.The names of all available templates are displayed in the Template Name


display. When you select a name in the Template Name display, the PropertyTemplate Preview display shows the connector-specific properties that havebeen defined in that template.After you have chosen the template you want to use, choose OK.

3. A configuration screen will display for the connector that you are configuring.The title bar of the configuration screen shows the broker that you are usingand the name that you have given to the connector. You can fill in all the fieldvalues to complete the definition now, or you can save the file and completethe fields later.When you are using the configuration screen, you can, if you wish, addadditional connector-specific properties, as described under “Settingapplication-configuration properties (ICS)” on page 230. Any such additionsbecome part of the configuration file that you are creating, but do not affect thetemplate that you used in creating the file.

4. To save the file, choose File > Save > to File or File > Save > Save to the project.To save to a project, you must be using ICS as the broker, and System Managermust be running. If you save as a file, the Save File Connector dialog displays.Choose *.cfg as the file type, verify in the File Name field that the name isspelled correctly and has the correct case, navigate to the directory where youwant to locate the file, and choose Save. The status display in the messagepanel of Connector Configurator indicates that the configuration file wassuccessfully created.

Important: The directory path and name that you establish here must matchthe connector configuration file path and name that you supply inthe startup file for the connector.

5. To complete the connector definition, enter values in the fields for each of thetabs of the Connector Configurator window, as described for your broker laterin this chapter.

Using Connector Configurator with ICS as the brokerTo use Connector Configurator to configure a connector that will be used with ICS,first select ICS as the broker mode in which you are running ConnectorConfigurator, as described under“Choosing your broker” on page 223.

In a typical ICS implementation, the configuration file that you create withConnector Configurator is not put into use until after you have deployed it to theICS server. You will perform that deployment (described in the ImplementationGuide for WebSphere InterChange Server) after you have finished using ConnectorConfigurator to complete the connector configuration file.

Completing a configuration fileThis topic assumes that you already have a starting point for your connectorconfiguration, either from an existing file (a connector definitions file, a repositoryfile, or a *.cfg file) or from an existing project in System Manager. If you do not,see “Creating a template of connector-specific properties” on page 224.

When you open a configuration file or a connector from a project, the ConnectorConfigurator window displays the configuration screen, with the attributes andvalues that Connector Configurator finds in the connector definition file.

The title of the configuration screen displays the type of the broker and the nameof the connector as specified in the file. Make sure the title indicates the


appropriate type for your broker--either ICS or WebSphere MQ Integrator Broker(for WMQI). If it does not, change the broker value before you configure theconnector. To do so:1. Under the Standard Properties tab, select the value field for the BrokerType

property. In the drop-down menu, select the value WMQI or ICS.2. The Standard Properties tab refreshes to display properties associated with the

selected broker. When you save the file, you retain this broker selection. Youcan save the file now or proceed to complete the remaining configurationfields, as described in “Setting the configuration file properties (WebSphere MQIntegrator Broker)” on page 234.

3. When you have finished making entries in the configuration fields, chooseFile>Save>To Project or File>Save>To File.If you are saving to file, choose *.cfg as the extension, choose the correctlocation for the file and choose Save.If multiple connector configurations are open, choose Save All to File to save allof the configurations to file, or choose Save All to Project to save all ICSconnector configurations to a System Manager project.Before it saves the file, Connector Configurator validates that values have beenset for all required Standard properties. If a required Standard property ismissing a value, Connector Configurator displays a message that the validationfailed. You must supply a value for the property in order to save theconfiguration file.

Using an existing fileYou may have an existing file available in one or more of the following formats:v A connector definition file. This is a text file that lists properties and applicable

default values for a specific connector. Some connectors include such a file in a\repository directory in their delivery package (the file typically has theextension .txt; for example, CN_XML.txt for the XML connector).

v An ICS repository file. Definitions used in a previous ICS implementation of theconnector may be available to you in a repository file that was used in theconfiguration of that connector. Such a file typically has the extension .in or.out.

v A previous configuration file for the connector. Such a file typically has theextension *.cfg.

Although any of these file sources may contain most or all of the connector-specificproperties for your connector, the connector configuration file will not be completeuntil you have opened the file and set properties, as described later in this chapter.

To use an existing file to configure a connector, you must open the file inConnector Configurator, revise the configuration, and then save the file as aconfiguration file (*.cfg file).

Follow these steps to open a *.txt, *.cfg, or *.in file from a directory:1. In Connector Configurator, choose File > Open > From File.2. In the Open File Connector dialog, choose one of the following file types to see

the available files:v Configuration (*.cfg)v ICS Repository (*.in, *.out)

Choose this option if a repository file was used to configure the connector inan ICS environment. A repository file may include multiple connectordefinitions, all of which will display when you open the file.


v All files (*.*)Choose this option if a *.txt file was delivered in the adapter package forthe connector, or if a definition file is available under another extension.

3. In the directory display, navigate to the appropriate connector definition file,select it, and choose Open.

Using an existing System Manager projectFollow these steps to open a connector configuration from a System Managerproject:1. Start System Manager. A configuration can be opened from or saved to System

Manager only if System Manager has been started.2. Start Connector Configurator.3. Choose File > Open > From Project.

Setting the configuration file properties (ICS)The topics in this section apply if you are using InterChange Server as theintegration broker. If you are using WebSphere MQ Integrator Broker as theintegration broker, see “Setting the configuration file properties (WebSphere MQIntegrator Broker)” on page 234. When you create and name a new connectorconfiguration file, or when you open an existing connector configuration file,Connector Configurator displays a configuration screen with tabs for the categoriesof required configuration values.

Connector Configurator requires values for properties in all of these categories:1. Standard Properties2. Connector-Specific Properties3. Supported Business Objects4. Associated Maps5. Resources6. Trace/Log File values7. Messaging (where applicable)8. Data handlers (applicable for connectors that use JMS messaging with

guaranteed event delivery)

Note: For connectors that use JMS messaging, an additional category may display,for configuration of data handlers that convert the data to business objects.

Important: Connector Configurator accepts property values in either English ornon-English character sets. However, the names of both standard andconnector-specific properties, and the names of supported businessobjects, must use the English character set only.

Standard properties differ from connector-specific properties as follows:v Standard properties of a connector are shared by both the application-specific

component of a connector and its broker component. All connectors have thesame set of standard properties. These properties are described in Appendix A ofeach adapter guide. You can change some but not all of these values.

v Application-configuration (application-specific) properties apply only to theapplication-specific component of a connector, that is, the component thatinteracts directly with the application. Each connector has application-specificproperties that are unique to its application. Some of these properties provide


default values and some do not; you can modify some of the default values. Theinstallation and configuration chapter of each adapter guide describes theapplication-specific properties and the recommended values.

The fields for Standard Properties and Connector-Specific Properties arecolor-coded to show which are configurable:v A field with a grey background indicates a standard property. You can change

the value but cannot change the name or remove the property.v A field with a white background indicates an application-specific property. These

properties vary according to specific needs of the application or connector. Youcan change the value and delete these properties.

v Value fields are configurable.v The Update Method field is informational and not configurable. This field

specifies the action required to activate a property whose value has changed.

Setting standard connector properties (ICS)To change the value of a standard property:1. Click in the field whose value you want to set.2. Either enter a value, or choose from the drop-down menu if one appears.3. After entering all values for the standard properties, you can do one of the

following:v To discard the changes, preserve the original values, and exit Connector

Configurator, choose File > Exit (or close the window), and choose No whenprompted to save changes.

v To enter values for other categories in Connector Configurator, choose the tabfor the category. The values you enter for Standard Properties (or othercategory) are retained when you move to the next category; when you closethe window, you are prompted to either save or discard the values that youentered in all of the categories as a whole.

v To save the revised values, choose File > Exit (or close the window) andchoose Yes when prompted to save changes. Alternatively, choose Save > ToFile from either the File menu or the toolbar.

Setting application-configuration properties (ICS)For application-specific configuration properties, you can add or change propertynames, configure values, delete a property, and encrypt a property:1. Right click in the top-left portion of the grid. A pop-up menu bar will appear.

Select Add to add a property or Add Child to add a child property for aproperty.

2. Enter a value for the property or child property.3. To encrypt a property, click the Encrypt box.4. Choose to save or discard changes, as described for Setting Standard Connector

Properties.

The Update Method displayed for each property indicates whether a component oragent restart is necessary to activate changed values.

Important: Changing a preset application-specific connector property name maycause a connector to fail. Certain property names may be needed bythe connector to connect to an application or to run properly.


Encryption for connector properties (ICS)Application-specific properties can be encrypted by clicking the Encrypt check boxin the Edit Property window. To decrypt a value, click to clear the Encrypt checkbox, enter the correct value in the Verification dialog box, and choose OK. If theentered value is correct, the value is decrypted and displays. The adapter guide foreach connector contains a list and description of each property and its defaultvalue.

If a property has multiple values, the Encrypt check box will appear for the firstvalue of the property. When you click the Encrypt check box, all values of theproperty will encrypted. To decrypt multiple values of a property, click to clear theEncrypt check box of the first value of the property, and then enter the correctvalue of the first value in the Verification dialog box. If the input value is a match,all multiple values will decrypt.

Update method (ICS)When WebSphere MQ Integrator Broker is the integration broker, connectorproperties are static. The Update Method is always Connector Restart. In otherwords, for changes to take effect, you must restart the connector after saving therevised connector configuration file.

Specifying supported business object definitions (ICS)This topic assumes that you have already created or acquired the intendedbusiness objects, created or acquired maps for them, and have saved both thebusiness object definitions and map definitions into System Manager projects.

Before you can make use of a connector (and before you can bind the connectorwith a collaboration’s ports), you must make selections under the SupportedBusiness Objects tab to specify the business objects that the connector will use. Youmust specify both generic business objects and corresponding application-specificbusiness objects, and you must specify associations for the maps between thebusiness objects.

Note: Some connectors require that certain business objects be specified assupported in order to perform event notification or additional configuration(using meta-objects) with their applications. For more information, see theConnector Development Guide for C++ or the Connector Development Guide forJava.

To specify that a business object definition is supported by the connector, or tochange the support settings for an existing business object definition, choose theSupported Business Objects tab and use the following fields:

Business object nameThese instructions assume that you started Business Object Designer with SystemManager running.

To designate that a business object definition is supported by the connector:1. Click in an empty field of the Business Object Name list. A drop-down list

displays, showing all the business object definitions that exist in the SystemManager project.

2. Click on a business object to add it.3. Set the Agent Support (described below) for the business object.


4. In the File menu of the Connector Configurator window, choose Save to Project.The revised connector definition, including designated support for the addedbusiness object definition, is saved to the project in System Manager.

To delete a business object from the supported list:1. To select a business object field, click the number to the left of the business

object2. From the Edit menu of the Connector Configurator window, choose Delete

Row. The business object is removed from the list display.3. From the File menu, choose Save to Project.

Note that deleting a business object from the supported list does not affect thecode of the connector, nor does it remove the business object definition itself fromSystem Manager. It does, however, change the connector definition and make thedeleted business object unavailable for use in this implementation of thisconnector.

Agent supportIndicating Agent Support for a business object means that the system will attemptto use that business object for delivering data to an application via the connectoragent.

Typically, application-specific business objects for a connector are supported bythat connector’s agent, but generic business objects are not.

To indicate that the business object is supported by the connector agent, put acheck in the Agent Support box. Note that the Connector Configurator windowdoes not validate your Agent Support selections.

Maximum transaction levelThe maximum transaction level for a connector is the highest transaction level thatthe connector supports.

For most connectors Best Effort is the only possible choice, because mostapplication APIs do not support the Stringent level.

You must restart the server for changes in transaction level to take effect.

Note: For this release, maximum transaction level of a connector is always BestEffort.

Associated maps (ICS)Each connector supports a list of business object definitions and their associatedmaps that are currently active in InterChange Server. This list displays when youselect the Associated Maps tab.

The list of business objects contains the application-specific business object whichthe agent supports and the corresponding generic object that the controller sendsto the subscribing collaboration. The association of a map determines which mapwill be used to transform the application-specific business object to the genericbusiness object or the generic business object to the application-specific businessobject.


If you are using maps that are uniquely defined for specific source and destinationbusiness objects, the maps will already be associated with their appropriatebusiness objects when you open the display, and you will not need (or be able) tochange them.

If more than one map is available for use by a supported business object, you willneed to explicitly bind the business object with the map that it should use.

The Associated Maps tab displays the following fields:v Business Object Name

These are the business objects supported by this connector, as designated in theSupported Business Objects tab. If you designate additional business objectsunder the Supported Business Objects tab, they will be reflected in this list afteryou save the changes by choosing Save to Project from the File menu of theConnector Configurator window.

v Associated MapsThe display shows all the maps that have been installed to the system for usewith the supported business objects of the connector. The source business objectfor each map is shown to the left of the map name, in the Business Object Namedisplay.

v ExplicitIn some cases, you may need to explicitly bind an associated map.Explicit binding is required only when more than one map exists for a particularsupported business object. When InterChange Server boots, it tries toautomatically bind a map to each supported business object for each connector.If more than one map takes as its input the same business object, the serverattempts to locate and bind one map that is the superset of the others. If there isnot a map that is the superset of the others, the server will not be able to bindthe business object to a single map, and you will need to set the bindingexplicitly.To explicitly bind a map:1. In the Explicit column, place a check in the check box for the map you want

to bind.2. Select the map that you intend to associate with the business object3. In the File menu of the Connector Configurator window, choose Save to

Project.4. Deploy the project to InterChange Server.5. Reboot the InterChange Server for the changes to take effect.

Resources (ICS)The Resource tab allows you to set a value that determines whether and to whatextent the connector agent will handle multiple processes concurrently usingconnector agent parallelism. Not all connectors support this feature, and use of thisfeature is not usually advised for connector agents that were designed in Java to bemulti-threaded, since it is usually more efficient to use multiple threads thanmultiple processes.

Setting trace/log file values (ICS)When you open a connector configuration file or a connector definition file,Connector Configurator uses the logging and tracing values of that file as defaultvalues. You can change those values in Connector Configurator.


To change the logging and tracing values:1. Choose the Trace/Log Files tab.2. For either logging or tracing, you can choose to write messages to one or both

of the following:v To console (STDOUT): Writes logging or tracing messages to the STDOUT

display.v To File: Writes logging or tracing messages to a file that you specify. To

specify the file, choose the directory button (ellipsis), navigate to thepreferred location, provide a file name, and choose Save. Logging or tracingmessage are written to the file and location that you specify.

Note: Both logging and tracing files are simple text files. You can use the fileextension that you prefer when you set their file names. For tracingfiles, however, it is advisable to use the extension .trace rather than.trc, to avoid confusion with other files that might reside on thesystem. For logging files, .log and .txt are typical file extensions.

Configuring messagingThe messaging properties are available only if you have set MQ as the value of theDeliveryTransport standard property and ICS as the broker type. These propertiesaffect how your connector will use queues.

Data handlersThe data handlers section is available for configuration only if you have designateda value of JMS for DeliveryTransport and a value of JMS forContainerManagedEvents. See the descriptions under ContainerManagedEvents inAppendix A, Standard Properties, for values to use for these properties. Foradditional details, see the Connector Development Guide for C++or the ConnectorDevelopment Guide for Java.

Setting the configuration file properties (WebSphere MQ IntegratorBroker)

The topics in this section apply if you are using WebSphere MQ Integrator (alsoreferred to as WMQI) as the integration broker.

When you create and name a new connector configuration file, or when you openan existing connector configuration file, Connector Configurator displays aconfiguration screen with tabs for the categories of required configuration values.

Connector Configurator requires values for properties in all of these categories:1. Standard Properties2. Connector-Specific Properties3. Supported Business Objects4. Trace/Log File values5. Data Handlers (where applicable)

Note: For connectors that use JMS messaging, an additional category may display,for configuration of data handlers that convert the data to business objects.For information about the values to use in the Data Handlers category, seethe Connector Development Guide for C++ or the Connector Development Guidefor Java.


Important: Connector Configurator accepts property values in either English ornon-English character sets. However, the names of both standard andconnector-specific properties, and the names of supported businessobjects, must use the English character set only.

Standard properties differ from connector-specific properties as follows:v Standard properties of a connector are shared by both the application-specific

component of a connector and its broker component. All connectors have thesame set of standard properties. These properties are described in Appendix A ofeach adapter guide. You can change some but not all of these values.

v Application-configuration (application-specific) properties apply only to theapplication-specific component of a connector, that is, the component thatinteracts directly with the application. Each connector has application-specificproperties that are unique to its application. Some of these properties providedefault values and some do not; you can modify some of the default values. Theinstallation and configuration chapter of each adapter guide describes theapplication-specific properties and the recommended values.

The fields for Standard Properties and Connector-Specific Properties arecolor-coded to show which are configurable:v A field with a grey background indicates a standard property. You can change

the value but cannot change the name or remove the property.v A field with a white background indicates an application-specific property. These

properties vary according to specific needs of the application or connector. Youcan change the value and delete these properties.

v Value fields are configurable.v The Update Method field is informational and not configurable. This field

specifies the action required to activate a property whose value has changed.

Setting standard connector propertiesTo change the value of a standard property:1. Click in the field whose value you want to set.2. Either enter a value, or choose from the drop-down menu if one appears.3. After entering all values for the standard properties, you can do one of the

following:v To discard the changes, preserve the original values, and exit Connector

Configurator, choose File > Exit (or close the window), and choose No whenprompted to save changes.

v To enter values for other categories in Connector Configurator, choose the tabfor the category. The values you enter for Standard Properties (or othercategory) are retained when you move to the next category; when you closethe window, you are prompted to either save or discard the values that youentered in all of the categories as a whole.

v To save the revised values, choose File > Exit (or close the window) andchoose Yes when prompted to save changes. Alternatively, choose Save > ToFile from either the File menu or the toolbar.

Setting application-configuration propertiesFor application-specific configuration properties, you can add or change propertynames, configure values, delete a property, and encrypt a property:1. Click in the field whose name or value you want to set.


2. Enter a name or value.3. To encrypt a property, click the Encrypt box.4. Choose to save or discard changes, as described for Setting Standard Connector

Properties.

The Update Method displayed for each property indicates whether a component oragent restart is necessary to activatechanged values.

Important: Changing a preset application-specific connector property name maycause a connector to fail. Certain property names may be needed bythe connector to connect to an application or to run properly.

Encryption for connector propertiesApplication-specific properties can be encrypted by clicking the Encrypt check boxin the Edit Property window. To decrypt a value, click to clear the Encrypt checkbox, enter the correct value in the Verification dialog box, and choose OK. If theentered value is correct, the value is decrypted and displays. The adapter guide foreach connector contains a list and description of each property and its defaultvalue.

Update methodWhen WebSphere MQ Integrator Broker is the integration broker, connectorproperties are static. The Update Method is always Agent Restart. In other words,for changes to take effect, you must restart the connector agent after saving therevised connector configuration file.

Specifying supported business object definitionsThe procedures in this section assume that you have already created:v Business object definitionsv MQ message set files (*.set files)

The *.set files contain message set IDs that Connector Configurator requires fordesignating the connector’s supported business objects. See the ImplementationGuide for WebSphere MQ Integrator Broker for information about creating the MQmessage set files.

Each time that you add business object definitions to the system, you must useConnector Configurator to designate those business objects as supported by theconnector.

Important: If the connector requires meta-objects, you must create message set filesfor each of them and load them into Connector Configurator, in thesame manner as for business objects.

To specify supported business objects:1. Select the Supported Business Objects tab and choose Load. The Open Message

Set ID File(s) dialog displays.2. Navigate to the directory where you have placed the message set file for the

connector and select the appropriate message set file (*.set) or files.3. Choose Open. The Business Object Name field displays the business object

names contained in the *.set file; the numeric message set ID for each businessobject is listed in its corresponding Message Set ID field. Do not change themessage set IDs. These names and numeric IDs are saved when you save theconfiguration file.


4. When you add business objects to the configuration, you must load theirmessage set files. If you attempt to load a message set that contains a businessobject name that already exists in the configuration, or if you attempt to load amessage set file that contains a duplicate business object name, ConnectorConfigurator detects the duplicate and displays the Load Results dialog. Thedialog shows the business object name or names for which there are duplicates.For each duplicate name shown, click in the Message Set ID field, and choosethe Message Set ID that you wish to use.

Setting trace/log file valuesWhen you open a connector configuration file or a connector definition file,Connector Configurator uses the logging and tracing values of that file as defaultvalues. You can change those values in Connector Configurator.

To change the logging and tracing values:1. Choose the Trace/Log Files tab.2. For either logging or tracing, you can choose to write messages to one or both

of the following:v To console (STDOUT): Writes logging or tracing messages to the STDOUT

display.v To File: Writes logging or tracing messages to a file that you specify. To

specify the file, choose the directory button (ellipsis), navigate to thepreferred location, provide a file name, and choose Save. Logging or tracingmessage are written to the file and location that you specify.

Note: Both logging and tracing files are simple text files. You can use the fileextension that you prefer when you set their file names. For tracingfiles, however, it is advisable to use the extension .trace rather than.trc, to avoid confusion with other files that might reside on thesystem. For logging files, .log and .txt are typical file extensions.

Configuring data handlersThe data handlers section is available for configuration only if you have designateda value of JMS for DeliveryTransport and a value of JMS forContainerManagedEvents. See the descriptions under ContainerManagedEvents inAppendix A, Standard Properties, for values to use for these properties. Foradditional details, see the Connector Development Guide for C++ or the ConnectorDevelopment Guide for Java

Using standard and connector-specific properties with ConnectorConfigurator

Connector configuration properties include both standard configuration properties(the properties that all connectors have) and connector-specific properties(properties that are needed by the connector for a specific application ortechnology).

Because standard properties are used by all connectors, you do not need to definethose properties within your configuration file; Connector Configurator already hasthose definitions, and it incorporates them into your configuration file as soon asyou create the file. For standard properties, your only task is to use ConnectorConfigurator to set the values of the properties.


For connector-specific properties, however, you will need to both define theproperties and set their values. Connector Configurator provides the interface forperforming both of these tasks.

Completing the configurationAfter you have created a configuration file for a connector and modified it, makesure that the connector can locate the configuration file when the connector startsup. To do so, open the startup file used for the connector, and verify that thelocation and file name used for the connector configuration file match exactly thename you have given the file and the directory or path where you have placed it.


Appendix C. Generating business object definitions usingSAPODA

v “Installation and usage”v “Using SAPODA in Business Object Designer” on page 243v “After using SAPODA” on page 258

This chapter describes SAPODA, an object discovery agent (ODA), which generatesbusiness object definitions for the IBM WebSphere Business Integration Adapter formySAP.com (SAP R/3 Version 4.x). Because the connector works with objects thatare based on IDoc types, BAPIs, and RFC-enabled function modules defined in anSAP system, SAPODA uses these objects to discover business object requirementsspecific to its SAP data source.

Note: Familiarity with IDoc types, BAPIs, and RFC-enabled function moduleswithin an SAP system can aid in understanding how SAPODA operates.

Installation and usageThis section discusses the following:v “Installing SAPODA”v “Before using SAPODA” on page 239v “Launching SAPODA” on page 241v “Running SAPODA on multiple machines” on page 242v “Working with error and trace message files” on page 242

Installing SAPODATo install SAPODA, use Installer for IBM WebSphere Business IntegrationAdapters. Follow the instructions in the WebSphere Business Integration AdaptersImplementation Guide for MQ Integrator, or, for InterChange System (ICS), the SystemInstallation Guide for UNIX or for Windows. When the installation is complete, thefollowing files are installed in the product directory on your system:v ODA\SAP\SAPODA.jar

v ODA\messages\SAPODAAgent.txt

v ODA\messages\SAPODAAgent_ll_TT.txt (message files specific to a to alanguage (_ll)country or territory (_TT))

v ODA\SAP\start_SAPODA.bat (Windows only)v ODA/SAP/start_SAPODA.sh (UNIX only)

Note: In this document, backslashes (\) are used as the convention for directorypaths. For UNIX installations, substitute slashes (/) for backslashes. Allproduct pathnames are relative to the directory where the product isinstalled on your system.

Before using SAPODAThis section describes the following:v “Before running SAPODA” on page 240v “Before using SAPODA” on page 241v “How to use SAPODA” on page 241


Before running SAPODABefore you can run SAPODA, you must:v Have a valid logon ID to the SAP systemv Have downloaded the SAP Java API, which SAP calls their Java Connector

(jCO).– If you have already followed instructions for installing the IBM WebSphere

Business Integration Adapter for mySAP.com on the same machine on whichyou install SAPODA, you should have already completed this step.

– If you are installing SAPODA prior to installing the adapter or on a differentmachine, you must download the SAP Java Connector.Make sure that you download the jCO for the operating system that yourconnector is running on. The jCO is available for download from SAP’swebsite at http://service.sap.com/connectors. You must have a SAPNetaccount to access the jCO (if you do not already have one, contact your localSAP BASIS administrator).

v Have copied the following jCO files to the appropriate directory and verifiedthat they are in the Path environment variable.

Important: If you cannot find these jCO files for an earlier version of jCO than1.1, contact technical support.

UNIX

– jCO.jar

– librfccm.o (AIX) or librfccm.so (Solaris)

– libjRFC11.so

– libjRFC12.so

If you have already followed instructions for installing the IBM WebSphereBusiness Integration Adapter for mySAP.com on the same machine on whichyou install SAPODA, copy these files from the /connectors/SAP directory to the/ODA/SAP directory. If you install SAPODA on a different machine from theconnector, after you unzip the jCO file, copy these four files to the /ODA/SAPdirectory.

End of UNIX

Windows

– jCO.jar

– librfc32.dll

– jRFC11.dll

– jRFC12.dll

If you have already followed instructions for installing the IBM WebSphereBusiness Integration Adapter for mySAP.com on the same machine on whichyou install SAPODA, copy these files from the \connectors\SAP directory to the\ODA\SAP directory. If you install SAPODA on a different machine from theconnector, after you unzip the jCO files, copy these four files to the \ODA\SAPdirectory.

For Windows, the librfc32.dll requires one or more C runtime dlls. The Cruntime dlls depend on the version of the SAP release being used. Through SAPrelease 45B, the C runtime dll required is msvcrt.dll version 5.00.7022 or newer.


Starting with SAP release 46A, the C runtime dlls required are msvcrt.dllversion 6.00.8267.0 or newer and msvcp60.dll version 6.00.8168.0 or newer. Thedll or dlls should be copied into the C:\WINNT\system32 directory. This dll orthese dlls may already be present and if not, can be found on the “PresentationCD” that contains the Windows SAPGUI setup in the folder<cddrive>:\GUI\Windows\Win32\system. See SAP OSS note number 0182805 formore information.

End of Windows

Before using SAPODABefore using SAPODA to generate a business object definition from an SAPIntermediate Document (IDoc) format, you must create the IDoc definition file foreach IDoc you want supported. SAPODA uses this file as input. For moreinformation, see “Generating the IDoc definition dile” on page 123.

How to use SAPODAAfter installing SAPODA, you must do the following to generate business objects:1. Launch the ODA.2. Launch Business Object Designer.3. Follow a six-step process in Business Object Designer to configure and run the

ODA.

The following sections describe these steps in detail.

Launching SAPODAYou can launch SAPODA in either of the following ways:v If you registered SAPODA with the Object Activation Daemon, you do not need

to manually start SAPODA. OAD maintains a list of registered ODA names, andlistens for requests to start the ODA. When you select the ODA’s name inBusiness Object Designer, OAD starts the ODA.For information on registering SAPODA, see the installation guide for yourWebSphere business integration system.

v If you have not registered SAPODA with the Object Activation Daemon, start itby running the appropriate file:

UNIXstart_SAPODA.sh

End of UNIX

Windowsstart_SAPODA.bat

End of Windows

Important: If you register the ODA with OAD, but run the script or batch filebefore selecting the ODA in Business Object Designer, Business ObjectDesigner may display two names when you press Find Agents: the oneregistered with OAD and the one in the script or batch file. If the twonames are identical, two identical names display. However, if bothnames represent the ODA in the same subnet and the ODA has been

Appendix C. Generating business object definitions using SAPODA 241

started manually, Business Object Designer connects only to themanually started ODA. In this case, Business Object Designer does notcall OAD. Attempting to start the second identically named ODA inthe same subnet causes the second ODA to quit with an error. Forinformation on changing the name of an ODA, see “Running SAPODAon multiple machines” on page 242.

You configure and run SAPODA using Business Object Designer. Business ObjectDesigner locates each ODA by the name specified in the AGENTNAME variable of eachscript or batch file. The default ODA name for this connector is SAPODA. Duringinstallation, if you register the ODA with an Object Activation Daemon, the wizardautomatically prefixes the hostname to the AGENTNAME value to make it unique.

Running SAPODA on multiple machinesIt is recommended that you change the name of the ODA when you run multipleinstances of it on different machines. To create additional uniquely namedinstances of SAPODA, specify a unique name in the AGENTNAME variable of thescript or batch file on each machine on which the ODA is installed.

To run the desired ODA, you select it by name from a list of available ODAs inBusiness Object Designer, which displays all active ODAs. Non-unique names cancause confusion when selecting the appropriate ODA to run.

A naming convention for assigning unique names is prefixing each name with thename of the host machine on which the ODA runs. If you registered the ODA withan Object Activation Daemon, you can use an ORB finder (osfind) to locateexisting CORBA object names on your network.

Figure 34 on page 244 illustrates the window in Business Object Designer fromwhich you select the ODA to run.

Working with error and trace message filesError and trace message files (the default is SAPODAAgent.txt) are located in\ODA\messages\, which is under the product directory. These files are language andcountry or territory specific and use the following naming convention:AgentNameAgent_ll_TT.txt

Where _ll is the language, and _TT is the country or territory, and where, whentaken together, constitiute a locale.

For instance, a Chinese mainland file name would be: SAPODAAgent_zh_CN.txt.

The same file name for Taiwan would be: SAPODAAgent_zh_TW.txt.

The Business Object Designer uses this information when selecting a message file.The default search order is to first look for the locale-specific file that matches thelocale in which the Business Object Designer is running. If that is not found, theBusiness Object Designer defaults to the English-US (en_US) version, and finally,the Business Object Designer looks for the file name without any locale orlanguage information.

If you create multiple instances of the ODA script or batch file and provide aunique name for each represented ODA, you can have a message file for eachODA instance. Alternatively, you can have differently named ODAs use the samemessage file. There are two ways to specify a valid message file:


v If you change the name of an ODA and do not create a message file for it, youmust change the name of the message file in Business Object Designer as part ofODA configuration. Business Object Designer provides a name for the messagefile but does not actually create the file. If the file displayed as part of ODAconfiguration does not exist, change the value to point to an existing file.

v You can copy the existing message file for a specific ODA, and modify it asrequired. Business Object Designer assumes you name each file according to thenaming convention. For example, if the AGENTNAME variable specifiesSAPODA1, the tool assumes that the name of the associated message file isSAPODA1Agent.txt. Therefore, when Business Object Designer provides thefilename for verification as part of ODA configuration, the filename is based onthe ODA name. Verify that the default message file is named correctly, andcorrect it as necessary.

Note: If a non-English locale is required, the same naming convention is stillapplicable; for example, SAPODA1Agent_zh_TW.txt.

Important: Failing to correctly specify the message file’s name when you configurethe ODA causes it to run without messages. For more information onspecifying the message file name, see “Configure initializationproperties” on page 245

During the configuration process, you specify:v The name of the file into which SAPODA writes error and trace informationv The name of the message filev The level of tracing, which ranges from 0 to 5.

Table 45 describes the tracing level values.

Table 45. Tracing levels

Trace Level Description

0 Logs all errors

1 Traces all entering and exiting messages for method

2 Traces the ODA’s properties and their values

3 Traces the names of all business objects

4 Traces details of all spawned threads

5 v Indicates the ODA initialization values for all of its properties

v Traces a detailed status of each thread that SAPODA spawned.

v Traces the business object definition dump

For information on where you configure these values, see “Configure initializationproperties” on page 245.

Using SAPODA in Business Object DesignerThis section describes how to use SAPODA in Business Object Designer togenerate business object definitions. For information on launching Business ObjectDesigner, see the Business Object Development Guide.


After you launch an ODA, you must launch Business Object Designer to configureand run it. There are six steps in Business Object Designer to generate a businessobject definition using an ODA. Business Object Designer provides a wizard thatguides you through each of these steps.

After starting the ODA, do the following to start the wizard:1. Open Business Object Designer.2. From the File menu, select the New Using ODA... submenu.

Business Object Designer displays the first window in the wizard, named SelectAgent. Figure 34 on page 244 illustrates this window.

To select, configure, and run the ODA, follow these steps:1. “Select the ODA”.2. “Configure initialization properties” on page 245.3. “Expand nodes and select objects” on page 247.4. “Confirm selection of objects” on page 249.5. “Generate the definition” on page 249 and, optionally, “Provide additional

information” on page 250.6. “Save the definition” on page 257.

Select the ODAFigure 34 illustrates the first dialog box in Business Object Designer’s six-stepwizard. From this window, select the ODA to run.

To select the ODA:1. Click the Find Agents button to display all registered or currently running

ODAs in the Located agents field.

Figure 34. Selecting the ODA


Note: If Business Object Designer does not locate your desired ODA, enter theAgent’s name directly into the Agent’s name field. If it still does notlocate the ODA, check the setup of the ODA.

2. Select the desired ODA from the displayed list.Business Object Designer displays your selection in the Agent’s name field.

Configure initialization propertiesThe first time Business Object Designer communicates with SAPODA, it promptsyou to enter a set of initialization properties as shown in Figure 35. You can savethese properties in a named profile so that you do not need to re-enter them eachtime you use SAPODA. For information on specifying an ODA profile, see theBusiness Object Development Guide.

Configure the SAPODA properties described in Table 46.

Table 46. SAPODA Properties

Row # Property Name Property Type Description

1 UserName String SAP logon user name (not required when generatinga definition only from an IDoc)

2 Password String SAP logon password (not required when generating adefinition only from an IDoc)

3 Client String SAP logon client number (not required whengenerating a definition only from an IDoc)

4 Language String SAP logon language (not required when generating adefinition only from an IDoc)

5 SystemNumber String SAP system number (not required when generating adefinition only from an IDoc)

Figure 35. Configuring Agent Properties


Table 46. SAPODA Properties (continued)

Row # Property Name Property Type Description

6 ASHostName String Host name of the SAP application server (notrequired when generating a definition only from anIDoc)

7 RFCTrace Single-card,multi-value

RFC tracing for the SAP system

8 DefaultBOPrefix String Text that is prepended to the name of the businessobject to make it unique.

You can change this later, if required, when BusinessObject Designer prompts you for Business ObjectSpecific Properties. For more information, see“Provide additional information” on page 250.

9 MaximumHits String Maximum number of objects returned during a nodesearch. For more information, see “Expand nodes andselect objects” on page 247.

Default is: 10010 TraceFileName String Name of the trace file. If the file does not exist,

SAPODA creates it in the \ODA\SAP directory. If thefile already exists, SAPODA appends to it.

SAPODA names the file according to the namingconvention. For example, if the agent is namedSAPODA, it generates a trace file namedSAPODAtrace.txt.

Use this property to specify a different name for thisfile.

11 TraceLevel Integer Level of tracing enabled for SAPODA

For more information on tracing, see “Working witherror and trace message files” on page 242.

12 MessageFile String Name of the error and message file.

SAPODA names the file according to the namingconvention. For example, if the agent is namedSAPODA, it names the message fileSAPODAAgent.txt.Important: The error and messagefile must be located in the \ODA\messages directory.

Use this property to verify or specify an existing file.13 File destination Directory Directory where ODA-generated files are stored.

Default is the default directory on the Windowssystem. It is recommended that you change thedefault setting to the\connectors\SAP\utilities\generatedfiles directory.

Important: Correct the name of the message file if the default value displayed inBusiness Object Designer represents a non-existent file. If the name isnot correct when you move forward from this dialog box, BusinessObject Designer displays an error message in the window from whichthe ODA was launched. This message does not popup in BusinessObject Designer. Failing to specify a valid message file causes the ODAto run without messages.


Expand nodes and select objectsAfter you configure all properties for SAPODA, Business Object Designer displaysa tree with the following the initial nodes:v IDoc types—You can:

– browse for extracted IDoc definition files– select IDocs in the SAP system (Basic IDoc Types and Extension Types)

Note: Extension Types are customer-defined IDoc Types.v BOR—select objects that represent BAPIs from the SAP applicationv RFC—select objects that represent RFC-enabled functions from the SAP

applicationv Dynamic Transaction and Retrieve—select the definitions that represent objects

from the dynamic transaction and dynamic retrieve metadata tables– HDR—select the tables required to represent an entity for SAP transactions

processed by the Hierarchical Dynamic Retrieve module

The nodes whose names are preceded by a plus sign (+) are expandable. Click onthem to display more nodes or leaves. SAPODA generates business objectdefinitions only from leaves.

Figure 36 illustrates this dialog box as originally displayed and with some nodesexpanded.

When a leaf’s name is displayed in bold type, you can select the leaf as the basisfor its business object to be generated. Use standard Windows procedures to selectmultiple leaves. In other words, depress the CTRL key while you use the mouse toselect multiple leaves.

1

2

Figure 36. Tree of schema with expanded nodes


Important: On a Windows system, if Business Object Designer cannot findrequired library files in the Path environment variable or the files arenot on the system, it displays a CORBA Exception while attempting toget the tree nodes. For information about these files, see “Beforerunning SAPODA” on page 240.

SAPODA uses a polymorphic node type that allows you to associate a flat file witha node. Initially the node displays without any leaves. You can browse a filesystem and select files to add to that node. The node is called polymorphicbecause its nature changes from a leaf to a branch when you associate it to one ormore files.

Figure 37 illustrates two ways of limiting the number of leaves that Business ObjectDesigner returns:v A context-sensitive menu that allows you to open a window for browsing files.

From this window, you can select which files to associate.v A wizard that allows you to specify search characters in the objects’ names.

After you have selected all desired leaves for object generation, click the Nextbutton. For information on how to filter the objects returned, see the BusinessObject Development Guide.

Examples of associating files to an IDOC

Example of searchingby RFC function name

Figure 37. Associating a file and entering search criteria


Confirm selection of objectsAfter you identify all the objects to be associated with a generated business objectdefinition, Business Object Designer displays the dialog box with only the selectedleaves and their node paths. Figure 38 illustrates this dialog box.

This window provides the following options:v To confirm the selection, click Next.v If the selection is not correct, click Back to return to the previous window and

make the necessary changes. When the selection is correct, click Next.

Generate the definitionAfter you confirm the selected objects, the next dialog box informs you thatBusiness Object Designer is generating the definitions.

Figure 39 illustrates this dialog box.

Figure 38. Confirming selection of nodes and leaves


Provide additional informationSAPODA prompts for additional information. The type of the top-level node (IDoctypes, BOR, RFC, or Dynamic Definitions) determines:v The set of properties that Business Object Designer displays in the BO Properties

window.v Whether Business Object Designer displays a second window that prompts you

for additional object generation information.

This section describes:v “IDoc Type: Providing additional information”v “BOR or RFC: Providing additional information” on page 254v “HDR: Providing additional information” on page 255

Note: No additional information is required for the Dynamic Transaction andRetrieval nodes.

IDoc Type: Providing additional informationSAPODA displays the BO Properties window to enable you to specify informationrequired for business objects based on IDoc types. The properties displayed in thiswindow differ depending on the source of the IDoc (an extracted file or adefinition in the SAP system) and whether the definition is being defined for theABAP Extension module. This section describes the following topics:v “The BO Properties Window—Common Properties” on page 251

Figure 39. Generating the Definition


v “The BO Properties Window—Property for IDoc Defined in the SAP System”v “The BO Properties Window—Specifying a Function module for the ABAP

Handler” on page 252

The BO Properties Window—Common Properties: Regardless of whetherSAPODA is generating the business object definition from an IDoc file or an IDocdefined in the SAP system, the BO Properties window for an IDoc type allows youto specify or change:v Prefix information.

The prefix is text prepended to the name of the business object to make itunique. If you are satisfied with the value you entered for the DefaultBOPrefixproperty in the Configure Agent window (Figure 35 on page 245), you do notneed to change the value here.

v Module typeThe module type choices are ALE or Extension. Because the ALE and the ABAPExtension modules have different requirements for their business objectdefinitions, it is important to specify which module will be using the businessobject.

Note: If there are multiple segments at the top-level of the IDoc, when SAPODAgenerates the business object definition for the ABAP Extension module, ituses the first IDoc segment to represent the top-level business object.SAPODA represents the other top-level segments as child business objects

The BO Properties Window—Property for IDoc Defined in the SAP System: Inaddition to the Prefix and module properties, the BO Properties windowrepresenting an IDoc defined in the SAP system also displays the Release property.You can use this property to identify an earlier version of the IDoc type.

Important: If the earlier version of the IDoc type has fewer segments than thecurrent version, SAPODA might create a definition with missingsegments or SAPODA might display an error indicating that thegeneration of the business object definition was unsuccessful. Thisinconsistency is due to different versions of SAP requiring differentAPI calls.

Figure 40 illustrates the two versions of the BO Properties window, one for anextracted IDoc Type definition file and one for an IDoc defined in the SAP system.


The BO Properties Window—Specifying a Function module for the ABAPHandler: If you select Extension as the module type, SAPODA prompts whetheryou want to enter function module names for any of the default verbs.

By default, when generating a definition for the ABAP Extension module,SAPODA specifies the following text for verb application-specific information atthe business object level of the top-level business object:

:/CWLD/IDOC_HANDLER

If you already know the function module names to pass to the ABAP handler,select Yes at this prompt. SAPODA displays the window illustrated in Figure 41.

BO Properties for an IDoc file

BO Properties foran IDoc file definedin SAP system

Figure 40. Providing additional information for an IDoc type business object


Figure 41 illustrates a BO Properties window in which two function modules havebeen specified.

After you save the business object definition, the General tab in Business ObjectDesigner displays the required application-specific information at the businessobject level of the topmost business object. Figure 42 illustrates such a windowwith the two specified function modules.

For more information about the ABAP handler, see “Business object data routing toABAP handlers” on page 51. For more information about application-specificinformation required by the ABAP Extension module, see “Developing businessobjects using IDocs” on page 70.

Figure 41. Specifying function modules for the ABAP handler

Figure 42. Specifying the ABAP handler in Business Object Designer


BOR or RFC: Providing additional informationThere are two BO Properties windows for a BOR or RFC Type. The propertiesdisplayed in the first window allow you to specify or change:v Prefix —If you are satisfied with the value you entered for the DefaultBOPrefix

property in the Configure Agent window (Figure 35 on page 245), you do notneed to change the value here.

v Verb —Specify the verb.v Server Support—If the definition is to be generated for the connector’s RFC

Server module, specify yes. If the definition is to be generated for theconnector’s BAPI module, specify no.

After you click OK to move forward from the first BO Properties window,SAPODA gives you the opportunity to reduce the size of the generated definition.You are prompted whether you want to remove from the definition any attributesthat represent optional parameters. This prompt displays only if there are optionalparameters to remove. Reducing the size of the definition can enhanceperformance later when the connector processes instances of the business object.

Figure 43 illustrates the properties displayed for a BOR or RFC-type object and theprompt that displays after you click OK.

If you click Yes in the prompt illustrated above, the second BO Properties windowdisplays. You can specify removal of each optional parameter of a BAPI/RFCinterface by changing its Value from Yes (include a corresponding attribute in thegenerated definition) to No (do not include an attribute).

If you click No in the prompt illustrated above, the final wizard displays. For moreinformation, see “Save the definition” on page 257.

Figure 44 illustrates the second BO Properties window.

1

2

Figure 43. Providing sdditional iInformation for BOR or RFC business objects


Important: A business object definition for a RFC-enabled function beginning with“Bapi” must have an attribute that represents a business objectcorresponding to a return structure or table. If a definition lacks suchan attribute, an error occurs when its corresponding generated code iscompiled. If you get this compile error, examine the BAPI to determineif SAP was using a different return structure. In this case, change thegenerated Java code to point to the proper parameter.

In addition to the specifications you provide in SAPODA, when you create adefinition for the RFC Server module, you may want to modify application-specificinformation after you save the business object definition. For more information, seeChapter 19, “Developing business objects for the RFC Server module”, on page 167.

HDR: Providing additional informationThere are two BO Properties window for an HDR table-based object. The propertydisplayed in the first window allows you to specify or change the business object’sprefix. If you are satisfied with the value you entered for the DefaultBOPrefixproperty in the Configure Agent window (Figure 35 on page 245), you do not needto change the value here.

Figure 45 illustrates this window.

Return parameter

Optional parameter

Figure 44. Specifying attributes for removal from the definition


In addition, only 512 bytes of information from a table can be returned. When atable returns more than 512 bytes, you will be presented with the dialog found inFigure 46. Answering “No” returns attributes (column descriptions) from thebeginning of the table until the 512 byte maximum is reached.

Answering “Yes” displays the second BO properties windows noted in Figure 47.The length in bytes for each attribute is provided in the window description. Youcan specific the inclusion or exclusion of an attribute for the business object bytoggling its value between “Yes” and “No.”

Figure 45. Providing additional information for an HDR business object

Figure 46. 512 byte warning


For more information, see Chapter 22, “Developing business objects for theHierarchical Dynamic Retrieve module”, on page 185.

Save the definitionAfter you provide all required information in the BO Properties dialog box andclick OK, Business Object Designer displays the final dialog box in the wizard.Here, you can save the definition to the server or to a file, or you can open thedefinition for editing in Business Object Designer. For more information, and tomake further modifications, see the Business Object Development Guide.

Note: When this step completes, Business Object Designer ends a manually-startedODA. To generate another definition, you must restart the ODA.

Figure 48 illustrates this dialog box.

Figure 47. Size and type of BO properties for an HDR business object


After using SAPODAThe business object definition that SAPODA generates from an IDoc Type, BAPIinterface, or RFC-enabled function does not contain all the information required forthe connector to process the business object. Therefore, after SAPODA finishesgenerating the definition, you must add all required information to the definition.Use Business Object Designer to examine and modify the business objectdefinition, and to reload or copy a revised definition into the repository.

For information on modifying a business object definition, see the Business ObjectDevelopment Guide. For information on the business object definition that a specificconnector module requires, and the modifications you must make before theconnector can process it, see the appropriate module’s documentation:v Chapter 13, “Developing business objects for the ALE module”, on page 123v Chapter 16, “Developing business objects for the BAPI module”, on page 145v Chapter 19, “Developing business objects for the RFC Server module”, on page

167

Figure 48. Saving business object definition


Appendix D. Connector feature list

This appendix details the features supported by the SAP R/3 SAP R/3 version 3.xconnector. For descriptions of these features, see “Appendix A: Connector FeatureChecklist” in the Connector Development Guide for Java.

Business object request handling featuresTable 47 lists business object request handling features supported by the connector.

Table 47. Business object request handling features

Category Feature Support Notes

CreateCreate verb Full

DeleteDelete verb Partial Typically, IBM WebSphere InterChange Server

uses the SAP’s Call Transaction API, whichsimulates a user’s interaction through a GUIto use a transaction. SAP, therefore, is incontrol of all database interaction. Each SAPtransaction determines whether or not aphysical or logical delete is executed. Further,any custom tables and transactions that acustomer may write may be available fordirect database interaction rather than usingthe Call Transaction API. In this case, clearly,physical deletes may be an option.

Logical delete Partial Typically, IBM WebSphere InterChange Serveruses the SAP’s Call Transaction API, whichsimulates a user’s interaction through a GUIto use a transaction. SAP, therefore, is incontrol of all database interaction. Each SAPtransaction determines whether or not aphysical or logical delete is executed. Further,any custom tables and transactions that acustomer may write may be available fordirect database interaction rather than usingthe Call Transaction API. In this case, clearly,physical deletes may be an option.

ExistExist verb Partial The connector operates by passing business

object data into the SAP application via anABAP function module. When this functionexecutes successfully, the connector returnsSUCCESS; when it fails, it returns FAIL.Because SAP is an open system, the connectorsupports an extremely open architecture,which allows an ABAP developer to doanything the SAP IDE permits. This includessupport for the development of any verb.

MiscAttribute names FullBusiness object names Full

Retrieve


Table 47. Business object request handling features (continued)


Ignore missing childobjects

No

Retrieve verb FullRetrieveByContent

Ignore missing childobjects

No

Multiple results NoRetrieveByContent verb Partial The connector operates by passing business

object data into the SAP application via anABAP function module. When this functionexecutes successfully, the connector returnsSUCCESS; when it fails, it returns FAIL.Because SAP is an open system, the connectorsupports an extremely open architecture,which allows an ABAP developer to doanything the SAP IDE permits. This includessupport for the development of any verb.

UpdateAfter-image support Partial The SAP connector operates by passing

business object data into the SAP applicationvia an ABAP function module. When thisfunction executes successfully, the connectorreturns SUCCESS; when it fails, it returnsFAIL. Because SAP is an open system, theSAP connector supports an extremely openarchitecture, which allows an ABAP developerto do anything the SAP IDE permits. Thisincludes support for the development of anyverb as well as any database manipulation orcode execution.

Delta support Partial The connector operates by passing businessobject data into the SAP application via anABAP function module. When this functionexecutes successfully, the connector returnsSUCCESS; when it fails, it returns FAIL.Because SAP is an open system, the connectorsupports an extremely open architecture,which allows an ABAP developer to doanything the SAP IDE permits. This includessupport for the development of any verb.

KeepRelations NoVerbs

Subverb support The connector operates by passing businessobject data into the SAP application via anABAP function module. When this functionexecutes successfully, the connector returnsSUCCESS; when it fails, it returns FAIL.Because SAP is an open system, the connectorsupports an extremely open architecture,which allows an ABAP developer to doanything the SAP IDE permits. This includessupport for the development of any verb.

Verb stability Full


Event notification featuresTable 48 lists the event notification features supported by the connector.

Table 48. Event Notification Features


Connector PropertiesEvent distribution Partial The connector implements this differently

from the standard, but provides all thefunctionality.

PollQuantity Fullevent table

Event status values Partial The connector has similar status values to thestandard values. However, it does not supportIN_PROGRESS.

Object key NoObject name FullPriority Partial The higher the number, the lower the priority.

Every time the connector polls, an eventpriority is decremented. When the priorityreaches 0, the event is processed.

Misc.Archiving FullCDK methodgotApplEvent()

Full

Delta event notification Partial The connector operates by passing businessobject data into the SAP application via anABAP function module. When this functionexecutes successfully, the connector returnsSUCCESS; when it fails, it returns FAIL.Because SAP is an open system, the connectorsupports an extremely open architecture,which allows an ABAP developer to doanything the SAP IDE permits. This includessupport for the development of any verb aswell as any database manipulation or codeexecution.

Event sequence FullFuture event processing FullIn-Progress event recovery N/APhysical delete event No Delete events are retrieved just like those of

any other verb.RetrieveAll FullSmart filtering FullVerb stability Full

General featuresTable 49 lists the general features supported by the connector.

Table 49. General features


Business ObjectAttributes

Foreign key No

Appendix D. Connector feature list 261

Table 49. General features (continued)


Foreign Key attributeproperty

Full

Key property Full During polling, the connector places theentire string of the event key in the firstattribute marked Key in the parent object.Retrieve processing in SAP relies on this toextract the key value from the incomingobject on a generic basis by checking thefirst attribute that is marked Key.

Max Length property NoRequired property Full This attribute is implemented by calling

initAndValidate() during doVerbFor().Connection Lost

Connection lost on poll FullConnection lost on requestprocessing

Full

Connection lost while idle NoConnector Properties

ApplicationPassWord FullApplicationUserName FullUseDefaults Partial This property is implemented for Create

and Update.Message Tracing General messaging Full

generateMsg() FullTrace level 0 FullTrace level 1 FullTrace level 2 FullTrace level 3 FullTrace level 4 FullTrace level 5 Full

Misc.CDK method logMsg() FullJava Package Names FullLogging messages FullMeta-data-driven design Partial The agent does not need to be recompiled

to support new business objects. However,additional code or data must be in place forthe target SAP system to handle newobjects.

NT service compliance FullTransaction support Partial Transaction support depends on the ABAP

processing in SAP, specifically the API thedeveloper uses. The connector operates bypassing business object data into the SAPapplication via an ABAP function module.When this function executes successfully,the connector returns SUCCESS; when itfails, it returns FAIL. Because SAP is anopen system, the connector supports anextremely open architecture, which allowsan ABAP developer to do anything the SAPIDE permits. This includes support for thedevelopment of any verb as well as anydatabase manipulation or code execution.

Special Value


Table 49. General features (continued)


CxBlank processing FullCxIgnore processing Partial The connector operates by passing business

object data into the SAP application via anABAP function module. When this functionexecutes successfully, the connector returnsSUCCESS; when it fails, it returns FAIL.Because SAP is an open system, theconnector supports an extremely openarchitecture, which allows an ABAPdeveloper to do anything the SAP IDEpermits. This includes support for thedevelopment of any verb as well as anydatabase manipulation or code execution.Therefore, a developer can handle CxIgnorevalues differently. These values are sent intoSAP as the literal ″/″.

Appendix D. Connector feature list 263


Index

AABAP Extension Module 31, 51

ABAP components 30and ABAP Handlers 32and Do_Verb_Nextgen 32and doVerbFor() 32and pollForEvents() 33business object conversion 48business object developmen 59business object processing 47calling 76components 29enabling 44event notification 33how it works 30initialization 31Java components 30testing business objects 85upgrading 95verb application-specific text 76

ABAP Handlers 32and create processing 53and delete processing 53and retrieve processing 53and update processing 53business object data reformatting 54data routing 51development APIs 62flat structure conversion 57processing business object data 53testing 87

ALE Modulesupported verbs 132

Architecture of the connector 3Archive table

deleting events 94event resubmission 93maintaining 92

BBAPI Module 140

business object development 145, 167business object naming conventions 146, 167components 139configuration 143files 143how it works 140initialization 140supported verbs 147verb application-specific text 149, 172

BAPI-Specific BOHandlercalling 149, 172

Batch program.See Event detection mechanism

BDC session, for Dynamic Transaction 66Business object data

and ABAP Handlers 53and SAP Native APIs 53reformatting 54

Business object data (continued)routing 51

Business object developmentABAP Extension Module overview 59ABAP Handler APIs 62BAPI Module overview 145, 167testing 85using Dynamic Retrieve 62using Dynamic Transaction 65using IDocs 70

Business object naming conventionsBAPI Module 146, 167

Business object processing 6, 31, 140, 161ABAP Extension Module 31, 47BAPI Module 140conversion to flat structure 57RFC Server Module 161verb application-specific text 6Vision Connector Framework 6

Business workflow.See Event detection mechanism

CClass

visionBOHandler 4visionConnector 4

Code enhancement.See Event detection mechanism

Configuringconnector-specific configuration properties 17the BAPI Module 143

Connectorarchitecture 3components 3Enabling the application for the ABAP Extension

Module 44installing 11, 12overview 3upgrading to Java-based version 26Vision Connector Framework 4

Connector components 4ABAP Extension Module 29BAPI Module 139connector modules 3, 5RFC Server Module 159Vision Connector Framework 3

Connector log filedisplaying 89managing 89setting options 89truncating the event log 90

Connector manager script 13Connector modules 5Connector transport files

installation 42overview 41verifying installation 44

CPIC user account 12Create processing

and ABAP Handlers 53


Create processing (continued)and IDoc Handlers 71

Current event queue.See Event queue

DData routing, ABAP Handler 51Delete processing

and ABAP Handlers 53and IDoc Handlers 71

Developing business objects.See Business object development

Dynamic Retrievedeveloping business objects 62tips and tricks 63

Dynamic Transactioncomposing a BDC session 66developing business objects 65tips and tricks 65, 66

EEvent

detection 37distribution 38, 44filtering 38, 45notification 33persistence 39polling 34priority 39, 45processing 36request 34return 36trigger 37

Event archive table.See Archive table

Event detection mechanismdesigning 77implementing 80

batch program 82business workflow 83code enhancement 80

overviewbatch program 79business workflow 79code enhancement 79

Event detection.See Event detection Mechanism

Event distribution, setting up 44Event filtering, setting up 45Event notification

ABAP Extension Module 33event polling 34Event triggering 37

Event pollingevent processing 36event request 34event return 36

Event priority, setting up 45Event queue

maintaining 92Event resubmission, from archive table 93Event trigger

event distribution 38event filtering 38

Event triggering 37event detection 37event persistence 39event priority 39event trigger 37

Eventsdeleting from archive table 94

FFlat structure, business object conversion 48Function module interface, CrossWorlds 61

GGateway service.

See SAP Gateway service

IIDoc Handlers

and create processing 71and delete processing 71and retrieve processing 73and update processing 71architecture 71object-specific 73translating data structures 73

IDocsdeveloping business objects 70

Initializing the ABAP Extension Module 31Initializing the BAPI Module 140Initializing the RFC Server Module 161Installing

connector prerequisites 11Java Connector (JCO) 11, 14, 240overview of connector transport files 41the BAPI Module 143the connector 11

JJava Connector installation 14JCO,

See Java Connector

LLog file.

See connector log fileLog, increasing tablespace size 45

MModules, connector 5Multiple connectors

starting 24

NNaming conventions.

See Business object naming conventionsNumber ranges, verifying 46


OOverview

ABAP Extension Module 29ABAP Extension Module business object development 59BAPI Module 139BAPI Module business object development 145, 167connector 3RFC Server Module 159

PPrerequisites, connector installation 11

RRemote Function Call.

See RFCResubmission

events from archive table 93Retrieve processing

and ABAP Handlers 53and IDoc Handlers 73

Return code 54RFC API, SAP’s 5RFC Library 5RFC Server Module 161

components 159configuration 165files 165how it works 161initialization 161

RFC ServerI Modulesupported verbs 170

SSAP Gateway service, monitoring connections 91SAP Native APIs

ABAP SQL 60Batch Data Communication (BDC) 61Call Transaction 60CrossWorlds implemented 60

SAP Native APIs, and business object data 53SAP RFC API 5Script

connector manager 13Starting multiple connectors 24

TTesting

ABAP Handlers 87business objects 85creating a test file 87preparing 85

Transport files.See Connector transport files

Truncating, the event log 90

UUnprocessed events, checking the event queue 92Update processing

and ABAP Handlers 53

Update processing (continued)and IDoc Handlers 71

UpgradingABAP Extension Module 95to the Java-based connector 26

VVerb application-specific text 6

ABAP Extension Module 76ABAP Handlers 52BAPI Module 141, 149, 172

VerbAppText.See Verb application-specific text

VerbsALEI Module support 132BAPI Module support 147RFC Server support 170

Vision Connector Framework 3, 4, 6how it works 5overview 4

Vision Connector Framework classvisionBOHandler 4visionConnector 4

visionBOHandler class 4visionConnector class 4

Index 267


Notices

IBM may not offer the products, services, or features discussed in this document inall countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or program(s) described in this publicationat any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM RTP Laboratory3039 Cornwallis RoadP.O. BOX 12195


Raleigh, NC 27709-2195U.S.A

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not necessarily tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

This information may contain examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples may includethe names of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

Programming interface informationProgramming interface information, if provided, is intended to help you createapplication software using this program.

General-use programming interfaces allow you to write application software thatobtain the services of this program’s tools.

However, this information may also contain diagnosis, modification, and tuninginformation. Diagnosis, modification and tuning information is provided to helpyou debug your application software.

Warning: Do not use this diagnosis, modification, and tuning information as aprogramming interface because it is subject to change.

Trademarks and service marksThe following terms are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States or other countries, or both:


IBMthe IBM logoAIXCrossWorldsDB2DB2 Universal DatabaseMQIntegratorMQSeriesTivoliWebSphere

Lotus, Domino, Lotus Notes, and Notes Mail are trademarks of the LotusDevelopment Corporation in the United States, other countries, or both.Microsoft,Windows, Windows NT, and the Windows logo are trademarks of MicrosoftCorporation in the United States, other countries, or both.

MMX, Pentium, and ProShare are trademarks or registered trademarks of IntelCorporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in theUnited States, other countries, or both.

Other company, product or service names may be trademarks or service marks ofothers. IBM CrossWorlds Servers V4.1, IBM CrossWorlds Full Toolset V4.1, IBMCrossWorlds Connectors V4.1, IBM CrossWorlds Collaborations V4.1, WebSphereBusiness Integration Adapters, V 2.0

Notices 271


��

Printed in U.S.A.

Adapter for mySAP.com (SAP R/3 V. 3.x) User Guide · New in release 4.6.x v The connector supports invocation of the ABAP Debugger for the appropriate function module when the connector

Documents