adr3 userguide

TIBCO Adapter™ for R/3

User’s GuideSoftware Release 5.1.0November 2003

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE TIBCO ADAPTER FOR R/3 USER’S GUIDE). USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIB, TIBCO, Information Bus, The Power of Now, TIBCO Rendezvous, TIBCO Designer, TIBCO Adapter, TIBCO ActiveEnterprise, TIBCO IntegrationManager, TIBCO Administrator, and TIBCO Hawk are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see the readme.txt file for the availability of this software version on a specific operating system platform.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

Copyright © 1997-2003 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

| iii

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviTIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviThird Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Terminology and Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxHow to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

SAP R/3 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2SAP R/3 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

TIBCO Adapter for R/3 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Adapter Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Logical Process Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6How the Adapter Works with SAP R/3 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Services Offered by the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Subscription Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Request-Response Invocation Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

IDoc Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17BAPI Transactional Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Data Chunking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Event Driven Inbound Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Inbound tRFC/IDoc reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Support for Multiple Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Multithreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Replacing Control Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Dynamic Subjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Validation of Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

TIBCO Adapter for R/3 User’s Guide

iv | Contents

QRFC Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Dynamic Application Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Schema Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Preparing your Environment for Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Operating System Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26SAP R/3 Application Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Pre-Installation Worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Installer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Upgrading an Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Uninstalling an Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Installation Registry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Microsoft Windows Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Installation History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Adapter Components and Compatible Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Adapter Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Required and Optional TIBCO Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Installing on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Installing the Adapter on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Combining Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Installation on UNIX Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Installing the Adapter on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Combining Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Post Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Permission Requirements on UNIX Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Prerequisites for Running the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Setting Environment Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Installation FAQs and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Speeding Up Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Running Out of Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Installation Errors on HPUX 11.00 64 bit Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Configuring TIBCO Hawk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Cannot Install the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Chapter 3 Preparing the SAP R/3 System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Design-time Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Run-time Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Outbound Messaging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Inbound Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Configurations in the SAP R/3 System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67


Contents | v

Chapter 4 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Creating a Project for the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Working with the Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Sample Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

RFC Outbound Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93RFC Inbound Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94IDoc Outbound Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94IDoc Inbound Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Convert the multi-file project to dat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Testing the Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Starting the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Outbound Connectivity Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Outbound Messaging Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Inbound Connectivity Test. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Inbound Messaging Test. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Stopping the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Chapter 5 Adapter Instance Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Adapter Instance Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Design-Time Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Run-time Inbound Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Run-time Outbound Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Adapter Services Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Logging Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Startup Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Monitoring Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Setting Inbound/Outbound Instance Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Configuration Task Sequence for a Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Configuration Task Sequence for a Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Configuration Task Sequence for Request-Response Invocation Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Configuration Task Sequence for Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Adding Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Adding Adapter Services Automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

IDocs Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147RFCs/BAPIs Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Publication Service Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Subscription Service Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167


vi | Contents

Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Schema Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Request-Response Invocation Service Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Schema Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Request-Response Service Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Schema Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Configuring Schema for Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Saving the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Chapter 6 Configuring the Adapter with Advanced Options . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Configuring Valid Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Adding Connections to an Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Adding an Active Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Setting up Active Connection Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Adding a Connection Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Setting up Connection Reference Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Assigning an Active Connection to an Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Adding a Client Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Selecting Client Connection Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Dedicated Application Server Client Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Configuring Dedicated Application Server Client Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Client Connection with Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Configuring Client Connection with Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Client Connection with saprfc.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Configuring Client Connection with saprfc.ini File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Setting Client Connection Advanced Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Setting up Client Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Setting Advanced Client Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Adding a Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Selecting Server Connection Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Default Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222


Contents | vii

Configuring Default Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

saprfc.ini Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Configuring Server Connection with saprfc.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Setting Server Connection Advanced Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Sample saprfc.ini Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Example: Registering an RFC Server Program Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Using Logon Groups to Connect an RFC Client to SAP Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Using a Dedicated Application Server to Connect an RFC Client Program to SAP R/3. . . . . . . . . . . . . . . 229

Configuring User Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Configuring User Exit for Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Configuring a User exit for a Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Saving an IDoc to a Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232Configuring IDoc Logging Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Configuring Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Configuring Subscription Services for Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Configuring Request-Response Services for Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Publishing IDocs on Dynamic Subjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Replacing Control Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Configuring Multiple Connections for Inbound Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Configuring Multiple Connections for Outbound Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246TIDManager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Interactions between the Adapter and the TIDManager server configuration . . . . . . . . . . . . . . . . . . . . . . 250Recovering from network outages and TIDManager server downtimes. . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Setting TIDManager Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Setting TIDManager Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Setting TIDManager Startup Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255Setting TIDManager Monitoring Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256Setting TIDManager General Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258Configuring a TIDManager server on JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Load Balancing Using Distributed Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Steps for Configuring Inbound Load-Balanced Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Multiple Inbound Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262Single Inbound Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Steps for Configuring Outbound Load-balanced Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

BDC Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268BDC Implementation through Standard RFC (ABAP4_CALL_TRANSACTION) . . . . . . . . . . . . . . . . . . . . 268BDC Implementation through Custom RFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Using Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Variable Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273


viii | Contents

Chapter 7 Program Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

SAP Language Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278TIBCO Adapter for R/3 Language Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279Getting Ready to Run Unicode on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Getting Ready to Run Unicode on UNIX Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282How the Adapter Handles Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Handling Multi-byte Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Chapter 8 Deploying and Starting an Adapter Using TIBCO Administrator Enterprise Edition . 287

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Create an EAR File in TIBCO Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Deploy the Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Deploying a 4.x TID Manager in TIBCO Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Start or Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Monitor the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Chapter 9 Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition 295

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Export the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Create a Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Set Properties in Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Assign Security Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Start or Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Start the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Monitor the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Adapter Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Properties File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Predefined Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307Obfuscating or Encrypting a Password in the Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Server Repository URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311TIBCO Rendezvous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311HTTP and HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Defining a urlFile to be Accessed via HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Local Project URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Install the Adapter as a Service on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Start and Stop the TIDManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Starting the TIDManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Stopping the TIDManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320


Contents | ix

Chapter 10 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Using the Adapter with a Revision Control System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Handling Large Internal Tables from SAP R/3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Enabling Data-Chunking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325IDoc Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Inbound BAPI Transactional Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Load-balanced configurations with BAPIs requiring explicit commit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Sample Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Invoking BAPIs/RFCs Using Transactional Semantics in SAP R/3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336Support for qRFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Multithreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339Multiple Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Posting BAPIs/RFCs/IDocs from multiple gateways in the Outbound Adapter. . . . . . . . . . . . . . . . . . . . . . 341Posting BAPIs/RFCs/IDocs from multiple RFC Destinations in the Outbound Adapter . . . . . . . . . . . . . . . 342Responding to dynamic changes in the Application Server environment. . . . . . . . . . . . . . . . . . . . . . . . . . 343Configuring the Inbound Adapter for multiple application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Event Driven Inbound Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Connectionless Inbound Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Performing explicit logon for RFCs/BAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Running an Adapter Instance on Two SAP R/3 Systems with a Single Connection . . . . . . . . . . . . . . . . . . . . . 353Sample Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Chapter 11 Monitoring the Adapter Using TIBCO Hawk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360Starting TIBCO Hawk Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361The Auto-Discovery Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362Invoking Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363Available Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

Appendix A Trace Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Appendix B SAP R/3 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

The SAP R/3 Business Application System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Exchanging Business Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477

Appendix C Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482

Appendix D SAP R/3 ALE Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489


x | Contents

SAP R/3 Graphic User Interface Version 3.1H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

Appendix E Wireformat Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

Backward Compatible RV Message Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531


| xi

Figures

Figure 1 Inbound and Outbound Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Figure 2 TID Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Figure 3 Typical Publication Service Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Figure 4 Typical Subscription Service Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Figure 5 Typical Request-Response Service Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Figure 6 Typical Request-Response Invocation Service Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Figure 7 Client Distribution Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Figure 8 IDoc in native RFC table format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Figure 9 IDoc in uncompressed “exploded” format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Figure 10 R3 Connections Folder Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Figure 11 Adapter Conversion between MBCS and Unicode Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Figure 12 Outbound Adapter Connecting to Multiple SAP R/3 Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Figure 13 Outbound Adapter Registering on Multiple Program IDs on One Gateway . . . . . . . . . . . . . . . . . 343

Figure 14 RFC Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Figure 15 Find RFC Destinations Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Figure 16 RFC Destination RFCTEST Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Figure 17 Select Gateway Options Pull-down Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Figure 18 Select Gateway Host and Gateway Service Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Figure 19 Completed Gateway Options Dialog Box. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Figure 20 Test Connection Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Figure 21 R/3 Adapter ALE/IDoc interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478

Figure 22 Client Distribution Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501


xii | Figures


| xiii

Tables

Table 1 TIBCO Adapter components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Table 2 Compatible products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Table 3 Supported platforms, package names, service packs and disk space for Microsoft Windows . . . 39

Table 4 Supported platforms, package names, patches and disk space for UNIX systems. . . . . . . . . . . . 43

Table 5 Windows (JVM 1.3.1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Table 6 Solaris (JVM 1.1.8 & 1.3.1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Table 7 HPUX (JVM 1.3.1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Table 8 AIX (JVM 1.3.1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Table 9 Linux (JVM 1.3.1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Table 10 IDoc Control Record Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Table 11 Input Parameters used in the RFC to implement BDC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Table 12 Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Table 13 Encoding/Locale Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Table 14 TIBCO Administrator Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Table 15 Adapter Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Table 16 Predefined Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Table 17 Optional properties for server-based URL (TIBCO Rendezvous) . . . . . . . . . . . . . . . . . . . . . . . . 311

Table 18 Optional properties for server-based URL (HTTP). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Table 19 Properties Required for HTTPS urlFiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Table 20 Optional parameters for local project URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Table 21 TIDManager Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Table 22 Input Parameters - To be set by the client for every data-chunking request . . . . . . . . . . . . . . . . 326

Table 23 Output Parameters returned by the adapter to the client for each chunking request. . . . . . . . . . 327

Table 24 Microagent Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Table 25 Tracing Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

Table 26 Error Messages with Changed Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421


xiv | Tables


| xv

Preface

This document describes supported features, platforms, installation, configuration, and overall architecture of TIBCO Adapter for R/3.

Topics

• Related Documents, page xvi

• Terminology and Acronyms, page xx

• How to Contact TIBCO Customer Support, page xxii


xvi | Preface

Related Documents

This section lists documentation resources.

TIBCO Product DocumentationThe following documents form the TIBCO Adapter for R/3 Documentation set:

• TIBCO Adapter Concepts: This manual introduces adapters by explaining what they are, and explains how to install, configure, deploy and manage adapters.

• TIBCO Adapter for R/3 User’s Guide — Read this manual to gain an understanding of the product.

• TIBCO Adapter for R/3 Examples Guide — Read this manual to gain better understanding of the adapter using examples that are provided with the installation.

• TIBCO Adapter for R/3 Release Notes — Read this document for a summary of new features, changes since last release and a description of any open or closed issues that may affect installing or using the adapter.

• TIBCO Adapter for R/3 readme.txt — Read this document to check the current release number, supported platforms and required software.

Other TIBCO Product DocumentationNote that only books that relate to adapters are listed. Each of the books is available from the doc directory in the product’s installation area.

• TIBCO BusinessWorks™ software:

— TIBCO BusinessWorks Concepts

— TIBCO BusinessWorks Process Design Guide

— TIBCO BusinessWorks Error Codes

— TIBCO BusinessWorks Palette Reference

— TIBCO BusinessWorks Quick Start

— TIBCO BusinessWorks Release Notes

• TIBCO ActiveEnterprise™ software:

— TIBCO ActiveEnterprise Concepts


Related Documents | xvii

• TIBCO Designer™ software:

— TIBCO Designer User’s Guide

— TIBCO Designer Palette Reference

— TIBCO Designer Release Notes

• TIBCO Administrator™ software:

— TIBCO Administrator User’s Guide

— TIBCO Administrator Server Configuration Guide

— TIBCO Administrator Installation Guide

— TIBCO Administrator TIBCO Enterprise for JMS Server Configuration Guide

— TIBCO Administrator Release Notes

• TIBCO IntegrationManager™ software:

— TIBCO IntegrationManager Concepts

— TIBCO IntegrationManager Administrator’s Guide

— TIBCO IntegrationManager Process Design Guide

— TIBCO IntegrationManager Reference

— TIBCO IntegrationManager Release Notes

• TIBCO Rendezvous™ software:

— TIBCO Rendezvous Concepts

— TIBCO Rendezvous Administration

— TIBCO Rendezvous Configuration Tools

• TIBCO Enterprise™ for JMS software:

— TIBCO Enterprise for JMS User’s Guide

— TIBCO Enterprise for JMS Release Notes

• TIBCO Hawk™ software:

— TIBCO Hawk Installation and Configuration

— TIBCO Hawk Administrator’s Guide

• TIBCO Adapter SDK

— TIBCO Adapter SDK Concepts


xviii | Preface

• TIBCO Runtime Agent

— TIBCO Runtime Agent Release Notes

— TIBCO Runtime Agent Administrator’s Guide

— TIBCO Runtime Agent Installation

— TIBCO ActiveEnterprise™ Features, Migration and Compatibility


Related Documents | xix

Third Party Documentation• SAP R/3: Implementation Guide by Bradley D. Hiquet, available from

Kelly-Lacey & Associates Inc. This is “A Manager’s Guide to Understanding SAP” that emphasizes the user’s point of view. Printed in 1998 by Macmillan Technological Publishing.

• SAP R/3 Business Blueprint by Thomas Curran and Gerhard Keller. Printed in 1998 by Prentice Hall PTR.

• SAP R/3 System, A Client/Server Technology by Rudiger Buck-Emden. This is a general technical overview that is easy to read. Printed in 1996 by Addison-Wesley.


xx | Preface

Terminology and Acronyms

Term Definition

API Application Program Interface.

Applicaction Server

The server on which the SAP R/3 processes run.

ALE/IDoc Application Link Enabling/Intermediate Documents.

RFC The SAP Remote Function Call Interface.

BAPI Business API (Functionally equivalent to RFC).

Component A self-contained replaceable functional unit of the adapter that provides a set of interfaces. TIBCO Adapter for R/3 has two kinds of components; r3Outbound and r3Inbound. r3Outbound encapsulates functionality for outbound communication with the SAP R/3 system while r3Inbound encapsulates the functionality for inbound communication with the SAP R/3 system.

CPIC Common Programming Interface for Communications. Rarely used directly, it forms the basic communications interface of SAP R/3.

EDI Electronic Data Interchange.

ABAP Advanced Business Application Programming is a language in SAP R/3 used to write SAP R/3 specific code.

Gateway Server A server used to exchange data with the SAP R/3 system.

Interface A functional sub-unit of the adapter that exposes one or more adapter services. For example, the RFCServer interface exposes RFC/BAPI Request-Response Invocation services.

RV TIBCO Rendezvous™ protocol; also in certain contexts refers to reliable message quality of service, as opposed to certified message.

RVCM TIBCO Rendezvous certified message quality of service.

RVDQ TIBCO Rendezvous distributed queue.

JMS Java Messaging Service


Terminology and Acronyms | xxi

SAP R/3 Native data

All SAP R/3 data that the adapter interacts with. It consists of RFC data types. This includes IDocs received as RFC tables in an RFC function call.

MBCS Multi-byte character string.

TID Transaction ID. A globally unique identifier used by transactional RFCs to ensure exactly-once execution of a transaction.

TIDManager Transaction Identifier Manager.

Inbound Instance An adapter configuration listening for messages inbound to SAP R/3. Inbound instances transfer messages from the TIBCO environment to SAP R/3.

Outbound Instance An adapter configuration listening for messages outbound from SAP R/3. Outbound instances transfer messages from SAP R/3 to the TIBCO environment.

RFC Server A SAP R/3 term for any external program that can accept and process RFCs/BAPIs/IDocs from the R/3 system.

RFC Client A SAP term for any program that can post RFCs/BAPIs/IDocs from an external system into the SAP R/3 system.

One Way Invocation protocol

One way invocation protocol allows you to invoke the BAPI/RFC in the SAP R/3 system without waiting for a reply from the system.

Term Definition


xxii | Preface

How to Contact TIBCO Customer Support

• For comments or problems with this manual or the software it addresses, please contact TIBCO Product Support on the web at:

http://support.tibco.com

Entry to this site requires a username and password. Customers with valid maintenance or support contract can obtain their username and password from that same website.

• For an overview of TIBCO Support Services, and information about getting started with TIBCO Product Support, visit this site:

http://www.tibco.com/services/support/default.jsp


| 1

Chapter 1 Introduction

TIBCO Adapter for R/3 enables SAP R/3 systems to exchange real-time business data with the TIBCO environment. This chapter introduces its features and components.

Topics

• SAP R/3 Overview, page 2

• TIBCO Adapter for R/3 Overview, page 3

• Features, page 14

• Advanced Features, page 17

• Schema Support, page 24


2 | Chapter 1 Introduction

SAP R/3 Overview

SAP R/3 is the world’s largest provider of client-server Enterprise Resource Planning solutions. It is a transaction-based system, encompassing many aspects of information systems such as Sales and Distribution, Purchasing, Human Resources and others.

Refer to the following sections to further your understanding of SAP R/3.

• Appendix B, SAP R/3 Overview, on page 473 for an overview of SAP R/3.

• Chapter 3, Preparing the SAP R/3 System, on page 61 for details on the setup that needs to be carried out on the SAP R/3 system.

SAP R/3 InterfacesThe adapter supports the most common SAP R/3 integration interfaces - BAPI, RFC and ALE/IDocs, which are described below in brief. A basic understanding of these three integration interfaces helps you appreciate the capabilities of the adapter.

• BAPI (Business Application Programming) — BAPIs are the methods exposed by SAP business objects. This interface is best used with the adapter for performing real time queries and updates to and from the SAP R/3 system. For example, creation of a sales order in SAP R/3 system using BAPI_SALESORDER_CREATEFROMDAT2. BAPIs are SAP's recommended integration interface over RFCs (Remote Function Call).

• RFC (Remote Functions Call) — The RFC interface allows non-SAP R/3 and SAP R/3 applications to execute SAP Advanced Business Application Programming (ABAP) functions that have been RFC-enabled. They are similar to BAPIs in functionality but are not attached to SAP Business Objects. There are two types of RFCs in SAP R/3,

— Synchronous RFCs — Used to send messages to an external system and receive replies. They are also used to query SAP R/3 system from an external system.

— Transactional RFCs (tRFCs) — Used to send or receive transactional data to and from the SAP R/3 system.

• ALE/IDoc (Application Link Enabling/Intermediate Documents) — IDocs are document containers for business transactional data, such as sales orders (example: ORDERS01) and order invoices (example: INVOIC02). ALE helps achieve cross-business functionality and facilitates the event driven, asynchronous exchange of information directly out of business transactions.


TIBCO Adapter for R/3 Overview | 3

TIBCO Adapter for R/3 Overview

The TIBCO Adapter for R/3 enables SAP R/3 systems to seamlessly integrate with the rest of the enterprise in a TIBCO environment - a suite of products to integrate applications within the enterprise, to reach partners beyond the enterprise, and to connect with other enterprises. The following sections give a brief of the adapter components.

Adapter Components

Configuration and Design Components

• Adapter Configuration Palette — When you install the TIBCO Adapter for R/3, a palette containing the configuration resources for the adapter is automatically loaded in TIBCO Designer.

The adapter configuration palette provides an easy-to-use graphic user interface. It allows you to configure adapter services, download RFC, BAPI and IDoc schemas directly from your SAP R/3 system, and save resulting configuration in a project.

Runtime Components

Runtime components deliver the core functionality of the adapter. They use configuration information and metadata to exchange messages between SAP R/3 systems and applications in the TIBCO environment.

Adapter Application

The adapter functions as an ALE/RFC/BAPI client and server interface to SAP R/3. It provides the following services:

• Publication Service — This service is used to publish IDocs from the SAP R/3 system to the TIBCO environment.

• Subscription Service — This service is used to subscribe to messages from the TIBCO environment and post them into the SAP R/3 system.

• Request-Response Invocation Service — This service is used to receive RFCs and BAPIs from the SAP R/3 system and invokes them as requests in the TIBCO environment.

• Request-Response Service — This service is used to execute RFC and BAPI requests in the SAP R/3 system.



The run-time adapter application comprises:

• Outbound Adapter — Typically, a SAP R/3 application outbound RFC/BAPI call or ALE workflow initiates an outbound message to the adapter. The adapter then extracts RFC parameters, performs basic data type conversion (if necessary) and publishes the message to the TIBCO environment. The adapter can be configured to initiate a remote request to another RFC server application. In the case of remote requests, replies are posted back to the calling RFC within the SAP R/3 system.

• Inbound Adapter — The adapter receives an inbound request from the TIBCO environment on a predetermined subject. When a message is received, data conversion to SAP R/3 takes place, and a call is dispatched to SAP R/3 system through an appropriate RFC function handler.

Figure 1 Inbound and Outbound Adapters



TIDManager Service

The TID Manager service prevents duplicate processing of IDocs and tRFCs in case of communication errors that occur when an IDoc or tRFC is executed in the SAP R/3 system.

Figure 2 TID Manager



Logical Process ArchitectureThe following figure shows the logical connectivity between SAP R/3 systems and the TIBCO environment using the adapter.

In the figure the two servers on the left are separate physical computers that host SAP R/3 systems. Software components indicated by shadowed boxes, such as “Outbound R/3 Adapter 1", are adapter configurations that can run on a single computer or can be distributed. The lines that connect the adapter components to SAP R/3 System instances are either direct physical connections or connections through a gateway and router.

The number of outbound (publication service) and inbound (subscription service) adapters is not limited by software constraints, and can be increased to handle message volume increases.

The following section describes how the adapter works with each of the SAP R/3 interfaces.



How the Adapter Works with SAP R/3 Interfaces

Business Application Programming Interface (BAPI)

The adapter extracts and stores BAPI schema definitions from the SAP R/3 system into the project at design-time. Both standard and custom BAPIs can be downloaded and used in the adapter. Each BAPI is encapsulated by an adapter service, which is used to:

• Execute business events in SAP R/3 from remote enterprise applications

Example: Use BAPIs to create a Sales order in SAP R/3 from an order management system receiving orders from the web.

• Trigger business events in a remote enterprise application from SAP R/3

Example: SAP R/3 invokes a BAPI to perform credit-card validation against an external clearing house.

Remote Function Call (RFC)

The adapter extracts and stores RFC schema definitions from the SAP R/3 system into the project at design-time. Both standard and custom RFCs can be downloaded and used in the adapter.

The underlying technology for RFCs and BAPIs is the same.

Application Link Enabling - Intermediate Documents (ALE/IDoc)

This interface is typically used with the adapter for asynchronous transfer of business data to and from the SAP R/3 system, for example, a batch transfer of sales orders from SAP R/3 to a data warehouse.

The adapter extracts and stores IDoc metadata for individual IDoc types into the adapter project at design-time. Both Standard IDocs and Custom IDocs are supported.

Each IDoc type definition in SAP R/3 is encapsulated as an IDoc service in the adapter. An IDoc service can be used to:

• Send business transaction data from SAP R/3 system in both real-time and batch mode.

Example: Send out shipping notification to a warehouse management system from SAP R/3 for materials to be picked and packed for shipping.

• Receive business transaction data in the SAP R/3 system as IDocs.



Example: A warehouse management system posts a shipping confirmation IDoc into the SAP R/3 system after the shipping operation is complete. This confirms the completion of the operation in SAP R/3.



Services Offered by the AdapterIn TIBCO terminology, an adapter offers ’services’ to the host application and to the TIBCO environment. A service broadly encapsulates routing rules for messages handled by the service and also custom configuration information.

The adapter offers a separate service for each BAPI, RFC and IDoc type configured in the adapter.

This section discusses the services provided by the adapter with common usage scenarios drawn from real-life customer requirements.

Publication ServiceThis service is used to publish information from SAP R/3 system. Only IDocs can be published. Multiple publication services can be configured to handle different IDoc types.

Example: ORDERS02 IDoc can be used to publish a sales order from SAP R/3 and MATMAS01 IDoc can be used to publish material information.

Figure 3 Typical Publication Service Flow

For example, material master records can be published to a legacy inventory management system in the enterprise, and customer master records transferred to an enterprise CRM application from the same adapter configuration. For details on configuring Publication Services, see Configuration Tab on page 152.



An adapter with IDoc services can be configured to receive IDocs from multiple SAP R/3 systems or multiple RFC destinations from the same SAP R/3 system. This is useful for enterprises that need to integrate multiple SAP R/3 systems. For details on how to configure an IDoc publication service to receive IDocs from multiple SAP R/3 systems, see Configuring Multiple Connections for Outbound Instance on page 246.

The adapter provides a rich variety of IDoc publication format options. IDocs may be processed and transferred in a completely self-describing format easily understood by partner systems. This facilitates straightforward mapping to the partner’s data formats. IDoc services can be configured to transfer data in SAP’s native table format and various other formats.

IDoc services may also be configured to process IDocs individually or in batches. The former is typically suited for real-time integration while the latter suits a batch offload scenario. See Identifying the Publication Mode on page 155 for the complete list of IDoc publication formats.

Subscription ServiceThis service is used to subscribe to messages from the TIBCO environment and post them into the SAP R/3 system. Only IDocs can be posted to SAP R/3. Multiple subscription services can be configured to handle different IDoc types.

Example: Sales information can be subscribed to and posted as ORDERS02 IDoc in SAP R/3.

Figure 4 Typical Subscription Service Flow



Multiple IDoc subscription services can be configured and each one may receive IDocs from one or more systems in the TIBCO environment. For instance, one adapter configuration can receive and post Sales Order documents from a legacy enterprise order management application to the SAP R/3 system. It can also receive and post updates to Materials master data from an enterprise inventory management application to the SAP R/3 system.

An adapter with IDoc subscription services may also be configured to connect to one or more SAP R/3 systems. See Configuring Multiple Connections for Inbound Instance on page 241 for details on how to configure and run the adapters connected to one or more SAP R/3 systems.

The IDoc subscription services offers a wide variety of IDoc formats for subscription suited for real-time and batch postings. See Identifying the Publication Mode on page 155 for details of available IDoc formats for subscription. By supporting and being completely compatible with IDoc publication service message formats, the IDoc subscription service allows easy end-to-end SAP integration.

Request-Response ServiceThis service is used to execute RFC and BAPI requests in the SAP R/3 system. Multiple adapter services can be configured for different BAPIs and RFCs.

Example: BAPI_CUSTOMER_GETDETAIL1 can be used to request the details of an existing customer from SAP R/3 and BAPI_SALESORDER_CREATEFROMDAT1 can be used to create a sales order in SAP R/3.

Figure 5 Typical Request-Response Service Flow



For instance, a BAPI_SALESORDER_CREATEFROMDAT1 adapter service can be invoked to create a sales order in the SAP R/3 system and get back the sales order number in a synchronous fashion. Or, the same BAPI service can be invoked transactionally in SAP. See Invoking BAPIs/RFCs Using Transactional Semantics in SAP R/3 on page 336 on how to configure and perform transactional invocations of BAPI/RFCs in SAP R/3.

The same adapter instances can be configured to connect to multiple SAP R/3 systems and execute different BAPIs/RFCs in different systems. This allows for easy maintenance at runtime because it requires fewer instances of adapters. See Configuring Multiple Connections for Inbound Instance on page 241 on how to configure and execute BAPIs in different SAP R/3 systems.

BAPIs/RFCs used for querying the SAP R/3 system may yield large resultsets. For example, a BAPI_SALESORDER_GETLIST service that queries the SAP R/3 system for a list of sales orders for a given customer, and a given period of time, may return a large list. Processing such large resultsets can be very resource intensive, and could significantly slow down the querying application. The adapter can help alleviate such problems by breaking the resultset in packets. See Handling Large Internal Tables from SAP R/3 on page 325 for details on how to configure this in an adapter service.

In some scenarios actions to be performed in SAP R/3 might be dependent upon the calling system’s credentials and rights. The adapter can be configured to enable and enforce dynamic logons for individual BAPI/RFC invocations as explained in the section Event-Driven Inbound Connections. In such cases the adapter will not use the static set of SAP R/3 connections created at startup. Dynamic logon is also useful when the BAPI service is only invoked occasionally as it avoids having to keep permanent connections to the SAP R/3 system.

If the adapter is configured with services for BAPIs requiring explicit commit in SAP R/3 (like the BAPI_SALESORDER_CREATEFROMDAT1 service), and the adapter has established multiple connections to the R/3 system, the adapter must be instructed to maintain connection contexts for the invoked BAPIs for subsequent commit/rollback based on business rules. See Inbound BAPI Transactional Support on page 331 for details on configuring an adapter with multiple connections and still maintain connection contexts for conducting BAPI transactions.



Request-Response Invocation ServiceThis service is used to invoke RFC and BAPI requests in the TIBCO environment. Multiple adapter services can be configured for different BAPIs and RFCs.

Example: A BAPI_MATERIAL_AVAILABILITY service can be invoked to check for material availability before invoking a BAPI_SALESORDER_CREATEFROMDAT1 service to create a sales order in a remote system using the same adapter.

Figure 6 Typical Request-Response Invocation Service Flow

This adapter service supports both synchronous and transactional modes.

Transactional RFC calls are typically made when a series of database operations must be performed in the remote enterprise application. Synchronous BAPI/RFC calls are more generally used for querying remote systems.

Transactional mode requires the adapter to execute a transactional RFC call exactly once and reject duplicates. The adapter provides stable transaction management capabilities through the TIDManager component. See TIDManager on page 250 for details on configuring and running an adapter for correct transaction management. The adapter’s transaction handling is coupled with the TIBCO Messaging protocols. This ensures that transactions are delivered to the remote system even if the remote system was unavailable at the time of the call.

The same adapter can be configured to receive BAPI/RFC requests from multiple SAP R/3 systems or multiple RFC Destinations on the same SAP R/3 system. This allows for easier maintenance at runtime because it requires fewer adapters. See Configuring Multiple Connections for Outbound Instance on page 246 for details on configuring and invoking BAPIs from different SAP R/3 systems in remote applications using the same adapter configuration.



Features

The adapter provides a rich set of features, which offer maximum flexibility for configuration and deployment in real-life usage scenarios.

The salient features are listed below. Refer to the relevant sections of this document for detailed description and usage information. For generic adapter features, refer to the TIBCO Adapter Concepts Book.

• Transaction Support — The adapter provides bi-directional support for BAPIs/RFCs with transactional semantics. Duplicate processing of transactional RFCs by the TIDManager component of the adapter. The adapter also provides support for QRFCs.

• Flexible Connectivity Options — The adapter provides multiple options to connect to the SAP R/3 system providing flexibility in implementation. Inbound adapter configurations can connect using dedicated connections to a specific SAP R/3 application server, and connect using load-balanced connections to the SAP messaging server. One adapter configuration can establish connections to one or more SAP R/3 systems.

• Dynamic Application Server Connection — This feature allows the Outbound adapter to dynamically connect to and service BAPIs/RFCs/IDocs from a cluster of SAP application servers under a central SAP instance.

• Server side data caching — The inbound adapter caches large record sets retrieved from the SAP R/3 system. Querying clients can retrieve the records in packets.

• Support for BAPIs Requiring External Commit — The inbound adapter supports external commit for BAPIs introduced in SAP R/3 release 4.0.

• Refreshing in-memory image of RFC — The adapter refreshes the in-memory image of RFCs periodically. Hence any change in the ABAP code of RFCs is reflected in the adapter automatically.

• A convenient easy-to-use configuration tool — The adapter is configured using an intuitive Graphical User Interface, TIBCO Designer. TIBCO Designer connects to a specified SAP R/3 system, downloads the schema for IDocs, RFCs and BAPIs for the required services, and transfers the schema and message routing rules for individual services to a central repository. Support for usage of global and client variables ensure easy and quick migration of adapter configurations from development to testing, and from testing to production environments.

• Support for TIBCO BusinessWorks — The adapter can be used in a TIBCO BusinessWorks 5.1 process.


Features | 15

• Scalability and Fault Tolerance — The adapter is multithreaded, ensuring that a single message being processed in the adapter does not become a bottleneck for subsequent messages. Simultaneous processing of messages results in high throughput and performance benefits. The TIBCO Distributed Queue (DQ) and TIBCO Enterprise for JMS queue protocols for messaging allow peak load balancing between different instances of the same adapter configuration (subscription and request-response services) and also offers fault-tolerance capabilities. The Publication and Request-response invocation services make use of SAP R/3’s load balancing features for messages originating from the SAP R/3 system. Refer Load Balancing Using Distributed Queue on page 260 on how to configure and deploy load-balanced configurations for the various adapter services.

• Messaging

The adapter supports TIBCO Rendezvous and TIBCO Enterprise for JMS as transports.

— TIBCO Rendezvous mode of transport supports the following messaging protocols:

Reliable (RV) — This ensures that each multicast or broadcast message is received as long as the physical network and packet recipients are working, and the loss of a message is detected.

Certified-delivery (RVCM, ensures atleast-once delivery of messages) — This guarantees that every certified message reaches its intended recipient in the order sent. Supported for all SAP R/3 interfaces (ALE/IDocS/RFC and BAPI).

Distributed Queue (RVCMQ) is designed to deliver a message to one-of-many service listeners (workers). It has incorporated the features of both Certified Messaging and Fault Tolerance. Senders of DQ are ordinary Certified Message senders.

— The JMS mode of transport supports the following connection types:

Queue — Queue messaging has one sender and one receiver per message. The receiver receives the message whether or not the receiver is active at the time the message is sent.

Topic — In a Topic message system, senders address messages to a topic. Many senders can publish on a single topic, and a single sender can publish to many receivers. Receivers subscribe to topics, and receive messages on those topics.

• Exception Handling, Monitoring and Message Tracking — The adapter employs effective exception-handling techniques and extensive audit trails. The adapter can be configured to work in concert with the TIBCO Hawk monitoring component to detect and handle exception situations. Each



message that is processed by an adapter service is tagged with a tracking-ID that enables complete end-to-end tracking of messages in the TIBCO environment.

• Security — The Obfuscation engine packaged with the adapter enables encryption of sensitive configuration information.

• Examples — A set of examples demonstrates configuration of the adapter as well as interactions with TIBCO IntegrationManager. Pre-configured sample R/3 adapter configuration files are included in the adapter installation.

Advanced features are briefly explained in the next section, Advanced Features on page 17. Refer to the relevant sections of this document for detailed description and usage information.

For an overview of the SAP R/3 system and description of the interfaces exposed by the R/3 system, see Appendix B, SAP R/3 Overview, on page 473.


Advanced Features | 17

Advanced Features

IDoc Filtering

IDocs can be used to send business-related data to external applications. Typically external applications are only interested in limited data whereas in SAP R/3 most segments of an IDoc are populated. SAP R/3 provides a filtering of IDoc for the master data (material master, customer master etc) but it does not provide any filtering mechanism for the transactional data (sales order, purchase order etc.). Using the IDoc filter feature provided in the adapter, data can be filtered at the Field as well as at the Segment level. To be consistent with SAP R/3, the adapter does not allow filtering of mandatory segments in the master IDocs.

Advantage The IDoc message can be trimmed in the adapter, which ensures less network traffic as well as less processing work on the receiving application side.

Usage Scenario This feature should be used when only a subset of the data contained in the IDoc is required by the external application.

Configuration See IDoc Filtering on page 328 for details.

BAPI Transactional SupportThe BAPIs introduced with SAP R/3 system releases 4.0 and later do not automatically commit their changes as in prior SAP R/3 releases. An external program executing a BAPI inside SAP R/3 now has a choice to commit or rollback changes. To commit or rollback the changes, every request to SAP R/3 for such BAPIs needs to be followed by BAPI_TRANSACTION_COMMIT or BAPI_TRANSACTION_ROLLBACK. Also BAPI_TRANSACTION_COMMIT/BAPI_TRANSACTION_ROLLBACK should be processed with the same handle as that of the actual transaction BAPI. The adapter provides this transactional BAPI support in single-threaded as well as multithreaded mode.

Advantage You can commit or rollback changes based on the reply from the transactional BAPI.

Usage Scenario This feature must be used to execute any transactional BAPI requiring an external commit.

Configuration See Inbound BAPI Transactional Support on page 331 for details.



Example An example (External_Commit_IM.dat) for this feature is provided in the examples directory of the adapter installation. See TIBCO Adapter for R/3 Example Guide for details.

Data ChunkingThis feature is used when a large amount of data is returned from SAP R/3 system. For example RFC_CUSTOMER_GET with kunnr="*" will return details of all customers. Such large amounts of data can be a bottleneck for the requesting system. In such circumstances data is retrieved in chunks. Instead of making one request to the adapter, you can make multiple requests. The number of records to be retrieved in one request is defined in the request itself. Repeated requests can be made to the adapter until all the required records are fetched.

Advantage Some applications may not be able to handle large data objects. Using the data chunking option you can divide the result data set into manageable chunks.

Usage Scenario Use this feature where SAP returns large amounts of data in reply to the RFC request. (For example, if the number of records returned are greater than 500).

Configuration None

Example An example for this feature, Data_Caching_IM.dat is provided with the installation in the folder adr3\5.1\examples. See TIBCO Adapter for R/3 Example Guide for details.

Event Driven Inbound ConnectionUsing this feature you can force an external application to provide the adapter (and SAP R/3) with a valid login id and password. This feature is configured at the BAPI/RFC level in the adapter. Any call to these BAPIs/RFCs will require proper authentication - the adapter will not service such calls using the default connections established during initialization.

Advantage You can use different login information to dispatch different requests. You can login to SAP R/3 with specific authorization for a particular request. The connection to the SAP R/3 system need not be open all the time.

Usage Scenario This feature can be used when:

• You do not want to keep a permanent connection to the SAP R/3 system open.

• You want to authenticate login information for each request made and dispatch subsequent calls on the newly created connection.



Configuration See Event Driven Inbound Connections on page 348 for detailed information on this feature. This section also provides configuration steps for this feature.

Inbound tRFC/IDoc reportingThis feature enables the adapter to send explicit reporting messages to the TIBCO environment on the status of Inbound message processed in the adapter. Adapter processing errors, application errors and information upon successful posting to the application are reported back to the TIBCO environment.

Advantage The adapter Request-Response (oneway protocol, tRFCs) and Subscription services process Inbound messages that are one way. In other words, senders of messages to these services do not receive explicit acknowledgement from the adapter regarding the status of such messages processed in the adapter. This feature allows sending systems to know the status of every Inbound message processed by these services.

Usage Scenario Publishing systems in the TIBCO environment can perform appropriate actions based on the reporting message sent out by the adapter. For instance, actions could be,

• Setting up an e-mail trigger or halting a subsequent dependent activity in case of error reports from the adapter.

• Proceeding with a subsequent dependent activity only upon confirmation of successful posting of a message into the SAP R/3 system.

Configuration See Configuring Reporting on page 234 for details.

Support for Multiple Application ServersA single instance of the adapter can exchange messages with multiple application servers both on the inbound (to a SAP R/3 system) and outbound (from a SAP R/3 system) sides. On the outbound side, the adapter can receive messages from multiple SAP application servers. On the inbound side, the adapter can be configured for multiple BAPI/RFC/IDocs, each interacting with a different application server.

Advantage A single adapter instance can serve multiple application servers obviating the need for multiple adapter instances. Load-balancing and fault tolerance across SAP R/3 application servers can also be achieved this way.



Usage Scenario On the outbound side this feature can be used for load balanced SAP R/3 configurations that use a messaging server.

On the inbound side this feature can be used to post the data to different SAP R/3 application servers.

Configuration See Configuring Multiple Connections for Inbound Instance on page 241 and Configuring Multiple Connections for Outbound Instance on page 246 for details.

MultithreadingThe adapter supports a static number of threads specified at the time of configuration. The number of connections to the application server equals number of threads. Multithreading allows the adapter to process multiple messages concurrently ensuring better performance.

Advantage Outbound Adapter Instance — The outbound adapter instance is used to publish the IDocs or send out RFC/BAPI requests. The outbound configuration can service multiple requests from R/3. It does not have to wait for a reply to a previous request to proceed with the next request. Transactional RFCs are sequenced by the underlying R/3 library and are handled sequentially by the adapter.

Inbound Adapter Instance — On the inbound side the adapter can post multiple IDocs to SAP R/3. The adapter instance can process multiple RFC requests for the same or different RFCs/BAPIs. The Inbound configuration can also service multiple requests from external systems for posting requests into SAP R/3 without waiting for a reply for the previous request. The adapter also handles simultaneous IDoc messages.

Usage Scenario Multiple threads greatly enhance performance in situations when the adapter idle-time for a given message is high. For example, on the inbound side, a request could take a long time, (a minute or more) to execute in SAP R/3. A single-threaded adapter would be waiting for a reply and is idle during most of the entire execution time. A multithreaded adapter will continue to service further requests even while waiting for the reply from SAP R/3. Similarly, on the outbound side, the adapter can receive and process further requests from SAP R/3 while waiting on one connection for a reply from the remote system.

Configuration See Multithreading on page 339 for configuration details.



Replacing Control FieldsThis feature is applicable to IDoc Publication service. It allows you to replace the value of the fields in the control record of an IDoc. For example, replacing values of the fields RCVPRN (receiving partner) or RCVPOR (receiving port), can be done within the adapter itself and no separate IDoc service is needed.

Advantage You have the flexibility to change the values of control record fields right in the adapter, - this does not require any external transformation.

Usage scenario This feature is useful when you do not need to transform the message, but simply want to set some fields in the control records. There is no need for transforming the message but couple of fields in the control record has to be replaced with ’fixed’ values.

Configuration See Replacing Control Fields on page 239 for details.

Example An example (R3ExamplesAdv.dat) for this feature is provided in the examples directory of the adapter installation. See TIBCO Adapter for R/3 Example Guide for details.

Dynamic SubjectsThis feature is applicable to IDoc Publication service. Subject for the IDoc publisher can be constructed based on content of the fields in the control record. This allows for content-based routing of messages based on the content.

Advantage Run-time dynamic construction of subjects, allows for content-based routing of messages.

Usage scenario You can publish messages for different partners on different subjects by using the partner number in your dynamic subject.

Configuration See Publishing IDocs on Dynamic Subjects on page 237 for details.

Example An example (R3ExamplesAdv.dat) for this feature is provided in the examples directory of the adapter installation. See TIBCO Adapter for R/3 Example Guide for details.

Validation of DestinationsA list of valid partners (destinations) can be maintained in the adapter configuration. The adapter will only publish IDocs meant for these destinations and will write the IDocs for all other destinations, to a file.



Advantage You can avoid publishing IDocs, which are not relevant.

Usage scenario IDoc messages can be filtered in the Publication service based on the receiving partner specified in R/3 (field RCVPRN in the control record of an IDoc).

Configuration See Configuring Valid Destinations on page 200 for details.

User ExitsThis feature is used to perform user-defined operations on IDocs just before publishing or immediately after subscribing from the TIBCO environment.

Advantage User exits can be used to carry out simple transformation of messages before publishing or immediately after subscribing to it in the TIBCO environment.

Example An example for this feature is provided in the examples directory of adapter installation.

Configuration See Configuring User Exits on page 230 and Configuring Multiple Connections for Inbound Instance on page 241 for details.



QRFC SupportThis feature is used to perform serialization of transactional RFCs.

In the SAP R/3 system, transactions can be processed as a queue. The sequence of the transaction in a queue can be defined separately, and each queue can be processed individually.

Advantage This feature improves processing performance of transactional RFCs.

Configuration See Support for qRFCs on page 337 for details.

Dynamic Application Server ConnectionThis feature allows the Outbound adapter to dynamically connect to and service BAPIs/RFCs/IDocs from a cluster of SAP application servers under a central SAP instance.

The adapter dynamically discovers and connects to new application servers added to the environment and drops connections to other servers that have been removed from the cluster.

Advantage The ability to dynamically discover all active application servers and connect to them eliminates adapter downtimes, which usually happens when reconfiguring to connect to a newer set of application servers. The intelligence built into the adapter allows it to respond dynamically to changes in the SAP R/3 environment and ensures that the adapter caters to all relevant application servers.

Usage scenario Use this feature to,

• balance the Outbound messaging load across application servers.

• invoke BAPIs/RFCs or post IDocs to the TIBCO environment from a clustered SAP application server environment, where the servers are moved across development, testing and production environments.

Configuration This feature requires no additional configuration in TIBCO Designer. Configuration is achieved through a properties file. See Event Driven Inbound Connections on page 348 for details.



Schema Support

The adapter uses schema to describe data received from or sent to the TIBCO environment.

Schemas are useful in a variety of situations, for example:

• Where several developers collaborate on an adapter application, a specification document normally defines the data model for several related adapter applications. Inside the TIBCO framework, you can define a schema to serve as the data model and update it as needed.

• When the data model of the adapter changes, developers do not have to redesign the business process.

• Using Schemas in conjunction with the various mapping tools available in the TIBCO environment, you can transfer data across applications with incompatible data formats.

Using the R/3 Adapter Configuration palette in TIBCO Designer, you can connect to and extract schema definitions (any standard or custom RFC/BAPI or IDoc) directly from the SAP R/3 system. Schemas are then stored into Designer projects for run-time use.

R/3 schemas, once saved into a Designer project can be used across projects by exporting/importing the schemas from/to a project in XML format.


| 25

Chapter 2 Installation

This chapter explains how to install TIBCO Adapter for R/3 on Microsoft Windows and UNIX systems.

Topics

• Preparing your Environment for Installation, page 26

• Installer Overview, page 31

• Installation Registry, page 34

• Adapter Components and Compatible Software, page 36

• Installing on Microsoft Windows, page 39

• Installation on UNIX Systems, page 43

• Post Installation, page 47

• Installation FAQs and Troubleshooting, page 51

This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see Table 3 on page 39 and Table 4 on page 43 for the availability of this software version on a specific operating system platform.


26 | Chapter 2 Installation

Preparing your Environment for Installation

The most time-consuming part of an adapter installation is the collection of environment information and parameters. This section helps you complete this process. It provides a checklist of parameters you should obtain from various system administrators within your organization before installing the adapter. Note that obtaining a SAP R/3 account can take some time depending on your corporate policies — so plan in advance!

Operating System RequirementsObtain the following information from the administrator of the machine on which you plan to install the adapter:

Do you have the required credentials to run the installer?

• On Microsoft Windows, administrator privileges are required to install.

• On UNIX systems, you can install as root or a regular user. See Installer Account on page 44 for details.

• Note that the TIBCO Runtime Agent (TRA) must be installed prior to installing the adapter and the adapter installation always places files under the TIBCO root directory that was set when the TRA was installed.

There should be enough space on the disk or partition to install the adapter. The adapter needs space in your temp area and the directory where it is installed.

• See Installation Registry on page 34 for details about temp folder space requirements on Microsoft Windows and UNIX systems.

• See Table 3 on page 39 for Microsoft Windows installations

• See Table 4 on page 43 for Unix System installations.

You must have write permissions to these directories to install the adapter. In addition, on UNIX systems certain other permissions must be set to run the adapter. See Permission Requirements on UNIX Systems on page 47 for details.

• To run the adapter you must have permissions to access the project where adapter configuration is stored.

• Depending on whether a repository server is used, and whether TIBCO Administrator is used to set access permissions, you may need an account identified by Administrator. See the TIBCO Administrator User’s Guide for details.


Preparing your Environment for Installation | 27

Determine how the adapter installation files are to be transferred to this system. The installation files can be downloaded from download.tibco.com (if you have an account setup to download).

SAP R/3 Application Requirements• Determine which SAP R/3 application versions are supported.

— See Supported SAP R/3 Application Versions on page 39 for Microsoft Windows.

— See Supported SAP R/3 Application Versions on page 43 for UNIX systems.

• It is recommended that the SAP R/3 GUI be installed on the machine for troubleshooting and testing purposes.

• Download and install the SAP Java Connector on the machine where the adapter is being installed. Download the SAP Java Connector from the following URL:

http://service.sap.com/connectors

A valid SAP Service ID is required. For more information, contact your SAP BASIS administrator.

The TIBCO Adapter for R/3 run-time and design-time have been tested using the libraries available with SAP JCO 2.0.9. It is recommended that you use the same version.



Pre-Installation Worksheet

Use this form to capture the information you will need to collect before starting installing the TIBCO Adapter for SAP R/3.

Adapter Machine Information

Field Name Field Description Field Value

Hostname

(Example: adapter1.tibco.com)

Name of the machine on which the adapter is being installed.

IP address

(Example: 192.168.12.12)

IP address of the machine on which the adapter is being installed.

User account

(Example: administrator)

User account to be used for the installation.

User domain (if Windows)

(Example: ENGR2)

Network domain to which the user belongs.

User password

(Example: admin)

User Password

Disk/path on which to install adapter

(Example: /opt/tibco)

How will machine be accessed

[ ] directly [ ] terminal server [ ] xterm [ ] telnet

[ ] other: ………………………

How will installation files be transferred to machine

[ ] CD-drive [ ] internet download

[ ] FTP to machine [ ] network disk mounting


Pre-Installation Worksheet | 29

SAP R/3 Outbound Connection Information

SAP R/3 Inbound Connection Information

• Dedicated Application Server Connection Information


SAP Gateway Host:

(Example: athps5)

Name of the machine on which the SAP gateway server is running.

SAP Gateway Service:

(Example: sapgw00)

Gateway service to connect to, on the gateway server.

Program ID:

(Example: idocpub)

Program name to which the RFC destination is mapped.


User account for adapter

(Example: jsmith)

SAP client account to be used by the adapter.

Password for adapter

(Example: 1$todo)

Password for the above account.

Application Server hostname

(Example: sapserver1.tibco.com)

Name of the SAP R/3 application server to connect to.

System No

(Example: 00)

System number for the application server.

Client

(Example: 210)

Number assigned to the SAP client to which this user belongs.

R/3 Logon Language

(Example: EN)

Language to be used to logon to SAP R/3 for this client.



• Load-balanced Connection Information

SAP R/3 Client Software

Please specify where software for the SAP R/3 GUI can be found within your organization:

[ ] It's already installed on adapter machine.

Location on disk: ………………………….

[ ] Installation files are available via :

FTP (Server : ………… User : ………… Password: ……… )

Disk mount (full path : ………………………………………..)

CD provided during install by (name/extension) : ………………………..


User account for adapter

(Example: jsmith)

SAP user account to connect from the adapter.

Password for adapter

(Example: abc$&)

Password for the above account.

Group Name:

(Example: PUBLIC)

SAP R/3 logon group name to be used for load balancing.

Messaging Server Name

(Example: msgsvr1)

Name of the central SAP R/3 instance to connect to for load balancing.

System Name:

(Example: TIBCO)

SAP R/3 System ID to be used for load balancing.


Installer Overview | 31

Installer Overview

The installer allows you to run in different modes. Each mode is supported on all platforms.

• GUI mode

• Console mode

• Silent mode

GUI Mode

In GUI mode, the installer presents panels that allow you to make choices about product selection, product location, and so on. You can invoke the installer by clicking on the executable.

Console Mode

Console mode allows you to run the installer from the command line. This is useful if your machine does not have a GUI environment

Silent Mode

Silent mode either installs using default settings or uses a response file that was saved during an earlier installation. Silent mode installs without prompting you for information.

• If no response file has been recorded earlier and you invoke the installer with the -silent argument, the default installation parameters are used.

• If a response file exists, and the installer is started with -options <responseFileName> as an argument, the installer uses the values specified by the user when the response file was generated.

Upgrading an AdapterSoftware from TIBCO uses three numbers to indicate whether the release is major, minor or a patch. For example, 5.0.0 indicates a major release, 5.1.0 indicates a minor release and 5.1.1 indicates a patch release. The installer for a patch release performs an automatic upgrade. For example, the installer automatically upgrades TRA 5.0.0 to 5.0.1 by overwriting the contents of the 5.0 directory.



For a major and minor release, the installer prompts whether you wish to upgrade, and informs you if incompatible products are on your system. If you proceed, major or minor releases are installed under a new directory that is named using the major or minor release numbers.

For example, if you have installed the 5.0.0 release and are upgrading to a 5.1.0 minor release, it will be installed under the 5.1 directory. This allows both the 5.0 and 5.1 releases to coexist on the same machine.

If you are upgrading the adapter, or reinstalling a clean version of the software, you may uninstall the product first or allow the installer to perform the upgrade or reinstall.

Note that, if you are reinstalling over the same adapter version:

• You are not prompted to supply the installation location. The software is automatically reinstalled where the previous version was installed.

• If any files are currently locked (that is, in use), the installer marks the file for deletion in the install location. After installation, the installer prompts you to reboot your system. You must reboot before using the software.

Uninstalling an AdapterThe TIBCO Installation Manager (TIM) allows you to:

• Display installed products

• Display product components

• Display product dependencies and references

• Uninstall products and all references

To start the program:

• On Microsoft Windows:

Click Start>TIBCO>TIBCO Installation Manager

• On Unix:

<install-path>/tibco/TibcoInstallationManager.bin

The TIBCO Installation Manager displays all TIBCO software installed on your machine. Details about the selected TIBCO product are displayed in the right rows. Click the Uninstall button to remove the selected product. Note that some products cannot be uninstalled from the utility. Instructions about uninstalling these products are listed in the uninstall window (after clicking the Uninstall button).


Installer Overview | 33

Click the TIBCO Installation Manager help button for information about using the program.



Installation Registry

The installer maintains an installation registry. The registry location depends on platform. This section explains where the registry files are located. The files have vpd as a prefix, which stands for Vital Product Database. Note that the installer does not recognize TIBCO ActiveEnterprise 4.x products.

Microsoft Windows PlatformsActiveEnterprise 5.1 products maintain the installation registry in the SystemDrive:\WINNT directory. The following files represent the installation registry:

SystemDrive:\WINNT\vpd.propertiesSystemDrive:\WINNT\vpd.properties.tibco.systemName

Installer Disk Space Requirements in Temporary Area

The entire package is extracted into a temp folder, typically SystemDrive:\Temp or SystemDrive:\Documents and Settings\<user_name>\Local Settings\Temp

The installer requires 66 MB of free space in the temp directory.

UNIX PlatformsThe installation registry is maintained in the following files in the user’s home directory:

User_Home_Directory/vpd.propertiesUser_Home_Directory/vpd.properties.tibco.systemName

If installation is performed by super-user (root), the installation registry is maintained as follows:

• On Solaris and HP-UX, in the root user’s home directory (which is /) has two vpd files.

• On Linux, in the /root directory has two vpd files.

• On AIX, in the /usr/lib/objrepos directory has two vpd files.

Do not edit, modify, rename, move, or remove any of the registry vpd files.


Installation Registry | 35

Installer Disk Space Requirements in Temporary Area

The installer first extracts a Java Virtual Machine (JVM) in a temporary directory and uses this JVM to launch itself. The size of the extracted JVM differs from platform to platform.

On UNIX platforms the following disk space is required in the temporary area:

• On Solaris, 91 MB of free disk space in /var/tmp

• On HPUX, 120 MB of free disk space in /var/tmp

• On AIX, 118 MB of free disk space in /tmp

• On Linux, 125 MB of free disk space in /tmp

If your system does not have sufficient free disk space in the above temporary area, you can still run the installer with a different temporary area by using the following option when starting the installer:

<install_package_name>.bin -is:tempdir /new_tmp

where /new_tmp has sufficient free disk space.

Disk Space Requirement in User’s Home Directory

On UNIX platforms when a regular (non-root) user installs a TIBCO 5.1 product, the installation registry (two vpd files) is maintained in the user's home directory. As more products are installed, entries are added into these vpd files.

The user's home directory must at least have 500 KB of free disk space.

Installation HistoryThe installer and uninstaller create a file called TIBCOInstallationHistory.xml in the same location where the installation registry is created. Each time an installation and uninstallation is performed, entries are appended to the file.

On Windows: SystemDrive:\WINNT\TIBCOInstallationHistory.xml

On UNIX: Users_Home_Directory/TIBCOInstallationHistory.xml

The file TIBCOInstallationHistory.xml therefore contains the record of all installation and uninstallation activities of all products, features and components.

Do not edit, modify, rename, move, or remove the TIBCOInstallationHistory.xml file.



Adapter Components and Compatible Software

You can install different adapter components on different machines. For example, you can run the runtime adapter on one machine and install the design-time components on another machine. This allows you to configure an adapter on one machine and run it on another.

Adapter ComponentsTable 1 describes the adapter components on the adapter installation package.

Required and Optional TIBCO ProductsDepending on the tasks you wish to perform, you must install one or more other TIBCO products. The next table describes required and optional products and their purpose.

Table 1 TIBCO Adapter components

Component Description

Run-time adapter This process does the actual work of passing and converting data to and from the vendor application. Parameters of data exchanges are stored in projects created using the adapter palette and the design-time adapter (see below).

Adapter palette Adapter-specific GUI that is loaded in TIBCO Designer (see next section for details) at configuration time.

TID Manager Eliminates duplicate transactions (tRFCs)

Table 2 Compatible products

Component Purpose

TIBCO Runtime Agent 5.1.2

Required. TIBCO Runtime Agent supplies a number of TIBCO and third-party libraries used by the adapter and other TIBCO products both at design-time and runtime. This includes RVD libraries, SDK libraries etc. For example maverick50.dll.

You must install TIBCO Runtime Agent on each machine that hosts an adapter. TIBCO Runtime Agent must be installed before you install the adapter.


Adapter Components and Compatible Software | 37

TIBCO Designer 5.1.2 Required. TIBCO Designer is an easy to use graphical user interface for design-time configuration of TIBCO adapters.

TIBCO Designer is installed as part of the TIBCO Runtime Agent installation.

TIBCO Administrator 5.1.2

Required. TIBCO Administrator is available in two editions, Repository Edition and Enterprise Edition. You must install either edition. The Repository Edition does not include the Application Management module. Enterprise Edition is required if you are using the adapter with TIBCO BusinessWorks. Administrator includes the following modules:

• User Management. Management of authentication, roles and users, that is, connecting roles (groups) and users to access control lists (ACLs). This includes security for server-based projects at design-time and for deployed applications at runtime.

• Resource Management. Monitoring of machines and of all running applications in a TIBCO administration domain. Alerts can be created, for example, to notify an administrator if the number of processes or disk usage exceed a certain number.

• Application Management. Uploading of Enterprise Archive (EAR) files, creation, configuration, deployment, and monitoring of applications. This console is also used to start and stop applications.

TIBCO Administrator is available as a separate installation and can be installed after installing the adapter.

TIBCO BusinessWorks 5.1.2

Optional. TIBCO BusinessWorks is a scalable, extensible, and easy to use integration platform that allows you to develop integration projects. TIBCO Adapters are typically part of integration projects created using BusinessWorks.

TIBCO BusinessWorks is available as a separate installation and can be installed after installing the adapter.

TIBCO Enterprise for JMS 3.1.1

Optional. TIBCO Enterprise for JMS allows you to use the Java Messaging Services (JMS) as the message transport for your adapter.

TIBCO Enterprise for JMS is available as a separate installation and can be installed after the adapter is installed.


Component Purpose



TIBCO Hawk 4.2.0 Optional. TIBCO Hawk allows you to use the adapter’s built-in Hawk microagents to monitor and manage the adapter.

TIBCO Hawk is available as a separate installation and can be installed after the adapter is installed.


Component Purpose


Installing on Microsoft Windows | 39

Installing on Microsoft Windows

Before starting the installation, review the topics in this section to determine that your system meets the basic requirements and that you have the prerequisite software installed.

Memory requirement for the adapter installation is around 256 MB.

The following is a list of prerequisites for installing the adapter on Microsoft Windows systems. See Installer Disk Space Requirements in Temporary Area on page 34 for additional disk space requirements.

Table 3 Supported platforms, package names, service packs and disk space for Microsoft Windows

Supported SAP R/3 Application Versions

The adapter works with the following versions of SAP R/3:

• SAP R/3 software, version 3.1H

• SAP R/3 software, version 3.1I

• SAP R/3 software, version 4.0B



• SAP R/3 software, version 4.6C

• SAP R/3 software 4.7 (Non-Unicode version)

Platform Package Names Service Pack Disk Space (MB)

Microsoft Windows NT

TIB_adr3-simple_5.1.0_w32.exe Service Pack 6 80 MB

Microsoft Windows XP Professional

TIB_adr3-simple_5.1.0_w32.exe 80 MB

Microsoft Windows 2000 Professional (Server or Advanced Server)

TIB_adr3-simple_5.1.0_w32.exe Service Pack 2 80 MB

Microsoft Windows 2003

TIB_adr3-simple_5.1.0_w32.exe 80 MB



TIBCO Runtime Agent Must be Installed Before the Adapter

Before you can install the adapter, you must install TRA. If you choose the Typical installation mode for TRA, the installer places all libraries and other products required by the adapter into the TIBCO HOME directory.

During installation, the adapter installer checks for the availability of all required products in the system. If any of these are not available, the installer does not proceed with the installation.

Installer Account

You must have administrator privileges for the machine on which the adapter is installed.

If you do not have administrator privileges, the installer will exit. You must then log out of the system and log in as a user with the required privileges, or request your system administrator to assign the privileges to your account.

Installing from Network Drive

If you intend to install the product on a network drive, you must ensure that the account used for installation has permission to access the network drive.

Installing on Windows 2000 and 2003 Terminal Server

There are two modes in Windows Terminal Server: Execute and Install. Users are logged on by default in Execute mode, which allows them to run applications. To install an adapter so that everyone can use it, log on as administrator in Install mode. When the adapter is installed in the Install mode, the installation registry is maintained in SystemDrive:\WINNT\.

The best way to install the adapter on Windows Terminal Server is to use the Add/Remove Programs control panel applet. This automatically sets your mode to Install during the installation and then back to Execute afterwards. Alternatively, you can manually change your mode to Install before starting the installation by typing the following at a command prompt:

C:\> change user /install

Change back to Execute mode after installation is complete by typing:

C:\> change user /execute

Windows Terminal Server must be running in remote admin mode, not application sharing mode. The adapter is not supported if installed on a machine that is using Windows Terminal Server in application sharing mode.


Installing on Microsoft Windows | 41

To check your current mode, type the following:

C:\> change user /query

Installing the Adapter on Microsoft WindowsYou can either download the adapter package or install the package from a CD. The installer prompts you to accept the license agreement. Then you can choose to perform a typical install or custom install.

• A typical install has minimal prompts and installs standard components in default locations.

• A custom install prompts you to choose which components of the product suite to install and installs only those components.

The installer checks your system for the installation home directory that was established when TIBCO Runtime Agent was installed. The adapter is installed under the installation home directory.

Use one of the following modes to install the software.

Install Using GUI Mode

GUI Mode allows you to input values in panels. Double-click on the following executable:

TIB_adr3-simple_5.1.0_w32.exe

Install Using Console Mode

Console mode allows you to install the software from a command line. The installer will prompt you for values. Type the following at the command prompt:

TIB_adr3-simple_5.1.0_w32.exe -is:javaconsole -console

When running in console mode you can move through the installation process as described next:

Enter Key or 1 = Moves forward in the installer2 = Goes back to previous screen3 = Cancels the Wizard and exits the installation or uninstallation4 = Redisplays the current screen

There must not be any spaces in the installation directory path.



Install Using Silent Mode

Silent mode allows you to install the software without prompts. Type the following at the command prompt:

TIB_adr3-simple_5.1.0_w32.exe -silent

Install and Generate a Response File

You can generate a response file during any installation of the product and can use the same file in future installations. For all installation modes using response file, the options in the file determines what will be installed.

To install and generate a response file, type the following at the command prompt:

TIB_adr3-simple_5.1.0_w32.exe -options-record C:\directory\<responseFile>

Install Using a Response File

You can use a previously generated response file for installation. For all installation modes, the response file determines what will be installed.

To install using a response file, type the following at the command prompt: TIB_adr3-simple_5.1.0_w32.exe -options

C:\directory\<responseFileName>

Combining OptionsYou can combine the different available options. For example, to install in silent mode using a response file, use: TIB_adr3-simple_5.1.0_w32.exe -silent -options <responseFileName>

To install using Console mode and generate a response file, use: TIB_adr3-simple_5.1.0_w32.exe -is:javaconsole -console -options-record <responseFileName>


Installation on UNIX Systems | 43

Installation on UNIX Systems

Memory requirement for the adapter installation is around 256 MB. Your operating system must meet the minimum patch requirements listed next. See Installer Disk Space Requirements in Temporary Area on page 35 for additional disk space requirements.

Supported SAP R/3 Application Versions

The adapter works with the following versions of SAP R/3:

• SAP R/3 software, version 3.1H

• SAP R/3 software, version 3.1I


Table 4 Supported platforms, package names, patches and disk space for UNIX systems

Platform Package Names Minimum Patch(es)Disk Space (MB)

Solaris 7 TIB_adr3-simple_5.1.0_s4_57_CC.bin 107544-03 106980-17 106950-16 108376-33 106300-12

106327-11 106541-18 107081-40 107636-08 107226-18 108374-05 107656-07

107702-09 107153-01

75 MB

Solaris 8 TIB_adr3-simple_5.1.0_s4_58_CC.bin 108940-33 108773-12 108652-37 109740-04

109742-04 109279-18 108921-13

75 MB

Solaris 9 TIB_adr3-simple_5.1.0_s4_58_CC.bin 75 MB

HP-UX 11, 11i TIB_adr3-simple_5.1.0_h7_110_aCC.bin 80 MB

AIX 5.1 TIB_adr3-simple_5.1.0_rs_51_xlrc.bin 95 MB

Red Hat AS 2.1

TIB_adr3-simple_5.1.0_lnx86_24_glibc.bin

75 MB





• SAP R/3 software, version 4.6C

• SAP R/3 software 4.7 (Non-Unicode version)

TIBCO Runtime Agent Must be Installed Before the Adapter

Before you can install the adapter, you must install TRA. If you choose the Typical installation mode for TRA, the installer places all libraries and other products required by the adapter into the TIBCO HOME directory.

During installation, the adapter installer checks for the availability of all required products in the system. If any of these are not available, the installer does not proceed with the installation.

Installer Account

TIBCO 5.x products can be installed by a regular (non-root) user and super-user (root). Different users can install the same product at different locations.

Product dependencies at install time are resolved at user level through the installation registry maintained at user's home directory. See Installation Registry on page 34 for more information.

Windows Environment

A window environment such as CDE (i.e. X Windows) is required to run the installer in GUI mode. It is not required for a console or silent mode installation.

Installing the Adapter on UNIXAfter running the software and accepting the license agreement, you can choose to perform a typical install or custom install.

• A typical install has minimal prompts and installs standard components in default locations.

• A custom install prompts you to choose which component of the product is to be installed and installs only those components.

The installer checks your system for the installation home directory that was established when TIBCO Runtime Agent was installed. The adapter is installed under the installation home directory.


Installation on UNIX Systems | 45

• If installing the adapter on AIX, use a non-root user account.

Use one of the following modes to install the software. The examples assume you are installing the adapter on Solaris 8.

Install Using GUI Mode

GUI Mode allows you input values in panels. Type the following in a terminal window and press ENTER:

% ./TIB_adr3-simple_5.1.0_s4_58_CC.bin

Install Using Console Mode

Console mode allows you to install the software from a command line. The installer will prompt you for values. Type the following in a terminal window:

% ./TIB_adr3-simple_5.1.0_s4_58_CC.bin -is:javaconsole -console

When running in console mode you can move through the installation process as described next:

Enter Key or 1 = Moves forward in the installer2 = Goes back to previous screen3 = Cancels the Wizard and exits the installation or uninstallation4 = Redisplays the current screen

Install Using Silent Mode with Default Values

Silent mode allows you to install the software without prompts using default values. Type the following in a terminal window:

% ./TIB_adr3-simple_5.1.0_s4_58_CC.bin -silent

Install and Generate a Response File

You can generate a response file during any installation of the product and can use the same file in future installations. For all installation modes using response file, the options in the file determines what will be installed.

To install and generate a response file, type the following at the command prompt:

% ./TIB_adr3-simple_5.1.0_s4_58_CC.bin -options-record

There must not be any spaces in the installation directory path.



/dir/<responseFile>

Combining OptionsYou can combine the different available options. For example, to install in silent mode using a response file, use: % ./TIB_adr3-simple_5.1.0_s4_58_CC.bin -silent -options /dir/<responseFileName>

To install using Console mode and generate a response file, use: % ./TIB_adr3-simple_5.1.0_s4_58_CC.bin -is:javaconsole -console -options-record /dir/<responseFileName>

The response file does not record selections at the component level It does record all other selections, for example, which products you wish to install.


Post Installation | 47

Post Installation

Ensure that there is only one copy of the individual SAP JCO components on your machine. In particular, ensure that the librfc32.dll (or librfccm.so or librfccm.sl or librfccm.o) library that comes with SAP JCO 2.0.9 is the only version of librfc on the machine. This library is also packaged with the SAPGUI. Hence, if you have SAPGUI installed on the machine and the librfc library packaged by SAPGUI precedes the SAP JCO 2.0.9 librfc library, the adapter will use the wrong librfc version.

If there is a version mismatch the following error is displayed.

Permission Requirements on UNIX SystemsAll adapter users must have read, write, and execute permissions for the following directories:

$TIBCO_HOME/adapter/adr3/5.1/bin $TIBCO_HOME/adapter/adr3/5.1/logs$TIBCO_HOME/tra/5.1/logs$TIBCO_HOME/logs

For example, if the adapter has been installed in /opt/tibco, the user who installed the adapter can make these directories writable for all other users by executing the following commands:

% chmod a+w /opt/tibco/adapter/adr3/5.1/bin/% chmod a+w /opt/tibco/adapter/adr3/5.1/bin/logs% chmod a+w /opt/tibco/tra/5.1/logs

Prerequisites for Running the AdapterYou need to carry out the following tasks for successful messaging between the application and the TIBCO environment.

• Prepare the SAP R/3 system to communicate with the adapter. See Preparing the SAP R/3 System on page 61 for details.

• Set environment variables. See Setting Environment Variables on page 48.



Setting Environment VariablesThe adapter sets the environment variables differently depending on whether the adapter is installed on UNIX or Windows.

Windows

The adapter’s default property file adr3.tra has a property named tibco.env.PATH. During installation, the installer updates the tibco.env.PATH in this file with the location of the TIBCO software required by the adapter.

For example, the installer writes the following for tibco.env.PATH in adr3.tra:C:/TIBCO/adapter/adr3/<ver>/hotfix/lib; C:/TIBCO/adapter/adr3/<ver>/lib;C:/TIBCO/tra/5.1/hotfix/bin;C:/TIBCO/tra/5.1/bin;C:/TIBCO/tpcl/5.1/bin;C:/TIBCO/TIBRV/bin

Note that the adr3.tra file is the default property file that is shipped with the adapter.

To launch your adapter configuration, make a copy of this file and update the repository and configuration url to the correct values in the copy.

When the adapter is started with this newly created custom property file, the system settings are automatically updated.

The following example illustrates the procedure to start the adapter from the command line:

1. Create an adapter configuration in TIBCO Designer and save it to a project.

2. Copy the default adr3.tra file to MyAdapter.tra

3. Update tibco.repourl and tibco.configurl parameters in MyAdapter.tra

4. Update application.args parameter to application.args adr3 -system:propFile <absolute path to MyAdapter.tra>

5. Start the adapter with the command adr3 --propFile MyAdapter.tra

It is assumed that MyAdapter.tra is in the adapter installation bin directory. If it is copied to any other location, provide the absolute path to this file in the command as explained in the previous step.

See Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition on page 295 for details.


Post Installation | 49

Unix

A shell script adr3setenv.csh is provided with the installation. Running this file in the C-Shell updates the system path and library path settings.

The following environment variables are updated by the script:SHLIB_PATH (HP-UX)

LD_LIBRARY_PATH (Solaris and Linux)

LIBPATH (AIX)

PATH (ALL Platforms)

Note that the shell script updates the environment for the current shell session only. If you open a new shell session, run the script afresh to update.


1. Create an adapter configuration in TIBCO Designer and save it to a project

2. Copy the adr3.tra file to MyAdapter.tra



5. Open a c-shell by typing csh at the prompt.

6. Run the script adr3setenv.csh in <install-dir>/5.1 with the following command:

source adr3setenv.csh

If the settings are updated successfully, the following message is displayed:

environment variables successfully set

7. Start the adapter with the following command:

adr3 --propFile MyAdapter.tra


See Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition on page 295 for details.

The following table lists useful environment variables that you can set on the machine where the adapter is installed.



Name Description Valid Values Default

RFC_TRACE Turns the RFC Trace on for all connections established by the adapter to the SAP R/3 system

0 - OFF

1 - ON

0

RFC_TRACE_DIR Defines location for RFC trace files A valid directory Working Directory

RFC_MAX_TRACE The maximal size (in megabytes) of trace files

8 MB

RFC_INI Location of the saprfc.ini file A valid directory Working Directory

CPIC_MAX_CONV Defines the maximum number of active RFC connections at a time

A valid integer 100


Installation FAQs and Troubleshooting | 51

Installation FAQs and Troubleshooting

This section lists some of the frequently asked questions, common errors along with their causes and solutions.

Frequently Asked Questions

Where is the installation log file located?

Install and uninstall log files are created in the TIBCO_HOME\log directory.

What should I do, if JVM crashes when I run the installer?

TIBCO product installer contains JVM 1.1.8 (except on linux and HP platforms which bundle 1.3.1). The installer first extracts the bundled JVM into a temporary area and then uses it to launch itself. If for some reason, the JVM crashes, you could still run the installer using another JVM, preferably JVM 1.3.1 or higher. The syntax is:

TIB_adr3-simple_5.1.0_w32.exe -is:javahome C:\j2sdk1.4.0TIB_adr3-simple_5.1.0_s4_58_CC.bin -is:javahome /opt/jre140

The executable name used in the example above is for Solaris 8.

The javahome directory must contain bin/java.exe or bin/java.

The installer will use the externally supplied JRE to launch itself.

Will 5.1 installer recognize a 3.x or 4.x installation?

TIBCO products follow a three digit release numbering scheme:

Major.Minor.Maintenance

Product releases that differ in either Major or Minor numbers will be a separate installation, and will not recognize the old installation. In this case, 5.1 is a minor release and hence will not recognize either 3.x or 4.x product installations.



Why and how should I set the DISPLAY variable on UNIX platforms for GUI mode?

The installer in GUI mode on UNIX, must open an additional window, generally for graphics. It uses the DISPLAY environment variable to let the user know on what computer the window is to be opened. If the environment variable is not set, the installer will either wait or abort after displaying:

InstallShield WizardInitializing InstallShield Wizard...Preparing Java(tm) Virtual Machine.................................................................................

The DISPLAY variable must be set to the IP address or name of the computer (on which the installer graphics window are to be displayed), followed by a screen address, which can be :0.0 . For example:

# Bourne shellDISPLAY=<ip_address>:0.0; export DISPLAY

# Korn shellexport DISPLAY=<ip_address>:0.0

# C-shellsetenv DISPLAY <ip_address>:0.0

For example, consider a scenario where you need to install the adapter on a remote HPUX machine (named itaska). Because you have a Solaris 5.6 machine (named alaska) that has a video card and monitor installed, you can run an X-window application on it. So you decide to telnet to itaska from alaska.

When you telnet to itaska, you will not get access to itaska’s monitor and will be unable to display an X-window application. That is why you must set the DISPLAY variable, which instructs the X-server to redirect all windows to the computer set in the variable. Before doing so, the computer (specified in the DISPLAY variable) must give permissions to share its monitor.

alaska> xhost + # give permission for all to its share monitoralaska> telnet itaskaWelcome to HPUX itaska 11.00User:Password:itaska> export DISPLAY=alaska:0.0 # set display on alaskaitaska> TIB_adr3-simple_5.1.0_h7_110_aCC.bin



What is uninst2 directory?

If the original uninstall directory is in use at uninstall time, it cannot be removed by the installer program. The installer then creates a second uninstall directory for the second installation. To remove the second installation, you must invoke the uninstall program from the second uninstall directory. The original uninstall directory can also be manually removed, if empty.

Speeding Up InstallationThe installer for TIBCO 5.x products is Java-based and requires a Java Virtual Machine (JVM) to launch. If the installer can use a JVM already on your system, installation is faster and uses less disk space. Otherwise, the installer extracts JVM from the installation package. This section explains where the installer searches for JVM, and how you can add a different location to the search path.

Every product installer is bundled with the appropriate platform-specific JVM version. When launched, the installer first searches for the appropriate JVM version on the target system.

• If the installer finds the required JVM version, it uses that JVM to launch itself.

• If the installer does not find the required JVM version, it extracts the bundled JVM into a temporary space and uses that JVM to launch itself.

How the Installer Searches for JVM

The installer by default searches for an appropriate JVM version in a set of standard locations. These standard locations are platform specific and are listed in JVM Search Locations on page 55. On each platform, the installer searches for JVM 1.3.1 only.

Speeding up JVM Search

You can speed up the JVM search by taking one of these actions before you launch the installer:

• Set the environment variable JAVA_HOME or JDKHOME to the JVM home directory, for example:

Unix Bourne or Korn shell:

JAVA_HOME=/opt/jre1.3.1; export JAVA_HOME

Unix C-shell setenv JAVA_HOME /opt/jre1.3.1



• Include a command line option -is:javahome when launching the installer. For example:

Benefits of Using Available JVM over Extracting Bundled JVM

• JVM search is quick. It is searched for in well defined locations. It can be sped up by setting an environment variable or by using a command line option.

• Extraction of bundled JVM is avoided, which saves both time and temporary disk space. Initial loading of the installer is faster.

• If the bundled JVM is extracted and used for launching the installer, then a copy of this JVM is installed for launching the uninstaller in the _jvm directory in the product location.

However, if JVM was resolved through JVM search, the uninstaller just points to this JVM and uses it later to launch itself. In this case, JVM is not installed. This is a major benefit in terms of disk space.

For example, on HP-UX, the size of JVM 1.3.1 is about 80 MB. When the TIBCO Runtime Agent (TRA) suite is installed, and if the bundled JVM is used for launching the installer, a copy of JVM 1.3.1 is installed for each of the five products in the suite. This results in an additional 400 MB of disk space used. If a local JVM can be used, these 400 MB are not needed.

• If the JVM the uninstaller points to is removed at any time, you can still run the uninstaller using the -is:javahome option to point to a different JVM location.

Microsoft Windows

1. Choose Start->Settings->Control Panel->System-Environment->System Variable or User Variables

2. Add a JAVA_HOME variable and set its value

NOTE: On Microsoft Windows, setting JAVA_HOME in a command prompt will not be effective.

Windows suite installer

<exe> -a -is:javahome c:\java\JRE\1.3.1

Other installers <exe_or_bin> -is:javahome /opt/jre1.3.1



JVM Search Locations

The following tables list the search locations for the different platforms.

The installer only searches for JVM version 1.3.1. If a different JVM version exists in the system, or is passed in using the environment variable or command-line option, the installer ignores that JVM and extracts the bundled JVM.

Table 5 Windows (JVM 1.3.1)

Location Description

Environment Set in ControlPanel, not in command prompt)JAVA_HOME JDKHOME

JVM 1.3.1

Registry \HKEY_LOCAL_MACHINE\SOFTWARE\ JavaSoft\Java Runtime Environment\ 1.3\JavaHome \HKEY_LOCAL_MACHINE\SOFTWARE\ JavaSoft\ Java DevelopmentKit\1.3\JavaHome

Directory \Program Files\JavaSoft\JRE\1.3.1\JavaSoft\JRE\1.3.1 \Java\JRE\1.3.1

Table 6 Solaris (JVM 1.1.8 & 1.3.1)


Environment JAVA_HOMEJDKHOME

Path /usr/jre1.3.1 /usr/java1.3.1 /usr/jdk1.3.1 /opt/jre1.3.1 /opt/java1.3.1 /opt/jdk1.3.1

Table 7 HPUX (JVM 1.3.1)


Environment JAVA_HOME

JDKHOME

Path /opt/java1.3

/opt/java1.3/jre



Running Out of Disk SpaceThe installer calculates the disk space required in product home location, for the selected components. The calculation is done before the actual installation (copying of files to system) begins. The installer will proceed only if sufficient free disk space is available in product home location.

However, if disk space is consumed by another process while the installer is copying the files, and if the required disk space is thereby reduced, the installer may fail and will then give a failure message.

Solution

While performing installation, avoid running other processes that consume disk space in product home location.

Installation Errors on HPUX 11.00 64 bit Platform

Error message

Installation on a HPUX 11.00 64 bit system may crash with the following error message:

Pid nnn killed due to trashed stack.

Table 8 AIX (JVM 1.3.1)


Environment JAVA_HOME JDKHOME

Path /usr/jdk_base/usr/jdk_base /usr/java131 /usr/java131

Table 9 Linux (JVM 1.3.1)


Environment JAVA_HOME JDKHOME

Path /usr/jre1.3 /usr/local/jre1.3 /opt/jre1.3 /opt/j2re1.3.1



Pid nnn was killed due to failure in writing the signal context.

This happens only on HPUX 11.00 64 bit systems. It does not happen on HPUX 11.00 32 bit system and HPUX 11.11 (or 11.i) system.

To determine the OS version on your system, run:

uname -a

To determine the kernel bits on your system, run:

getconf KERNEL_BITS

Resolution

HPUX kernel patch PHKL_27282, resolves the above crash.

To determine if your system has the kernel patch, run:

/usr/sbin/swlist -l product PHKL_27282

or

what /stand/vmunix | grep PHKL_27282

If your system is an HPUX 11.00 64 bit system and it does not have the patch, first install HPUX kernel patch PHKL_27282 and then proceed with the installation. Installation of patch PHKL_27282, will reboot your system.

Configuring TIBCO Hawk

Error

TIBCO Runtime Agent includes the TIBCO Hawk Agent only. If you install the full TIBCO Hawk package after installing TIBCO Runtime Agent and do not have a Java Runtime Environment (other then the TIBCO JRE) installed, the TIBCO Hawk Configuration tool is unable to determine the Java home location and the JVM executeable. The TIBCO Hawk services will not start correctly and you will be unable to start the TIBCO Hawk Display.

Resolution

1. Start the TIBCO Hawk Configuration tool. For example, on Microsoft Windows:

Start>TIBCO>TIBCO Hawk>Hawk Configuration

2. Under the General tab, click Advanced.

3. In the Java Home Directory field, provide the path to Java. For example:



C:\tibco\jre\1.4.2

4. In the JVM Executable field, provide the JVM executable. For example:

java.exe

The services will start properly and the TIBCO Hawk Display will run.

Cannot Install the AdapterOn HP-UX and AIX platforms, even though the correct version of TIBCO Runtime Agent version is already installed on the system, installation of an adapter that depends on TIBCO Runtime Agent may fail in the dependency resolution.

The TIBCO product installer maintains the registry information in the vpd.properties.tibco.systemName file. The value for systemName is determined by InetAddress.getLocalHost().getHostName(). However, the method getHostName(), returns different values based on the JRE versions used. For example, on AIX, JRE 1.3.1 returns only systemName, whereas JRE 1.4.0 returns systemName.domainName. Because of this, the installer is not able to load the correct registry file.

Resolution

On Unix platforms, the installer registry file vpd.properties.tibco.systemName is located in the user’s home directory.

Case 1: If the vpd.properties.tibco.systemName file exists:

$ cd user’s_home_directory$ ln -s vpd.properties.tibco.systemName

vpd.properties.tibco.systemName.domainName

For example:$ cd ~$ ln -s vpd.properties.tibco.upside vpd.properties.tibco.upside.tibco.com

where upside is systemName, and tibco.com is domainName

Case 2: If the vpd.properties.tibco.systemName.domainName file exists:

$ cd user’s_home_directory$ ln -s vpd.properties.tibco.systemName.domainName vpd.properties.tibco.systemName

For example:

$ cd ~$ ln -s vpd.properties.tibco.upside.tibco.com vpd.properties.tibco.upside



where upside is systemName, and tibco.com is domainName.


| 61

Chapter 3 Preparing the SAP R/3 System

This chapter gives an overview of the minimum requirements and authorizations required to extract metadata from a SAP R/3 system in TIBCO Designer during the configuration stage. The steps for customizing a SAP R/3 system for Inbound and Outbound messaging are also described.

You must enable the SAP R/3 system for messaging with the TIBCO environment by carrying out appropriate customization. No modifications or additional code is required in the SAP R/3 system itself.

Topics

• Design-time Requirements, page 62

• Run-time Requirements, page 64

• Configurations in the SAP R/3 System, page 67


62 | Chapter 3 Preparing the SAP R/3 System

Design-time Requirements

The following are the design-time requirements:

• Obtain a valid SAP R/3 user ID and password that allows access to a dedicated SAP R/3 application server. This is necessary even if you plan to configure the adapter for Outbound messaging only. A valid user ID and password is required to extract metadata for BAPIs/RFCs/IDocs using TIBCO Designer.

• Obtain required authorization from your SAP R/3 system administrator to execute Remote Function Calls and access tables in SAP R/3 for the design-time user ID. You will not be able to successfully extract schema information in TIBCO Designer without the necessary permissions in SAP R/3 for your user-id.

Specifically, ensure that the following Remote Function Calls can be executed successfully from transaction SE37 in your SAP R/3 GUI with the test-data provided.

Remote Function Call Test Input Data

RFC_GET_TABLE_ENTRIES systems TABLE_NAME = EDBAST (4.x and higher SAP R/3 systems)

TABLE_NAME = EDIDOT (for 3.x SAP systems)

RFC_GET_TABLE_ENTRIES TABLE_NAME = EDICM

RFC_GET_TABLE_ENTRIES TABLE_NAME = EDCIMT

EDI_IDOC_SYNTAX_GET PI_IDOCTYP = MATMAS01

PI_CIMTYP = <empty> or extended idoctype for MATMAS01, if any

RFC_GET_STRUCTURE_DEFINITION_P (for 4.x and higher systems) RFC_GET_STRUCTURE_DEFINITION_P

_3 (for 3.x SAP systems)

TABNAME = E1MARAM

RFC_FUNCTION_SEARCH FUNCNAME = * (or name of any RFC/BAPI)


Design-time Requirements | 63

• If you are configuring an Inbound adapter and the run-time connection parameters for the adapter are going to be different from the design-time, obtain the relevant connection information. For configuring a load-balanced inbound adapter, you will need parameters to connect to a messaging server for a specific logon group.

RFC_GET_FUNCTION_INTERFACE_P (4.x and higher SAP systems) RFC_GET_FUNCTION_INTERFACE (3.x SAP systems)

FUNCNAME = <name of any RFC/BAPI>

Remote Function Call Test Input Data

Ensure that your login parameters specify the correct language. IDocs/RFCs/BAPIs specific to a particular language will not be retrieved if you login to SAP R/3 from the SAP R/3 GUI or TIBCO Designer with a different language.



Run-time Requirements

Customization required for run-time interactions with the adapter are described here. The GUI screen shots describing the customization process in this chapter use SAP R/3 version 4.6C.

For customization process using SAP R/3 version 3.1H GUI see, SAP R/3 ALE Configuration on page 489. For other SAP R/3 versions refer to SAP R/3 documentation.

Additional steps might be required, depending on pre-existing maintenance and allocations in the client SAP R/3 system. Please refer to the help section in the SAP IMG (Implementation Guide) and other appropriate SAP R/3 user documentation before customizing.

Outbound MessagingThe SAP R/3 system has to be customized to send out BAPI/RFC Invocations and Intermediate Documents to the TIBCO environment. This section describes the minimum configuration to be done in the system to achieve outbound messaging.

Configuration Needed for Invoking BAPIs/RFCs from the SAP R/3 System

1. Define an RFC destination in the SAP R/3 system.

An RFC Destination should be defined and mapped to a program-id. The Outbound adapter registers on the SAP R/3 gateway with this program-id (specified in the adapter configuration) and receives BAPIs/RFCs invoked on the corresponding RFC Destination. An RFC destination allows the SAP R/3 system to invoke BAPIs/RFCs in the Outbound adapter.

For configuration details, see Defining RFC Destinations on page 76.

2. Make sure that the required authorizations for executing BAPIs and RFCs exist for the SAP R/3 username intended to be used.

Configuration Needed for Publishing IDocs from the SAP R/3 System

All required ALE outbound customizing can be done using the SAP implementation management guide (IMG, transaction SALE).

The following minimum steps must be performed to enable the transfer of SAP R/3 system IDocs to the TIBCO environment.


Run-time Requirements | 65

1. Create a logical system for the adapter. See Creating a Logical System for an Adapter Instance on page 68 for details.

2. Associate the client logical system with a SAP R/3 Client. See Creating a Logical System for the SAP R/3 Client on page 72 for details.

3. Define the customer distribution model - this defines what IDocs can be transferred in the outbound direction. See Establishing the Distribution Model on page 73 for details.

4. Define RFC destination. See Defining RFC Destinations on page 76 for details.

5. Define the Partner Profile. See Defining Partner Profiles on page 79 for details.

6. Set up (maintain) the RFC Transactional Port. See Maintaining Partner Profile on page 82 for details.

Inbound Messaging

Configuration Needed for Invoking BAPIs/RFCs from the TIBCO environment

Ensure that the SAP R/3 client performing invocations in SAP R/3 through the adapter (that is the Inbound adapter logged on to SAP R/3 with specific client connection parameters) has authorizations to invoke BAPIs/RFCs in the SAP R/3 system.

Authorization for each business activity needs to be given to the SAP R/3 client if that activity is performed via the adapter. For instance, if the Inbound adapter is configured to create sales orders in SAP R/3, then the SAP R/3 client needs all the required permissions to create a sales order.

Verify the authorizations by test-executing the BAPI/RFC from transaction se37 in the SAP R/3 GUI without specifying a destination.

ALE Customization for transferring IDocs from the TIBCO environment

All required ALE inbound customizing can be done using the SAP implementation management guide (IMG, transaction SALE).

The following minimum steps must be performed to enable the transfer of messages from the TIBCO environment into the SAP R/3 system as IDocs.

1. Create a logical system for the adapter. See Creating a Logical System for an Adapter Instance on page 68 for details.

2. Associate the client logical system with a SAP R/3 Client. See Creating a Logical System for the SAP R/3 Client on page 72 for details.



3. Define the customer distribution model - this defines what IDocs can be transferred in the inbound direction.

4. Define the Partner Profile. See Defining Partner Profiles on page 79 for details.

5. Maintain the Partner profiles. In the inbound parameters of partner profile, associate a Process Code for each IDoc type defined for the partner profile. Link this process code to a Function-module, which processes the inbound IDoc.


Configurations in the SAP R/3 System | 67

Configurations in the SAP R/3 System

The following section provides the steps required to customize the SAP ALE system, using the SAP R/3 GUI version 4.6C to operate with the adapter.

The steps are listed next.

• Creating a Logical System for an Adapter Instance

• Creating a Logical System for the SAP R/3 Client

• Establishing the Distribution Model

• Defining RFC Destinations

• Defining Partner Profiles

• Maintaining Partner Profile

• Defining an Extended IDoc Type



Step 1: Creating a Logical System for an Adapter Instance

The first requirement is to create an ALE logical system to represent the adapter publication service.

To create a logical system for the adapter application, follow these steps:

1. Log onto the SAP R/3 Server.

2. Run the sale transaction:

An ALE window appears with a hierarchical choice of configuration and maintenance options.

3. Navigate to,

Basic Settings>Logical Systems>Define logical system

and click



When you click to the left of the phrase Define logical system the following warning window appears.

4. Click to continue.

A Change View window appears like the following:

5. Click the New Entries button to create a new logical system.

An empty New Entries: Overview of Created Entries list window appears.

6. Enter the name of the new application logical system — DOCVIEW is shown below for example — under the Log.System column.



Enter a suitable description under the Short Text column.

7. Save the new logical system.

The Enter Change Request window appears.

Assign a change request to the change using an existing change request, or create a new change request. If you want to create a new change request, complete the following step.

8. Click on Create request in the bottom button bar.

The Create Request window appears.



9. Enter a short description and save the request.

The system returns you to the Change View window.

10. Scroll down the alphabetical list to verify the creation of the new logical system.

11. Click to return to the initial window.



Step 2: Creating a Logical System for the SAP R/3 Client

The logical system for the client represents the client itself as a business entity, so that the relationship between the client and other logical systems can be set up. To create a logical system for the adapter client, follow these steps:

1. Log onto the SAP R/3 Server.

2. Run the sale transaction.

3. Navigate to

Basic Settings>Set up logical system> Assign logical system to the client

4. Click the New Entries button to request the interface used to create a new logical system.

An empty New Entries window appears.

5. Enter the name of the new logical system in the top window and enter the city.

6. Choose from the Logical System pop-up, the client for which you want to create the new logical system (often the logical system you’re logged into).

7. Enter a suitable description under column Short Text and choose a role, such as Test.

8. Save the new logical system.



Step 3: Establishing the Distribution Model

To make ALE work properly, your SAP R/3 system needs to know the relationship between the logical systems. You can establish these relationships through the Maintain Distribution Model dialog.

To establish the distribution model, follow these steps:


2. Click next to Maintain distribution model.

The following window is displayed:

3. Click the Model View button to create a model view that contains the relationships between logical systems you want to establish.

The Create Model View window is displayed.

4. Type in the name and short description for the new model view, then click

to create the model view.



5. In the Maintain Distribution Model window, click Add Message type to establish the relationship between the logical systems you created.

6. Give the model view a name, then establish the relationship between the adapter and the client by choosing your client logical system (example - CLIENT830) as the Sender/client and your Adapter logical system (example - DOCVIEW) as the Receiver/server. Choose a message type (example - DOCMAS).

7. Repeat the process to include the type of the message you later want to send to the TIBCO environment. For example, include MATMAS if you want to send material IDocs.

8. Click and save.



Now you have established the relationship between the logical systems. You can view it by expanding the model on the original Distribution Model screen.

Figure 7 summarizes the distribution model as set up for the adapter application.

Figure 7 Client Distribution Model



Step 4: Defining RFC Destinations

An RFC destination allows the SAP R/3 system to call service functions in the R/3 Outbound Adapter configured as an IDoc publisher. RFC uses TCP/IP to interface with the R/3 Outbound Adapter.

One or more RFC destinations for the R/3 Outbound Adapter processes have to be defined. Usually, only one RFC destination is used. Multiple Outbound Adapter processes can be load balanced by a SAP R/3 gateway via a single RFC destination. Multiple destinations can be useful when different destinations are to be used for different ports. The ports are in turn used for different message types.

1. Run the sale transaction and navigate to

Communication>Define RFC Destination>TCP connections



2. Click the Create button. The following window appears.

3. Specify the RFC destination. The RFC destination should have the same name as the adapter logical system you created. Choose T (TCP/IP connection) as

the connection type, and click .

4. Save the setting.



5. In the RFC Destination window, click Registration and specify the Program ID.

6. Click the Save icon. This completes definition of an RFC destination.

The Program ID must match the Program ID value in the adapter instance in the repository. See Configuring Default Server Connection on page 222. It is a good idea to use a different name than that of the logical system itself. Also, it is recommended that you do not associate the name to the RFC destination or logical system.



Step 5: Defining Partner Profiles

The partner profile consists of information about the partners participating in a logical system.

Given below are a couple of examples for information included in a partner profile,

• information on transferred documents

• information on whether the logical system receives or transmits data.

To set up the partner profiles, follow these steps:

1. Run the sale transaction and choose Communication>Generate Partner Profiles.

2. In the window that appears, select the distribution model you defined earlier as the Model View and the logical system for the Adapter you defined earlier as the Partner system.

3. For all other fields, retain the default settings.

4. Choose the execute button.



5. If execution works without errors, save the partner profile by clicking the small open-folder icon. The partner profile will be created with the default port.

6. Enter transaction we21 or run transaction nsale and navigate to

Communication>Manual Maintenance of Partner Profiles >Define Port

7. Click on Transactional RFC to highlight it and click the Change (Pencil) icon.

In case you want to change the port associated with the message type, following steps need to be carried out to create a port.



8. Click New entries on the next window.

9. Enter (or select) the name of the logical system and give a description for the new port. This completes definition of a partner profile.

If multiple logical message types are used in your environment, it is recommended that you define different ports for different message types or for groups of message types.

The presence of the “Version” entry is important. It determines the version of IDocs transmitted, 30x or 40x. Version value of 2 causes EDI_DC (IDoc version 30X) metadata to be used for the IDoc publisher mode. Version value of 3 causes EDI_DC40 (IDoc version 40X) metadata to be used for the IDoc publisher mode.



Step 6: Maintaining Partner Profile

An outbound partner profile must be defined for each logical message type that is to be sent to the TIBCO environment. The outbound partner profile defines the message syntax to be used for the logical message type, the transfer mode, the port to send to, and the workflow parameters (where error notifications are to be sent etc.). In the previous section (Defining Partner Profile), the partner profile is created for logical message type MATMAS. This section explains how you change the partner profile to add, delete or change the message types and associated parameters.

1. Run transaction sale and work through the hierarchy displayed to:Communication>Manual Maintenance of Partner Profiles>Maintain Partner Profile.

2. Choose the adapter logical system you defined earlier and LS as the partner type, then click the change (pencil) icon.

3. In the next window, enter ALE as the partner type and A (active) as the partner status.

4. Select Outbound Parameters.

5. Change the Outbound Parameters so each message type is included for your publisher.



6. Save the Partner Profile for the publisher.



Step 7: Defining an Extended IDoc Type

SAP R/3 makes basic IDoc types available for use with SAP processes. You can create extensions to a basic IDoc type using the procedure described in this section.

1. To create an IDoc extension, initiate transaction WE30. The Develop IDoc Types screen is displayed. An example of this screen is shown below. Set the Extension radio button as shown below to indicate that you are going to create an extension to an existing IDoc type.

2. Enter the name of your IDoc extension in the ObjectName text box. Note that names used by SAP R/3 are case insensitive. See the following example.



3. Click the Create icon (folded paper) or enter the function F5 key to proceed with extension creation. The Create extension screen is displayed, as shown below.

4. Set the Create new radio button. This step associates the new extension with a basic IDoc type. This is done by entering the name of a basic IDoc type, such as DEBMAS03, in the text entry box labeled Linked basic type.

5. Click the down arrow to the right of the text entry box and select the basic type from the list that is displayed. When you have entered the basic IDoc type, enter a description in the Description box. When your entries are

complete, click to proceed with the extension creation.

6. The following Create extension screen is displayed. This screen shows the initial default segments contained in the new IDoc extension, as defined by



the basic IDoc type (DEBMAS03 in the example). Add segments using this screen.

7. For example, you can add a second child segment to segment E1KNA1L by highlighting the current child segment and clicking on the Create icon (folded paper).

8. An information screen is displayed as shown in the following example. Click

to acknowledge the information.



9. The Attribute Maintenance screen is displayed as displayed in the following example. Enter a valid existing segment type, such as ZLEON as shown in the example screen. Also enter values for the Minimum and Maximum Number

of segments that are allowed. Click .

10. The Create Extension screen is displayed again with the new child segment as shown in the example below. Save the new IDoc extension.


| 89

Chapter 4 Getting Started

This chapter describes the basic steps that are required to configure and run the adapter. More extensive details for each of the steps described here are provided later in the manual.

Topics

• Creating a Project for the Adapter, page 90

• Working with the Sample Project, page 91

• Sample Configurations, page 93

• Testing the Configurations, page 96


90 | Chapter 4 Getting Started

Creating a Project for the Adapter

To begin the configuration process, you must first open a project for your adapter using TIBCO Designer. Although you will probably want to consult the TIBCO Designer User’s Guide for detailed information, here are the general steps you should follow to begin configuring the adapter.

1. Run TIBCO Designer either from the Start menu in Microsoft Windows or by issuing the <install_dir>/bin/Designer.sh command from the UNIX command line. The following screen is displayed.

2. Select the New empty project button to begin a new project that will specify all of the configuration details associated with a given instance for the adapter.

3. Save the project. For details on saving, refer to the latest TIBCO Designer documentation.


Working with the Sample Project | 91

Working with the Sample Project

The adapter installation provides you with a sample pre-configured project gettingStarted, which is available in the following path,

TIBCO_HOME\adapter\adr3\5.1\examples\gettingStarted\gettingStarted

.dat

This section explores this sample project and presents an overview of the TIBCO Adapter for R/3 configuration palette.

Step-by-step instructions are available on how to work with the adapter palette, save the changes to the sample project and start up the sample adapter configurations. The steps are listed next.

Open the gettingStarted project in TIBCO Designer. You cannot directly open a dat file in TIBCO Designer and make modifications to the configurations. To do this, complete the following steps:

1. Convert the dat file to a multi-file project.

a. Open TIBCO Designer. In the first screen that is displayed, click Administration. The screen is shown next.

b. Then click the Convert DAT to Files icon. In the window that is displayed, browse and select gettingStarted.dat. Click OK.



2. Click the Open existing project icon from the first TIBCO Designer screen. Browse to the directory where the converted multi-file project is saved and click OK.


Sample Configurations | 93

Sample Configurations

A TIBCO Adapter for R/3 Configuration is recognized by the configuration palette icon.

There are four sample configurations provided covering the most elementary configurations:

• RFC Outbound Configuration

• RFC Inbound Configuration

• IDoc Outbound Configuration

• IDoc Inbound Configuration

RFC Outbound ConfigurationThis is a Request-Response Invocation service configuration for the RFC RFC_CUSTOMER_GET that can send out a request for customer details from the SAP R/3 system to the TIBCO environment on the message subject RFC.CUSTOMER.GET.

1. Click on this configuration on the project panel. This displays the top-level configuration details for this configuration in the configuration panel.

2. If you want to test the connectivity and messaging for Outbound RFCs, navigate to the Outbound Connection tab and specify a valid program-id, gateway host and gateway service parameters for the adapter.

3. Open out the configuration in the project panel and navigate to the Adapter Services folder. This folder displays information about the RFC_CUSTOMER_GET service including the quality of service, the associated RFC schema and the messaging subject in the Configuration, Schema and Advanced tabs respectively. Go to the Advanced tab and set the message subject to RFC.CUSTOMER.GET.

4. Save the project. This configuration is now ready to be tested.

Before you make changes, take a backup of this project.



For details on testing this configuration, see Outbound Connectivity Test on page 96 and Outbound Messaging Test on page 100.

RFC Inbound ConfigurationThis is a Request-Response service configuration for the RFC RFC_CUSTOMER_GET that can receive a request for customer details from the TIBCO environment on the message subject RFC.CUSTOMER.GET. The service invokes the RFC in SAP R/3 and sends back the reply to the TIBCO environment.


2. If you want to test the connectivity and messaging for Inbound RFCs, navigate to the Inbound Connection tab and specify the client connection parameters to make a dedicated connection to a SAP R/3 application server.

3. Open out the configuration in the project panel and navigate to the Adapter Services folder. This folder displays information about the RFC_CUSTOMER_GET service including the quality of service, the associated RFC schema and the messaging subject in the Configuration, Schema and Advanced tabs respectively. Go to the Advanced tab and set the message subject to RFC.CUSTOMER.GET


For details on testing this configuration, see Inbound Connectivity Test on page 105 and Inbound Messaging Test on page 105.

IDoc Outbound ConfigurationThis is an IDoc Publication service configuration for the basic IDoc-type MATMAS01 that receives an IDoc from the SAP R/3 system and publishes it in the TIBCO environment on the message subject IDOC.MATMAS01.


2. If you want to test the connectivity and messaging for Outbound RFCs, navigate to the Outbound Connection tab and specify a valid program-id, gateway host and gateway service parameters for the adapter.

3. Open out the configuration in the project panel and navigate to the Adapter Services folder. This folder displays information about the MATMAS01 service including the quality of service, the associated IDoc schema and the messaging subject in the Configuration, Schema and Advanced tabs respectively.


Sample Configurations | 95

4. Go to the Advanced tab and set the message subject to IDOC.MATMAS01.


For testing this configuration, see Outbound Connectivity Test on page 96 and Outbound Messaging Test on page 100.

IDoc Inbound ConfigurationThis is an IDoc Subscription service configuration for the basic IDoc-type MATMAS01 that receives an IDoc from the TIBCO environment on the message subject IDOC.MATMAS01 and posts the IDoc into the SAP R/3 system.


2. If you want to test the connectivity and messaging for Inbound RFCs, navigate to the Inbound Connection tab and specify the client connection parameters to make a dedicated connection to an SAP R/3 application server.

3. Open out the configuration in the project panel and navigate to the Adapter Services folder. This folder displays information about the MATMAS01 service including the quality of service, the associated IDoc schema and the messaging subject in the Configuration, Schema and Advanced tabs respectively.

4. Go to the Advanced tab and set the message subject to IDOC.MATMAS01.


For testing this configuration, see Inbound Connectivity Test on page 105 and Inbound Messaging Test on page 105.

Convert the multi-file project to datTo test and deploy the project you have created, convert the project to dat format.

To do this, once you have saved the project in the TIBCO Designer screen, export the multi-file project to a dat. Select Project>Export Full Project from the menu. Browse and select the location of the directory you wish to save the dat file to. Ensure that the directory is different from the multi-file project. Name the project gettingstarted.dat and click OK.



Testing the Configurations

Steps to test the sample configurations are described in this section.

Starting the adapter1. Go to the <ADR3_HOME>\<ver>\bin directory and open the default launcher

file provided with the installation, adr3.tra. The Url to the repository project points to the gettingStarted project already.

2. All configuration Urls are commented. Uncomment the relevant configuration Url and launch the adapter by providing just the executable name adr3 in the command line from the bin directory.

For example, to run the sample Outbound RFC Configuration, the configurl to be uncommented in the launcher file is /tibco/private/adapter/RFCOutbound

3. To run the sample Inbound RFC Configuration after this, comment out the above configurl and uncomment the configurl /tibco/private/adapter/RFCInbound

Ensure that the adapter traces out on the console, a message that looks like the following,2003 Jan 22 11:23:34:298 GMT +5 SAPAdapter.R3AdapterConfiguration Info [Adapter] AER3-000082 Successful initialization of Adapter

Outbound Connectivity Test After the Outbound adapter is started, make sure that the SAP R/3 system can principally communicate with it through the RFC destination that you have defined. The testing procedure is described next.

1. On SAP R/3 system run transaction SM59. Alternatively, you can run transaction SALE and then choose:

Communication>Define RFC Destination


Testing the Configurations | 97

The following screen appears:

2. Double-click on the TCP/IP... line to expand its list of destinations. Scroll down to find your RFC destination in the list, such as CHANDRA shown below:



3. Double-click on your RFC destination. The following screen appears.



4. Change the program ID appropriately and select connection from the Test menu. Ensure that the program ID specified matches that specified in the adapter instance. The program ID is case sensitive. The bottom line of the screen should show: Connection: Chandra O.K.

5. The following connection performance screen is displayed and shows communication between SAP R/3 and the adapter.

If error messages are shown, it usually means that the configuration parameters are wrong. Look into the configuration file to verify that the parameters match the environment. Then repeat the test.

If the following SAP error message appears:

Connection Error: Program Publisher not registered / Transaction

program not registered

either the adapter is not running or the Program ID names do not match.



Outbound Messaging Test

RFC Invocation Test

Log on to the SAP R/3 GUI and execute function SE37 as shown below,

or, select Tools>AbAPWorkbench>Function Builder from the menu.

The Function Builder screen is displayed, as shown in the following example. In the Function module text entry box enter the name of the RFC function to be used in the test.

1. Click Sngl. test to initiate execution of the RFC_CUSTOMER_GET function.



The following Test Function Module screen is displayed. Specify the target system and message data to be sent.

2. Enter the RFC target system identifier (which refers to the RFC destination that has the program ID on which the adapter is registered), customer number (KUNNR), and customer name (NAME1) into the window. The following shows an example of using DEV2 as the target system, and * wildcards (get data for all customer numbers and names).

3. Click the Execute Function button, to initiate transfer of the RFC message data.



You can verify that the messages were transferred and acknowledged by the adapter by observing the Result: value on the Test Function screen. To view the result, double-click on the icon to the right of Result:.

Note that 18 RFC entries were transferred. The command window in which the adapter was executed prints the line Connection State: Available when the messages have been received.

IDoc Publication Test

This section outlines an example of how to test the publication of an IDoc message. You test the transmission of an IDoc configured to be sent on the TIBCO environment. Note that SAP R/3 system release 4.0B is used.

1. For example, if you have configured the logical message type MATMAS, run the transaction bale. From the Goto menu, select ALE Master Data.

2. Then select Material>Send from the General pull-down menu.



3. Enter a value in the Material field and specify the logical system. The value used in the example is 100-100.

The following two messages appear.

You can also do a publication test if you have configured SISCSO. Try to create a sales order using transaction va01. For other logical message types run a corresponding transaction that creates the IDoc.

You can verify that an IDoc is actually received by the adapter and published on the TIBCO environment by running the Rendezvous program tibrvlisten that monitors the subject under which the adapter publishes and displays messages as they are published. The following is an example of the first few lines from tibrvlisten:C:\WINNT\Profiles\bob\Desktop>tibrvlisten SAP.IDOC.*tibrvlisten: Listening to subject SAP.IDOC.*Received: subject=SAP.IDOC.SALoopbackIdoc-Instance1, reply=<none>, message=...

If the tibrvlisten program does not receive any IDocs, go to Monitoring menu in the transaction, bale. Check whether an IDoc was created during your test transaction using IDoc overview or using transaction we05.



4. Set the time range for the check.

5. Verify that the status is data passed to port OK.

6. Double-click on the Total Direction Outbound line of the IDoc Lists window. Verify that the IDocs requested to be sent were actually sent.

If not, there is still something wrong with your SAP R/3 ALE configuration. Correct the error that is indicated by the status. If no, IDoc is created despite status “data passed to port OK”, re-check the RFC destination.



Inbound Connectivity TestAfter the Inbound adapter is started, make sure that the adapter is successfully connected to the SAP R/3 system as client. Verify the connection from SAP GUI from the SAP R/3 transaction smgw.

On the SAP R/3 system run transaction smgw.


This screen lists details of clients logged on to the SAP R/3 system.

Check for the entry adr3 in the column TP Name. If the status shows as CONNECTED, then the adapter is successfully connected to the system.

Inbound Messaging Test

RFC Invocation Test

1. Run TIBCO IntegrationManager.

2. Open the R3Examples_Instance.dat project available in the following area:TIBCO_HOME/adapter/adr3/5.1/examples



3. Open the TIBCO IntegrationManager transform rfc_customer_get. The following screen is displayed.

4. The Customer Name (NAME1) and the Customer ID (KUNNR) are included in the Mapper as input values. Invoke the request from the process.

5. See the output in the console window of the TIBCO IntegrationManager engine.

6. The console window of the inbound instance also indicates that the request from TIBCO IntegrationManager for RFC_CUSTOMER_GET was made.

7. Check for the trace message in the adapter console.

IDoc Subscription Test

Try to receive an IDoc of one of the logical message types that you have configured to be sent from the adapter to the TIBCO environment. Publish MATMAS01 messages as described under IDoc Publication Test on page 102, and subscribe to them using the Subscriber adapter.



Go to IDoc overview or transaction we05 in the SAP R/3 GUI and check that the SAP R/3 system has received back the published IDoc.

To be certain that you received the same IDoc messages sent through the adapter onto the TIBCO environment, compare the IDoc message numbers sent with the one received. Double-click on the Total Direction Inbound text under Status description. The IDoc message number received must be the number sent plus one. So, if message number 349068 was sent, you should see message number 349069 on the inbound side.

If the IDoc was published but not received by the Inbound adapter, check the subject name specified for the subscriber/consumer in the Inbound adapter’s configuration file.

Stopping the AdapterYou can stop the adapter using any one of the following options:

• From a command window, stop the adapter by sending the following message on the terminate subject or terminate topic. Ensure that this is the message specified in the General tab. See General Tab on page 125 for details on the message subject. The convention of the subject is %%Domain%%.%%Deployment%%.adr3.%%InstanceId%%.exit with message content as "now". Example — To stop an adapter instance called IDocOutbound, available in the GettingStarted.dat, type the following command on the DOS prompt:

tibrvsend domain.GettingStarted.adr3.IDocOutbound.exit "now"

Once the adapter receives the ’now’ message on the stop subject, it will complete any pending transactions, cleanup resources, and then terminate.

• Start TIBCO Hawk. Invoke the stopApplicationInstance() method for the adapter configuration. Check for the trace message in the adapter console.


| 109

Chapter 5 Adapter Instance Options

This chapter describes the procedures to create an adapter instance and assign it services by configuring standard settings. All configuration tasks are performed in TIBCO Designer and the information is stored in a project that is later used by the run-time adapter. The adapter services are used to communicate with the SAP R/3 system.

Topics

• Overview, page 110

• Adapter Instance Fields, page 111

• Configuration Task Sequence for a Publication Service, page 140

• Configuration Task Sequence for a Subscription Service, page 141

• Configuration Task Sequence for Request-Response Invocation Service, page 142

• Configuration Task Sequence for Request-Response Service, page 143

• Adding Adapter Services, page 144

• Adding Adapter Services Automatically, page 145

• Publication Service Options, page 152

• Subscription Service Options, page 167

• This example shows the advanced configuration options for a subscription service created for the MATMAS01 IDoc., page 175

• Request-Response Service Options, page 184

• Configuring Schema for Adapter Services, page 191

• Saving the Project, page 196


110 | Chapter 5 Adapter Instance Options

Overview

Each adapter instance must have its corresponding configuration defined. The configuration is accessed whenever an adapter application is started.

Configuration is done with TIBCO Designer. Ensure that TIBCO Designer has been installed before continuing (see the TIBCO Designer User’s Guide). All the adapter configuration information is saved as a project in a repository.

Configuration TasksUse the following sequence to create and configure an adapter service.

1. Start TIBCO Designer and open a multi-file project. See the TIBCO Designer User’s Guide for details.

2. Drag the R3AdapterConfiguration icon from the palette panel to the design panel. This creates an adapter named, by default, R3AdapterConfiguration.

3. Define the adapter instance by assigning a new name and select the R/3 connection type in the Configuration tab.

4. Optionally change logging options. See Logging Tab on page 130 for details.

5. Define design-time connection options using the Design-time Connection tab. See Design-Time Connection Tab on page 115 for details.

6. Define inbound connection options if you are configuring an inbound instance. See Run-time Inbound Tab on page 118 for details.

7. Define outbound connection options if you are configuring an outbound instance. See Run-time Outbound Tab on page 121 for details.

8. Define both inbound and outbound connection settings if the connection type, both is selected in the Configuration tab.

9. Add a service to the adapter instance by dragging the service icon from the palette panel and dropping it in the design panel. See Adding Adapter Services on page 144 and Adding Adapter Services Automatically on page 145 for details.

10. Use the tabs of the service to set the combination of options required for the service.

11. Save the project as a server repository project and exit TIBCO Designer.

After configuring the adapter, you must create the run-time adapter property file and add the project name and adapter instance name. See Create a Properties File on page 298 for details.


Adapter Instance Fields | 111

Adapter Instance Fields

An R3 Adapter Configuration Resource represents an adapter instance. You can configure an Inbound Instance, Outbound Instance, or both.

Use the following steps to configure an adapter instance:

1. Drag and drop an R3 Adapter Configuration icon from the palette panel to the design panel.

2. If an adapter instance is being created for the first time in the project, a message box may be displayed with the following message:

Loading R/3 Product Classes...

3. Use the following tabs to configure the adapter instance:

• Configuration Tab on page 111

• Design-Time Connection Tab on page 115

• Run-time Inbound Tab on page 118

• Run-time Outbound Tab on page 121

• Adapter Services Tab on page 123

• General Tab on page 125

• Logging Tab on page 130

• Monitoring Tab on page 134

Configuration TabThe Configuration tab can be used to configure an adapter instance.

Instance Name

Use the default name or replace it with a name of your choice.

• An instance name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name.

• An instance name cannot use global variables.

• An instance name must be unique with respect to other adapter instances for the same adapter in the project. The same instance name can be used to name an adapter instance for a different adapter in the same project. For example,



an R/3 adapter instance named TEST and a Siebel adapter instance named TEST can coexist in the same project.

• Each instance name must be unique per adapter within a project even if each instance is defined in a different folder. That is, configuring same-named adapter instances in different folders will not make their names unique.

When you create an adapter instance, the palette automatically creates several resources for it. The names of these resources derive from the name of the instance they belong to. Changing the adapter instance name results in an automatic regeneration of the resources names. If you manually modify any resource name, that particular name will not be automatically regenerated next time you rename the adapter instance. The following resources in the adapter are automatically named when you name the adapter instance.

• Subject name

• CM name

• CMQ name

• Ledger file

• Default Client Connections

• Default Server Connections

• Active Connection

Description

Provide information about the adapter instance that you want stored in the project. The field is optional.

Version

The version string indicates the ActiveEnterprise (AE) format in which the adapter instance is saved. An adapter instance can be saved in AE 4.0 or AE 5.0 format.

When a new adapter instance is created in TIBCO Designer 5.x, the version string is set to AE Version 5.0. When a 4.x adapter instance is opened in Designer 5.x, the Version field is set to AE Version 4.0.

• If a 4.x adapter instance is to be run against a 4.x run-time adapter, the instance must be saved with the Version field set to AE Version 4.0.

If you are using TIBCO Designer 5.x to modify 4.x adapter instances, change only features supported by the 4.x. run-time adapter and use the validation utility to verify the instance before deploying the project. The validation utility scans the project and returns warnings if any 5.0 features are defined



for 4.x adapter instances. Invoke the utility from the Project>Validate Project for Deployment menu command in Designer.

• If a 4.x adapter instance is to be run against a 5.x run-time adapter, the Version field should be set to AE Version 5.0.

To change versions, click the Change Version button.

Message Filter

Specify a message filter, if you have configured a message filter resource for use with the adapter. The filter allows you to manipulate incoming and outgoing data before sending it on the network or handing it to the target application. Filters can be written using the TIBCO Adapter SDK. See the TIBCO Adapter SDK Programmer’s Guide for information about writing a message filter.

Show All Tabs

Check this box to display additional tabs for configuring advanced options. If any of the following configurations are required, this check box has to be selected:

• Configuring an adapter instance to a specific Active Connection Resource

• Configuring TID Management as remote

• Configuring a ReadIDocFromFilePlugin

• Setting Adapter Encoding (for running the adapter on Unix platforms) or the Locale (for running the adapter on Windows platform)

For instructions on setting advanced configuration parameters, see Configuring the Adapter with Advanced Options on page 197.



R/3 Connection Type

Select the type of instance. The possible values are Inbound, Outbound, or Both. Default is Both. If you select Inbound, proceed to enter the Inbound configuration parameters in the Run-time Inbound tab. If you select Outbound, enter the Outbound configuration parameters in the Run-time Outbound tab. If you select both, enter configuration details in both the Run-time Inbound and Run-time Outbound tabs.

The adapter instance type Both is a test adapter instance. It is recommended not to shift between Both to Inbound or Both to Outbound. There is no automatic mechanism to change the adapter services to reflect the change. You need to manually delete the Publication service if the change was made from Both to Inbound and vice versa.

An Inbound or an Outbound instance can be changed to a Both type of instance. It is recommended that no services be configured before you change the instance type from Both to either Inbound or Outbound.

Regardless of the R/3 Connection Type you have chosen in the Configuration Panel, a client connection reference and a server connection reference are created whenever you drag a configuration resource into the Design Panel.

For example when Outbound is selected as the R/3 Connection Type upon creation of adapter configuration, a client connection reference is also created in the R/3 Connections.

Conversely, when Inbound is selected, a server connection reference is created in addition to the client connection reference.



Sample Configuration Tab Screens

The following example shows the basic configuration tabs, along with the default values. The R/3 Connection Type can be Both, Inbound or Outbound.

Design-Time Connection TabUse the following steps to set up Design-Time connection options. Many of the following fields make use of global variables. Click the Global Variables tab in the project panel to enter a value for a global variable.

Application Server

The host name of the SAP R/3 system instance. Example: sapsvr

If the SAP R/3 system is behind a firewall, then the SAP router string should be mentioned along with the application server name.



System Number

The integer specifying the SAP R/3 Database instance.Example:00

Client

The integer specifying the SAP R/3 client.Example: 853

Username

Specify a valid name for logging onto the SAP R/3 system

Password

Specify a valid password corresponding to the user name.

Remember Password

If this field is not checked, the password must be entered each time the project is opened. If it is checked, the password will be stored in the project repository.

R/3 Logon Language

Select the language to be used when logging onto the SAP R/3 system.

Use Design-time Connection for Run-time

Select this check box to copy Design-Time parameters to the Run-Time tabs (Run-time Inbound and Run-time Outbound tabs).

Use Design-time Connection for Run-time

Select this check box if you need the design-time parameters to be copied to the run-time inbound connection.

If this check box is selected, the default run-time inbound connection would not be allowed to be modified. All fields in the Run-time Inbound tab will be disabled. To add custom values in the default Run-time Inbound connection, you need to clear the Use Design-time Connection for Run-time check box.



Test Connection

Click Apply and click Test Connection to verify the connection parameters specified.

If connectivity is available the following message box is displayed.

If connectivity is not available an error message with details of the error is displayed.

Test the connection before proceeding with other configuration.



Sample Design-time Connection Tab Screen

The following example shows the Design-time Connection tab.

Run-time Inbound TabYou can configure an Inbound Adapter Instance using the Run-time Inbound tab. On creating an adapter instance one inbound connection is created by TIBCO Designer, and the inbound connection is of the Dedicated Application Server type.

The inbound connection information is used as the default client connection for the instance. By default, the default client connection is used as the client connection reference when creating a Subscription service or a Request-Response service. The Run-time Inbound tab is displayed if you have selected the R/3 Connection type as Both or Inbound in the Configuration tab.

You can use the default client connection, which is a Dedicated Application Server connection or specify if it is a load balancing or a saprfc.ini client connection.



The options available vary depending on the type of client connection used. For details on changing default client connection to Load Balancing or saprfc.ini client connection, refer to the following sections:

— Client Connection with Load Balancing on page 212

— Client Connection with saprfc.ini file on page 214

Application Server

The network name of the SAP R/3 application server host machine.

System Number

SAP R/3 database instance number.

Client

SAP R/3 client number.

User Name

Valid user name to log into the specified SAP R/3 client.

Password

Valid password corresponding to the user name.

R/3 Logon Language

Language to be used when logging into the SAP R/3 system.

Test Connection

Click Apply and then Test Connection to verify that valid options have been specified.

Inbound Connection Reference

Click Go to reference resource.. against this field to configure advance settings for the default connection reference.

Test the connection before you proceed with further configuration.



An Inbound adapter instance can be configured with multiple client connections. For details see Adding a Client Connection on page 208.

Sample Run-time Inbound Tab Screen

In this example, an inbound connection is being configured in dedicated application server mode, which is the default mode.

An adapter instance with multiple inbound connections can have only one connection, set as the default. In case of multiple inbound connections, only the configuration of the default inbound instance is displayed. During creation of adapter services, the default inbound connection is used to configure connections requiring inbound connectivity to the SAP R/3 system.



Run-time Outbound TabYou can configure an Outbound adapter instance using the Run-time Outbound tab. This tab is displayed only if you select Outbound as the R/3 Connection Type in the Configuration tab.

The default type or the saprfc.ini file type can be used as the default server connection. See Default Server Connection on page 222 and saprfc.ini Server Connection on page 224 for details.

The options available on the Run-time Outbound tab vary depending on the type of server connection used. Options for the default type is detailed in this section.

Program ID

Specify a valid existing program ID that identifies the RFC Server program for the SAP R/3 system.

Gateway Service

Specify the SAP R/3 gateway service. The default value is sapgw00.

Gateway Host

Specify the gatewayHost name or IP address or router string. If there is no specified machine acting as a gateway host, this is the same as the appserver.

RFC Trace

Specify whether the trace is on or off. Possible values are 0 or 1 only.0 denotes trace is OFF1 denotes trace is ONIf any other values are entered, an error is displayed. If you do not provide a valid value, then it defaults to the original value. The default value is 0.

Click Apply.

Before specifying a server connection reference ensure that the required server connection has been created. See Adding a Server Connection on page 221 for details. During creation of adapter services, the default outbound connection is used to configure connections requiring outbound connectivity to SAP R/3.



Outbound Connection Reference

Click the Go to referenced resource.. button against this field to configure advance settings for the default connection reference.

An outbound adapter instance can be configured with multiple server connections. For details see Adding a Server Connection on page 221.

Sample Run-time Outbound Tab Screen

In this example, an outbound connection is being configured in the default mode.

An adapter instance with multiple outbound connections can have only one connection, set as the default. In case of multiple outbound connections, only the configuration of the default outbound instance is displayed.



Adapter Services TabYou can change the Active Connection resource assigned to an adapter instance and also configure TID Management for the instance using the Adapter Services tab.

Valid Destinations

Enter valid destinations in this field. Example: tibrvd. See Configuring Valid Destinations on page 200 for details.

TID Management

All PublicationServices

By default, TID Management is set to local. If you select remote TID Management, the adapter requires a TIDManager instance. Specify the TIDManager Client.

All SubscriptionServices

By default, Inbound TIDManagement is turned off. To enable Inbound TIDManagement, choose local or remote from the dropdown.

If you select local TIDManagement, you will need to specify the local TID filename.

If you select remote TIDManagement, the adapter requires a TIDManager server to be configured. Specify the TIDManager RpcClient endpoint here which will communicate with the server.

TIDManager Client

The TID Management Client field is displayed only if the TID Management field is set to remote. Ensure that the TIDManager client in all the adapter instances matches the TIDManager server in the TIDManager being used. Also ensure that the subject name of the TIDManager client is configured appropriately and that the client and the TIDManager server are on the same transport. The TIDManager Client field displays only if the TID Management field is set to Remote.

When an Active Connection reference is modified, all connection configuration for the adapter instance changes. See Assigning an Active Connection to an Adapter on page 207.

Select local TID Management if there is only one adapter instance using the Program IDs defined in any server connections defined in the instance. If there are multiple instances sharing the same Program ID they must share the same TIDManager. Else, it is not possible to ensure that data is being sent only once from the SAP R/3 system.



TIDManager Client Retry Count

Specify the number of retries from the Adapter to the TIDManager server after which the Adapter should conclude that the TIDServer is down.

See Inbound TIDManagement on page 251 for details of usage of this parameter

TIDManager Client Retry Interval

Specify the time interval in milliseconds between any two ping attempts to the TIDManager server. This will be used when the TIDManager server is unreachable.

TID filename

The TID file is used by the TIDManager to maintain state information on the transaction IDs (TID) sent from SAP. By default, the name of the TID file is tidFile.tid.The TID filename field displays only if the TID Management field is set to Local.

See Setting TIDManager General Options on page 257 for details on setting TIDManager Options.

Click Apply.

Sample Adapter Services Tab Screen



In this example, a valid destination is displayed along with remote TIDManager settings.

General TabYou can set Termination Subject or Topic, Adapter Encoding Information, Active Connection Reference and Plugin details using the General tab.

Termination Subject or Topic

A message sent on the termination subject (if Rendezvous is the transport) or topic (if JMS is the transport) stops the adapter. The default value of the termination subject is given next.%%Domain%%.%%Deployment%%.adr3.%%InstanceId%%.exit

The message should contain "now" in the body.

Example: tibrvsend domain.<project name>.adr3.<instance name>.exit "now"

See TIBCO Rendezvous Concepts for information about specifying subject names. See the TIBCO Enterprise for JMS User’s Guide for information about publishing on a topic.



Adapter Encoding (for Unix)

Click the arrow to select the encoding to use. The following options are available.

• ASCII

• ISO8859-1, ISO8859-2, ISO8859-5, ISO8859-7, ISO8859-8, ISO8859-9

• UTF-8

• Shift_JIS (CP943)

• Shift_JIS (TIBCO)

• Shift_JIS (932)

• KSC-5601

• Big5

The adapter may support other encodings not in the pick list. See TIBCO Adapter Concepts for a list of additional encodings that can be input in this field. Note that the palette does not validate encoding values that are typed into the field. This value is only applicable if you want to run the adapter on any Unix platforms. The run-time adapter will throw an error if the encoding value you type is not supported.

Adapter Locale (for Windows)

Specify value in this field in case you want to run the adapter on Windows platform. If you do not enter any value, the system default locale of the machine on which you run the adapter will be picked up. Example: japanese_japan.932 for running the adapter on a Japanese machine.

ActiveConnections Reference

Specify the name of the active connection to be assigned to the adapter. Changing the reference of the active connection used by an adapter instance will change all client and server connections used by the adapter. The facility to change the active reference allows you to use an existing active connection without having to reconfigure another adapter instance.

a. Click the Browse Resources.. button to locate the Active Connection instance.

b. Click the Go to referenced resources.. button to select a new client or server connection reference for the Active Connection. The Active Connection folder is displayed. Select the required connection reference resource from the project. The resource configuration tab displays. Browse to locate the required server or client connection, click Apply and return to



the adapter configuration tabs. See Setting up Connection Reference Options on page 205 for details on setting connection references.

ReadIDocFromFile

The adapter supports plugins, which are essentially customized dynamic libraries that are loaded by the adapter on startup. For detailed information on plugins, refer to the TIBCO Adapter SDK documentation.

The TIBCO Adapter for R/3 packages the ReadIDocFromFile plugin. This plugin may be used to re-publish IDoc messages written to a file.

An IDoc message gets written to a file under the following circumstances:

• A Publication service or a Subscription service configuration with a list of Valid Destinations will write an IDoc message from R/3 to a file if the IDoc message's destination is not one of those configured.

• A Subscription service configuration will write an IDoc message to a file, if the R/3 system gives a valid process exception. The exception could be due to invalid data etc., while posting the IDoc. In this case, the data may be manually changed in the file and replayed later using the plugin.

IDocs received by a subscription service, which do not conform to the IDoc schema are written to files. The files are written in the format in which they are transported in the TIBCO environment. Such invalid messages cannot be replayed by the plugin and are written to a file only to avoid loss of valuable data.



You can use the ReadIDocFromFile plugin to republish IDocs that are in a file format on the file system. The plugin is available only when the adapter configuration type is chosen as Outbound since the plugin is always attached to a Publisher endpoint.

Enabled

Select this check box to enable the plugin.

Endpoint Reference

Select the publisher endpoint to be referenced. Click the Browse resources button against this field to locate the required publisher endpoint in the Sessions folder.

If you need access to modify the configuration details of the publisher session, click the Go to referenced resources.. button.

Mode

Select the mode from the drop-down list. See Identifying the Publication Mode on page 155 for details on the various modes.

The ReadIDocFromFile plugin can be used in the following cases:

— Simulating the sending of IDocs from the SAP R/3 system.

The plugin when attached to a Publisher and invoked reads IDocs written to files and republishes them in the TIBCO environment.

— IDocs that have failed due to the correctness of the IDoc, network outages and other problems.

IDocs meant to be posted into the SAP R/3 system from the TIBCO environment are written to files by IDoc Subscriber instances under the conditions listed above. The plugin can be invoked to read these files and republish them after the cause of the problem is identified and rectified. The IDoc Subscriber receives these IDocs again and posts them into SAP R/3. The IDoc message will be written to a file in the batched mode and the plugin can read and replay IDoc files written in this mode only. For details of the mode, see Mode “10Xbatched” on page 160.

To run the adapter with the ReadIDocFromFile plugin, add -system:plugin ReadIDocFromFile.<extension> to the application.args parameter in the TRA file.

For example,

application.args -system:propFile %TIB_ADR3_HOME%/bin/adr3.tra

-system:plugin ReadIDocFromFile.dll



Directory

Specify the directory path where the IDoc files are located.

Filename

Specify the filename of the IDocs. Wild cards can be specified. Characters supported are * and ?. Wild cards can be used anywhere in the filename.

Click Apply. The ReadIDocFrom File plugin is initialized when the adapter instance is initialized, IDoc files matching the selection criteria are read and published.

Sample General Tab Screen

In this example, the ReadIdocFromFile plugin has been enabled to publish all .idoc files from the adapter’s bin directory in the explode mode.

The ReadIDocFromFile plugin does not delete or move processed IDocs to a different location. Processed files must be managed manually, before starting the adapter instance again.



Logging Tab

Use Advanced Logging

When Use Advanced Logging is not selected (the default), you can set two standard output destinations (sinks) for trace messages and set the tracing level for the roles selected.

When Use Advanced Logging is selected, you have complete control on selecting the destinations and associating desired roles with each of the destinations.

To create and configure the sinks, select the log sinks folder under the Advanced folder in the project panel.

To create sinks, drag and drop the Generic log sink icon from the palette panel into the design panel. From the configuration panel, select the sink type. The following are the sink types available:

— File

— Hawk

— Network

— STDIO

When File and STDIO sinks are created from the Generic log sink they offer further configuration options. For the File sink, the file limit, file count, and the option to append or overwrite can be specified. When created by default, this is set to 30000 bytes, 3 and append mode respectively. For the STDIO sink, the option to write to stdout or stderr can be selected. When created by default, stdout is selected.

The Hawk sink uses the hawk session, created and used by the adapter for monitoring purposes, to send tracing messages to the TIBCO Hawk monitor or Display. For details on Hawk sessions, see Using Global Variables on page 272. The configuration for the Hawk sink involves specifying the MicroAgent Name that must be specified in the configuration panel.

The Network sink is used to publish tracing message on TIBCO Rendezvous. The configuration for the network sink involves specifying the session, and the subject on which the trace messages needs to be published.

For all the sinks, optionally the name and description for the sinks can be provided.



Log to Standard I/O

(STDIO Sink) When selected, trace messages are displayed in the command prompt window where the adapter is started. When not selected, trace messages do not display in the window.

Log File

Specify the name of the log file (log sink) to which trace messages are written. Global variables can be used to specify the location of the log file. See Using Global Variables on page 272 for more information.

The roles available are Info, Debug, Warning, and Error messages. The trace message generated depends on the roles selected. Turning on the roles can affect the performance of the adapter. Therefore, it is recommended that you turn on the required roles only.

Given next is a sample outbound log file..2001 Jun 5 16:04:57:227 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000158 Adapters initialization mode: Repository Encoding: ISO8859-1

2001 Jun 5 16:04:57:309 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000265 Creating a Server connection

2001 Jun 5 16:04:57:329 SAPAdapter.SAOutboundIdoc-Instance008 Info [Configuration] AER3-000007 TID management is local

2001 Jun 5 16:04:57:347 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000103 Adding Table parameter IDOC_DATA_REC_40, Type IDOC_DATA_REC_40

2001 Jun 5 16:04:57:351 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000103 Adding Table parameter IDOC_CONTROL_REC_40, Type IDOC_CONTROL_REC_40

2001 Jun 5 16:04:57:368 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000103 Adding Table parameter IDOC_DATA, Type IDOC_DATA

2001 Jun 5 16:04:57:372 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000103 Adding Table parameter IDOC_CONTROL, Type IDOC_CONTROL

2001 Jun 5 16:04:57:379 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000082 Successful initialization of Adapter

2001 Jun 5 16:05:02:845 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000195 Transaction created A065E08300893B1D65E400B4

2001 Jun 5 16:05:02:849 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000167 Connection State: Pending invocation

2001 Jun 5 16:05:02:850 SAPAdapter.SAOutboundIdoc-Instance008 Info [Application] AER3-000098 IDOC RFC Function invoked: IDOC_INBOUND_ASYNCHRONOUS



2001 Jun 5 16:05:02:887 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000116 Function call is transactional, TID: A065E08300893B1D65E400B4

2001 Jun 5 16:05:02:888 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000106 Table = { IDOC_DATA_REC_40 }

2001 Jun 5 16:05:02:902 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000107 Number of records in table IDOC_DATA_REC_40 = 8

2001 Jun 5 16:05:02:902 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000106 Table = { IDOC_CONTROL_REC_40 }

2001 Jun 5 16:05:02:908 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000107 Number of records in table IDOC_CONTROL_REC_40 = 1

2001 Jun 5 16:05:02:910 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000091 Total IDOC Count in this run: 1

2001 Jun 5 16:05:02:911 SAPAdapter.SAOutboundIdoc-Instance008 Info [Application] AER3-000084 Received IDOC Name/Number/Receiving Partner: MATMAS01/0000000000730901/PUBTEST, Count: 1

2001 Jun 5 16:05:03:014 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000085 IDOC sent in explode mode tracking=#BSMjWyPDClpZbUp67WHcc4IarkxKo#

2001 Jun 5 16:05:03:109 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000166 Connection State: Available

2001 Jun 5 16:05:03:127 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000197 Transaction committed A065E08300893B1D65E400B4

2001 Jun 5 16:05:03:366 SAPAdapter.SAOutboundIdoc-Instance008 Info [Adapter] AER3-000198 Transaction confirmed 2001 Jun 5 16:05:27:336 SAPAdapter.SAOutboundIdoc-Instance008

Info [Adapter] AER3-000163 Checking for connections

The default log file name for the adapter is adapter.log, and is written to the same directory where your project is stored. The default log file name for the TIDManager is TIDManager.log.If no file name is specified, trace information is not written to a file.

Log Info/Debug/Warning/Error Messages

Trace messages of the selected level(s) will be collected in the named log sink. You can configure what levels of trace messages you want logged, and where trace messages are sent. There are three types of logs (log sinks) that you can configure to hold trace messages, corresponding to three levels (roles) of trace messages, Information, Warning and Error. A fourth level of trace messages, Debug, is reserved and should not be enabled unless requested by the TIBCO Product Support Group. This option writes a lot of information to the log file and significantly reduces the speed of the adapter.



Sample Logging Tab Screen

In this example, the default settings of the logging options display. Standard logging is being used, as the Use Advanced Logging box is cleared. The level of logging has been set to include Info, Warning and Error messages.

Startup Tab

Default Startup State

This field is predefined and cannot be changed. It sets the default startup state for endpoints. Active means endpoints are auto-created and active at adapter startup.

Show Startup Banner

This check box is enabled by default. The startup banner displays the run-time adapter version, the infrastructure version on which the adapter is built, and copyright information in the console window when the adapter is started. Clear this checkbox if you do not want the startup banner to be displayed.



Default Session

This field is predefined and cannot be changed.

Metadata Search URL

This field is predefined and cannot be changed. The field specifies the location where the adapter searches for base schemas. The adapter searches for any schema that has been defined and saved at this location, and that should be loaded at startup.

Sample Startup Tab Screen

Monitoring TabMany of the following fields make use of global variables. Click the Global Variables tab in the project panel to enter a value for a global variable.



Enable Standard Microagent

Allows you to turn on or off the standard TIBCO Hawk Microagent. The way to turn it on or off is also configurable. By clicking the globe icon, a standard check box or text value (true or false) can be used to turn the standard microagent on or off.

Standard Microagent Name

This is the name for the standard microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used. The InstanceId variable need not be set because it is automatically set at run time by the run-time adapter.

Enable Class Microagent

Allows you to turn on or off the instance or class specific standard TIBCO Hawk Microagent. The way to turn it on or off is also configurable. By clicking the globe icon, a standard check box or text value (true or false) can be used to turn the class microagent on or off.

By default, the input field is populated with the global variable HawkEnabled.

Class Microagent Name

This is the name for the class microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used.

Default Microagent Session

This field is disabled and cannot be changed.

R/3 Adapter MicroAgent Name

The name of the adapter microagent used to configure microagents specific to the adapter. The name specified appears in the TIBCO Hawk monitoring console and the methods associated with the microagent are made available. By default, the name is SAPAdapterMicroAgent.

The global variable should only be used in cases where all instances of the project share the same behavior.

In cases where all instances do not share the same behavior, the check box option must be used.



R/3 Adapter MicroAgent Type

Select the type from the drop-down box. By default, it is set to local.

The session name and the corresponding session is automatically generated by TIBCO Designer. Do not change the session name or the session. However, you can modify the session parameters if required. Navigate to the Sessions folder under the Advanced folder to modify the session parameters.

Make sure you have set the correct parameter value for the global variables that correspond to the TIBCO Hawk configuration. If the session parameters are not set properly, the microagents will not display in the TIBCO Hawk Display.

You can use microagents to supplement the monitoring information provided by the standard logging levels capability. Examples of supplemental information that you can obtain with microagents include the repository URL, command line arguments used to start the adapter, and so on.

See Chapter 11, Monitoring the Adapter Using TIBCO Hawk, on page 359 for a list of all supported microagents.



Sample Monitoring Tab Screen

Defining a TIBCO Hawk Session

A default TIBCO Rendezvous session, HawkSession is defined in the project whenever a new instance of the adapter is configured. You can use this session to monitor the adapter using TIBCO Hawk. Use the following steps to modify the parameters of this default session.

1. In the project tree panel, click the R/3 Adapter Configuration icon defined for your adapter instance.

2. Select the Advanced>Sessions>R3HawkDefault.



3. The default values in the Service, Network and Daemon fields are 7474, None and tcp:7474. Change the default values if required and click Apply. The screen shot of the default HawkSession is given next.


Setting Inbound/Outbound Instance Options | 139

Setting Inbound/Outbound Instance Options

Use both the Run-time Inbound and the Run-time Outbound tabs to configure an instance that is both outbound and inbound. Specify the type of instance in the Configuration tab by selecting Both in the R/3 Connection Type field.

Enter both Outbound and Inbound Connection Parameters. See Run-time Inbound Tab on page 118 and Run-time Outbound Tab on page 121 for instructions on setting Inbound and Outbound configuration options.



Configuration Task Sequence for a Publication Service

Use the following task sequence to create and configure an adapter publication service:

1. Start TIBCO Designer and open a project. See the TIBCO Designer User’s Guide for details.

2. Drag the R/3 Adapter Configuration icon from the palette panel to the design panel. This creates an adapter named, by default, <name of the default configuration>. Define the adapter configuration by assigning a new name and optionally change logging options. See Adapter Instance Fields on page 111 for details on defining adapter configuration settings.

3. Add a publication service to the adapter configuration by dragging the service icon from the palette panel and dropping it in the design panel. The fields in the Configuration and Advanced tabs are disabled until the schema is associated with the service as described in step 4.

4. Schema association can be carried out in the Schema tab for IDoc.

a. Click Fetch IDocs to retrieve the list of IDocs based on the IDoc filter provided.

b. Click Select IDoc, a list of IDocs is displayed in a separate window.

c. Choose an IDoc from the list displayed and click OK. The schema of the selected IDoc is downloaded and displayed in the tab. The IDoc is displayed in a hierarchical manner similar to the display in the SAP R/3 system. Click on the nodes to expose the relationship to those nodes and display the fields for those segments.

d. Services are created appropriately for the IDoc and associated with the IDoc’s schema.

5. Under the Configuration tab, set the combination of options required for your service. See Configuration Tab on page 152 for details.

6. Save the project and exit TIBCO Designer.

7. Create the run-time adapter property file and add the project name and adapter configuration name. See Adapter Properties File on page 306 for details.

The names of the fields in segments are displayed, the length is not displayed. The field lengths are available in the project’s schemas folder.


Configuration Task Sequence for a Subscription Service | 141

Configuration Task Sequence for a Subscription Service

Use the following task sequence to create and configure an adapter subscription service:



3. Add a subscription service to the adapter configuration by dragging the service icon from the palette panel and dropping it in the design panel. The fields in the Configuration and Advanced tabs are disabled until the schema is associated with the service as described in step 4.

4. Schema association can be carried out in the Schema tab for IDoc.



c. Choose an IDoc from the list displayed and click OK. The schema of the selected IDoc is downloaded and displayed in the tab. The IDoc is displayed in a hierarchical manner similar to the display in the SAP R/3 system. Click on the nodes to expose the relationship to those nodes and display the fields for those segments.




7. Create the run-time adapter property file and add the project name and adapter configuration name. See Adapter Properties File on page 306 for details.




Configuration Task Sequence for Request-Response Invocation

Service

Use the following task sequence to create and configure an adapter Request-Response Invocation service:



3. Add a Request-Response Invocation service to the adapter configuration by dragging the service icon from the palette panel and dropping it in the design panel. The fields in the Configuration and Advanced tabs are disabled until the schema is associated with the service as described in step 4.

4. Schema association can be carried out in the Schema tab for RFC/BAPI.

a. Click Fetch RFC/BAPI to retrieve the list of RFC/BAPIs based on the RFC/BAPI filter provided.

b. Click Select RFC/BAPI, a list of RFCs/BAPIs is displayed in a separate window.

c. Choose an RFC or BAPI from the list displayed and click OK. The schema of the selected RFC or BAPI is downloaded and displayed in the tab. The RFC or BAPI details displayed is similar to the display in the SAP R/3 system.

d. Services are created appropriately for the RFC/BAPI and are associated with the RFC/BAPI schema.



Create the run-time adapter property file and add the project name and adapter configuration name. See Adapter Properties File on page 306 for details.


Configuration Task Sequence for Request-Response Service | 143

Configuration Task Sequence for Request-Response Service

Use the following task sequence to create and configure an adapter Request-Response service:


2. Drag the R/3 Adapter Configuration icon from the palette panel to the design panel. This creates an adapter named, by default, <name of the default configuration>. Define the adapter configuration by assigning a new name and optionally change logging options. See Overview on page 110 for details on defining adapter configuration settings.

3. Add a request-response service to the adapter configuration by dragging the service icon from the palette panel and dropping it in the design panel. See Configuration Tab on page 184 for details. The fields in the Configuration and Advanced tabs are disabled until the schema is associated with the service as described in step 4.

4. Schema association can be carried out in the Schema tab for RFC/BAPI.


b. Click Select RFC/BAPI, a list of RFCs/BAPIs is displayed in a separate window.

c. Choose an RFC or BAPI from the list displayed and click OK. The schema of the selected RFC or BAPI is downloaded and displayed in the tab. The RFC or BAPI details displayed is similar to the display in the SAP R/3 system.


5. Under the Configuration tab, set the combination of options required for your service.


Create the run-time adapter property file and add the project name and adapter configuration name. See Adapter Properties File on page 306 for details.



Adding Adapter Services

After basic configuration of an adapter instance is complete you can add one or more adapter services to an instance. The Adapter Services folder is automatically created when an adapter instance is created.

Adapter services can be added to the adapter in two ways:

• Automatically - Using the R/3 Filters tab available at the Adapter Services folder level. See Adding Adapter Services Automatically on page 145 for details on adding services automatically.

• Manually - Dragging adapter service resources from the palette panel to the design panel.

Use the following steps to add adapter services manually:

1. Drag the R3 Adapter Configuration icon from the palette panel to the design panel.

2. In the project panel, select the Adapter Services folder.

3. Drag the required Service icon from the palette panel to the design panel.

4. Specify the options in the tabs.

For details refer to the corresponding section for the service to be added.

• Publication Service Options

• Subscription Service Options

• This example shows the advanced configuration options for a subscription service created for the MATMAS01 IDoc.

• Request-Response Service Options

Subject names are normally defined by the system. If you manually change a subject name, you must not use SAP.IDoc as a subject since this name is used by the system.


Adding Adapter Services Automatically | 145

Adding Adapter Services Automatically

This section describes how to add services automatically. Use the R/3 Filters tab from Adapter Services folder and select the required IDocs, RFCs and BAPIs. Adapter services are automatically created.

For example, go to the IDocs tab and from the list of IDocs displayed, select the Used? check box against the IDoc MATMAS01. Two adapter services are automatically created, one for Publication and another for Subscription.

Use the following steps to add adapter services automatically:

1. Drag the R3 Adapter Configuration icon from the palette panel to the design panel.

2. In the project panel, select the Adapter Services folder.

R/3 Filters tab Specify the following options in the R/3 Filters tab.

IDoc Filter — The IDoc filter used to restrict the number of IDocs returned from the SAP R/3 system. By default, * is specified. Values like CRE*01* cannot be used, the * can appear only at the beginning or the end of the expression. Example: MAT*

RFC Filter — The RFC Filter used to restrict the number of RFCs or BAPIs returned from the SAP R/3 system. The RFC Filter can be used to restrict the number based on the actual name of the RFC or BAPI. By default, RFC* is specified. There is no restriction on the usage of *. Values like BAPI*ORDER are allowed.

RFC Group Filter — The RFC Group Filter used to restrict the number of RFCs or BAPIs returned from the SAP R/3 system. By default, * is specified. The RFC Group Filter can be used to restrict the number based on the RFCs or BAPIs associated to a particular set of function groups in SAP R/3. If the function group is not known, leave the value of the RFC Group Filter as * and specify a value in the RFC Filter field.

To download the list of BAPIs/RFCs with namespaces, you can enter the entire name of the RFC or give a partial filter in the RFC Filter. Ensure that the RFC Group Filter is blank.

Example :

• To download a list of all BAPIs/RFCs with namespaces give RFC Filter as "/*" and leave the RFC Group Filter blank.



• To download an RFC with name space SAPTRX just give RFC Filter as /SAPTRX/* and leave the RFC Group Filter blank.

The character '/' is a reserved character in the TIBCO environment. To support namespaces, the adapter performs a literal translation and replaces '/' with '__SLASH__'

The "/" in a BAPI or a RFC name in a namespace will be replaced with "__SLASH__" at design-time and saved to project with this name.

At run-time, the adapter replaces the "__SLASH__" with the "/" character in all its interactions with the SAP R/3 system.

Example: The RFC /tibco/MY_CUSTOM_RFC will be visible in the TIBCO environment as __SLASH__tibco__SLASH__MY_CUSTOM_RFC.

This applies to parameters referred to by the BAPI/RFC as well.

3. Click Fetch IDocs to retrieve the list of IDocs based on the IDoc filter provided. As the list of IDocs is retrieved, an additional tab named IDocs is displayed. The IDocs tab contains the list of IDocs available for selection.

The columns presented in the IDocs tab are dependent on the SAP R/3 release currently being used.

4. Click Fetch RFC/BAPIs to retrieve the list of RFCs or BAPIs based on the RFC Filter and RFC Group Filter.

The default RFC Filter expression "*' does not download BAPI/RFCs with namespaces.



Example In this example IDocs and BAPIs would be retrieved as follows:

• 3.1I and 4.0 or later SAP R/3 releases - Basic IDoc types starting with CREMAS will be retrieved. Extended IDoc types linked with basic IDoc types starting with CREMAS will also be retrieved.

• 3.1H or earlier SAP R/3 release - Basic or extended IDoc types starting with CREMAS will be retrieved.

• BAPIs starting with BAPI_SALES in all available function groups will be retrieved.

IDocs TabUse the following steps to add services for selected IDocs.

1. Drag the R3 Adapter Configuration icon to the design panel.

2. In the project panel, select the Adapter Services folder and specify the required filter criteria, then click Fetch IDocs. While the IDocs are being fetched the IDocs tab is displayed.

3. Click the IDocs tab and proceed to select the required IDocs.

iDoc Tab Select the required IDocs in the IDocs tab.

The list of IDocs displayed depends on the SAP R/3 Logon Language provided in the Design-Time Connection tab in the adapter configuration. Only those IDocs maintained in the SAP R/3 Logon Language are shown. If IDocs are not listed, make sure that IDocs exist in the SAP R/3 system.

If a SAP R/3 Logon Language other than English, French, Italian, Danish, Dutch, Norwegian, Portuguese, Spanish, Finnish, and Swedish is in use, the description of the IDoc may be incorrect in some cases.



The fields displayed depend on the version of SAP R/3 release that is currently in use. Two possible scenarios are detailed in this section.

SAP R/3 Releases 4.x

Basic Type - The name of Basic IDoc type in SAP R/3

Extended Type - The name of Extended IDoc type in SAP R/3

Description - The description of IDoc in SAP R/3

Used - Check this box to select the IDoc schema to be downloaded and for appropriate adapter services to be created.

Operation Type - The operation type. Possible values are Outbound, Inbound, or Both. Values shown depend on the SAP R/3 Connection Type inside the adapter configuration.

Release 4.x? - Check this box to download IDoc schema using 4.x schema. By default, it is enabled.

Release 3.x? - Check this box to download IDoc schema using 3.x schema.

When you click Apply, the IDocs are retrieved from the SAP R/3 system and adapter services are created.

SAP R/3 Releases 3.x

IDoc Type - The name of basic or extended IDoc type in SAP R/3.

Description - The description of IDoc in SAP R/3.

Used - Check this box to select the IDoc schema to be downloaded and for appropriate adapter services to be created.

Operation Type - The operation type. Possible values are Outbound, Inbound, or Both. Values shown depend on the SAP R/3 Connection Type inside the adapter configuration.

4. Click Apply. The IDocs are retrieved from the SAP R/3 system and adapter services are created.

The sequence in which fields are displayed in the IDocs tab can be modified using drag and drop.

Connection Type Service(s) Automatically Added

Inbound Subscription Service

Outbound Publication Service



Example In this example, the list of IDocs retrieved from a 4.x SAP R/3 system is shown.

RFCs/BAPIs TabUse the following steps to add services for selected RFCs/BAPIs.

1. Drag the R3 Adapter Configuration icon to the design panel.

2. In the project panel, select the Adapter Services folder. Specify the required filter criteria and click Fetch RFC/BAPIs. While the RFC/BAPIs are being fetched the RFC/BAPIs tab is displayed.

3. Click RFC/BAPIs and then select the required RFC/BAPIs to automatically add the required services.

RFC/BAPI Tab Select the required RFCs or BAPIs in the RFC/BAPI tab.

Name — The name of the RFC or BAPI. The node alongside this field can be used to obtain information on the parameters available in the RFC or BAPI. If the parameter pertains to a structure (denoted by "struct") or table (denoted by "sequence"), field information for these types can be obtained by expanding the node alongside the name of the parameter.

Type — The type of BAPI.

Both Publication and Subscription Service

Connection Type Service(s) Automatically Added

The sequence in which fields are displayed in the RFC/BAPI tab can be modified using drag and drop.



Direction — Direction of the BAPI parameter. The possible values are In, Out or In/Out. If the parameter is an Import parameter, the direction is In. If the parameter is an Export parameter, the direction is Out. If the parameter is a Table, the direction is In/Out.

Used? — Check this box to select the RFC/BAPI schema to be downloaded and for appropriate adapter services to be created.

Operation Type — The operation type. Possible values are Request-Response Invocation or Request-Response.

Invocation Protocol — Select the appropriate Invocation Protocol in order to create an adapter service for a particular RFC or BAPI. Possible Invocation types are Request/Reply and One Way.

4. Click Apply.

Example The list of RFCs or BAPIs is grouped based on their respective function module. Using the above as an example, BAPI_SALESORDER_CREATEFROMDAT1 is inside function group 2032

Expanding the node alongside the name allows for browsing the interface of the RFC or BAPI as shown in the following example.

One way invocation protocol allows you to invoke the BAPI/RFC in the SAP R/3 system without waiting for a reply from the system.

To configure a One Way RFC/BAPI select One Way from the Invocation Protocol.



Publication Service Options

A publication service is used to publish an IDoc from an SAP R/3 system as a TIBCO Rendezvous message or TIBCO Enterprise for JMS message.

A separate Publication service is required for every IDoc that needs to be published. If the same IDoc must be published in different modes, a separate publication service is required for each mode. In cases where the mode is not explode, the service still needs to be associated with an IDoc although the IDoc schema will not be used. For details on publish modes, see Identifying the Publication Mode on page 155.

You can configure publication service parameters under the following tabs:

• Configuration Tab

• Schema Tab

• Advanced Tab

Configuration TabThis is standard configuration. You can specify publication service configuration options using the Configuration tab.

Name — Name of the publication service.

Transport Type — Select the type of message transport used by the service.

— JMS indicates that JMS (Java Messaging Service) mode of transport will be used by the service. An adapter service that uses the JMS mode of transport can communicate only with the TIBCO Enterprise for JMS server.

— Rendezvous indicates that TIBCO Rendezvous will be used to transport messages.

Communication with the SAP server requires the existence of “logical systems,” the identification of IDoc “message types,” and other custom modifications using the SAP graphical user interface. While these are not R/3 Adapter configuration issues, they must be complete before IDocs can be transmitted. See Appendix D on page 489 for an example of customizing the SAP server to communicate with the adapter.

By default, a new publication service is named PublicationService. Once the IDoc is selected using the Schema tab, the service name is changed to reflect the IDoc name.


Publication Service Options | 153

The transport can be configured to use a trusted store and identity resource for use in SSL (Secure Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field which uses a dialog to perform SSL configuration.

To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help.

Publish Mode — Select the appropriate publication mode. See Identifying the Publication Mode on page 155 for details.

5. If you selected Rendezvous in the Transport Type field, the following options need to be specified:

Wire Format — The format in which messages are to be published. Different options are displayed according to the Transport Type selected.

One of the following wire formats can be selected for sending the message. Publishers and subscribers can only send and receive data if they agree on a specific wire format. Possible values are:

— ActiveEnterprise Message, an externally-described XML message format supported by the TIBCO Adapter SDK. Control information for validation is sent in the message. This format allows ActiveEnterprise components to perform extra validation on messages sent or received.

— XML, allows you to retrieve data as XML documents and metadata as XML Schemas (XSD).

— Rendezvous Message, a self-describing message format used by TIBCO Rendezvous applications. Control information for validation is not sent in the message. For Rendezvous wire format, a message of type RVMSG_RVMSG (Rendezvous 5.x) or TIBRVMSG_MSG (Rendezvous 6.x) is always sent when this format is selected. If a publisher sends a simple RVMSG_STRING or TIBRVMSG_STRING, an exception is passed to the subscribing application.

If the SSL configuration is used by the adapter service sessions, you should manually change the configuration of the R3JmsTopicSession to SSL. This can be done by selecting the Use SSL? checkbox in the R3JmsTopicSession session.

For integrating two SAP R/3 systems, the wire format and transport type for both the publisher and subscriber must be same, otherwise an error will occur.



Quality of Service — Select the type of service to be used for publishing messages. Possible values are:

— Reliable indicates reliable message delivery, where messages are received without explicit confirmation.

— Certified (default) indicates certified message receipt, which offers stronger assurances of message receipt, along with tighter control, greater flexibility and fine-grained reporting.

6. If you selected JMS in the Transport Type field, specify the following options:


For JMS mode of transport only one wire format is available. Publishers and subscribers can only send and receive data if they agree on a specific wire format.


Delivery Mode — The delivery mode for the message. There are two options to choose from.

— Persistent indicates that the message will be available to a JMS client even if the JMS server goes down.

— Non-persistent indicates that the message will not be available to a JMS client if the JMS server goes down.

See the TIBCO Enterprise for JMS User’s Guide for more information.

Connection Factory Type — A message can be published to a topic or sent to a queue.

— Queue indicates that a message sent to a queue is consumed by one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not. This messaging model is known as point-to-point.

— Topic indicates that a message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic. This messaging model is known as publish-subscribe.

For details on JMS concepts refer to the TIBCO Enterprise for JMS User’s Guide.

Transactional (RVTX) quality of service is not supported.



7. Click Apply

See Configuring Schema for Adapter Services on page 191 for details on configuring data schema for adapter services. See Configuring User Exits on page 230 for details on setting advanced options for a publisher service.

Example This example shows a publication service created for MATMAS01 IDoc.

The following example shows a publication service configured for JMS mode of transport.

Identifying the Publication Mode

You can select from the publication modes available by using the drop-down box in the Publish Mode field.



The Mode options include:

— None means that the IDoc message is processed in native RFC table format without inclusion of the IDoc metadata.

— Explode means that the message is expanded and self-describing because it includes IDoc metadata.

— Exploded Batch means the message contains a batch of self-describing IDoc data, each IDoc in an exploded format.

— 10Xcif means transfer backward-compatible certified intermediate format (CIF).

— 10Xbatched means transfer backward-compatible batched format.

— 10Xbatched NL means transfer backward-compatible batched format separated by a new line. This is equivalent to the 10X Batch mode for adapter Publisher 1.X with PutEndOfLineInIDoc parameter set to 1. In this mode the adapter puts an end-of-line character at the end of each row of IDoc control and data records before publishing them.

For detailed information on each of the Mode options, refer to the following sections.

Mode “none”

In the default interface mode, IDoc output from an SAP R/3 system is processed in the native RFC table format. This compressed (unexploded) form uses metadata to describe an IDoc. The IDoc data is most efficiently transmitted in this format, because no additional processing is required to expand the IDoc segments and fields. For best performance the decompression (exploding) step is left for the stage when the data is actually consumed.

IDocs of SAP R/3 System Releases 3.x and 4.x (port types 3 and 4) are supported. SAP R/3 releases 4.x are also capable of sending IDocs in a format understandable by older releases, including 3.x.



For SAP R/3 releases 4.x, the IDoc contains the following records:

• EDI_DC40 (one control record)

• EDI_DD40 (multiple data records)

For SAP R/3 releases 3.x, an IDoc contains the following records:

• EDI_DC (one control record)

• EDI_DD (multiple data records)

Figure 8 shows a truncated example of 4.x IDoc data transmitted in the default “explode” mode. In this example the control record follows the data records. Note that for transmission purposes, the order is not significant to the adapter.

Figure 8 IDoc in native RFC table format

The following is an example of an XML schema for an IDoc in 3.x mode:<class name="INBOUND_IDOC_PROCESS">

<attribute class="sequence[EDI_DC]" name="IDOC_CONTROL"/><attribute class="sequence[EDI_DD]" name="IDOC_DATA"/>

</class>

The following is an example of an XML schema for an IDoc in 4.x mode:<class name="IDOC_INBOUND_ASYNCHRONOUS">



<attribute class="sequence[EDI_DC40]" name="IDOC_CONTROL_REC_40"/>

<attribute class="sequence[EDI_DD40]" name="IDOC_DATA_REC_40"/>

</class>

Default Mode “Exploded”

IDocs are initially received in compressed form as RFC tables. The received IDoc is expanded and serialized into a hierarchical ActiveEnterprise message structure, called the ActiveEnterprise Message format, using IDoc metadata. Figure 9 shows an IDoc in expanded format. Metadata specifies the hierarchical structure, including contained records and fields, associations between different segments, and repetition information. The ActiveEnterprise Message format is described in the TIBCO Adapter SDK Concepts manual.

The exploded form facilitates application integration by using an intermediate transformation application such as TIBCO IntegrationManager. For more information on how to use TIBCO IntegrationManager, see the TIBCO IntegrationManager User’s Guide.

If multiple IDocs are received in a batch, then each IDoc in the batch is split from the other IDocs and sent individually.

The SAP R/3 system sends out data to the adapter with padded blanks wherever a field in the IDoc segment does not occupy the complete field length or a field is not populated at all.

By default, the adapter trims off the trailing spaces from blank padded fields, and cuts out blanks-only fields.

To override this behavior and allow the adapter to pass on all fields received from the SAP R/3 system as is to the TIBCO environment, you can specify the following parameter in the adapter properties file.adr3.preserveFieldBlanks=ON

This flag causes the adapter not to trim any of the blank-padded fields or filter out empty fields coming from the SAP R/3 system.



Figure 9 IDoc in uncompressed “exploded” format

Mode "Exploded Batch"

In the previous version of the adapter, the SAP R/3 system sent IDocs in a batch. The adapter was configured to send IDocs in the Explode mode and the IDocs were sent one by one. Using the Batched Explode mode, the adapter sends a batch of IDocs in the explode mode. Similarly on the subscriber side, the adapter receives the IDocs in a batch and processes them in SAP R/3. This improves the performance of the adapter.

If the ALE outbound profile for an IDoc-type is set up to Collect IDocs, IDocs are collected within the SAP R/3 system till the packet size value is reached and then sent to the adapter in one shot.

The Exploded Batch publication mode ensures that individual IDocs are ’exploded’ to a self-describing format and also maintained as a batch. The batch of exploded IDocs is then published as one single message by the adapter.



Mode “10Xcif”

The unexploded form of an IDoc is received and converted to a SAP Certified Intermediate Format (CIF). The IDoc message is transformed to a CIF string that contains Group, Segment and Field name value pairs, in an implicit hierarchical structure. CIF is one of SAP standards for exchanging information with non-SAP systems.

If multiple IDocs are received in a batch, then each IDoc in the batch is split from the other IDocs and sent individually.

Mode “10Xbatched”

The10X batched format is useful to offload extensive volumes of IDocs from an SAP R/3 system by first collecting them into the ALE layer, and then dispatching the collected IDocs in one single transaction. This achieves the best throughput for both the SAP R/3 system, and the adapter.

If an ALE outbound profile is not set up to collect IDocs, the IDocs are sent by the SAP R/3 system immediately to the adapter, as they are created. In that case, the adapter packs each IDoc received into a batch format that contains only one IDoc and then dispatches it. If more than one IDoc is received, the “batched” message contains a string of IDocs packed together. All control records precede the data records in the package.



Schema TabPublication services must be associated with the IDoc schema. Schema association can be carried out in the Schema tab.

The procedure to obtain IDocs is detailed in this section.

1. Click Fetch IDocs to retrieve the list of IDocs based on the IDoc filter provided.

2. Click Select IDoc, a list of IDocs is displayed in a separate window.

3. Choose an IDoc from the list displayed and click OK. The schema of the selected IDoc is downloaded and displayed in the tab. The IDoc is displayed in a hierarchical manner similar to the display in the SAP system. Click on the nodes to expose the relationship to those nodes and display the fields for those segments.

4. Services are created appropriately for the IDoc and associated with the IDoc’s schema.

The none, explode and the exploded batch modes can be configured with wire formats, ActiveEnterprise message, XML and Rendezvous message. The 10Xcif and 10Xbatched modes can be configured only with Rendezvous messages.




Example In this example IDocs have been retrieved.



On selecting the required IDoc the service is created as shown in the following screen.

Advanced TabAdvanced options can be set for a publication service using two modes of transport, TIBCO Rendezvous and JMS. The procedures are detailed below:

If TIBCO Rendezvous is selected in the Transport Type field (under the Configuration tab):

You can configure the subject to be used when publishing IDocs either by using an Endpoint Reference or by changing the subject name.

Endpoint Reference — Specify the endpoint to be used by the Publication service. Click Browse to locate the endpoint reference.



Message Subject — Specify the subject name to be used by default when publishing.

1. Click Apply.

2. Click Go To to access and modify the configuration options of the endpoint, if required. See TIBCO Designer Adapter Resource Management Guide for details on configuring endpoints.

Example This example screen shows the advanced configuration options for a publication service created for the MATMAS01 IDoc.

You can overwrite the subject by entering the new subject in Message Subject field. If you are using global variables in the subject names, ensure that they are not deleted.

If you need to globally change the variables %%Domain%% and %%Deployment%% in the default subject name, use the Edit >Global Variables menu option. Ensure that the values are not set to null.

If you need to override the subject name for a specific adapter configuration, override it by entering the required value in the Message Subject field and not by changing the Global Variables. Once you override the subject name manually, further updating must be carried out manually when required. The subject name is not generated automatically.



If JMS is selected in the Transport Type field (under the Configuration tab):

Destination — The destination is the name on which the service publishes to a topic or sends messages to a queue if you are setting advanced options for a publication service.

Endpoint Reference — Specify the endpoint to be used by the service. Click Browse to locate the endpoint reference.

1. Click Apply.

2. Click Go To to access and modify the configuration options of the endpoint, if required. See TIBCO Designer Adapter Resource Management Guide for details on configuring endpoints.

The advanced options are identical for all types of services using JMS as the mode of transport.

JMS administrator should define the destinations that will be used by the adapter services. See TIBCO Enterprise for JMS documentation for details.



Example This example screen shows the advanced configuration options for a publication service.


Subscription Service Options | 167

Subscription Service Options

A subscription service is used to receive IDocs from the TIBCO environment and then send it to the SAP R/3 system. A separate subscription service is required for every IDoc to be sent to the SAP R/3 system.

You can configure Subscription service parameters under the following tabs:


• Schema Tab

• Advanced Tab

Configuration TabSubscription service configuration options can be specified using the Configuration tab.

1. Specify the following options in the Configuration tab:

Name — A unique and meaningful name for the subscriber.

In cases where the IDoc is being sent in a TIBCO Rendezvous 5.x message format, the service must still be associated with an IDoc even though the schema of the IDoc will not be used. This also applies to IDocs sent using 10Xcif, 10Xbatched and 10XbatchedNL modes.

Communication with the SAP server requires the existence of “logical systems,” the identification of IDoc “message types,” and other custom modifications using the SAP graphical user interface. While these are not R/3 Adapter configuration issues, they must be complete before IDocs can be transmitted. See Appendix D on page 489 for an example of customizing the SAP server to communicate with the adapter.

By default a new subscription service is named SubscriptionService. Once the IDoc is selected using the Schema tab, the service name is changed to reflect the IDoc name.










One of the following wire formats can be selected for sending the message. Publication and Subscription services can only send and receive data if they agree on a specific wire format. Possible values are:



— Rendezvous Message, a self-describing message format used by TIBCO Rendezvous applications. Control information for validation is not sent in the message. For Rendezvous wire format, a message of type RVMSG_RVMSG (Rendezvous 5.x) or TIBRVMSG_MSG (Rendezvous 6.x) is always sent when this format is selected. If a publication service sends a simple




RVMSG_STRING or TIBRVMSG_STRING, an exception is passed to the subscribing application.

Quality of Service — Select the type of service to be used for subscribing to messages. Possible values are:

— Reliable indicates reliable message delivery, where messages are received without explicit confirmation.

— Certified (default) indicates certified message receipt, which offers stronger assurances of message receipt, along with tighter control, greater flexibility and fine-grained reporting.

— Distributed Queue indicates load balancing should be enabled.

See TIBCO Rendezvous Concepts for details about quality of service.


Wire Format — The format in which messages are to be subscribed. Different options are displayed according to the Transport Type selected.

For JMS mode of transport only one wire format is available. Publication and Subscription services can only send and receive data if they agree on a specific wire format.


Delivery Mode — An adapter subscription service can be durable or non- durable.

— Durable indicates that the service is registered with the JMS server. Messages sent to a durable subscription service are held by the JMS server

For an IDoc being received as TIBCO Rendezvous 5.x message, the wire format must be Rendezvous message.

The wire format and transport type for both the Publication and Subscription services must be same, otherwise an error will occur.

Transactional (RVTX) quality of service is not supported.



until they are consumed by the service. The service can be down and expect to receive its messages when it comes back up.

— Non-durable indicates that the service is not registered with the JMS server. Messages sent to a non-durable subscription service are not held by the JMS server. If the service is down, it will not receive the messages that arrived at the JMS server while the service was down.

For details, see the TIBCO Enterprise for JMS User’s Guide.





4. Select the Receive IDOCs in Exploded Mode checkbox to receive IDocs in the exploded batch format. See Identifying the Publication Mode on page 155 for details of the exploded batch format.

5. Click Apply.

See Configuring Schema for Adapter Services on page 191 for details on configuring data schema for adapter services. See Advanced Tab on page 173 for details on setting advanced options for a Subscriber service.



Example This example shows a subscription service created for MATMAS01 IDoc configured using default options.

The following example shows a subscription service configured for JMS mode of transport.

Schema TabSubscription services must be associated with the IDoc schema. Schema association can be carried out in the Schema tab.

The procedure to obtain IDocs is detailed in this section.



1. Click Fetch IDocs to retrieve the list of IDocs based on the IDoc filter provided.

2. Click Select IDoc, a list of IDocs is displayed in a separate window.

3. Choose an IDoc from the list displayed and click OK. The schema of the selected IDoc is downloaded and displayed in the tab. The IDoc is displayed in a hierarchical manner similar to the display in the SAP R/3 system. Click on the nodes to expose the relationship to those nodes and display the fields for those segments.

4. Services are created appropriately for the IDoc and associated with the IDoc’s schema.

Example In this example IDocs have been retrieved.





Advanced TabAdvanced options can be set for a subscription service using two modes of transport, TIBCO Rendezvous and JMS. The procedures are detailed below:


1. Specify the following options in the Advanced tab:

Endpoint Reference — Specify the endpoint to be used by the Subscription service.

Click Browse to locate the endpoint reference.



Message Subject — Specify the subject name to be used by default when subscribing.

Client Connection Reference— Select the appropriate client connection reference. By default, the client connection for that instance is used. You can point to a different client connection. Click Browse to locate the client connection reference.

2. Click Apply.

You can overwrite the subject by entering the new subject in Message Subject field. If you are using global variables in the subject names, ensure that they are not deleted. If you need to globally change the variables %%Domain%% and %%Deployment%% in the default subject name, use the Global Variables tab to change the variable value. Ensure that the values are not set to null.

If you need to override the subject name for a specific adapter configuration, override it by entering the required value in the Message Subject field and not by changing the Global Variables. Once you override the subject name manually, further updating must be carried out manually when required. The subject name will not be generated automatically.

If the IDoc is to be posted to a client other than the client in the default client connection, the client connection reference must be changed to point to the appropriate client.




1. Specify the following options in the Advanced tab,

Destination — The destination is the name on which the service subscribes to a topic or receives from a queue if you are setting advanced options for a subscription service.


2. Click Apply.

Example This example shows the advanced configuration options for a subscription service created for the MATMAS01 IDoc.




Request-Response Invocation Service Options | 177

Request-Response Invocation Service Options

A request-response invocation service is used to invoke an Outbound RFC or BAPI from the SAP R/3 system to the adapter. A separate request-response invocation service is required for every RFC or BAPI to be invoked.

You can configure parameters under the following tabs:


• Schema Tab

• Advanced Tab

Configuration TabUse the Configuration tab to specify transport type, quality of service and invocation protocol to be used for the Request-Response Invocation service.


Name — A unique and meaningful name for the Request-Response Invocation service.





To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL configuration options are

By default a new Request-Response Invocation service is named Request-ResponseInvocationService. Once the RFC or BAPI is selected using the Schema tab, the service name is changed to reflect the RFC/BAPI name.



explained in the online help associated with the session dialog. Click the question mark to display the online help.



One of the following wire formats can be selected for sending the message. Publication and Subscription services can only send and receive data if they agree on a specific wire format. Possible values are:


Quality of Service — Select the quality of service to be used. Possible values are:

— Reliable (default) indicates reliable message delivery, where messages are received without explicit confirmation.

— Certified indicates certified message receipt, which offers stronger assurances of message receipt, along with tighter control, greater flexibility and fine-grained reporting.




For JMS mode of transport only one wire format is available. Publication and Subscription service can only send and receive data if they agree on a specific wire format.





Delivery Mode — The delivery mode for the message. There are two options to choose from.

— Persistent indicates that the message will be available to a JMS client even if the JMS server goes down.

— Non-persistent indicates that the message will not be available to a JMS client if the JMS server goes down.





4. Click Apply.

See Configuring Schema for Adapter Services on page 191 for details on configuring data schema for adapter services. See Configuring Multiple Connections for Inbound Instance on page 241 for details on setting advanced options for a request-response invocation service.



Example This example shows a request-response invocation service that is configured using the default values.

The following screen shot shows a request-response invocation service configured to use JMS as the mode of transport.

Schema TabRequest-Response Invocation services must be associated with the RFC/BAPI schema. Schema association can be carried out in the Schema tab.

The procedure to obtain RFC/BAPIs is detailed in this section.



1. Click Fetch RFC/BAPI to retrieve the list of RFC/BAPIs based on the RFC/BAPI filter provided.

2. Click Select RFC/BAPI a list of RFCs/BAPIs is displayed in a separate window.

3. Choose an RFC or BAPI from the list displayed and click OK. The schema of the selected RFC or BAPI is downloaded and displayed in the tab. The RFC or BAPI details displayed is similar to the display in the SAP R/3 system.

4. Services are created appropriately for the RFC/BAPI and are associated with the RFC/BAPI schema.



Advanced TabAdvanced options can be set for a request-response invocation service using two modes of transport, TIBCO Rendezvous and JMS. The procedures are detailed below:


You can configure the subject to be used when invoking an inbound RFC or BAPI, by changing the subject in the Advanced tab.


Endpoint Reference — Specify the endpoint to be used by the Request-Response Invocation service. Click Browse to locate the endpoint reference.

Message Subject — Specify the subject name to be used by default.

2. Click Apply.






Destination — The destination is the name on which the service publishes to a topic or sends messages to a queue if you are setting advanced options for a publication service. The destination is the name on which the service subscribes to a topic or receives from a queue if you are setting advanced options for a subscription service.


1. Click Apply.

Example This example shows the advanced configuration options for a Request-Response Invocation service.





Request-Response Service Options

A request-response service is used to invoke an Inbound RFC or BAPI, in the SAP R/3 system, from the adapter. A separate request-response service is required for every RFC or BAPI.

You can configure parameters under the following tabs:


• Schema Tab

• Advanced Tab

Configuration Tab1. Specify the following options in the Configuration tab:

2. By default, a request-response service is named Request-Response Service. Once the RFC or BAPI is selected using the Schema tab, the service name is changed to reflect the RFC/BAPI name.

Name — A unique and meaningful name for the request-response service.








Request-Response Service Options | 185

Quality of Service — Select the quality of service to be used. Possible values are:

— Reliable (default) indicates reliable message delivery, where messages are received without explicit confirmation.

— Certified indicates certified message receipt, which offers stronger assurances of message receipt, along with tighter control, greater flexibility and fine-grained reporting.

— Distributed Queue indicates load balancing should be enabled.


3. Click Apply.

See, Configuring Schema for Adapter Services on page 191 for details on configuring data schema for adapter services. See Advanced Tab on page 188 for details on setting advanced options for a request-response service.

If the service is to be invoked as request/reply invocation protocol, the quality of service should be Reliable. If it is to be invoked as one way invocation protocol the quality of service should be Certified. If the adapter instance is to be load-balanced with other similarly configured inbound instances the quality of service should be Distributed Queue.

If the SAP R/3 system expects a response from the adapter, the invocation protocol should be configured as request/reply. If no reply is expected, the protocol should be set to oneway.



Example This example shows a request-response service that is configured using the default values.

The following screen shot shows a request-response service configured to use JMS as the mode of transport.

Schema TabRequest-Response services must be associated with the RFC/BAPI schema. Schema association can be carried out in the Schema tab.

The procedure to obtain RFC/BAPIs is detailed in this section.

1. Click Fetch RFC/BAPI to retrieve the list of RFC/BAPIs based on the RFC/BAPI filter provided.



2. Click Select RFC/BAPI a list of RFCs/BAPIs is displayed in a separate window.

3. Choose an RFC or BAPI from the list displayed and click OK. The schema of the selected RFC or BAPI is downloaded and displayed in the tab. The RFC or BAPI details displayed is similar to the display in the SAP R/3 system.

4. Services are created appropriately for the RFC/BAPI and are associated with the RFC/BAPI schema.



Advanced TabAdvanced options can be set for a request-response service using two modes of transport, TIBCO Rendezvous and JMS. The procedures are detailed below:


When invoking an RFC or BAPI in the SAP R/3 system the subscribed subject must match the subject on which the request is being sent. You can configure the subject to be used when invoking an inbound RFC or BAPI, either by using an Endpoint Reference or changing the subject.


Endpoint Reference — Endpoint to be used by the Request-Response service. Click Browse to locate the endpoint reference.

Message Subject — Subject name to be used by default.

Client Connection Reference — Select the appropriate client connection reference. By default, the client connection for that instance is used. You can point to a different client connection. Click Browse to locate the client connection reference.

Commit Required — If an external commit is required select this check box, else leave it unchecked.

Commit Expiry(ms) — If an external commit is required specify the time (in milliseconds) after which the commit expires. Default is 60000 ms (one minute).



If the RFC or BAPI needs to be invoked for a client other than the one referenced in the default client connection, the client connection reference must be modified to point to the appropriate client.



Logon Required — If the RFC or BAPI being invoked in the SAP R/3 system requires explicit, check this box, else leave it unchecked. See Event Driven Inbound Connections on page 348 for details.


Destination — The destination is the name on which the service publishes to a topic or sends messages to a queue if you are setting advanced options for a Publication Service. The destination is the name on which the service subscribes to a topic or receives from a queue if you are setting advanced options for a subscription service.



2. Click Apply.

3. Click Go To to access the configuration options of the endpoint reference or the client connection reference.


The invocation protocol for an RFC or BAPI cannot be determined using the properties available in the Request-Response service.



Example This example shows the advanced configuration options for a request-response service.


Configuring Schema for Adapter Services | 191

Configuring Schema for Adapter Services

Adapter services must be associated with the IDoc or RFC/BAPI schema. Schema association can be carried out in the Schema tab for IDoc or RFC/BAPI schema depending on the type of service.

Use the following steps to configure adapter service schema.

1. Drag the required adapter service icon from the palette panel to the design panel, then click Schema. The tab displayed depends on the type of service. In the case of publication and subscription services IDoc schema can be obtained. In the case of request-response invocation and request-response RFC or BAPI schema can be obtained. The procedure for both is detailed in this section.

Schema Tab IDoc



c. Choose an IDoc from the list displayed and click OK. The schema of the selected IDoc is downloaded and displayed in the tab. The IDoc is displayed in a hierarchical manner similar to the display in the SAP system. Click on the nodes to expose the relationship to those nodes and display the fields for those segments.


RFC/BAPI


b. Click Select RFC/BAPI a list of RFCs/BAPIs is displayed in a separate window.

c. Choose an RFC or BAPI from the list displayed and click OK. The schema of the selected RFC or BAPI is downloaded and displayed in the tab. The




RFC or BAPI details displayed is similar to the display in the SAP R/3 system.


Example 1 In this example IDocs have been retrieved.



Example 2 In this example RFCs/BAPIs have been obtained.



On selecting RFC_LOGIN and clicking OK the service is configured as shown in the following screen.



Saving the Project

Configuration information for an adapter instance and all other parameter settings related to the adapter instance are saved as a TIBCO Designer project. You can save the project any time during configuration. Each time you save a project, any configuration information you have entered is saved as a multi-file project.

For details on saving a project, see the TIBCO Designer User’s Guide.


| 197

Chapter 6 Configuring the Adapter with Advanced Options

This chapter explains how to configure the adapter using advanced options.

Topics


• Configuring Valid Destinations, page 200

• Adding Connections to an Adapter, page 201

• Adding an Active Connection, page 203

• Adding a Connection Reference, page 205

• Adding a Client Connection, page 208

• Dedicated Application Server Client Connection, page 210

• Client Connection with Load Balancing, page 212

• Client Connection with saprfc.ini file, page 214

• Setting Client Connection Advanced Options, page 216

• Adding a Server Connection, page 221

• Default Server Connection, page 222

• saprfc.ini Server Connection, page 224

• Setting Server Connection Advanced Options, page 226

• Sample saprfc.ini Files, page 228

• Configuring User Exits, page 230

• Saving an IDoc to a Directory, page 232

• Publishing IDocs on Dynamic Subjects, page 237

• Replacing Control Fields, page 239

• Configuring Multiple Connections for Inbound Instance, page 241


198 | Chapter 6 Configuring the Adapter with Advanced Options

• Configuring Multiple Connections for Inbound Instance, page 241

• Configuring Multiple Connections for Outbound Instance, page 246

• TIDManager, page 250

• Setting TIDManager Configuration Options, page 253

• Setting TIDManager Logging Options, page 254

• Setting TIDManager General Options, page 257

• Setting TIDManager Monitoring Options, page 256

• Load Balancing Using Distributed Queue, page 260

• Using Global Variables, page 272


Overview | 199

Overview

This chapter describes advanced configuration options available in the adapter palette so that you can refine and enhance various adapter operations.

Some of the advanced configuration options include adding connections to an adapter, modifying TIDManager configuration, configuring valid destinations, etc.

Connections required by an adapter are created by default as described in the previous chapter on adapter configuration. You can however use advanced options to create new connection references, add and configure server and client connections. You can also maintain advanced client configuration options.



Configuring Valid Destinations

The Adapter Services tab can also be used to specify a list of destinations to which the IDocs will be sent. This list of destinations applies globally to all IDoc types that are sent from the SAP R/3 system or to the SAP R/3 system. Typically, these destinations are SAP R/3 logical system names, but they can be a bank identifier, a customer identifier, or any Partner Type currently configured.

The RCVPRN field of an IDoc’s control record specifies the receiving partner (destination) for the IDoc. If an IDoc’s RCVPRN field has a value that is not configured as a valid destination, the IDoc is not published to the TIBCO environment. The IDoc will be logged (saved) into an ASCII text file under the configured directory. For details on how to save IDoc under a directory, see Saving an IDoc to a Directory on page 232.

To configure valid destinations,

1. In the Adapter Services tab, enter the valid destinations in the Valid Destinations field. The screen is shown next.

2. To add a new entry in the list, enter the name of the valid destination in the list separated by comma.

3. Click the Apply button.

4. Click the Apply button to apply your changes.

As entries get saved, they are automatically converted to uppercase. This is done to ensure consistency with the syntax of logical systems in SAP R/3.


Adding Connections to an Adapter | 201

Adding Connections to an Adapter

You can modify the default connections or create additional connections to suit your requirements. On creating an adapter instance a basic set of connections are created depending on whether the adapter instance is Inbound, Outbound or Both. Connections can be shared by adapter instances in the same project.

The default connections created for an adapter instance that is both Inbound and Outbound are listed in the next table:

When an adapter instance is created, if no other adapter instance exists, an R3 Connections folder is created under the project folder. The hierarchy of the R3 Connections folder will be as follows:

Figure 10 R3 Connections Folder Hierarchy

Client Connections folder - For client connection information shared by all clients. In this case, clients are SAP R/3 clients. A client connection folder can contain individual client connection information. A default client connection is created when an adapter instance is created.

Connection Type Default Name

Client Connection R3AdapterConfigurationInboundConnection

Server Connection R3AdapterConfigurationOutboundConnection

Active Connection R3AdapterConfigurationActiveConnections

Connection Reference clientConnectionReference

serverConnectionReference



Server Connections folder - For server connection information shared by the server. By server, we mean SAP R/3 server. A default server connection is created when an adapter instance is created.

Client folder - For SAP R/3 client information. A default client is created when an adapter instance is created.

R3AdapterConfiguratioActiveConnections folder - For Connection Reference information indicating the default active server or client connection. Default connection references to a client connection and a server connection are also created by default.

You can carry out the following connection configuration:

• Adding an Active Connection

• Adding a Connection Reference

• Adding a Client Connection

• Adding a Server Connection

The following sections describe each of these connection resources in detail.


Adding an Active Connection | 203

Adding an Active Connection

All connections maintained inside an adapter instance are configured using the Active Connection Resource available from the palette panel.

When you configure an adapter instance, an Active Connection instance is created by default with reference to one client connection and one server connection. If the default configuration does not meet your requirements, you can modify the existing Active Connection instance or create a new one. An appropriate reference to the Active Connection instance must be provided in the adapter instance.

For details on associating an adapter instance with an Active Connection Reference, see Assigning an Active Connection to an Adapter on page 207.

Setting up Active Connection Configuration OptionsUse the following steps to add and configure an Active Connection.

1. Select R3Connections in the project panel. Drag and drop an ActiveConnection icon from the palette panel to the design panel.


ConfigurationTab

Name — Specify a unique and meaningful name for the Active Connection. By default, the Active Connection folder is named R3AdapterConfigurationActiveConnections. You can change it to a name of your choice.

Description — Enter a brief description.

3. Click Apply.

After creating an Active Connection instance, the next step is to create references from the Active Connection to the required client or server connections.

See Adding a Connection Reference on page 205.



ExampleThis example shows the basic active connection folder screen. The active connection folder has been assigned a name


Adding a Connection Reference | 205

Adding a Connection Reference

A Connection Reference is used to associate a particular client or server connection inside an Active Connection. On creating an adapter instance, two default connection references are created. One points to the client connection created by default on creation of the adapter instance and the second points to the server connection created by default on creation of the adapter instance. If multiple client or server connections are being maintained you must specify one of each type as the default.

You can configure Connection reference parameters using the following tab:


Setting up Connection Reference OptionsDefault Connection References are automatically created when you configure an adapter instance. If additional connection references are required, use the following steps to create them.

1. Drag an ActiveConnection icon from the palette panel to the design panel.

2. Drag and drop a ConnectionReference icon from the palette panel to the design panel. The Configuration tab displays.


ConfigurationTab

Name — Assign a unique and meaningful name to the Active Connection. By default the name is ConnectionReference. You can change this to a name of your choice.

Referenced Connection — Enter the client or server connection to be referenced by the Active Connection. Click Browse to locate the required client or server connection.

See Adding a Client Connection on page 208 and Adding a Server Connection on page 221, for details on configuring client connection and server connection parameters.

Ensure that client connections and server connections have been created prior to creating connection references. See Adding a Client Connection on page 208 and Adding a Server Connection on page 221 for details.



Default connection — Select this check box if the specified Referenced Connection needs to be set as the default client connection or server connection for the associated adapter instance.

4. Click Apply.

5. If you need to view or modify the client connection or server connection parameters, click Go To. The display changes to the Configuration tab of the connection specified.

ExampleThis example shows a connection reference configuration created by default for client connections.

If multiple client or server connections have been referenced, only one connection per type can be set as the default for that particular type.

Ensure that when any connection reference is made Default (by selecting the Default Connection check box), the default connection is made the top most child under the Active Connection folder.

If there is a combination of Server Connection References and Client Connection References, make sure that the default Server Connection Reference is at the top (first) of all Server Connection References and default Client Connection Reference is at the top (first) of all Client Connection References. Making the Default Connection Reference the top element can be achieved by Sorting. For details on sorting, refer to TIBCO Designer documentation.


Adding a Connection Reference | 207

Assigning an Active Connection to an AdapterAs described earlier, a default Active Connection instance is created when an adapter instance is created. A reference pointing to the Active Connection is also created in the adapter instance, by default.

In cases where a different Active Connection is required, an appropriate reference must be set up in the adapter instance.

To associate an adapter instance with an Active Connection Reference, do the following:

1. Select the General tab.

2. Click Browse resources.. against the Active Connection Reference field.

3. Select the required Active Connection from the Select a Resource Window. Click OK and click Apply. The screen shot is given next.

It is recommended that you associate one instance with one active connection.



Adding a Client Connection

Client connections can be of three types:

• Dedicated Application Server Client Connection

• Client Connection with Load Balancing

• Client connection with saprfc.ini file

A client connection of the Dedicated Application Server type is created by default when you configure an Inbound adapter instance. You can add client connections as per your configuration needs, choosing from the three types available.

Use the Configuration Tab to select the type of client connection you want to configure.

Selecting Client Connection TypeUse the following steps to select the required client connection type.

1. Select the Client Connections folder in the project panel. You can specify a Name for the folder and enter the Description in the Configuration tab.

2. Drag and drop a ClientConnection icon from the palette panel to the design panel.

3. Select the ClientConnection type in the Configuration tab:

Additional client connections are required in cases where an adapter instance must connect to multiple R/3 application servers or clients. Each application server or client would have its own client connection.

Client connections requiring gateway hosts different from that of the application server are not supported. The workaround is to use client connections in conjunction with saprfc.ini.


Adding a Client Connection | 209

ConfigurationTab

Select Connection Type — Select the type from the drop down list. The possible types are:

— Dedicated Application Server Client Connection

— Client Connection with Load Balancing

— Client Connection with saprfc.ini file

4. Click Apply. The appropriate configuration panel displays. A Client is automatically created in the Clients folder using the configuration information provided in the Client Connection, only if the Client Connection is configured.

5. The name of the client is derived from the client connection name. However, advanced configuration for the client is maintained in the client.

In cases where a dedicated connection is required and the gateway server host differs from the application server, you must select saprfc.ini file as the ClientConnection type.

Make a note of the client name for future reference in case advanced configuration is required.



Dedicated Application Server Client Connection

A client connection can be configured for a specific SAP R/3 application server.

Use the following tabs to configure Dedicated Application Server Client Connection parameters.


• Advanced Tab

Configuring Dedicated Application Server Client ConnectionA Dedicated Application Server is created by default when you configure an adapter instance. You can add connections as required.

Use the following steps to configure a Dedicated Application Server client connection.

1. Select the client connection type as Dedicated Application Server, to display the Inbound Connection tab.


ConfigurationTab

Application Server — The network name of the host SAP application server machine.

System Number — The SAP R/3 database instance number.

Client — The SAP R/3 client number.

User name — Specify a valid user name to log into the SAP R/3 client specified

Password — Specify a valid password corresponding to the user name.

R/3 Logon Language — Select the language to be used when logging into the SAP R/3 system.

3. Click Apply.

4. Click the Advanced tab to access advanced configuration parameters. See Setting Client Connection Advanced Options on page 216.

5. Click Test Connection to verify the connection configuration settings.


Dedicated Application Server Client Connection | 211

ExampleIn this example a client connection of the dedicated application server has been configured.



Client Connection with Load Balancing

Use the following tabs to configure a client connection that uses load balancing.


• Advanced Tab

Configuring Client Connection with Load BalancingDuring creation of the client connection, you can specify the client configuration type as Load Balancing. To use load balancing, the client machine initiating the request must have a service named sapmsXXX defined on the system, where XXX is the value of systemName. The default service value is 3600/tcp, and can be changed.

Use the following steps to configure a client connection that uses load balancing.

1. Drag a ClientConnection icon from the palette panel to the design panel.

2. Select Load Balancing from the Select Client Connection Type drop down combo box.

3. Click Apply. The Configuration tab is displayed.

4. Specify the following options in the Configuration tab.

ConfigurationTab

System Name — The SAP/R3 system ID used in conjunction with load balancing. For example, TIB.

Msg Server — The message server used in conjunction with load balancing. For example, SAPSVR.

Logon Group — The SAP logon group that is used in conjunction with load balancing. For example, PUBLIC.


User Name — Valid user name for logging into the SAP R/3 client specified.

Password — Valid password corresponding to the user name.

R/3 Logon Language — Language to be used when logging into the SAP system.

5. Click Apply.

In SAP R/3, names of Logon Groups are case sensitive.


Client Connection with Load Balancing | 213

6. Click the Advanced tab to configure advanced parameters. See, Setting Client Connection Advanced Options on page 216.

7. Click Test Connection to verify the connection configuration settings.

ExampleIn this example a client connection of the load balancing type has been configured.



Client Connection with saprfc.ini file

A client connection can be configured to use a saprfc.ini file.

Use the following tabs to configure a client connection with the saprfc.ini file.


• Advanced Tab

Configuring Client Connection with saprfc.ini FileDuring creation of the client connection, you can specify the client connection type as saprfc.ini. If selected, the saprfc.ini file is used.

• The file must exist in the current working directory of the process making the connection request.

or

• An environment variable named RFC_INI must be defined that points to the directory and filename.

The filename does not have to be saprfc.ini. Assuming that the file was named tibco.txt and it was located under the temp directory on the C drive, the environment variable would be defined with the value C:\temp\tibco.txt.

Use the following steps to configure a client connection that uses the saprfc.ini file.

1. Drag a ClientConnection icon from the palette panel to the design panel.

Select Saprfc.ini file from the Select Client Connection Type drop down box.

In cases where a dedicated connection is required and the gateway server host differs from the application server, you must select saprfc.ini file as the Client Connection type.

2. Click Apply.


Since the adapter requires configuration from the repository, it is recommended that the INI file be used during the early stages of development and test. By using the INI file to define the connection parameters, you avoid making changes in the repository which may take longer compared to editing the INI file itself.


Client Connection with saprfc.ini file | 215

ConfigurationTab

Destination — The destination application server name. Used in conjunction with the saprfc.ini file, the name defines the set of attributes to be retrieved from the INI file during the registration of the connection to SAP R/3.


User Name — Specify a valid user name to log into the SAP R/3 client specified.


R/3 Logon language — Specify the language to be used when logging into the SAP system.

4. Click Apply.

5. Click the Advanced tab to configure advanced parameters. See, Setting Client Connection Advanced Options on page 216.

ExampleIn this example a client connection has been configured to use the saprfc.ini file.



Setting Client Connection Advanced Options

Use the following steps to set up advanced client connection options.

1. Click the Advanced tab to enter advanced configuration information.


Advanced Tab Number of Reconnect Attempts Before Suspending Impacted

Service(s) — The number of times the connection management process tries to connect to the application before the listener for a subscription or a one-way request-response invoke service is suspended. The default value for this field is 1.

Maximum number of Reconnect Attempts — The maximum number of times the adapter will retry to establish a connection to the SAP R/3 system. By default, it is set to 3. This has to be greater than or equal to the value in the Number of retries before suspend field. For retry to continue forever, set the value to -1.

Interval Between Reconnect Attempts (milliseconds) — The time interval between two successive retries, in milliseconds. The default value is 30000ms.

Adapter Termination Criteria (after max number of reconnect

attempts — This field is relevant for Inbound configurations connected to multiple SAP R/3 systems. This field indicates whether the adapter should stop after all attempts to reconnect are exhausted for just one SAP R/3 system or all SAP R/3 systems.

— First Service indicates that the adapter should stop after all retry attempts to connect to just one R/3 system are exhausted.

— Last Service indicates that the adapter should stop only after retry attempts to connect to all SAP R/3 systems are exhausted.

The default setting is First Service.

The advanced properties options are identical for all three types of client connections.

The Adapter Termination Criteria (after max number of reconnect attempts) setting is applicable only when an Inbound configuration is connected to multiple SAP R/3 systems.


Setting Client Connection Advanced Options | 217

Max Connections — The number of SAP connections in the client connection. By default, it is set to 1. A maximum of 8 connections is allowed.

The Max Connections option is used to configure the maximum number of threads in the adapter instance.

Startup Connectionless — Select this check box if you do not require to connect to the SAP R/3 system during initialization of the adapter. If this check box is selected, connection to the SAP R/3 system is made when the message arrives.

3. Click Apply.

ExampleThe example displays the advanced client connection options.



Setting up Client Configuration Options

A Client is automatically created as a result of the Client Connection configuration process. There are two ways to modify Client configuration information.

— Modify the Client Connection information

— Directly modify the Client configuration

However, advanced Client configuration must be configured directly under the Advanced tab of Client configuration.

Use the following tabs to configure client parameters:


• Advanced Tab

Use the following steps to configure R/3 Clients:

1. Select the Client folder in the project panel.


ConfigurationTab

Name — The name derived from the client connection instance associated with this client.

Description — A description of the client.

Client — The SAP R/3 client number. This number must exist in the SAP R/3 system.

User Name — Specify a valid user name to log into the SAP R/3 client specified


R/3 Logon Language — Select the language to be used when logging into the SAP system.

3. Click Apply.

4. Click the Advanced tab to configure advanced properties.

ExampleThis example shows the configuration options of a client during creation of a client connection.


Setting up Client Configuration Options | 219



Setting Advanced Client Options

You can specify the tracing and debugging parameters for a SAP R/3 client using advanced options. This option can be used to carry out debugging of RFCs from the SAP R/3 GUI.

Use the following steps to set tracing and debugging parameters at the SAP level:

1. Click the Advanced tab.

2. Specify the following options:

Advanced Tab RFC Trace — Indicate whether the trace is on. Possible values are 0 or 1. By default, set to 0.

ABAP Debug — Indicate whether the debug is on. Possible values are 0, 1, or 2. By default, set to 0.

Use SAPGUI — Indicate whether the trace or debug is on. Possible values are 0 or 1. Default value is 0.

3. Click Apply.

Value Significance

0 The corresponding trace or debug is turned OFF

1 The corresponding trace or debug is turned ON.

2 The corresponding trace or debug is turned on, but launching of the SAP GUI occurs only during the invocation of an RFC.

If other values are entered, an error message appears. If a valid value is not provided, the original value is used.

The trace files are generated in the working directory of the adapter. This is set in the adr3.tra file using the parameter application.start.dir=C:/Tibco/adapter/adr3/5.1

In case you want the files to be generated into a separate directory you can define an environment variable RFC_TRACE_DIR and assign its value as the directory of your choice. Beware, that in this case, you will not be able to put trace files of separate instances into separate folders as only the value assigned to RFC_TRACE_DIR will always be picked.


Adding a Server Connection | 221

Adding a Server Connection

Server connections can be of two types, default or saprfc.ini file. A server connection of the default type is created automatically when you configure an outbound adapter instance. You can add server connections as per your requirements, choosing from the two types available.

Use the following tab to select the type of server connection you need to configure.


Selecting Server Connection TypeUse the following steps to create a server connection and select the connection type.

1. Select Server Connections in the project panel, specify a unique and meaningful Name for the server connection and enter the Description in the Configuration tab.

2. Drag and drop a ServerConnection icon from the palette panel to the design panel.

3. Select the connection type in the Configuration tab:

ConfigurationTab

Select Connection Type — Select the type from the drop-down list. The possible types are:

— Default Server Connection

— saprfc.ini Server Connection

4. Click Apply, the appropriate Configuration tab is displayed.

The following sections provide instructions on configuring the two types of server connections.

Multiple server connections are required in those cases where an outbound adapter instance needs to connect to multiple Gateway Host servers or connect to SAP R/3 system using multiple Program IDs. See, Multiple Connections, on page 341 and Chapter 10, Advanced Features for details on multiple Program IDs.



Default Server Connection

Use the following tabs to configure Default Server Connection parameters.


• Advanced Tab

Configuring Default Server ConnectionUse the following steps to configure a default server connection.

1. Drag a ServerConnection icon from the project panel to the design panel.

2. Select the server connection type as Default.

3. Click Apply.


ConfigurationTab

Program ID — A valid existing program ID defined in the RFC destination inside the SAP R/3 system (sm59). The program ID identifies the RFC server program for the SAP R/3 system. For details on configuring multiple program IDs see Multiple Connections on page 341.

Gateway Service — The SAP R/3 gateway service. The default value is sapgw00.

On Microsoft Windows: A corresponding entry (e.g., sapgw00 3300/tcp) must also be in the services file on the computer’s C: drive at the following directory location: winnt\system32\drivers\etc

Gateway Host — The gatewayHost name, IP address or router string. If there is no machine acting as a gateway host, it is the same as the application server.

RFC Trace — Indicate whether the trace is on or off. Possible values are 0 or 1 only. By default the value is 0.0 - trace is turned OFF. 1 - trace is turned ON. If any other values are entered, an error is displayed. If you do not provide a valid value, then it defaults to 0.

5. Click Apply.

6. Click the Advanced tab to set advanced configuration parameters. See Setting Server Connection Advanced Options on page 226.


Default Server Connection | 223

ExampleIn this example, a server connection is being configured in the default mode.



saprfc.ini Server Connection

The server connection can be configured to use the saprfc.ini file.

Use the following tabs to configure Server Connection with saprfc.ini file.


• Advanced Tab

Configuring Server Connection with saprfc.ini Use the following steps to configure a server connection that uses the saprfc.ini file.

1. Select Server Connections in the project panel, enter the Name and Description of the Server Connections folder in the Configuration tab.

2. Drag and drop a Server Connection icon from the palette panel to the design panel, the Configuration tab is displayed.

3. In the Server Connection Type field, select saprfc.ini file.

4. Click Apply.

5. Specify the following option in the Configuration tab.

ConfigurationTab

Destination — The destination application server name. Used in conjunction with the saprfc.ini file, it defines the set of attributes to be retrieved from the INI file during registration of the connection to SAP R/3.

6. Click Apply.

7. Click the Advanced tab to set advanced configuration parameters. See Setting Server Connection Advanced Options.

See Sample saprfc.ini Files on page 228 for samples files.


saprfc.ini Server Connection | 225

ExampleIn this example a server connection that uses the saprfc.ini file has been configured.



Setting Server Connection Advanced Options

The Advanced tab is used to configure the connection retry management for Server Connections.

1. Click the Advanced tab in the Configuration panel.


Advanced Tab Maximum Number of Reconnect Attempts — The maximum number of times the adapter will retry to establish a connection to the SAP R/3 system. By default, it is set to 3. For retry to continue forever, set the value to -1.

Interval Between Reconnect Attempts (milliseconds) — The time interval between two successive retries, in milliseconds. The default value is 30000ms.

Adapter Termination Criteria (after max number of reconnect

attempts) — This field is relevant for Inbound configurations connected to multiple SAP R/3 systems. This field indicates whether the adapter should stop after all attempts to reconnect are exhausted for just one SAP R/3 system or all SAP R/3 systems.

— First Service indicates that the adapter should stop after all retry attempts to connect to just one SAP R/3 system are exhausted.

— Last Service indicates that the adapter should stop only after retry attempts to connect to all SAP R/3 systems are exhausted.

The default setting is First Service.

Max Connections — The number of outbound SAP connections in the server connection. By default, it is set to 1. A maximum of 8 connections is allowed. The Max Connections option is used to configure the maximum number of threads in the adapter instance.

3. Click Apply.

The Stop on Retry Fail setting is applicable only when an Inbound configuration is connected to multiple SAP R/3 systems.


Setting Server Connection Advanced Options | 227

ExampleIn this example advanced options for a server connection are displayed.



Sample saprfc.ini Files

The following sample demonstrates using the saprfc.ini file for:

• Register RFC Server programs

• Connect RFC Client programs to SAP

Refer to the SAP Documentation accompanying your SAP R/3 installation for additional information.

Example: Registering an RFC Server Program ExampleThe following parameters register an RFC server program at an SAP gateway, in SAP using transaction SM59. To reference the block, the destination field in the server connection should be defined as DEST-TIB-R. See Configuring Server Connection with saprfc.ini on page 224 for details.DEST=DEST-TIB-RTYPE=RPROGID=UseAUniqueProgramIDGWHOST=sapsvrGWSERV=sapgw00RFC_TRACE=0

It is important to note that if PROGID is not defined, the value of DEST is used instead.

The RFC server program is registered as follows:

• Program ID is UseAUniqueProgramID

• SAP gateway is sapsvr

Using Logon Groups to Connect an RFC Client to SAP ExampleThe next parameter connects an RFC Client program to SAP using logon groups. In SAP using transaction SMLG, the logon group defined is SPACE

The SAP System ID (SID) is TIB and the message server is sapsvr.

In this example, there is no RFC tracing since RFC_TRACE is defined with a value of 0.

In this example, there is no RFC trace and ABAP debugging since RFC_TRACE and ABAP_DEBUG are defined with a value of 0.


Sample saprfc.ini Files | 229

To reference the parameters given below, the destination field in the client connection should be defined as DEST-TIB-B. See Configuring Client Connection with Load Balancing on page 212 for details.

Note that if R3NAME is not defined, the value of DEST is used instead.DEST=DEST-TIB-BTYPE=BR3NAME=TIBMSHOST=sapsvrGROUP=SPACEABAP_DEBUG=0USE_SAPGUI=0

Using a Dedicated Application Server to Connect an RFC Client Program to SAP R/3

The parameters given below connect an RFC Client program to SAP R/3using a dedicated application server.

The application server is sapsvr and the system number is 00.

Similar to the load balancing example, there is no RFC trace and ABAP debugging.

To reference the parameters given below, the destination field in the client connection should be defined as DEST-TIB-A. See Configuring Dedicated Application Server Client Connection on page 210 for details.

In this example, it is assumed that running on the same machine as the application server is a gateway service. If this is not the case, you need to define the additional parameters GWHOST and GWSERV. These parameters are similar to the ones available under Registered RFC Server programs (see Using Logon Groups to Connect an RFC Client to SAP Example on page 228).DEST=DEST-TIB-ATYPE=AASHOST=sapsvrSYSNR=00RFC_TRACE=0ABAP_DEBUG=0

USE_SAPGUI=0



Configuring User Exits

This feature is used to perform user-defined operations on IDocs before publishing or after subscribing from the TIBCO environment.

Configuring User Exit for Publication ServiceTo associate a User Exit operation to a publication service, the check box in the Advanced tab of the Publication service should be selected and the corresponding operation should also be associated.

If you define an operation and associate it to a particular service, the operation is invoked and its results are used for posting to the TIBCO environment.

The defined operation is invoked by the adapter after receiving the IDoc message from SAP R/3 and converting it into a format corresponding to the configured publication mode.

If the User Exit operation is configured for request-response, the reply from the User Exit is published. In case of Oneway operations, the adapter just invokes the remote operation and does not publish data in the TIBCO environment.

1. User Exits — Select the User Exits check box for this publication service.

2. RPCClient — Choose the RPC Client from the reference field for making the invocation. Only RPC Clients are listed. Do not select RPC Clients associated with adapter services.


Configuring User Exits | 231

3. In the Operation Name field, specify the name of the operation.

4. From the Invocation Protocol drop-down list, select the type of invocation, whether oneway or request/reply.

You must enter values in all the fields to create a new operation and to save the user exit information in the project. See TIBCO Adapter for R/3 Example Guide for an example of User Exit.

Configuring a User exit for a Subscription ServiceTo associate a user exit operation to a subscription service, the check box in the Advanced tab of the particular service should be selected and the corresponding operation should also be associated.

If you define an operation and associate it to a particular service, the operation is invoked and its results are used for posting to SAP.

Configuration of user exit on the inbound side is similar to the outbound side. For details, see Configuring User Exits on page 230. The screen shot is given next.



Saving an IDoc to a Directory

An IDoc message gets written to a file under the following circumstances:

• When a Publication service or a Subscription service receives an IDoc whose destination is not there in the list of valid destinations.

• A Subscription service configuration will write an IDoc message to a file, if the SAP R/3 system gives a valid process exception. The exception could be due to invalid data etc., while posting the IDoc. In this case, the data may be manually changed in the file and replayed later using the ReadIDocFromFile plugin. This file can be configured to be written under a required directory.

Configuring IDoc Logging DirectorySteps to configure an IDoc logging directory are given next.

1. Navigate to the Advanced tab of the Publication service as shown in the next screen.

2. In the Write Idoc To Directory field, enter the directory in which these files are to be saved.

Each of the IDocs will be written to a unique file. The name of the file is created according to the following syntax:

Filename = IdocType_DateTimeStamp_IdocCount.idoc

Validation of the directory will not be done during design-time. If this field is not populated, the ASCII text file will be logged in the current working directory of the adapter.


Saving an IDoc to a Directory | 233

For example, MATMAS01_20030825114438762_1.idoc

These ASCII files may be manually replayed, if necessary, using the ReadIDocFromFile plugin. For details on the ReadIDocFromFile, see General Tab on page 125.



Configuring Reporting

This feature enables the adapter to report adapter processing errors, application errors or informational messages about successful posting of messages to the SAP R/3 system for all one way inbound scenario.

This includes:

• Subscription service messages posted in the SAP R/3 system as IDocs

• Oneway Request-Response service messages invoked in the SAP R/3 system as RFCs

• Oneway Request-Response service messages invoked in the SAP R/3 system as tRFCs

Configuring Subscription Services for Reporting 1. Select the Advanced tab of the service.

2. Select the Confirmation Required check box. A Confirm Publisher reference reference field is displayed.

3. Create a publisher endpoint under the Advanced->Sessions-><any session> with required transport, quality of service and subject attributes.


Configuring Reporting | 235

4. Associate this publisher endpoint to the Subscription service by referring to this endpoint in the Confirm Publisher reference field. The screen shot is given next.

Configuring Request-Response Services for Reporting 1. Select the Advanced tab of the service.

2. Select the Confirmation Required check box. A Confirm Publisher reference reference field is displayed.

3. Create a publisher endpoint under the Advanced->Sessions-><any session> with required transport, quality of service and subject attributes.

It is recommended to configure a reporting publisher endpoint under a dedicated session, rather than the same session as the Subscription service.



4. Associate this publisher endpoint to the Request-Response service by referring to this endpoint in the Confirm Publisher reference field. The screen shot is given next.

Even though the confirm publisher reference is displayed for configuration for non oneway protocol Request-Response services, the feature is available at run-time for Request-Response services in oneway protocol only.

It is recommended to configure a reporting publisher endpoint under a dedicated session, rather than the same session as the Subscription service.


Publishing IDocs on Dynamic Subjects | 237

Publishing IDocs on Dynamic Subjects

You can configure the adapter to publish an IDoc on a dynamic subject name and specify the dynamic subject using a special notation. Before the adapter publishes an IDoc, it constructs the subject name by using the contents of the control record of the IDoc.

An IDoc control record contains the following fields, which are listed in alphabetical order in Table 10:

Use these names to specify a dynamic subject name. To use a control record field name within a dynamic subject name, you must surround the control record field name with two $ characters. For example, to use RCVPRN control record field, you must use $RCVPRN$ within a dynamic subject name. Some examples are given below: MYSUBJECT.$MANDT$$RCVPRN$.$DOCNUM$

$TABNAM$.TEST

MARY.$SNDPRN$.IDOC

To configure dynamic subject names do the following:

1. In the Advnaced tab of the Publication service, enter the dynamic subject names in the Message Subject field. The screen shot is given next.

Table 10 IDoc Control Record Fields

ARCKEY CIMTYP CREDAT CRETIM STD

DIRECT DOCNUM DOCREL DOCTYP STDMES

EXPRSS IDocTYP MANDT MESCOD STDVRS

MESFCT MESTYP OUTMOD RCVLAD STD

RCVPFC RCVPOR RCVPRN RCVPRT TEST

RCVSAD REFGRP REFINT REFMES TABNAM

SERIAL SNDLAD SNDPFC SNDPOR

SNDPRN SNDPRT SNDSAD STATUS



2. Click Apply.

The adapter scans the dynamic subject name and replaces the control record field names (such as $SNDPRN$, $DOCNUM$, and so on) with actual values from the control record of the IDoc. The resulting subject name must be a valid TIBCO Rendezvous subject name in case of RV transport and a valid destination name in case of JMS transport.

If you specify a name that does not represent a valid control record field name, the subject name is left intact. For example, if you specify A.$XYZ$ for the dynamic subject name, the adapter leaves the subject name intact because XYZ does not represent a valid control record field name. In short, the adapter publishes under the subject A.$XYZ$. Some of the control record fields (of the IDoc) may be empty.


Replacing Control Fields | 239

Replacing Control Fields

Replacing control fields is a feature available for the IDoc Publication service. Using this feature you can replace the field value for the control record. For example you can override the receiving partner value coming from SAP with your inputs.

Configuring control fields replacement:

1. The Advanced tab of the Publication service is shown below.



2. Click the Control Fields button to invoke the following screen.

3. In the Name field, enter the control field record, which is to be replaced.

4. In the Value field, enter the value to be changed.

5. Click Set to add the name value pair.

6. To remove an entry from the list, choose the entry and then click Delete.

7. Click Save to apply the changes.

As entries get added to the list, the name is automatically converted to uppercase. This is done to ensure consistency with the syntax of SAP R/3 system.

The name value pairs you have entered are added to the project only when you click Save.


Configuring Multiple Connections for Inbound Instance | 241

Configuring Multiple Connections for Inbound Instance

For an inbound instance the connections are specified at the service level. This means, you can have different connections for different services. When the adapter instance is configured all the services have a default connection. You can add new connections to the adapter and then for each service specify one of the newly added connections.

Carry out the following steps to add a new connection.

1. Configure an inbound adapter instance.

This will create default connection for all the services. Expand the R3Connections>ClientConnections folder to view this connection. The name of the connection will contain the adapter instance name. Similarly there will be a reference created for this connection in the ActiveConnections folder of that particular adapter instance. This is the default connection and if needed the parameters of this connection can be modified.

2. Click on the R3Connections>ClientConnections folder. Drag and drop the ClientConnection icon from the palette panel to the design panel.



3. Select the Client connection type and click Apply. Enter all the parameters for the second connection in the Inbound Connection tab. You can specify advanced connection parameters in the Advanced tab. Click Apply.

4. Click on the Active Connection folder for the adapter instance. Drag and drop a ConnectionReference icon from the palette panel to the design panel.



5. Enter an appropriate name in the Name field. Click the Browse Resource icon to display the Select a Resource window.



6. Select the newly created Client Connection resource. Click OK to attach the client connection you created to this reference resource.

7. Click on the Advanced tab of the service for which this connection was created. In the Client Connection Reference field, click the Browse Resource icon to display the Select a Resource window.



8. Select the client connection for this service and click Apply to save the adapter instance.

9. Save the adapter configuration and start the adapter. The adapter dispatches the calls to SAP R/3 on the connections configured for each service.



Configuring Multiple Connections for Outbound Instance

Server connections are specified at the instance level. The configured services can use all the connections created for the instance.

Carry out the following steps to add a new server connection to the adapter.

1. Configure an outbound adapter.

This will have a default connection. Expand the R3Connections>ServerConnections folder to view this connection. The name of the connection will contain the adapter instance name. Similarly there will be a reference created for this connection in the ActiveConnections folder of that particular adapter instance. This is the default connection and if needed the parameters of this connection can be modified.

2. Click on the R3Connections>ServerConnections folder. Drag and drop the ServerConnection icon from the palette panel to the design panel.


Configuring Multiple Connections for Outbound Instance | 247

3. Select the Server connection type and click Apply. Enter all the parameters for the second connection in the Outbound Connection tab. Specify advanced connection parameters in the Advanced tab. Click Apply.

4. Click on the Active Connection folder for the adapter instance. Drag and drop a ConnectionReference icon from the palette panel to the design panel.



5. Enter an appropriate name in the Name field. Click the Browse Resource icon to display the Select a Resource window.


Configuring Multiple Connections for Outbound Instance | 249

6. Select the newly created Server Connection resource. Click OK to attach the server connection you created to this reference resource.

7. Save and start the adapter instance. Now whenever you start the adapter it will act as an RfcServer and create connections for all SAP application servers.



TIDManager

The Transaction Identity Manager (TIDManager) is used when tRFCs or IDocs are exchanged with the SAP R/3 system to ensure exactly-once delivery. The TIDManager component ensures that no transactional data is lost or duplicated in case of communication errors between the adapter and the SAP R/3 system.

The TIDManager server configuration is required in one of the following two scenarios:

• Outbound Configurations — Scenario where multiple publication service configurations (for IDocs) or Request-Response Invocation service configurations (for tRFCs) use the same program IDs and running in a load balanced fashion.

• Inbound Configurations — Scenarios where multiple Subscription service configurations (for IDocs) or Request-Response service configurations (for tRFCs) run in a load-balanced fashion.

Outbound configurations sharing the same program ID should reference the same remote TIDManager server configuration.

Interactions between the Adapter and the TIDManager server configurationWhen configured for remote TIDManagement, the adapter invokes the TIDManagement operations on the remote TIDManager server in the TIBCO environment. The adapter and the TIDManager server can interact on TIBCO Rendezvous (default) or JMS transports.

The TIDManager server maintains the status of each Transaction Identifier (TID) associated with a transaction being executed by the adapter. The TID status is maintained in a TID file that is created and maintained on the local file system by the TIDManager server.

Ensure that the TIDManager Client in the Adapter Services tab of each adapter instance has been configured correctly. See Adapter Services Tab on page 123 for details on setting RPC client reference.

The subject specified for the RPC client should match the subject specified for the RPC Server referenced in the options of the TIDManager. See General Tab on page 257.

If more than one TIDManager is maintained for the same Program ID, once-only delivery from SAP cannot be guaranteed.


TIDManager | 251

Recovering from network outages and TIDManager server downtimes When an adapter is configured for remote TIDManagement, it is mandatory for the TIDManager server to be up and running to perform TIDManagement operations. The adapter cannot proceed with a transaction if it is unable to communicate with the TIDManager server. Thus availability of the TIDManager server is critical for remote TIDManagement.

Outbound TIDManagement

In case of remote TIDManagement for outbound configurations, if the TIDManager server is not running or not reachable because of network outages, the adapter throws the following errors upon receiving a transaction from the SAP system:2003 Aug 29 10:07:52:633 GMT +5 SAPAdapter.R3AdapterConfiguration Error [Adapter] AER3-000102 TID operation timed out.

2003 Aug 29 10:07:52:633 GMT +5 SAPAdapter.R3AdapterConfiguration Error [Adapter] AER3-000410 Server thread exited, message : Rpc invocation timeout

The transaction itself is not lost and is maintained in the SAP system’s tRFC queue. The SAP system will periodically try to push out the transactions and clear the queue. If communication to the TIDManager server is restored, normal processing will continue.

Inbound TIDManagement

In case of remote TIDManagement for outbound configurations, if the TIDManager server is not running or not reachable because of network outages, the adapter throws the following errors upon receiving an IDoc from the TIBCO environment:03 Aug 29 10:20:37:192 GMT +5 SAPAdapter.R3AdapterConfiguration1 Error [Adapte] AER3-000102 TID operation timed out.

03 Aug 29 10:20:37:212 GMT +5 SAPAdapter.R3AdapterConfiguration1 Error [Adapter] AER3-000493 Remote TIDManager server unreachable

The AER3-000493 error is also published as a Hawk Notification that can be subscribed to from TIBCO Hawk.

The TID operation timeout condition determined by the configurable parameter TIDManager Client Retry Count in the adapter configuration

The TIDManager Client Retry Count determines the number of times the adapter will try to invoke the TID operation on the TIDManager server before concluding that the TIDManager server is indeed unreachable.



Once the TIDManager server is found to be unreachable, the Subscriber adapter cannot proceed with posting the IDoc. The IDoc should not be confirmed to the sending application in the TIBCO environment as it will result in message losses.

Hence, upon detection of this situation, the adapter suspends all its subscription services, does not confirm received IDocs to the TIBCO environment, and goes into a silent retry mode to try and reconnect to the TIDManagement server. This is achieved by pinging the TIDManager server periodically. The adapter will continue to remain in this suspended state till it establishes communication with the TIDManagement server again.

The configurable parameter TIDManager Client Retry Interval in the adapter configuration determines the time interval in milliseconds between any two ping attempts to the TIDManager server.

For details on stopping a TIDManager see Stopping the TIDManager on page 320.

Use the following tabs to configure the TIDManager instance:

• Configuration Tab on page 253

• Logging Tab on page 130

• Startup Tab on page 133

• Monitoring Tab on page 134

• General Tab on page 257


Setting TIDManager Configuration Options | 253

Setting TIDManager Configuration Options

Use the following steps to configure a TIDManager instance:

1. Drag an R3TIDManagerConfiguration icon from the palette panel to the design panel.


ConfigurationTab

Instance Name — Assign a unique name to the TIDManager instance. By default the name is R3TIDManagerConfiguration. You can change it to a name of your choice.

Show All Tabs — Select this check box to access the General tab. See Setting TIDManager Monitoring Options on page 256 for details on setting monitoring options.

3. Click Apply.

It is recommended that you use the Program ID defined in SAP as part of the TIDManager name.



Setting TIDManager Logging Options

You can configure logging preferences and information in the Logging tab. You can configure the level(s) of trace messages to be logged, and then specify the destination for the trace messages. You have the option of using advanced logging options or standard logging options.

Use the following steps to set up TIDManager logging options.

1. Drag the R3TIDManager Configuration icon from the palette panel to the design panel.

2. Click Logging. The Logging tab is displayed.

TIDManager logging options are identical to those of an adapter instance. For instructions on setting logging options see Logging Tab on page 130.


Setting TIDManager Startup Options | 255

Setting TIDManager Startup Options

TIDManager Startup options are similar to the adapter instance level startup options. The only difference is that the DefaultSession field in the Startup tab of the TIDManager does not have a configured default session. See Startup Tab on page 133 for details.



Setting TIDManager Monitoring Options

Configure TIBCO Hawk information for the TIDManager using the monitoring options. You can use microagents to supplement the monitoring information provided by the standard logging levels capability.

Use the following steps to configure TIDManager monitoring options:

1. Drag the R3TIDManagerConfiguration icon from the palette panel to the design panel.

2. In the Configuration tab, select the Show All Tabs check box and click Monitoring, the Monitoring tab is displayed.

TIDManager monitoring options are similar to those set for an adapter instance. For instructions on setting monitoring options see Monitoring Tab on page 134

See the TIBCO Designer Adapter Resource Management Guide for information on Monitoring, Hawk Agents and Microagents. You can access it using the Help menu. Click Help>Help For>Adapter Resource.

The fields R/3 Adapter Microagent Name and R/3 Adapter Microagent Type, described in the referenced section, are not applicable for TIDManager monitoring.


Setting TIDManager General Options | 257

Setting TIDManager General Options

Configure the RPC Server endpoint to be used by the TIDManager. Ensure that the subject assigned to the RPC server matches the subject name of the RPC client. This RPC client is referred to in the TID Manager Client field in the Adapter Services tab of the adapter instances using this TIDManager instance.

Use the following steps to configure TIDManager options.

1. Drag the R3TIDManagerConfiguration icon from the palette panel to the design panel.

2. Select the Show All Tabs check box in the Configuration tab to display the General tab.

3. Specify the following options in the General tab:

General Tab TIDManager Server — Specify the TIDManager server reference. Click Browse to locate the appropriate server endpoint.OrClick Go To, the RPC Server Session Configuration tab is displayed, allowing you to configure the RPC server. By default, an endpoint named TID_RPC_SERVER is provided for a TIDManager instance for messaging on TIBCO Rendezvous. For details on configuring a TIDManager server for JMS messaging, see Configuring a TIDManager server on JMS on page 259.

By default, the subject name for the TIDManager Server Session is SAP.TIDMANAGER. You can change the subject as appropriate. The subject must be unique for each TIDManager.

See the TIBCO Designer Adapter Resource Management Guide for information about configuring endpoints. You can access it using the Help menu. To access it click Help>Help For>Adapter Resource.

TID Filename — Assign a unique TID filename. The TID file is used by the TIDManager to maintain state information on the transaction IDs (TID) sent from SAP. By default, the name of the TID file is tidFile.tid.

The subject name should match subject names being used by TIDManager Client references in all adapter instances using this TIDManager.

It is recommended that you use the name of the TIDManager instance as part of the filename.



4. Click Apply.

ExampleThis example shows the run time options set for the default TIDManager instance.

The subject specified for the TIDManager Server and the TID filename must be unique for each TIDManager instance.

You must change the name of the log file, adapter.log, if you intend to run multiple R/3 TIDManagers.


Setting TIDManager General Options | 259

Configuring a TIDManager server on JMS1. In the project panel, select the Advanced>Sessions folder for the TIDManager

Server configuration.

2. Create a JMS Session at the level of the default TIDManagerSession.

3. Create a JMS RPC Server under this new session and associate the TIDManager server to this RPC Server.

Example



Load Balancing Using Distributed Queue

Load balancing, as the name indicates, is a concept that allows message loads to be balanced or shared by multiple adapter instances. Load balancing ensures no single instance is over-loaded, and minimizes stress-failures.

It also allows fault-tolerance by avoiding a single point of failure. The adapter can run in load-balanced configurations both on the Inbound side as well as the Outbound.

Steps for Configuring Inbound Load-Balanced InstancesThis section outlines the steps necessary to configure inbound load-balanced instances containing subscription services and request-response services. During the configuration of the services, the Quality of Service must be configured as Distributed Queue as shown in the following screen:

This section outlines the steps used to configure inbound load-balanced instances containing Subscription services (Inbound IDocs) and/or Request-Response services (Inbound RFC/BAPI.)

During the configuration of the adapter services, the Quality of Service must be configured as type Distributed Queue.

Configuration of inbound load-balanced instances can be done either by:

1. Creating multiple inbound instances where the CMQ names are the same across the instances.


Load Balancing Using Distributed Queue | 261

Or

2. Creating one inbound instance that can be invoked multiple times.

RVCMQ Session Attributes

The behavior of RVCMQ is complex and attributes for RVCMQ sessions must be set with care. This section lists relevant sections from the TIBCO Rendezvous Concepts manual. For more detailed information, see the manual itself. Also see TIBCO Designer SDK Resource Guide for details on configuring an RVCM Session. You can access TIBCO Designer documentation using the Help menu. Click Help>Help for>Adapter Resources

— Understanding Rank and Weight

— Weight Values

— Assigning Weight

— Rank among members with different weight

— Rank among members with equal weight

— Status quo among members with equal weight

— Adjusting Weight

— Understanding and setting heartbeats

It is recommended that you have a good grasp of the concepts listed below and discussed in TIBCO Rendezvous Concepts manual before you finalize the configuration of any inbound instance running in RVCMQ mode.

Before changing the Quality of Service, please make sure that no network sinks have a Session Reference, referring to the Default Sessions (DefaultRVSession, DefaultRVCMSession, DefaultRVCMQSession) created by the palette. To avoid this, have a Custom Session associated with the Network Sink.

To avoid message loss after activation of a suspended RVCMQ service, assign CompleteTime to a value greater than Zero.When the completeTime is assigned Zero the scheduler does not set a timer and does not reassign tasks when the task completion confirmation is not received. So after activation of a suspended service the scheduler does not reassign the task to the worker member. For more information on RVCMQ parameters, refer to TIBCO Rendezvous documentation.



Multiple Inbound ConfigurationsUse the following steps to configure an inbound instance as part of a group of load balanced instances:

1. Assign one of the instances as the master or root. Make a note of the RVCMQ session name in this instance. Obtain the RVCMQ session using these steps:

a. Click the Advanced tab of one of the services.

b. Click Go To corresponding to the endpoint reference. The Configuration tab for the endpoint is displayed.

c. As the view changes from the service’s Advanced tab to the endpoint’s Configuration tab, the focus in the project panel also shifts to the endpoint. Then find the session linked to the endpoint selected, as shown in the following figure.

In the example shown, the endpoint named EndpointForSubscriptionService is linked to the RVCMQ session named R3AdapterConfigurationRVCMQSession. This name should be saved for subsequent steps.

2. For other instances that have not been assigned as the master or root, the CMQ name property of the RVCMQ sessions used by those instances must be changed to reflect the name in step 1. Change the CMQ Name property, using the following steps:



a. Identify the RVCMQ sessions used by the instances. Refer to Step 1. on page 262 of the first point.

b. For each instance, change the CMQ Name property of the session as shown in the following example:

In the example shown, if the RVCMQ session of the master or root were R3AdapterConfiguration2RVCMQSession, then the CMQ Name for the session would be R3AdapterConfigurationRVCMQSession.

Single Inbound ConfigurationConfigure an inbound instance with RVCMQ quality of service and invoke it multiple times.

Use client variables to specify different log file names for each invocation of the instance. If this is not done, then all trace messages are written to the same file.



For each file sink available in the Log Sinks folder, make sure to include %%LOG_FILENAME%% as the filename. It is assumed that a value is passed along with the tra file.

For information on client variables refer to your TIBCO Repository Documentation.

File sinks are located in the project in the following path:

Instance>Advanced>Log Sinks

In this example, the filename for the sink fileSink has been updated to reflect %%LOG_FILENAME%%.

The client variable LOG_FILENAME is used to illustrate how to configure filenames at run-time. As long as the client variable is unique, you can use any name.



Steps for Configuring Outbound Load-balanced InstancesThis section outlines the steps necessary to configure Outbound Load-balanced instances containing Publication services (Outbound IDocs) and/or Request-Response Invocation services (Outbound RFC/BAPI). The steps outlined in this section are applicable for any adapter instance configured with the R/3 Connection type Outbound or Both.

Outbound Load-balanced instance can be configured either by

1. Creating multiple outbound instances using the same Program ID for the Server Connections.

Or

2. Creating one outbound instance that can be invoked multiple times.

The subsequent section focuses on the second option where one outbound instance is created using client variable substitution as the means for providing unique names for both the RVCM session name and File Sink filename during each invocation of the adapter instance.

Single Outbound Instance

To invoke the same adapter instance multiple times, use the steps outlined below when configuring the instance using TIBCO Designer.

1. For each RVCM with a client variable, for example, session in the Sessions folder, replace the value of the CM Name with %%PASSED_CM_NAME%%. The Ledger File and log file values should also be changed to reflect the usage of the same client variable. It is assumed that a value would be passed along with the tra file.

When creating multiple instances, make sure that the TIDManager Client references the same remote TIDManager instance.

The client variable PASSED_CM_NAME is used to illustrate how to configure CM names and ledger file names at run-time. As long as the client variable is unique, you can use any name.



2. For each file sink available in the Log Sinks folder, include %%LOG_FILENAME%% as the filename. It is assumed that a value would be passed along with the tra file.

The client variable LOG_FILENAME is used to illustrate how to configure filenames at run-time. As long as the client variable is unique, you can use any name.



For information on client variables refer to your TIBCO Repository Documentation.

In the example screen, file sinks are located in the project in the following path:

Instance name>Advanced>Log Sinks

In this example, the filename for the sink fileSink has been updated to reflect %%LOG_FILENAME%%.



BDC Implementation

SAP R/3 provides many interfaces for transferring external data to SAP R/3. RFCs, BAPIs and IDocs are the most commonly used interfaces. BDC, which is one of the data transfer mechanisms provided by SAP, can be used for data integration in the absence of standard BAPIs, RFCs or IDOCs. One of the advantages of BDC is when data is posted in SAP using BDC transaction all the validations required for that transaction are performed on the data.

Sometimes, it is much easier, cleaner and faster to write a custom RFC for a custom screen that fills a custom table in SAP.

Using BDCs you can create transactions in SAP by going through the SAP dialog screens of a particular transaction. For instance, you can create a purchase order through BDCs by going through the different screens of the Purchase Order Creation transaction. (ME21).

The following methods can be used to implement BDCs:

• BDC implementation through standard RFC (ABAP4_CALL_TRANSACTION). See BDC Implementation through Standard RFC (ABAP4_CALL_TRANSACTION) on page 268 for details.

• BDC implementation through custom RFCs. In this case you will have a custom RFC for every transaction in SAP. See BDC Implementation through Custom RFCs on page 271 for details.

BDC Implementation through Standard RFC (ABAP4_CALL_TRANSACTION)SAP provides a standard RFC that can be used for implementing BDCs. It supports both SAP standard transactions like ME21 as well as customer specific custom transactions like ZE21. The RFC configuration needed in the adapter is just like any other RFC configuration in TIBCO Designer. TIBCO BusinessWorks or TIBCO IntegrationManager can call the RFC in both request-response mode as well as transactional one-way invocation mode depending upon the need.

To get the PO number after it is created, you should use the request-response mode. To post the PO and not receive a reply you should use the transactional mode. You will not be able to get exceptions back from the SAP system if you use the transactional mode. To receive the errors immediately, use the request-response mode.

The RFC used to implement BDC is called ABAP4_CALL_TRANSACTION. It accepts a fixed number of parameters and the transaction code as inputs and carries out the transaction in SAP. The key inputs for executing this RFC are:


BDC Implementation | 269

Table 11 Input Parameters used in the RFC to implement BDC

TCODE Transaction code that needs to be called from the adapter.

SKIP_SCREEN This field has to be always “X” because we are executing this transaction from outside SAP. It can be left blank to see the screens when we are executing the BDC within the SAP system.

MODE_VAL There are three modes. Always use “N” since we are executing the call from outside SAP.

A Display all screens

E Display errors

N Background processing

UPDATE_VAL There are three modes of updates.

L Local

S Synchronous

A Asynchronous

UPDATE parameter specifies how updates produced by a transaction should be processed. You can select between these modes:

UPDATE_VAL = A

Asynchronous updating. In this mode, the called transaction does not wait for any updates it produces to be completed. It simply passes the updates to the SAP update service. Asynchronous processing therefore usually results in faster execution of your data transfer program. Asynchronous processing is NOT recommended for processing any larger amount of data. This is because the called transaction receives no completion message from the update module in asynchronous updating. The calling data transfer program, in turn, cannot determine whether a called transaction ended with a successful update of the database or not. If you use asynchronous updating, then you will need to use the update management facility (Transaction SM12) to check whether updates have been terminated abnormally during session processing. Error analysis and recovery is less convenient than with synchronous updating.

UPDATE_VAL = S

Synchronous updating. In this mode, the called transaction waits for any updates that it produces to be completed. Execution is slower than with asynchronous updating because called transactions wait for updating to be completed. However, the called transaction is able to return any update error message that occurs to your program. It is much easier for you to analyze and recover from errors.

This is the preferred method in our case since we are executing the transaction from outside and this allows good error handling also.

L Local updating. If you update data locally, the update of the database will not be processed in a separate process, but in the process of the calling program. (See the ABAP keyword documentation on SET UPDATE TASK LOCAL for more information.)



The BDC data is the key structure through which the data is passed to complete the SAP transaction. So if you to pass through SAP screens 100 and 200 and fill fields’ f1 to f7. The USING_TAB would look like

SAPSCREEN 100

X F1 10000

F2 20000

F3 30000

F4 4000

F5 59

SAPSCREEN 200

X F6 6000000

F7 70000000

Output Parameters:

MESS_TAB gives the output of the BDC. Usually the last line of this sequence would give the PO Number details.

Configuration Steps for BDC Implementation using Standard RFC


2. Download the ABAP4_CALL_TRANSACTION RFC (either one-way or request response depending upon the implementation need)

3. Design a TIBCO BusinessWorks or TIBCO IntegrationManager process that can accept the standard set of BDC inputs. The input data that is set determines which SAP Transaction should be executed. So irrespective of the number of SAP transactions you need to execute there is only one process that is needed for the BDC itself.

4. If there is a need for having multiple BDC services, then consider having the same services in multiple adapter instances.

USING_TAB (BDCDATA)

PROGRAM BDC module pool

DYNPRO BDC Screen number

DYNBEGIN BDC screen start

FNAM Field name

FVAL BDC field value


BDC Implementation | 271

BDC Implementation through Custom RFCsOnce a BDC data is recorded using the SHDB transaction in SAP, you can create a specific custom RFC for that particular data set and the transaction itself. TIBCO BusinessWorks or TIBCO IntegrationManager can then use this program to create the transaction in SAP.

Configuration Steps for BDC Implementation using Custom RFCs


2. Download the custom RFC created for the specific BDC recording.

Example: Z_BDC_CREATE_PO (either one-way or request-response depending upon the implementation need)

3. Design a TIBCO BusinessWorks or TIBCO IntegrationManager process that can accept the set of BDC inputs. The input data set in this case can only be specific to creating the PO in SAP. So each one of the SAP transactions has its own process for executing the BDC.

4. If there is a need for having multiple BDC services, then consider having the same services in multiple adapter instances.

The most important step in designing the BDC is the collection of the BDC input data and the order in which the SAP screens should be traversed. Sometimes, the number of fields and the screens involved could be very simple and straight-forward (example: custom screens in SAP). But in case of standard SAP transactions, the number of fields and screens are quite complex and the flow of screens could be varied. (For instance, you can create a PO by filling ten fields and two screens, you can also fill hundred fields across ten screens in different order).

The order to traverse the screens should be fixed. Once the same transaction is run in SAP by following the same order of screens and filling the same fields, you can start recording the process. At the end of the recording, SAP system gives a file that can be downloaded; this is the sample data with which data mapping should be done. Every field name and field value in the data file, should be understood and mapped. It is recommended that you run the BDC for testing purposes before getting into the complexities of the mapping process.



Using Global Variables

The variable substitution mechanism can override global variables predefined in the project in a restricted manner. Predefined variables can be viewed and set in TIBCO Designer. Variables are specified as %%VARNAME%% and cannot contain any white space.

Variable substitution allows you to accomplish the following.

• Substitute string variables specified in the project at startup time.

• Locally define the value for a variable for a specific project. The local value takes precedence over any global value.

• Specify the value for a variable in a properties file. This overrides the project repository and values set in code, but not variables set on the command line.

• Enforce the pre-defined variables listed in Predefined Global Variables on page 273.

Variables can be used anywhere in the configuration and will be replaced by the locally-defined adapter instance.

Variable SpecificationThe adapter can specify variables:

• In the project during configuration using TIBCO Designer

• In a properties file

Properties file values overwrite values set in the project.

Specifying Variables Using TIBCO Designer

Global variables provide an easy way to set defaults for use throughout your project.

For example, you could assign the value 7474 to the predefined global variable RvDaemon. You can then use the variable in different sessions in your adapter. If you wish to change the TIBCO Rendezvous daemon for your adapter, you can globally set it to a different value or override it from the command line.

To use global variables in your project, follow these steps:

1. In the project panel, select the Global Variables tab.


Using Global Variables | 273

The project panel is updated to display all currently defined global variables. You now have these choices:

— To assign or change a variable value, select that region and triple-click the variable. The variable expands so you can change either the variable name or the variable value. Press Enter when you’re done.

— To add a new global variable group, click the leftmost icon. Specify the name of the group, then press Enter. With the group icon selected, you can click the abc icon to add variables to the group.

— To add a global variable, click the abc icon. A new global variable item is added to the bottom of the list. Supply the variable name and, optionally, the value. Press Enter when you’re done.

The global variable is now displayed in the global variables list.

2. When you want to use the global variable in the fields of a resource, enter the variable name surrounded by %% on both sides.

When the project is deployed and the configured components are run, all occurrences of the global variable name are replaced with the global variable value (unless it was overridden in a way that had higher precedence). For example, RvServiceTest would be replaced with 7800.

A number of global variables are predefined. See Predefined Global Variables on page 273 for information. You may add definitions of any variables you need to the predefined variables.

Predefined Global VariablesThe next table lists and explains the predefined global variables. Some global variables are automatically used within the system when an adapter instance is configured.

Table 12 Predefined Global Variables

Variable Description

Deployment Defaults to the TIBCO Designer project name. This value can be any string value. This global variable is used by the system to partially define the subject name defined for a service.

DirLedger Specifies the path name of the TIBCO Rendezvous certified messaging ledger file. The default is the root installation directory.



DirTrace Specifies the path name for log file used by the adapter. The default is the root installation directory.

Domain The default value for file-based local projects is MyDomain. The value for server-based projects is the domain to which the project was saved.

HawkEnabled Indicates whether TIBCO Hawk is used to monitor the adapter. True indicates that a Hawk microagent is defined for the adapter. False indicates the microagent is not to be used.

JmsProviderUrl Tells applications where the JMS daemon is located. Setting this value mostly makes sense in early stages of a project, when only one JMS daemon is used.

JmsSslProviderUrl

Tells applications where the JMS SSL daemon is located.

RemoteRvDaemon TIBCO Rendezvous routing daemon (rvrd) to be used. See TIBCO Administrator Server Configuration Guide for details about setting up a domain using rvrd.

RvDaemon TIBCO Rendezvous daemon. Sessions use this daemon to establish communication. The default value is 7500.

RvNetwork TIBCO Rendezvous network. This variable need only be set on computers with more than one network interface. If specified, the TIBCO Rendezvous daemon uses that network for all outbound messages.

In most cases, you can leave the default.

RvService TIBCO Rendezvous service. The Rendezvous daemon divides the network into logical partitions. Each transport communicates on a single service. A transport can communicate only on the same service with other transports.

Unless you are using a non-default TIBCO Rendezvous configuration, you should leave the default (7500).




Using Global Variables | 275

RvaHost Computer on which the TIBCO Rendezvous agent runs. This variable is only relevant if you are using the TIBCO Rendezvous Agent (rva) instead of the TIBCO Rendezvous daemon, and if you have configured a non-default setup. See TIBCO Rendezvous Administration for details about specifying the rva parameters.

RvaPort TCP port where the TIBCO Rendezvous agent (rva) listens for client connection requests. See TIBCO Rendezvous Administration for details about specifying the rva parameters. Defaults to 7501.

TIBHawkDaemon TIBCO Rendezvous daemon used in the TIBCO Hawk session. See the TIBCO Hawk Installation and Configuration manual for details about this parameter.

TIBHawkNetwork TIBCO Rendezvous network used by the TIBCO Hawk session. See the TIBCO Hawk Installation and Configuration manual for details about this parameter.

TIBHawkService TIBCO Rendezvous service used by the TIBCO Hawk session. See the TIBCO Hawk Installation and Configuration manual for details about this parameter.

AppServer The network name of the SAP R/3 application server host machine.

Client SAP R/3 client number.

CodePage SAP R/3 application server code page. Set this to view IDoc/RFC /BAPI schema descriptions in non LATIN-1 character sets in TIBCO Designer.

GatewayHost The gatewayHost name or IP address or router string. If there is no specified machine acting as a gateway host, this is the same as the Appserver.

GatewayService The SAP R/3 gateway service. The default value is sapgw00.

Password Valid password corresponding to the user name.





ProgramID Valid existing program ID that identifies the RFC Server program for the SAP R/3 system.

SystemNumber SAP R/3 database instance number.

UserName Valid user name to log into the SAP R/3 client specified.




| 277

Chapter 7 Program Internationalization

This chapter describes Unicode and how to apply it using TIBCO Adapter for R/3.

Topics

• SAP Language Support, page 278

• TIBCO Adapter for R/3 Language Support, page 279

• Getting Ready to Run Unicode on Windows, page 280

• Getting Ready to Run Unicode on UNIX Platforms, page 282


278 | Chapter 7 Program Internationalization

SAP Language Support

Single and Multibyte Codepages

SAP provides multi-lingual support through simple single-byte codepage (ISO8859-1,ISO8859-2) and multi-byte codepage (like ShiftJIS, Big5 etc.) installations.

Simple codepage installations of SAP R/3 cannot support characters outside of the codepage with which the system is installed.

Blended Code Pages

In order to support more languages from unrelated code pages, SAP introduced the notion of blended code pages. A SAP blended code page comprises characters from the intersection of two or more code pages and from a disjoint set of these code pages. Creating a code page in such a way allows users to use some characters from any of the code pages.


TIBCO Adapter for R/3 Language Support | 279

TIBCO Adapter for R/3 Language Support

The adapter provides multi-lingual support for simple single-byte and multi-byte installations of SAP R/3.

The underlying mechanisms for language support on Windows and UNIX platforms are different and discussed next

Language Support on Windows

Support for ISO8859-1 codepages is straight-forward and is provided by default.

To support ISO8859-2, multibyte and SAP R/3 blended-codepages, the adapter makes use of native platform C function calls. These calls are used to convert between SAP multibyte characters and Unicode characters transmitted in the TIBCO environment.

Multi-lingual support on Windows platforms requires the relevant codepages to be installed on the system where the adapter is deployed.

Language Support on Unix platforms

Support for ISO8859-1 codepages is straight-forward and is provided by default.

To support single-byte ISO8859-2 and multibyte codepages, the adapter makes use of the support provided by the underlying TIBCO Adapter SDK conversion routines. These routines convert between SAP multibyte characters and Unicode characters transmitted in the TIBCO environment.

Blended Code Page installations are not supported on UNIX platforms.



Getting Ready to Run Unicode on Windows

Complete the following steps prior to running the adapter so that it can handle messages in different encodings.

1. Configure inter-communication encoding

The wire format encoding used for communication between adapters and TIBCO applications is determined by the encoding property set in the project. The adapter configuration can be saved in a local or repository server-based project.

— If the adapter configuration is saved in a TIBCO Administrator based project, inter-communication encoding is determined by repo.encoding property in the tibcoadmin.tra file. Every adapter configuration that uses the repository server for storing and retrieving configuration data from a project uses this encoding setting when communicating. This assures that all TIBCO components that use the same repository also use the same encoding value to communicate. The repo.encoding property value can be ISO8859-1 (the default) or UTF-8. If English or other ISO8859-1 language data is transmitted between adapters, ISO8859-1 should be used, otherwise UTF-8 must be used.

— If an adapter configuration is saved in a local project, the inter-communication encoding is determined by the encoding property of the local project file. To communicate with other TIBCO components using the same encoding, the local project file encoding property setting for all TIBCO components must be identical. Use the Repository Finder in TIBCO Designer to set the encoding property for a local project. The default encoding is ISO8859-1.

When a local project is later promoted to a repository server-based project, the encoding property set in the project file is superseded by the server's encoding property.

The encoding property discussed above is the encoding used by the communication between adapters and applications, not the encoding used for the persistent storage of the project files. Project files are always saved using UTF-8.

2. Ensure availability of required locales on the system.

The adapter uses the system conversion routines to handle Multibyte-to-Unicode (Outbound) and Unicode-to-Multibyte (Inbound) conversions. The necessary codepages for effecting these conversions have to be installed on the system where the adapter runs.


Getting Ready to Run Unicode on Windows | 281

Make sure that the appropriate locales exist and are valid on your operating system. To verify, do the following.

Microsoft Windows (NT,2000 and XP): Verify registry entries under\\HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\Nls\Codepage

All string values associated to this registry pertain to code pages valid on your system.

3. Configure the adapter for the appropriate locale. To specify the locale for the adapter configuration, navigate to the General tab, and enter the locale in the textbox provided. For details, see General Tab on page 125.

In the figure below, the adapter is configured for processing Shift-JIS character data.

The setting maybe overridden from the adapter properties file by setting the adr3.locale parameter.

Example: adr3.locale=Polish_Poland.1250

The locale string is of the form "Language_Country.<NLS CodePage number>"

In order for the above to be set correctly, an Input Locale for Japanese must exist on the operating system and the code page file c_932.nls must exist under the \winnt\system32 directory.

To view the possible set of input locales, refer to the Regional Setting Properties available from the Control Panel.

See Encoding/Locale Table on page 283 for a list of input locale values.

4. If you are using a SAP blended code page:

a. Create appropriate locales on your SAP R/3 application server by using the locale character map, locale source, and methods file provided by SAP.

b. Copy shared libraries for conversion of data encodings to the same directory as the adapter.

c. Set the adapter’s OS environment SAP_CODE_PAGE variable to the appropriate code page.

If you pass a code page value that is not supported by the operating system, an error will be raised and the adapter immediately exits.



Getting Ready to Run Unicode on UNIX Platforms

Complete the following steps prior to running the adapter so it can handle messages in different encodings.

1. Configure inter-communication encoding

The wire format encoding used for communication between adapters and TIBCO applications is determined by the encoding property set in the project. The adapter configuration can be saved in a local or repository server-based project.

— If the adapter configuration is saved in a TIBCO Administrator based project, inter-communication encoding is determined by repo.encoding property in the tibcoadmin.tra file. Every TIBCO Adapter for R/3 configuration that uses the repository server for storing and retrieving configuration data from a project uses this encoding setting when communicating. This assures that all TIBCO components that use the same repository also use the same encoding value to communicate. The repo.encoding property value can be ISO8859-1 (the default) or UTF-8. If English or other ISO8859-1 language data is transmitted between adapters, ISO8859-1 should be used. Otherwise use UTF-8.

— If an adapter configuration is saved in a local project, the inter-communication encoding is determined by the encoding property of the local project file. To communicate with other TIBCO components using the same encoding, the local project file encoding property setting for all TIBCO components must be identical. Use the Repository Finder in TIBCO Designer to set the encoding property for a local project. The default encoding is ISO8859-1.

When a local project is later promoted to a repository server-based project, the encoding property set in the project file is superseded by the server's encoding property. The encoding property discussed above is the encoding used by the communication between adapters and applications, not the encoding used for the persistent storage of the project files. Project files are always saved using UTF-8.

2. Select the appropriate locale encoding

On Unix platforms, the adapter uses the underlying TIBCO Adapter SDK conversion routines to handle Multibyte-to-Unicode (Outbound) and Unicode-to-Multibyte (Inbound) conversions. The necessary code point values are available in the tibicudata.dat file available in <TRA-install dir.>/bin.


Getting Ready to Run Unicode on UNIX Platforms | 283

Refer to the TIBCO Adapter Concepts book for details of the encoding to be set in the adapter.

3. Specify the encoding for the adapter configuration

Configure the adapter for the appropriate encoding. To specify the encoding for the adapter configuration, navigate to the General tab, and choose an encoding from the dropdown. See General Tab on page 125 for details.

In the figure below, the adapter is configured for processing Shift-JIS character data, Shift-JIS(932).

The setting maybe overridden from the adapter properties file by setting the adr3.encoding parameter. Example: adr3.locale=ibm-943. Refer to Encoding/Locale Table on page 283 for possible values.

The adapter does not perform any validation for the encoding value upon startup. Appropriate errors are thrown at run-time incase of conversion errors.

Table 13 Encoding/Locale Table

Character data-types in SAP R/3 IDoc/RFC/BAPI schema are single-byte representations.

A field, say KUNNR in RFC_CUSTOMER_GET, of type char.10 means that the KUNNR field can hold 10 bytes of data.

International characters belonging to multi-byte character sets can be accommodated only to the extent of the total number of bytes as specified in the schema description.

As an illustration, consider the field KUNNR in RFC_CUSTOMER_GET. The field can hold 10 characters of English data (single-byte), but can hold only 5 characters of a double-byte character set. When more than 5 double-byte characters are set to the KUNNR field, the field is not guaranteed to be processed completely.

Encoding/Locale On UNIX On Windows

ASCII ascii Not required to set this. System default.



ISO8859-1 LATIN_1 Not required to set this. System default.

ISO8859-2 ibm-912 <language_territory.codepage>

Example: Polish_Poland.1250





UTF-8 UTF8 Not Applicable.

Shift_JIS (CP943) ibm-943 Japanese_Japan.932

Shift_JIS (TIBCO) tibx-943 Not Applicable.

Shift_JIS (932) tibx-932 Not Applicable.

KSC_5601 ibm-949 Korean_Korea.40949

Big5 ibm-1370 Chinese_Taiwan.950

GBK ibm-1386 Chinese_China.40936

Encoding/Locale On UNIX On Windows


How the Adapter Handles Unicode | 285

How the Adapter Handles Unicode

In Unicode mode the adapter performs conversion for text data to and from SAP MBCS strings and Unicode Wide character strings. The conversion is straightforward when target or source SAP R/3 system code pages are single byte; for example ISO-LATIN-1. Under this configuration, nothing more is required at the SAP R/3 application server side.

Handling Multi-byte Code PagesWhen the source or target SAP R/3 application server code pages are multi-byte; for example SHIFT-JIS, conversion from MBCS to Unicode and back needs alternate interfaces.

Figure 11 shows how the adapter handles conversion between Multi-byte strings and Unicode strings.

The conversion libraries depicted in the figure are the TIBCO Adapter SDK libraries on UNIX platforms and native Operating System libraries on Windows platforms.

Figure 11 Adapter Conversion between MBCS and Unicode Strings

SAP R/3 System

BAPI IDOC

sRFCtRFC

Single Code Pageor Blended Code

Page

SAP R/3 System

BAPI IDOC

sRFCtRFC

UNICODE R/3Adapter

Adapter SDK

UNICODE R/3Adapter

Adapter SDKUTF16BE

UTF16BE

Conversion

Libraries

DoubleByte

Strings

MultiByte

Strings

Single Code Pageor Blended Code

Page

TIBCO Environment

UTF 8 UTF 8



Outbound Call Process

On the Outbound side, an RFC/IDoc call is made by the R/3 System in an external adapter server. The text data is maintained in the SAP R/3 system as multi-byte characters.

1. The SAP R/3 System makes an outbound RFC call on the outbound adapter. The following SAP/ABAP types are sent as character data: TYPC, DATS, TIME, NUMC.

2. After obtaining text data, the adapter converts the multi-byte string into a wide character string (Unicode 2.0).

On Windows platforms, the adapter uses the standard C library function mbstowcs() for conversion. This conversion is dependent on the operating system and the locale passed to the adapter. If the SAP R/3 system code page is one of the blended types, the mbstowcs() function uses the functions defined in the conversion shared libraries for handling multi-byte characters. The standard C library conversion functions are defined with entry points that allow them to use custom defined functions in the conversion libraries.

On UNIX platforms, the TIBCO Adapter SDK routines perform the necessary conversions based on the adapter encoding value configured for the adapter.

3. The TIBCO Adapter SDK libraries then serialize the message in UTF-8 encoding before passing it to the TIBCO environment.

Inbound Call Process

On the Inbound side, the adapter client makes an RFC call in the SAP R/3 system. The text data is maintained in the SAP R/3 System as multi-byte characters.1. On the receiving side, the adapter gets the data from the TIBCO environment

as a wide character string (Unicode UTF-16BE).

2. The adapter converts the Unicode wide character strings into SAP multibyte characters which is then sent to SAP R/3 in an RFC call.

On Windows platforms, the adapter uses the standard C library function wcstombs() to convert the wide character string into a multi-byte string. The wcstombs() function is dependent on the operating system and the locale passed to the adapter.

On UNIX platforms, the TIBCO Adapter SDK conversion routines are used to convert from Unicode to SAP multibyte strings. This conversion is dependent on the adapter encoding configured for the adapter.


| 287

Chapter 8 Deploying and Starting an Adapter Using TIBCO Administrator Enterprise Edition

This chapter explains deploying and starting the adapter using TIBCO Administrator Enterprise Edition web interface. See the TIBCO Administrator documentation set for details about using Enterprise Edition.

Topics


• Create an EAR File in TIBCO Designer, page 289

• Deploy the Project, page 290

• Start or Stop the Adapter, page 292

• Monitor the Adapter, page 293


288 | Chapter 8 Deploying and Starting an Adapter Using TIBCO Administrator Enterprise Edition

Overview

An adapter instance can be deployed, started and managed using TIBCO Administrator Enterprise Edition or TIBCO Administrator Repository Edition.

• Enterprise Edition must be used if your adapter is part of a TIBCO BusinessWorks process.

• Repository Edition is used for adapters that do not participate in TIBCO BusinessWorks processes. If you are using Repository Edition, see Chapter 9, Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition, on page 295 for details.

The following table summarizes the features available in each edition.

The modules are optional. That is, Repository Edition can be installed with or without the User Management module. The User Management module is required to set security options for adapter projects.

Table 14 TIBCO Administrator Features

Feature Enterprise Edition

Repository Edition

tomcat web server Yes Yes

TIBCO Administration Server Yes Yes

TIBCO Administration GUI Yes Yes

User Management module Yes Yes

Resource Management module Yes No

Application Management module Yes No


Create an EAR File in TIBCO Designer | 289

Create an EAR File in TIBCO Designer

Generate an Enterprise Archive file (EAR) that contains information about the adapter services to deploy.

The EAR file contains information on what you wish to deploy. This could be one or more adapters, one or more TIBCO BusinessWorks process engines, or both.

In TIBCO Designer, follow these steps to create an EAR:

1. Configure the adapter instance.

2. Drag and drop the Enterprise Archive resource from the palette panel to the design panel. If there are any configured adapter services in your project, an Adapter Archive resource becomes available in the palette panel.

3. Drag the Adapter Archive into the design panel and specify information in the Configuration tab, then click Apply.

4. Go to the Enterprise Archive and click Build Archive to create the archive file.

See Also

See the TIBCO Designer User’s Guide for more information about this procedure. The guide is available from the Designer Help menu.

Building an archive creates the EAR file, which you can then deploy from TIBCO Administrator. If you make changes to the business processes or adapter services included in the archive, you need to rebuild the archive. Saving the project does not affect the archive.



Deploy the Project

Before deploying a project, the machine on which the adapter is installed must be part of a TIBCO administration domain. After you have installed the TIBCO Administration Server, any machine on which you install TIBCO Runtime Agent (required by an adapter) can be added to the administration domain. The TIBCO software installed on the machine is then visible and accessible via the TIBCO Administrator GUI.

When you deploy a project, startup scripts and other information about the different components are sent to the machines to which the components were assigned. The project data store and TIBCO Administration Server are updated with the deployed components.

To deploy a project:

1. Import the EAR file into TIBCO Administrator Enterprise Edition.

2. Assign adapter archives in the EAR file to adapters installed in the administration domain and likewise assign process archives to process engines.

3. Specify startup options for each adapter service.

4. If desired, set up your deployment for fault tolerance by specifying more than one adapter instance to run on different machines. The secondary instances will run in standby mode until they are needed.

Password Handling

At design-time, the adapter uses a password to connect to the backend application and fetch metadata. At run-time, the adapter uses a password to connect to the back-end application and interoperate with it. If you create a 4.x configuration using TIBCO Designer 5.1, and use the configuration against a 4.x adapter version, some special considerations are required for security.

When deploying the adapter check the Service property of the global variable in the global variables section, then go to the Advanced tab of the adapter archive and set the password value under the Run-Time Variables section.

Do not set the password to type Password in the global variables section for adapter configurations that are set to AE Version 4.0 or AE Version 5.0 (in the Configuration tab Version field) or any intermediate version.


Deploy the Project | 291

See Also

See the TIBCO Administrator User’s Guide for an introduction to the TIBCO administration domain and detailed information about the above steps.

See the TIBCO Administrator Server Configuration Guide for fault tolerance information.

Deploying a 4.x TID Manager in TIBCO AdministratorTo deploy a 4.x TID Manager in TIBCO Administrator, carry out the following steps:

1. Click on the Add Custom Software button to make a new entry for the 4.x TID Manager under the Installed Software list. Refer to the screen given next for the valid values.

2. Choose the TID Manager entry as the target application while deploying the EAR file created with the 4.x TID Manager. For details on creating an EAR file, see Create an EAR File in TIBCO Designer on page 289.



Start or Stop the Adapter

The TIBCO Administrator Application Management module allows you to start, and stop deployed applications.

To start the adapter from the module:

1. In the Administrator GUI left pane, expand Application Management > Application-Name > Service Instances.

2. In the Service Instance panel, select the check box next to the adapter service.

3. Click the Start Selected button.

The status changes from Stopped to Starting up to Started.

4. To stop the adapter, click the Stop Selected button.

See Also

See the TIBCO Administrator User’s Guide for more information.


Monitor the Adapter | 293

Monitor the Adapter

TIBCO Administrator offers a number of monitoring options. • Specify alerts and TIBCO Hawk rulebases for each machine in the domain.

• Specify alerts and Hawk rulebases for each adapter service.

• View the log for each adapter service.

See Also

See the TIBCO Administrator User’s Guide for information about configuring the above monitoring options.


| 295

Chapter 9 Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition

This chapter explains how to deploy an adapter, then start and stop it on the command line. Repository Edition is used to manage adapter projects.

Topics


• Export the Project, page 297

• Create a Properties File, page 298

• Set Properties in Properties File, page 299

• Assign Security Options, page 300

• Start or Stop the Adapter, page 301

• Monitor the Adapter, page 305

• Adapter Properties File, page 306

• Server Repository URL, page 311

• Local Project URL, page 316

• Install the Adapter as a Service on Microsoft Windows, page 318

• Start and Stop the TIDManager, page 319


296 | Chapter 9 Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition

Overview

If your adapter is not used in a TIBCO BusinessWorks process, you can use TIBCO Administrator Repository Edition to manage adapter projects.

If your adapter is used in a TIBCO BusinessWorks project, you must use TIBCO Administrator Enterprise Edition to deploy and manage your projects. See Chapter 8, Deploying and Starting an Adapter Using TIBCO Administrator Enterprise Edition, on page 287 for details.

See Overview on page 288 for a description of features available in both Enterprise Edition and Repository Edition.


Export the Project | 297

Export the Project

In TIBCO Designer, after configuring, verifying and testing your project, export the project to a server repository.

1. Click Project>Export Full Project.

2. Click the Server Repository tab in Export Project.

3. Provide values for the required fields and click OK.

See Also

See the TIBCO Designer User’s Guide for details about the required fields. The guide is available from the Designer Help menu.



Create a Properties File

Before starting the adapter you must create a properties file or edit the default properties file. Each run-time adapter instance must have a unique properties file. The easiest way to deploy an adapter is to copy the default adr3.tra file to a unique name and edit the properties defined in the file.

To create a properties file:

1. Navigate to the adapter installation area:cd <install-path>\tibco\adapter\adr3\5.1\bin

2. Copy the default adr3.tra file to a unique name.

Edit the predefined properties in the copied file as explained in Set Properties in Properties File on page 299.


Set Properties in Properties File | 299

Set Properties in Properties File

The properties file contains a set of predefined properties. At a minimum, the following properties must be defined in the adapter property file. For a description of all predefined properties, see Adapter Properties File on page 306.

• The tibco.repourl property identifies the project in which the adapter configuration is defined.

• The tibco.configurl property identifies the adapter instance to start.

• The application.args property identifies the properties file to pass to the adapter.

• The application.start.dir property identifies the working directory for the adapter.

See Also

Adapter Properties File on page 306

tibco.repourl tibcr://<project-name>tibco.configurl /tibco/private/adapter/<adapter-instance-name>application.args adr3 -system:propFile C:/tibco/adapter/adr3/5.1/bin/<name>.traapplication.start.dir C:/tibco/adapter/adr3/5.1/<start_directory>



Assign Security Options

You must have installed TIBCO Administrator Repository Edition with the User Management module to assign security options. Setting security options is not required, but recommended.

The User Management module allows authorized users to specify security options for a TIBCO administration domain. Security has two components:

• Authentication. Specify users and passwords.

• Authorization. Give users access to individual components in the TIBCO administration domain.

By default, the administrative user for the administration domain has privileges to create users and assign privileges. That user can create additional users with the same full access privileges if appropriate.

Roles

TIBCO Administrator allows you to create a roles tree and assign users to one or more roles. You can then perform authorization on a per-role basis.

This capability is critical, for example, if a large number of users need read access to information about running projects but only a few users should be authorized to start and stop the project.

Authorization

TIBCO Administrator allows privileged users to authorize users for GUI Access or Data Access (or both).• GUI access is given on a per-tab basis. For each tab you can select in the

TIBCO Administrator GUI, you can specify which users are allowed read or write privileges.

• Data access is given on a per-data store basis. A repository data store is associated with each project. You can set various levels of access (read, write, variables) for data stores of each deployed project and for the system data store.

See Also

See the TIBCO Administrator User’s Guide for details about creating roles and authorizations.


Start or Stop the Adapter | 301

Start or Stop the Adapter

The run-time adapter can be run as a console application on all platforms. On Microsoft Windows platforms only, the adapter can also be installed and started as a Windows service.

Setting the Environment Variables on UNIX

A shell script adr3setenv.csh is provided with the installation. Running this file in the C-Shell updates the system path and library path settings.

The following system settings are updated by the script:SHLIB_PATH (HP-UX)

LD_LIBRARY_PATH (Solaris and Linux)

LIBPATH (AIX)

PATH (ALL Platforms)

Note that the shell script updates the system settings for the current shell session only. If you open a new shell session, run the script afresh to update system settings.


1. Create an adapter configuration in TIBCO Designer and save it to a project

2. Copy the adr3.tra file to MyAdapter.tra



5. Open a c-shell by typing csh at the prompt.

6. Run the script adr3setenv.csh in <install-dir>/5.1 with the following command:

source adr3setenv.csh

If the settings are updated successfully, the following message is displayed:

environment variables successfully set

7. Start the adapter with the following command:

adr3 --propFile MyAdapter.tra




Start the AdapterThe following command starts the adapter as a console application using the default adr3.tra properties file. The default file has been edited with the name of the Designer project, the adapter service and properties file to pass to the application. Because the properties file has the same name prefix as the executable, it need not be specified on the command line.

adr3 --run

You can run the adapter as a console application using a custom properties file. For example, the next command starts the adapter service that is identified in the adr3pub.tra properties file, which is located in the same directory as the executable. The absolute pathname to the properties file must be given if it is located in a different directory than the executable.

adr3 --run --propFile adr3pub.tra

See Adapter Properties File on page 306 for information about modifying the properties file.

Adapter Command Line Options

Table 15 describes the command line options for the adapter.

Table 15 Adapter Command Line Options

Option Description

--run --propFile <fileName> Launches the adapter using the specified properties file. This is the default option, if no options are specified on the command line.

--help Displays help about the executable’s command-line options.

--install --propFile <fileName> Microsoft Windows Only. Installs the application as a Windows Service using the specified properties file.

If propFile is not given, the property file prefix name must have the same name as the adapter executable prefix name.


Start or Stop the Adapter | 303

Stop the AdapterUse one of the following methods to stop the adapter:

• From a command window, stop the adapter by sending the following message on the terminate subject or terminate topic. Ensure that this is the message specified in the General tab. See General Tab on page 125 for details on the message subject. The convention of the subject is

--uninstall --propFile <fileName> Microsoft Windows Only. Uninstalls the Windows Service associated with the adapter.


--start --propFile <fileName> Microsoft Windows Only. Start the Windows Service using the specified properties file.


--stop --propFile <fileName> Microsoft Windows Only. Stops the Windows Service using the specified properties file.


The standard command line options used in the TIBCO ActiveEnterprise 3.x are still valid.

Table 15 Adapter Command Line Options

Option Description

The properties file name for all command line options defaults to the same name as the executable with the .tra extension (for example, for adr3.exe, the properties file is named adr3.tra). The default location of the properties file is the same directory as the executable.

If the properties file is not in the default location with the default name, you must explicitly specify the absolute pathname of the properties file on the command line. If the properties file is in the default location with the default name, you can omit the properties file from the command line.



%%Domain%%.%%Deployment%%.adr3.%%InstanceId%%.exit with message content as "now". Example — To stop an adapter instance called IDocOutbound, available in the GettingStarted.dat, type the following command on the DOS prompt:

tibrvsend domain.GettingStarted.adr3.IDocOutbound.exit "now"

Once the adapter receives the ’now’ message on the stop subject, it will complete any pending transactions, cleanup resources, and then terminate.

• Start TIBCO Hawk. Invoke the stopApplicationInstance() method for the adapter configuration. Check for the trace message in the adapter console.


Monitor the Adapter | 305

Monitor the Adapter

If you have installed TIBCO Hawk, you can use the methods defined in the adapter’s standard and custom microagents to monitor it.

See Also

For details about monitoring, see Chapter 11, Monitoring the Adapter Using TIBCO Hawk, on page 359.



Adapter Properties File

The run-time adapters parse a properties file at startup. The default run-time adapter properties file is named adr3.tra.

The default properties file is located in bin subdirectory of the adapter installation directory.

Each line in a properties file is a single property. Each property consists of a key and a value. The key starts with the first non-whitespace character and ends at the first "=" or ":" or whitespace character. The value starts at the first character after the equal sign (=). For example:

tibco.configurl=/tibco/private/adapter/R3AdapterConfigurationtibco.repourl=tibcr://TEST_PROJECTadr3.maxconnections=admintibco.clientVar.service=7600tibco.clientVar.daemon=tcp:7600

Properties defined in the properties file override the same properties defined in the project.

Properties File FormatThe following restrictions apply to properties:

• The "!" character may not be used as a comment line indicator. Only the "#" character is recognized.

• The line continuation character is ignored (a value must fit on a line).

• The key may not contain any of the termination characters. Java allows termination characters by escaping the value with a preceding "\" character. The adapter does not support this syntax.

Tagging Values for Obfuscation

The presence of a "#" character as the first character in a value (not the key) indicates that the value has been obfuscated or is to be obfuscated. The obfuscation command-line tool prompts for values to be obfuscated when it encounters a value with "#" as the first character in the properties file.

When the obfuscate tool is run, it rewrites the properties file with the obfuscated value in place. See Obfuscating or Encrypting a Password in the Properties File on page 309 for more information.


Adapter Properties File | 307

Predefined PropertiesThe next table describes predefined properties. Properties that start with ntservice are available only on Microsoft Windows platforms.

All paths inside a properties file, including Windows directory names, must use forward slashes.

Table 16 Predefined Properties

Property Description

tibco.repourl Identifies the absolute pathname to the Designer project where the adapter configuration is defined. See Server Repository URL on page 311 for information about the locator string.

tibco.configurl Specifies the location of the adapter configuration inside the project file.

• If a relative path is specified, the adapter service is assumed to be under the default area in the project: /tibco/private/adapter/

• If an absolute path is specified, the adapter configuration is looked up in the project as defined by the argument.

tibco.username The user name and password used by the repository server to access the project.

tibco.password

tibco.clientVar.<varname>

Specifies run-time values to substitute for global variables defined in the project. This value takes precedence over the named global value set in the project. Substitution takes place only at start up.

You append the global variable to tibco.clientVar, then give its value. For example: tibco.clientVar.DirLedger=C:/tibco/adapter/adr3/5.1/ledger

adr3.perfMon <on/off> Turns the performance statistics microagent on or off. The default is off. If this property is set to on, the adapter does all the performance related calculations. When you invoke the TIBCO Hawk methods, if this property is set to off, default values are displayed and not the valid values.

adr3.addCustomHawkMethodstoClassMAgent <on/off>

If set to on, custom methods are added to the class microagent. If set to off, the invocation of these custom methods will return default values. Default is on.



ntservice.name Name for this Windows Service.

This property is useful if you wish to have multiple Windows Services for the same executable. That is, you may wish to have two adapters running on the same machine. By specifying different service names and display names for the adapters, you can accomplish this.

ntservice.displayname Name to display in the Services control for this Windows Service.

This property is useful if you wish to have multiple Windows Services for the same executable. That is, you may wish to have two adapters running on the same machine. By specifying different service names and display names for the adapters, you can accomplish this.

ntservice.starttype Start type for this Windows Service. Either manual or automatic. For example: ntservice.starttype automatic

You can use this property to initially set the start type for the service, but once the service is installed, use the Windows Services control to change the start type of services.

ntservice.binary.path.absolute

Absolute path to the executable that is run when the service is started. For example:ntservice.binary.path.absolute C:/tibco/adapter/adr3/5.1/bin/adr3.exe

ntservice.interactive Specifies whether the Windows Service is interactive. Either true or false. ntservice.interactive=true

ntservice.account Username under which to run the Windows Service.

You can use this property to initially set the account for the service, but once the service is installed, use the Services control to change the user account of services.

ntservice.password Password for the username in the ntservice.account property.

You can use this property to initially set the password for the user account, but once the service is installed, use the Services control to change the password.

adr3.Hawk500 This parameter is for backward compatibility with 4.x for loading the TIBCO Hawk Microagent methods. By default this parameter is set to on. While running the 4.x configuration ensure that this is set to off.




Adapter Properties File | 309

Obfuscating or Encrypting a Password in the Properties File

Password Handling

At design-time, the adapter uses a password to connect to the backend application and fetch metadata. At run-time, the adapter uses a password to connect to the back-end application and interoperate with it. If you create a 4.x configuration using TIBCO Designer 5.1, and use the configuration against a 4.x adapter version, some special considerations are required for security.

If you plan to run the adapter locally, define the run-time password value to be a global variable. Before starting the adapter, include the run-time password as client variable in the adapter’s .tra file and obfuscate it using obfuscate tool. For example, if the password value is defined as %%myPassword%%, create a global variable named myPassword in the global variables section with no value and include the following entry in the adapter’s .tra file:

tibco.clientVar.myPassword

Obfuscating a Password

If the run-time adapter uses a password to access the vendor application, the password is stored in readable form as a value to the tibco.clientVar.<variable>=# <password> property in the run-time adapter’s properties file. You can use the obfuscate tool to hide the password in the properties file so the password cannot be viewed by unauthorized users.

To obfuscate the password:

1. Using TIBCO Designer, open the adapter configuration and navigate to the panel where the password used by the run-time adapter to connect to SAP

adr3.maxconnections Specifies the maximum number of server/client connections to be established with R/3. It is recommended to set this only when maxConnections is greater than one and when you have to override the value of maxConnections specified in the project.

adr3.setlocale Specifies the locale encoding for the adapter instance, to be used with UTF-8 encoded projects



Do not set the password to type Password in the global variables section for adapter configurations that are set to AE Version 4.0 or AE Version 5.0 (in the Configuration tab Version field) or any intermediate version.



R/3 is defined. In the password field, provide a user defined global variable, such as %%MyPassword%%. The global variable must also be added to the global variable list. See Using Global Variables on page 272 for information about creating global variables.

2. In the run-time adapter properties file, verify that the tibco.clientVar.<variable>=# <password> property is defined in the file.

3. Run the obfuscation tool supplied with adapter software against the properties file. This tool is named obfuscate.exe and resides in the <install_dir>\tibco\tra\<n.n>\bin directory.

The command syntax on Windows for a default installation is:C:\tibco\tra\5.1\bin\obfuscate <tra-file-path-name>

where <tra-file-path-name> is the absolute pathname of the adapter properties file that contains the tibco.clientVar.<variable>=# <password> property.

For example, on Windows:C:\tibco\tra\5.1\bin>obfuscate

C:\tibco\adapter\adr3\5.1\bin\adr3.tra

The password is now obfuscated and you can start the adapter with the changed properties file.

Encrypting a Password

Encryption is only supported for version 5 adapters and higher. If you have a property in a properties file that needs to be encrypted, follow these steps:

1. In the property file, add the #! characters in front of the value you wish to encrypt. For example:

Repo.serverPassword = #!mysecret

2. Invoke the obfuscate utility from the command line:

<install-path>/tibco/tra/5.1/bin/obfuscate.exe --propertyfile=<property-file-name>

The next time you open the property file, mysecret will have been replaced with a random sequence of characters.

If you don’t want to obfuscate a password, remove the # at the beginning of the obfuscated password and replace it with the password in plain text.


Server Repository URL | 311

Server Repository URL

The server repository URL identifies the project to load when the adapter starts. The string is given as a value to the tibco.repourl property, which is specified in the adapter’s properties file.

The property syntax differs depending on the protocol with which the adapter and repository server communicate.

• TIBCO Rendezvous

• HTTP and HTTPS

TIBCO Rendezvous In case of a TIBCO Rendezvous transport, the locator string begins with tibcr:// or tibcr@. Next comes the project name.

In addition, the following optional properties are supported. They are separated by colons:

Table 17 Optional properties for server-based URL (TIBCO Rendezvous)


daemon TIBCO Rendezvous rvd daemon value

service TIBCO Rendezvous rvd service value

network TIBCO Rendezvous rvd network value

rva TIBCO Rendezvous rva host and port

subject Instance discovery subject

discoveryTime Timeout value in seconds for instance discovery

timeout Timeout value in seconds for server requests

operationRetry Number of retries when timeout occurs

userName Any identifier (null or empty implies read only with guest privileges)

password User password for security.



Examples

tibcr://myInst:service=5456:userName=ann:timeout=4000tibcr@myInst:service=5456:urlFile=/tibco/props/fredsProps.txttibcr://myInst:urlFile=/tibco/props/fredsProps.txt

HTTP and HTTPSIn case of HTTP transports url begins with http://.

In case of HTTPS transports url begins with https://.

Host name and port number are next (http://host:port). The port number is optional. If it is not specified, the default value used is 8080 for HTTP and 8443 for HTTPS.

regionalSubject TIBCO Rendezvous subject prefix used for regional read-operation in the load balancing mode. For additional information see the TIBCO Administrator Server Configuration Guide.

typeAccess Type of adapter connection. Valid values are:• CLIENT_USAGE_DONT_CARE

Adapter reads until update, then switches to write. This is the default.

• CLIENT_USAGE_READ_ONLY

Adapter is not allowed to do updates.• CLIENT_USAGE_READ_WRITE

Adapter can do both reads and updates.

urlFile Path to the adapter’s properties file.

The property file identifier can either be a fully qualified path or a relative path. The legal properties in this file are the same as optional properties specified above. The properties in the file are appended to the repository locator string. If the same property appears in both locator string and property file, the properties in the locator string take precedence. Property values starting with # are considered obfuscated.

Table 17 Optional properties for server-based URL (TIBCO Rendezvous)




The host name and port number are followed by the project name, which is preceded by a question mark (?), for example, http://host:8080/?inst1

Optionally, administrator/repo may be included as part of the instance name, for example, http://host:8080/administrator/repo/?inst1

In addition, remote HTTP/HTTPS adapters support the following optional properties separated by &. Note that when & is used as the properties separator, and the URL is specified on the command line, the URL should be enclosed in quotes so that shell does not interpret it.

HTTPS-specific properties should be placed in a property file and that file should be specified using "urlFile=". urlFile is therefore a required property for HTTPS.

Table 18 Optional properties for server-based URL (HTTP)


timeout Timeout value in seconds for server requests.

operationRetry Number of retries if a timeout occurs.

userName Any identifier (null or empty implies read only with guest privileges).

password User password for security.

typeAccess Whether it is read only or read-write. Valid values are:• CLIENT_USAGE_DONT_CARE



Adapter is not allowed to do updates.• CLIENT_USAGE_READ_WRITE




Exampleshttp://host:8080?myInst&userName=ann&timeout=4000http://host:8080/administrator/repo?myInst&userName=ann&timeout=4000https://host:8443?myInst&urlFile=httpsProps.inihttps://host:8443/administrator/repo?myInst&urlFile=httpsProps.inihttps://host:8443/administrator/repo?urlFile=httpsProps.ini

Defining a urlFile to be Accessed via HTTPSIf the URL file is to be accessed via HTTPS, the following information must be included in the properties file:


The property file identifier can either be a fully qualified path or a relative path. The legal properties in this file are the same as optional properties specified above. The properties in the file are appended to the repository locator string. If the same property appears in both locator string and property file, the properties in the locator string take precedence. Property values starting with # are considered obfuscated. See Defining a urlFile to be Accessed via HTTPS on page 314.

Table 18 Optional properties for server-based URL (HTTP)


Table 19 Properties Required for HTTPS urlFiles


trustedCertFormat Format of the SSL certificate. Can be one of P12, PEM, DER (or ANS1).

httpsVendor Name of the SSL provider.

The property is ignored because openssl is the only vendor supported.

keyFile Key file.

Keys can either be embedded as in the case of P12 and DER or non-embedded as in the case of PEM. Key file is relevant only in case of non-embedded key files, that is, PEM and P7.



Examples

Following is an example for a url File containing HTTPS specific properties:

httpsVendor=j2setrustedCerts=H:/downloads/certs/clientcerts/trustedcerts/RSA/PEM/RSA1024ca1.cert.PEMtrustedCertFormat=PEMtrustedCertPassword=RSA1024ca1identityFile=H:/downloads/certs/clientcerts/idcert/RSA/P12/RSA1024ca2.cert.P12

identityType=P12keyPassword=RSA1024ca2egdSocket=/etc/egd-pool

identityFile Location of the identity file.

identityType Format of the identity file. Can be one of P12, PEM, DER (or ANS1).

trustedCertPassword Password for the certificate specified by trustedCerts.

trustedCerts Location of the trusted certificate or certificate chain.

egdSocket If using HTTPS transport on UNIX platforms other than Linux, this property specifies the location of the socket from which to get the random number.

Table 19 Properties Required for HTTPS urlFiles




Local Project URL

Local repositories start with the instance name, which can optionally be preceded by localrepo@. The project name can either be a fully qualified path or a relative path. The .dat extension is optional.

In addition, adapters support the following optional properties separated by colons:

Table 20 Optional parameters for local project URL

Parameter Description

userName Any identifier (if not present or empty makes a read-only client)


The property file identifier can either be a fully qualified path or a relative path. The legal properties in this file are the same as optional properties specified above. The properties in the file are appended to the repository locator string. If the same property appears in both locator string and property file, the properties in the locator string take precedence. Property values starting with # are considered obfuscated.

typeAccess Type of client connection. Valid values are:

• CLIENT_USAGE_DONT_CARE



Adapter is not allowed to do updates.

• CLIENT_USAGE_READ_WRITE


• CLIENT_USAGE_REACQUIRE_INSTANCE_LOCK

Adapter is allowed to overwrite this local repository even if a lock file exists, as long as it’s the same user.

• CLIENT_USAGE_FORCE_INSTANCE_LOCK

• Adapter is allowed to overwrite this local repository even if a lock file exists. WARNING: Using this option may result in other users overwriting your project.

See the TIBCO Administrator Server Configuration Guide for additional information.


Local Project URL | 317

Examples

./instances/myInst.dat:userName=deborah

c:/tibco/administrator/myInst/myInst.dat:urlFile=c:/tibco/administrator/props/deb

myProj.dat

myProj

myProj/myrepo.dat



Install the Adapter as a Service on Microsoft Windows

The following command lines show how to install the adapter as a service, start the service, stop the service, then uninstall the service. Because no properties file is specified, the default properties file, adr3.tra is used.

1. Install the adapter as a service:adr3 --install

2. Start the adapter service:adr3 --start

3. Stop the adapter service:adr3 --stop

4. Uninstall the adapter service:adr3 --uninstall

If the properties file is not in the default location with the default name, you must explicitly specify the absolute pathname of the properties file on the command line.

You can create multiple services for the same adapter configuration by specifying a different Service Name and Display Name for each. This may be required for load balancing, if the subscriber quality of service is set to Distributed Queue. Each adapter configuration must have a unique properties file and it must be specified on the command line. In addition, each property file should have a unique value for the following Service Name and Display Name properties:

ntservice.namentservice.displayname

For example, the following command line lines show how to install the adapter as a service, start the service, stop the service, then uninstall the service using the adr3test.tra property file. The same commands can be used to install another adapter on the same machine, providing a different properties file is given.

5. Install the adapter as a service:adr3 --install --propFile adr3test.tra

6. Start the adapter service:adr3 --start --propFile adr3test.tra

7. Stop the adapter service:adr3 --stop --propFile adr3test.tra

8. Uninstall the adapter service:adr3 --uninstall --propFile adr3test.tra


Start and Stop the TIDManager | 319

Start and Stop the TIDManager

The TIDManager guarantees that no transactional data is lost or delivered twice. It ensures exactly once delivery. We recommend that the TIDManager be run on a high-capacity, high throughput machine, that is either the same as, or closely connected to, the gateway server machine connected to the SAP R/3 RFC port. We also recommend that this machine have minimum vulnerability to being overloaded with network traffic or any other preventable stress.

Starting the TIDManager The TIDManager component parses a properties file at startup. The default properties file is named adr3TIDManager.tra.

The default properties file is located in the same directory as the adapter executable, and this is always the bin subdirectory of the adapter installation directory. For example, the adapter installation directory on Windows is by default TIBCO_HOME\adapter\adr3\5.1. The executable and properties file for the TIDManager is located in TIBCO_HOME\adapter\adr3\5.1\bin.

The properties file normally uses the .tra extension, but other file name extensions are permitted. If no properties file is specified on the command line, the executable looks for a properties file named executable_name.tra. For example, if the executable is named adr3TIDManager.exe, it looks for a properties file named adr3TIDManager.tra.

Each properties file consists of a set of property name and value pairs. The property name and the property value can be separated by a single space or an equal sign (=).

For details on the properties file, refer to Predefined Properties on page 307.

When you configure an adapter instance as a Windows service, if the TIDManager client is remote, you must assign the TIDManager as a dependency to the service.

All paths inside a properties file, including Windows directory names, must use forward slashes.



In addition to the standard properties, the following property is applicable to the TIDManager.

Stopping the TIDManagerUse one of the following methods to stop the TIDManager:

• From a command window, stop the TIDManager by sending the following message on the terminate subject or terminate topic. Ensure that this is the message specified in the General tab. See Setting TIDManager General Options on page 257 for details on the message subject. The convention of the subject is %%Domain%%.%%Deployment%%.adr3TIDManager.%%InstanceId%%.exit

with message content as "now". Example — To stop a TIDManager called R3TIDManagerConfiguration, available in the test.dat, type the following command on the DOS prompt:

tibrvsend domain.test.adr3TIDManager.R3TIDManagerConfiguration.exit "now"

Once the TIDmanager receives the ’now’ message on the stop subject, it will complete any pending transactions, cleanup resources, and then terminate.

• Run the TIBCO Hawk method, stopApplicationInstance() associated with the TIDManager TIBCO Hawk microagent.

Table 21 TIDManager Properties


adr3TIDManager.tidFile Specifies the name and location of the TIDManager file where the transaction IDs are managed.


| 321

Chapter 10 Advanced Features

This chapter covers advanced features offered by TIBCO Adapter for R/3.

Topics

• Handling Large Internal Tables from SAP R/3, page 325

• IDoc Filtering, page 328

• Inbound BAPI Transactional Support, page 331

• Invoking BAPIs/RFCs Using Transactional Semantics in SAP R/3, page 336

• Multithreading, page 339

• Multiple Connections, page 341

• Event Driven Inbound Connections, page 348

• Running an Adapter Instance on Two SAP R/3 Systems with a Single Connection, page 353


322 | Chapter 10 Advanced Features

Using the Adapter with a Revision Control System

TIBCO Designer supports revision control systems such as MicroSoft Visual SourceSafe and Perforce. If you are using a revision control system, you must manually add some configured resources to the revision control system and check in the resources when completing the instance configuration.

As part of service configuration, the adapter creates schema files in root/AESchemas/ae/<SAPSystemNumber>/basic. For example, if you configure a publication or a subscription service in an adapter configuration Instance1, the following files are created:Project_root/AESchemas/ae/45B/basic/Idocs.aeschemaProject_root/AESchemas/ae/45B/basic/structures.aeschema

If you configure a Request-Response Invocaton or a Request-Response service in an adapter configuration Instance1, the following files are created:Project_root/AESchemas/ae/45B/basic/functionModules.aeschemaProject_root/AESchemas/ae/45B/basic/structures.aeschema

The file ae.aeschema found under Project_root/AESchemas/ae/scalar/ae.aeschema will be modified to update custom scalars if necessary.

The file R3Connections.adr3Connections under Project_root will be modified to update connections for the instance.


Using the Adapter with a Revision Control System | 323

When the project is saved and a revision control system has been specified, the adapter displays a warning that additional files were created and should be added to the revision control system. This warning appears only when the files are created for the first time. The warning displays a Go To Resource button that helps in navigating to the resource. You should use the Multi-User>Add Resources to RCS menu command to add these files to the revision control system.

For information about how to use the Multi-User feature in TIBCO Designer, refer to the TIBCO Designer User’s Guide.

Copy, Cut, Paste and Move Operations

To successfully copy and paste a service from adapter Instance1 to Instance2, the adapter configuration file for the Instance2 and the connection file must be checked out.

To successfully cut and paste a service from adapter Instance1 to Instance2, the adapter configuration file for both Instance1 and Instance2 and the connection file must be checked out.

To successfully move a service from adapter Instance1 to Instance2, the adapter configuration file for both Instance1 and Instance2 and the connection file must be checked out.



Regeneration When Moving, Copying and Pasting

• Default subjects are not regenerated to reflect the new instance name when a service is moved.

• Manually changed certified messaging and certified messaging queue ledger file names are regenerated to defaults when a service is moved, or copied and pasted to a new instance.

• If a service associated with a custom session is moved, or copied and pasted, the custom session is not moved, or copied and pasted. The session is regenerated as a default session.


Handling Large Internal Tables from SAP R/3 | 325

Handling Large Internal Tables from SAP R/3

Certain BAPIs/RFCs configured as Request-Response services query the SAP R/3 system based on specific search criteria. Depending on the queries executed in the SAP R/3 system, the records retrieved by the adapter could vary between a few to many hundreds. Example: BAPI_SALESORDER_GETLIST returns the list of sales orders for a given customer within specific dates for a sales organization to the TIBCO environment.

The adapter allows you to retrieve controlled number of records for convenience and easy processing and handling at the requesting client-side in the TIBCO environment. The BAPI itself is executed only once in the SAP R/3 system. The adapter caches the entire resultset retrieved from the SAP R/3 system, say 1000 sales orders, and splits the 1000 sales orders into multiple chunks.

The client can make multiple requests to the adapter to retrieve each chunk. The cache maintained by the adapter can be browsed in the forward and backward directions. The adapter also indicates to the client by means of a return variable whether all chunks have been returned or not. The adapter also allows you to clear the maintained cache from the client.

A typical usage would be displaying of Salesorders from the SAP system to multiple users on Web-browsers over the internet. Each user specifies the number of salesorders to be displayed on each screen and navigates using Previous and Next buttons. The client-side only converts the user actions into suitable requests to the adapter and formats the data chunks.

This feature offers powerful capabilities when used in combination with the dynamic-logon feature.

Enabling Data-Chunking To enable data-chunking, you must set appropriate attributes in the closure argument in the userClosure attribute of the request class. The userClosure class is a packet that is associated with the actual application request from the client and defines the nature of the actual request to the adapter.

The adapter provides a userClosure class, RFCCLOSURE. This class contains attributes for defining data-chunking requests.

The RFCCLOSURE class is included by default in every Repository project containing a TIBCO Adapter for R/3 configuration and is available under /classes/ae/SAPAdapter40/classes in the Repository Project.



The following table lists the input and output parameters for the RFCCLOSURE class. The input parameters should be set by the client and the output parameters are returned to the client based on which the client takes necessary action.

Table 22 Input Parameters - To be set by the client for every data-chunking request

Name Description Valid Values

GUID A globally unique identifier. This associates the client request with adapter-side cache. Each cache is identified solely by the GUID passed by the client.

Unique String

bUseCache Identifies if the request from the client is a data-chunking request. When this is set, caching is turned on in the adapter.

Boolean (0/1)

packetSize The number of records the adapter should send back to the client in the reply. If multiple tables are returned from the SAP R/3 system with different number of records, then every table in the reply will contain those many rows specified by the packetSize. If the number of remaining rows is less than the packetSize for a table, that table returns all the remaining rows.

If there are multiple tables in the reply and if all the records for a table have been sent, the next invocation would not contain any records for that table.

An integer number

cacheDirection Indicates to the adapter which direction to browse the cache in. A "forward" direction returns the next set of records in the cache. A "backward" direction returns the previous set of records from the cache. Defaults to "+" if not set.

Forward ’+’Backward ’-’

bClearCache Indicates to the adapter whether to clear the cache or not. This attribute is meaningful only for caches already created in the adapter. The GUID specifies which cache to clear. A separate request has to be made for each cache for the BAPI/RFC concerned. On receipt of the clear-cache request, the adapter simply clears the cache and returns a success message to the client.

Boolean (0/1)


Handling Large Internal Tables from SAP R/3 | 327

Table 23 Output Parameters returned by the adapter to the client for each chunking request

Also, note the following while enabling the client to make use of the data-chunking feature:

— Since browsing in the negative direction is possible at anytime during a chunking call sequence, the adapter does not automatically clear the cache after sending back all retrieved records. The cache is automatically cleared only if the cacheDirection attribute is never set.

— The client has to explicitly clear the cache by setting the bClearCache attribute to true. A separate cache-clearing request has to be made for the same RFC/BAPI for which caching is enabled. The GUID associated with the cache should also be set to identify the cache to be cleared.

Name Description

bMore Indicates the status of the cache. If there are more chunks to be return to the client from the adapter cache, this returns true else false. The client can take necessary action based on this flag.

CurrentRowCount Maintains the current count of the rows returned to the client in a cache. For example, if there are 1000 records totally and packetSize is 100, and the adapter returns records 801-900 in the course of the chunking requests, currentRowCount is set to 900. In case records from multiple tables are returned, this attribute always indicates the row count of the table with the maximum records.

maxRowCount Maintains the total size of the cache in terms of records. For example, if there are 1000 records totally, maxRowCount is always set to 1000. In case records from multiple tables are returned, this attribute always indicates the size of the table with the maximum records.

If the cache is not cleared, the adapter memory usage will go up with each caching call.



IDoc Filtering

The default behavior of an IDoc Publication Service is to publish the complete IDoc data received from the SAP R/3 system. IDoc Filtering enables an IDoc Publication Service to filter segments and fields of an IDoc received from the SAP R/3 system before publishing the IDoc message to the TIBCO environment. Selective publishing of segments or fields at run-time is achieved by specifying the segments or fields to filter in the IDoc publication service schema. This can be done in TIBCO Designer at design-time.

The filtered IDoc message that is published in the TIBCO environment will continue to conform to the original IDoc schema, but the data for the segments and fields filtered will not be published. Subscribing systems can use the original IDoc schema downloaded into the project to receive the filtered IDoc messages.

To configure filtering for an IDoc Publication Service, follow the below steps:

1. Go to the Schema tab of the Publication Service. This tab displays the SAP schema for the IDoc type. For example, in the screens given in this section, the schema for MATMAS01 is displayed.

2. Filter out an IDoc segment or field by selecting the check box provided against each of the IDoc segments or fields. For example, in the first screen in this


IDoc Filtering | 329

section, the segment E1MARCM and its children segments are being filtered. The second screen shows field-level filtering in the segment E1MAKTM.

— To filter an entire IDoc segment and its children segments, select the check box against that segment. The children segments are automatically filtered at run-time.



3. Click Apply and save the project.

Segments that are defined as mandatory in the SAP R/3 system are not filtered even if the check boxes against these segments are selected.


Inbound BAPI Transactional Support | 331

Inbound BAPI Transactional Support

An external system invoking a BAPI Request-Response service in the adapter has the choice to explicitly commit or rollback the changes applied to one or more business objects by the BAPI in the SAP R/3 system. The explicit commit or rollback is not a mandatory requirement for all BAPIs but is needed wherever the underlying BAPI in SAP R/3 is implemented this way.

For example, an invocation of BAPI_SALESORDER_CREATEFROMDAT2 in the SAP R/3 system from the adapter does not effect permanent changes to database till an explicit commit invocation is made with BAPI_TRANSACTION_COMMIT.

To maintain the contexts for individual BAPI invocations, the Request-Response service for the BAPI requiring explicit commit needs additional configuration in TIBCO Designer. Before configuring a BAPI Request-Response service for explicit commit, run through the checklist given below to ensure that the service really requires configuration for explicit commit.

Explicit configuration for this feature is required only when one or more of the following conditions are satisfied:

• The BAPI requires explicit commit/rollback in the SAP R/3 system.

• Multiple connections (maxConnections > 1) are configured for the client, which invokes the BAPI in the SAP R/3 system.

• The adapter configuration is to be run in a load-balanced fashion.



The steps for configuring a BAPI Request-Response service for explicit commit are given below:

1. Go to the Advanced tab of the BAPI Request-Response service and select the Commit Required check box, as shown in figure below.

2. Set the CommitExpiry value. This field defines the maximum time, in milliseconds, for the adapter to hold the transaction context for each invocation of the BAPI. It starts from the moment the BAPI invocation in SAP R/3 is complete. Upon expiry of this time-interval, the transaction context for an invocation is released. A Commit/rollback request for this invocation sent to the adapter after commitExpiry will not be executed in the SAP R/3 system.



3. Configure Request-Response services in the same configuration for the standard SAP R/3 commit/rollback BAPIs, API_TRANSACTION_COMMIT and BAPI_TRANSACTION_ROLLBACK as shown in figure below.

See the table given below for descriptions of these BAPIs.

Load-balanced configurations with BAPIs requiring explicit commitThe commit/rollback BAPI is required to be executed in the same adapter instance as the one that executes the BAPI requiring the commit/rollback.

In load-balanced Inbound adapter configurations, it is not guaranteed that the commit/rollback BAPI invocation will be performed on the same adapter instance that received the invocation of the BAPI requiring commit. Consequently, the request-response services for BAPI_TRANSACTION_COMMIT and BAPI_TRANSACTION_ROLLBACK cannot be run with Quality of Service set to Distributed Queue (in TIBCO Rendezvous transport) or Queue (in TIBCO Enterprise for JMS transport).

BAPI Task

BAPI_TRANSACTION_COMMIT • Ends current transaction

• Commits changes

• Initiates new transaction

BAPI_TRANSACTION_ROLLBACK • Ends current transaction

• Discards changes

• Initiates new transaction



Exactly-once execution of commit/rollback in the SAP R/3 system from the correct adapter instance in a load-balanced setup is achieved as follows:

1. Configure the request-response services for BAPI_TRANSACTION_COMMIT and BAPI_TRANSACTION_ROLLBACK with Quality Of Service, Reliable (in TIBCO Rendezvous transport) or Topic (in TIBCO Enterprise for JMS transport).

2. Startup each instance of the adapter in the load-balanced configuration, setting the following parameter in the properties file adr3.commitid to a unique value for each instance.

The parameter value can be any unique string, and should not contain spaces.

Example: adr3.commitid=InstID001

adr3.commitid=InstID002

Sample ScenarioAssume a scenario where a sales order is to be created. Depending on the result the sales order will either be committed or rolled back using the appropriate external BAPI. When the sales order creation BAPI is sent to the adapter with the Commit Required flag enabled, the adapter instance generates a session ID, which is passed in the user closure (RFCclosure) argument of the reply schema. This session ID needs to be mapped to the request event of BAPI_TRANSACTION_COMMIT or BAPI_TRANSACTION_ROLLBACK and sent to the SAP R/3 system.

Procedure


2. Download the RFC, which requires commit or rollback. For example, BAPI_SALESORDER_CREATE_FROM_DAT2. See Adding Adapter Services Automatically on page 145 for details.

If BAPI Commit is being used with multithreading feature of the adapter, then it is recommended that you use a separate session for servicing the BAPI Commit request.



3. Check the Commit Required parameter and the Commit Expiry parameter for the downloaded RFC as shown in the following example. See Advanced Tab on page 188 for details.

4. Download BAPI_TRANSACTION_COMMIT and BAPI_TRANSACTION_ROLLBACK.

5. Start the adapter instance.

6. When an RFC with the Commit Required flag enabled is triggered from a client application, the Session ID is returned as part of the reply. This Session ID is mapped to the request event of BAPI_TRANSACTION_COMMIT or BAPI_TRANSACTION_ROLL BACK (depending on the content of the reply) and sent to the SAP R/3 system. This ensures the commit or rollback of the transaction.

For another example, refer to the Integration of External Commit with the Adapter using BAPI section from the TIBCO Adapter for R/3 User’s Guide.



Invoking BAPIs/RFCs Using Transactional Semantics in SAP R/3

BAPIs and RFCs can be invoked using transactional semantics in the SAP R/3 system.

The transactional semantics in SAP R/3 ensures data consistency and exactly-once execution, in case of exception situations (network outages or system failures) in SAP R/3 while the call is being executed.

Transactional RFCs (tRFCs) are always executed as one-way invocations and are best suited for transferring transactional data into the SAP R/3 in real-time. To execute a BAPI/RFC in a transactional mode, the BAPI/RFC has to be downloaded and saved to the adapter configuration as a one-way operation.

Any one-way Request-Response service can be executed as a tRFC in R/3. To execute a one-way BAPI/RFC as a tRFC, each invocation of the BAPI/RFC should be accompanied by userClosure information, as defined in the class RFCCLOSURE under /tibco/public/classes/ae/SAPAdapter40/RFCCLOSURE.

The parameters that need to be set in the RFCCLOSURE class and sent along with each tRFC request are:

• bTransactional — This boolean variable determines whether the call must be invoked transactionally or not in SAP R/3. Set this to true for a tRFC invocation.

• TID — Each tRFC invocation has to be carried out with a globally unique transaction identifier (TID) that uniquely identifies each tRFC invocation. Based on this parameter SAP internally ensures exactly-once invocation for the transaction associated with this TID. The sending system is responsible for generating and setting this parameter for each tRFC call.

With valid values for bTransactional and TID, a one-way Request-Response invocation is recognized as a tRFC call by the adapter and the call is invoked with transactional semantics in the SAP R/3 system.

Ensure that the TID parameter is a non-null unique identifier for each tRFC invocation.


Invoking BAPIs/RFCs Using Transactional Semantics in SAP R/3 | 337

By default, the messaging protocol for one-way BAPI/RFC services is set to Certified messaging.

Support for qRFCsqRFC is an enhancement on tRFC. qRFC allows tRFC invocations to be handled sequentially in the target SAP R/3 system. The adapter allows external systems in the TIBCO environment to invoke tRFCs as qRFCs in the SAP R/3 system.

Inbound qRFC

Any tRFC can be invoked as a qRFC in the inbound adapter. No design-time configuration is required. All parameters necessary to invoke a tRFC as a qRFC can be provided at run-time as part of the RFCCLOSURE class discussed in the previous section.

The qRFC parameters that have to be set in the RFCCLOSURE for performing a qRFC invocation in the SAP R/3 system are discussed below:

• bQueue

This boolean variable determines whether the call must be invoked as a qRFC or not in SAP R/3. Set this to true for a qRFC invocation. This value is applicable only if the bTransactional attribute is also set to true.

• qName

Every qRFC invocation is made in the SAP R/3 system for a specific queue defined in the system. Set this field to indicate which queue the qRFC call is to be inserted into.

• qCount

This is the counter for the receiving queue in the SAP R/3 system. Specify unique integer values for each qRFC invocation inserting into a specific queue.

It is strongly recommended to use the Certified Messaging protocol for one-way BAPI/RFC invocations. The SAP system requires that if any exception situation (like network outages) occurs during the execution of the call in R/3, then the transactional call be repeated with the same TID later, to avoid data inconsistencies. This requirement is automatically handled by the certified messaging protocol.



Outbound qRFC

Outbound qRFC calls can be invoked in the adapter from the SAP R/3 system. The adapter extracts the queue parameters for each qRFC invocation from the SAP R/3 system and appends them in the request’s RFCCLOSURE class that is passed on to the TIBCO environment.

The queue-name and queue-count values are extracted from the SAP R/3 system for each qRFC invocation. They are set to the qName and qCount attributes of the RFCCLOSURE class respectively. The attribute bQueue is set to true.

This allows receiving systems in the TIBCO environment to recognize tRFC/qRFC invocations made by the outbound adapter.


Multithreading | 339

Multithreading

Multithreading of an application allows the application to simultaneously process multiple, independent events. Multithreading is supported in both inbound and outbound instances.

You can configure the number of threads required for each client or server connection. The number of threads should be equal to the number of connections required. The maximum limit is eight threads per client connection or server connection.

tRFC invocations (including IDocs) from SAP R/3 are handled sequentially by the underlying R/3 interface library. Hence all transactional RFCs are sequenced by the adapter as well. Consequently, multiple threads will not contribute to enhanced performance of tRFC Request-Response Invocation services and IDoc Publication services in the adapter.

By default, every additional thread created is assigned a stacksize of 1.25MB. To avoid stack overflows at runtime, ensure that this stack limit is sufficient for the largest message that you would expect by sending out a single message of this size to the adapter.

The stack size for an adapter configuration can be increased by specifying it as a parameter from the command-line during startup or in the adapter TRA file.

For example, to set the stacksize to 2MB, specify the following parameter in the TRA file, adr3.stacksize 2097152 or provide the following command line argument while starting upadr3 -system:repourl C:/Repositories/StackTest.dat -system:configurl /tibco/private/adapter/SAPAdapter40/R3AdapterConfiguration -system:stacksize 2097152

Note that the stacksize value must be specified in bytes.

For details on setting up number of threads see the following sections: - Setting Client Connection Advanced Options on page 216- Setting Server Connection Advanced Options on page 226



Multithreading with Distributed Queues

BAPI/RFC Request-Response services and IDoc Subscription services may be run in load-balanced Distributed Queue (or RVDQ) mode. For multithreading to be enabled for such configurations, ensure that the worker tasks for worker instances are set to values less than 1. The number of threads active in each instance is equal to the worker task set for that instance, provided sufficient connections are created for the configuration.


Multiple Connections | 341

Multiple Connections

The adapter can connect to multiple gateways/program IDs on the outbound side and multiple application servers on the inbound side.

Posting BAPIs/RFCs/IDocs from multiple gateways in the Outbound AdapterThe SAP R/3 gateway enables communication between different SAP R/3 application servers or between an application server and an external program.

The host machine on which the SAP R/3 gateway resides is called the Gateway Host. Each SAP R/3 application server can communicate to external systems through its own gateway often residing on the same machine as the application server. Alternatively, the gateway process may also reside on a machine entirely different from the one where the application server runs. In such cases, multiple application servers can share the same gateway and the gateway host acts as a centralized gateway server.

The Outbound adapter can service requests to invoke or post BAPIs/RFCs/IDocs in the TIBCO environment from one or multiple SAP gateways. This is achieved by configuring the adapter for multiple Outbound connections. See Configuring Multiple Connections for Outbound Instance on page 246 for details.



Figure 12 Outbound Adapter Connecting to Multiple SAP R/3 Gateways

Posting BAPIs/RFCs/IDocs from multiple RFC Destinations in the Outbound Adapter

From within a single SAP R/3 gateway, RFCs/BAPIs/IDocs are passed on to the Outbound adapter from RFC destinations. When an RFC/BAPI or an IDoc is executed on a specific RFC Destination, the SAP R/3 system passes on the request to the adapter registered on the Program ID that is mapped to the RFC Destination.

A single instance of the Outbound adapter can service RFCs/BAPIs/IDocs from multiple RFC destinations. This is achieved by configuring the adapter for multiple Outbound connections in TIBCO Designer palette. See Configuring Multiple Connections for Outbound Instance on page 246 for details.



Figure 13 Outbound Adapter Registering on Multiple Program IDs on One Gateway

Responding to dynamic changes in the Application Server environment Load balancing Outbound messaging on the SAP side is achieved by clustering multiple application servers under a central SAP Instance.

The Outbound adapter can respond to dynamic changes to such clustered environments in terms of detecting addition or removal of application servers to or from the cluster. The Outbound adapter automatically registers itself with all active application servers in a cluster and receives and processes messages from the servers.



To achieve this, the Outbound adapter is to be run in conjunction with a discovery agent that is supplied with the adapter Run-time environment installation. The figure given next explains the steps involved in this dynamic discovery scenario. gw1, gw2 in the figure are the gateway hosts through which the SAP R/3 application servers communicate to the Outbound adapter.

The Discovery Process

The discovery agent is a special pre-configured Inbound adapter. The discovery process involves the following steps, also schematically presented in the above figure.

1. Discovery Agent polls the central SAP R/3 instance, retrieves the list of application servers connected to the central Instance.

2. The discovery agent publishes the list as a message to the TIBCO environment.

3. The Outbound adapter configuration(s) pick up the discovery message.

4. The Outbound adapter configurations(s) register on the gateway hosts of discovered application servers.



The Outbound adapter automatically disconnects from application servers that have gone down and cleans up connections after all attempts to retry to the application server are exhausted. The Outbound adapter does not create a new connection to a gateway host, if it is already connected to it.

Configuring the Outbound Adapter

The Outbound adapter does not need additional configuration in TIBCO Designer to be able to respond to dynamic changes to the application server environment.

The following properties need to be set in the adapter launcher file to enable this feature for an Outbound adapter configuration.

• adr3.discovery — This property can be used to turn on/off the dynamic-discovery feature. The feature is turned off by default. To turn it on, specify, adr3.discovery=ON

• adr3.discovery.pid— This property allows you to specify the program-ids on which to register with the discovered application server's gateway. Multiple program-ids can be specified as comma-separated values.

Example:adr3.discovery.pid=tibcotest

adr3.discovery.pid=tibcotest,idoctest

If the dynamic-discovery feature is turned on, this is a mandatory property. The adapter will exit on starting up with an appropriate error if this property is not specified.

• adr3.discovery.listenerSubject — This specifies the subject to listen on to subscribe to the discovery message published by the discovery agent. The discovery message contains the list of active application servers. If not specified, this property defaults to R3.APPSERVERS.ACTIVE

Ensure that the discovery-listener subject matches the publish subject on the discovery agent side.

Example:adr3.discovery.listenerSubject=APPSERVER.DISCOVERY.DYNAMIC

• adr3.discovery.listenerSession — This specifies the TIBCO Rendezvous or JMS session to be used by the discovery listener.

Example:adr3.discovery.listenerSession=MyDiscoverySession

A valid session by this name should be available in the project. If not specified, this property defaults to the default adapter session R3RVSession



• adr3.discovery.maxconnections —This property specifies the maximum number of connections that can be established to the gateway of each discovered application server. If not specified, it defaults to 1.adr3.discovery.maxattempts

adr3.discovery.retryinterval

These parameters together define the behavior of the outbound adapter in the event of connection loss to a gateway. Connection loss could be due to network glitches or because of a planned shutdown. Because the adapter cannot distinguish between the two causes, it will behave in exactly the same way in both situations.

If an application server has been brought down because of a planned shutdown, it will still continue to establish a valid connection till all attempts are exhausted.

Example:adr3.discovery.maxattempts=10

adr3.discovery.retryinterval=30000

Note that the retry interval must be specified in milliseconds.

If not specified, maxattempts defaults to 3, and retryinterval to 30000 milliseconds.

Configuring the Discovery Agent

The discovery agent is a preconfigured Inbound adapter. The configured repository is available in the adapter bin directory as adr3Discoverer.dat.

Bring up the discovery-agent with the following command from command line

adr3 --propFile adr3Discoverer.tra

Configuring the Inbound Adapter for multiple application serversTypically, an Inbound adapter is configured to connect to a messaging server belonging to a central SAP instance, which distributes load across multiple application servers.

Do not open this configuration in TIBCO Designer. All parameters that may need to be customized are exposed in the launcher file, adr3Discoverer.tra.



The Inbound adapter can also establish dedicated connections to multiple application servers that may not be part of a messaging server configuration. To achieve this, the Inbound adapter should be configured for multiple Inbound Connections in the TIBCO Designer palette. During configuration, ensure that each BAPI/RFC/IDoc Service configured points to that application server to which Inbound messages for that service are posted. Refer to Configuring Multiple Connections for Inbound Instance on page 241 for details.



Event Driven Inbound Connections

This feature allows users to dynamically establish connections to the SAP system in an inbound adapter configuration. This feature provides flexibility to external systems and the following advantages acrue:

• The inbound adapter need not be connected to the SAP R/3 system always, if the RFC/BAPI Request-Response services or IDoc Subscription services configured in the adapter are not invoked frequently.

• External systems can login with specific authorizations in SAP after authentication and execute RFCs/BAPIs in SAP through the inbound adapter with these authorizations.

Connectionless Inbound ConfigurationsAny Inbound adapter can be configured to start up connectionless. Such an Inbound adapter configuration does not establish any connections to the SAP R/3 system during startup.

Request-Response and/or Subscription services configured in the adapter will make use of connections created dynamically.

A dynamic connection may be created in one of the following two ways:

— Based on logon parameters defined at design-time

— Based on logon parameters passed at run-time (explicit logon)

Based on the logon parameters defined at design-time

In this case, the adapter opens and closes connections on a per-message basis. The connection parameters for opening connections are picked up based on the Connection references configured for the corresponding Request-Response or Subscription services.


Event Driven Inbound Connections | 349

Configuration

To enable this feature, instruct the adapter not to establish connections on startup by browsing to R3Connections folder>ClientConnections folder for the particular configuration and selecting the Startup Connectionless check box in the Advanced tab for each of the configured Client connections.

Based on dynamic logon with different logon parameters and authorizations

In this case, the external system can logon to the SAP R/3 system by explicitly performing a logon operation in the adapter. Once logged on, the external system can use this SAP R/3 logon session for performing BAPI/RFC invocations in the SAP R/3 system.

This feature is available for BAPIs/RFCs only and not IDocs.

If an Inbound adapter is configured with Request-Response services for explicit logon, no client connection information is saved to the TIBCO Designer project. Hence, do not use this feature if you are configuring IDoc Subscription services.



To enable this feature,

1. Select the Show All Tabs at the adapter configuration level, go to the Adapter Services tab and select the Enable Connectionless check box as shown below.

2. Configure individual Request-Response services for explicit-logon. See Performing explicit logon for RFCs/BAPIs on page 350 for configuration details.

Performing explicit logon for RFCs/BAPIsAn RFC/BAPI Request-Response Service can be enabled for explicit logon by selecting the Logon Required check box in the Advanced tab for the RFC/BAPI service. The client system invoking the RFC/BAPI should use the Logon class for logging on to the SAP system. The Logon class is found under Schemas/Classes/ae/SAPAdapter40/classes in the TIBCO Designer project panel.

Any RFC from an external system to the Inbound adapter instance can be configured to require explicit logon in order to be serviced. Such an RFC cannot use connections established by the inbound adapter instance during initialization.

All inbound adapter instances expose Logon and Logoff operations. The RFC first obtains a valid connection by logging on to the inbound adapter instance after supplying valid logon information. This connection is used to service the RFC.

When configuring a Request-Response Service for an RFC, you can enable use of event driven inbound connections by selecting the Logon Required check box in the Advanced tab. See, Advanced Tab on page 188 for details. To obtain details of the Logon class use the Schemas folder in the project panel. The path is as follows:Schemas/Classes/ae/SAPAdapter40/classes

When the explicit logon feature is in use, the adapter’s load balancing functionalities, RVCMQ and multiple instances of the adapter cannot be used.


Event Driven Inbound Connections | 351

The inbound instance uses a preconfigured subject name to process logon requests. The subject name is preconfigured and cannot be modified.RFCClient.RPCServer.<adapter instance name>

To logon to the inbound adapter instance, appropriate attributes have to be set for the Logon class in the Request, and the operation must be invoked with the preconfigured subject.

If the logon operation is successful and a valid client connection to the SAP R/3 system is obtained through the inbound adapter instance, a Session ID is sent back in the reply to the calling system. The reply contains the Session ID in its RFCCLOSURE class. To obtain details of the RFCCLOSURE class use the Schemas folder in the project panel. The path is as follows:Schemas/Classes/ae/SAPAdapter40/classes

The external system invokes the RFC with this Session ID to be serviced by the inbound adapter instance. By default, the external system can continue to use this Session ID for all subsequent invocations of this RFC. When the session is no longer required, the connection to the SAP R/3 system is closed by explicitly logging off from the SAP R/3 system through the same inbound adapter instance. To obtain details of the Logoff class use the Schemas folder in the project panel. The path is as follows:Schemas/Classes/ae/SAPAdapter40/classes

The inbound instance uses a preconfigured subject name to process logoff requests. The subject name is preconfigured and cannot be modified.RFCClient.RPCServer.<adapter instance name>

The Session ID obtained after logon is passed in the request.

If the external system requires a separate connection for each invocation, each invocation should be preceded by a separate logon request. Each invocation of the RFC needs to be populated with the appropriate Session ID. However, in such cases, explicit logoff is not necessary. To terminate the session and disconnect from the SAP R/3 system, the attribute bLogoutAfterCall in RFCCLOSURE should be set to TRUE and the appropriate Session ID must be populated. If bLogoutAfterCall is set to true, the connection is closed on servicing the RFC. By default, bLogoutAfterCall is FALSE.

The following attributes are not supported for RFCs that require authentication:

• useSAPGUI

• abapDebug

• rfcTrace



While the Logon-Required property for an RFC is at an RFC level and has to be determined at design time, the termination of a session with bLogoutAfterCall is at individual invocation level and can be determined at run-time by the external system.


Running an Adapter Instance on Two SAP R/3 Systems with a Single Connection | 353

Running an Adapter Instance on Two SAP R/3 Systems with a

Single Connection

This section describes how to configure an adapter instance to run on two SAP R/3 systems with a single connection.

Sample Scenario Assume a sample scenario with two SAP systems, one named CER and the other, LCM. Each has RFC destinations named RFCTEST with program id = RFCTEST (sm59 transaction). Assume also that you have configured an adapter instance (Outbound) to run on CER (for example). Refer to the following procedure to configure the other system (LCM) so that it can use the same SAP R/3 adapter instance.

Procedure

1. Log in to the second system, LCM, and invoke sm59 transaction.

Figure 14 RFC Destinations



2. Click on Find, and enter the name of your RFC Destination as shown in Figure 15. (This example assumes the name RFCTEST.)

Figure 15 Find RFC Destinations Screen

3. Click on Continue and the following screen appears:

Figure 16 RFC Destination RFCTEST Screen

4. From the menu options, select Destination>Gateway options as shown in the next screen.



Figure 17 Select Gateway Options Pull-down Menu

The following window appears:



Figure 18 Select Gateway Host and Gateway Service Dialog Box

5. Enter the values for Gateway host and Gateway Service that corresponds to the system against which the adapter is already running (recall in this scenario, it is CER).

6. Fill the entries as shown in the next screen.

Figure 19 Completed Gateway Options Dialog Box

7. Save the destination.

8. Test the connection using the Test Connection button on the button bar. It should show OK.

When assigning a specific gateway host to an RFC destination, you must ensure that this gateway host is available at all times. Regardless of whether or not you are able to make an RFC request from another host, if the specified gateway host is unavailable, then the RFC request to the adapter will not be successful.



Figure 20 Test Connection Button

Now, you’re ready to run the adapter from the other system (LCM in our scenario).

However, the disadvantage in this scenario is that if the SAP system’s CER is down, the adapter instance cannot obtain messages from the other SAP system’s LCM. In a scenario where one instance of the adapter can connect to multiple program IDs of multiple SAP systems the problem does not arise.


| 359

Chapter 11 Monitoring the Adapter Using TIBCO Hawk

This chapter explains how to use TIBCO Hawk microagents to monitor and manage the adapter.

Topics


• Starting TIBCO Hawk Software, page 361

• The Auto-Discovery Process, page 362

• Invoking Microagent Methods, page 363

• Available Microagents, page 365


360 | Chapter 11 Monitoring the Adapter Using TIBCO Hawk

Overview

TIBCO Hawk is a sophisticated tool for enterprise-wide monitoring and managing of all distributed applications and systems. System administrators can use it to monitor adapters in a wide area network of any size. TIBCO Hawk can be configured to monitor system and adapter parameters and to take actions when predefined conditions occur. These actions include: sending alarms that are graphically displayed in the TIBCO Hawk display, sending email, paging, running executables, or modifying the behavior of a managed adapter.

Unlike other monitoring applications, TIBCO Hawk relies on a purely distributed intelligent agent architecture using publish or subscribe to distribute alerts. TIBCO Hawk uses TIBCO Rendezvous for all messaging and thus gains the benefits and scalability from the TIBCO Rendezvous features of publish/subscribe, subject name addressing, interest-based routing, and reliable multicast.

TIBCO Hawk is a purely event-based system that uses alerts. The agents are configured with rules that instruct them on everything from what and how to monitor to what actions to take when problems are discovered. Thus the workload is fully distributed throughout the enterprise. Every agent is autonomous in that it does not depend on other components to perform its functions.

The TIBCO Hawk Enterprise Monitor consists of these components:

• Display—GUI front end that displays alarms and provides editors to create rule bases, create tests, view messages, and invoke microagents to request information or initiate an action.

• Agents—Intelligent processes that perform monitoring and take actions as defined in rules.

• Rulebases—Rules that are loaded by agents to determine agent behavior.

• Application Management Interface (AMI)—Manages network applications via TIBCO Rendezvous and supports communication between a network application and monitoring TIBCO Hawk agents, including the ability to examine application variables, invoke methods, and monitor system performance.

• Microagents—Feed information back to TIBCO Hawk and expose action methods to rulebases.

For more information, see the TIBCO Hawk documentation.


Starting TIBCO Hawk Software | 361

Starting TIBCO Hawk Software

The TIBCO Hawk agent can be configured to start automatically during the system boot cycle. See the TIBCO Hawk Installation and Configuration guide for information about starting TIBCO Hawk.

The TIBCO Hawk Administrator’s Guide explains how to start the TIBCO Hawk Display.

The guides are included in your TIBCO Hawk software installation area.



The Auto-Discovery Process

After you start an instance of TIBCO Hawk Display, it continually discovers machines running TIBCO Hawk Agents on your network. Container icons are created for each agent, and arranged hierarchically in clusters. By default, agent icons are clustered according to subnets.

At first, the Agents container is empty. Its counter displays a value of zero and, on the right, the Discovered counter is also at zero. Both icons are initially green in color to show that no alerts, or warning messages, are in effect. As agents are discovered, the counters increment to reflect the current number of discovered agents:

Monitored network nodes are arranged in a hierarchical tree of containers. Clicking a container in the left panel displays nested items on the right.

Icon colors change to reflect the highest level of alert found on discovered agents. For explanations of icon elements and characteristics, see your TIBCO Hawk Administrator’s Guide.


Invoking Microagent Methods | 363

Invoking Microagent Methods

A set of default microagents, platform-specific and platform-independent, is loaded when a TIBCO Hawk Agent is started. When you install and start the TIBCO Adapter for R/3, microagents for the adapter are dynamically added to the local agent.

The following steps describe how to invoke a microagent method by specifying a microagent, method name, and optional method arguments.

To invoke a microagent method on a TIBCO Hawk Agent:

1. In TIBCO Hawk Display, right-click on the agent icon and select Get Microagents.

If TIBCO Hawk security is implemented on your system and you do not have access to microagents on this agent, an error dialog displays. Select another agent, or contact your system administrator to obtain access.

2. The Microagents, Methods and Arguments dialog displays. The panel on the upper left lists microagents you can access on the current agent.

This dialog has two modes, Invoke and Subscribe. Invoking a method immediately returns a single set of current results. Subscribing provides updates of current results at regular intervals. Radio buttons at the bottom of the dialog control these modes.

3. Click a microagent name, such as Self, to display a list of associated methods and text descriptions in the panels below.



4. Select Get MicroAgents. The MicroAgents Methods, and Arguments window appears as shown in the figure below.

If the method accepts arguments, fields for each argument display in the upper right panel. Detailed help text displays in the lower panel.

5. Specify any arguments for the method invocation.

6. Verify that the Invoke radio button is selected.Click the Invoke button to invoke the selected method.

The Invocation Results dialog displays the results returned by the method.

7. Click Done to close the dialog.

These steps describe how to interactively invoke a microagent method and receive a single set of results in TIBCO Hawk Display. You can also use a microagent method as the data source of a TIBCO Hawk rule. Rules automatically receive method results, apply tests to evaluate them, then take action if necessary. For more information on building TIBCO Hawk rules and rule bases, see your TIBCO Hawk Administrator’s Guide.


Available Microagents | 365

Available Microagents

Each adapter has three microagents, a standard TIBCO Hawk microagent named COM.TIBCO.ADAPTER.xyz where xyz is the adapter configuration name, a custom microagent and a class microagent. The microagents provide:

• Business level statistics—statistics that report the progress of the adapter as it interacts with the vendor application. For example, in a database adapter such statistics might indicate whether objects were successfully or unsuccessfully inserted, updated, or deleted in the database.

• Queries that return information about the state of the adapter. This can be an important tool for seeing the internals of an adapter and debugging it if something appears wrong. For example, methods can return information about threads, internal queues, or connections to the target system. Using these methods, one might be able to identify certain bottlenecks or gauge how successfully an adapter is scaling with respect to the current environment.

• Updates of the adapter runtime parameters. This includes retrieving the current runtime parameters and setting new runtime parameters without restarting the adapter. An example of this is getting and setting the polling interval. Updating a runtime parameter through the Hawk microagent only affects the setting of the instance that is running. It does not make a permanent change of the setting in either the repository or the .tra file.

By default all microagents, custom, standard and class microagents are available at runtime.

perfMon property value set in the adapter’s property file affects the business statistics related methods. If this property is set to on, the adapter does all the performance related calculations. When you invoke the methods, if the perfMon property is set to off, default values are displayed and not the valid values.

You can disallow adding custom methods to the class microagent when deploying the adapter by changing the addCustomHawkMethodstoClassMAgent property value in the adapter’s property file. If this property is set to on, custom methods are added to the class microagents. If set to off, these methods are not visible. See Adapter Properties File on page 306 for more information.

Custom microagents are deprecated in this release. All business statistics related methods which were part of the custom microagent are now available in the class microagent.



The following table lists each method available for the adapter and page on which the method is explained.

Table 24 Microagent Methods

Method Description Page

activateTraceRole() Activates a mapping of a role to a sink at runtime.

369

deactivateTraceRole() Deactivates a mapping of a roles to sinks at runtime.

370

getActivityStatisticsByOperation(Operation)

Returns statistics about one operation. 371

getActivityStatisticsBySchema(SchemaName)

Returns statistics about any activities on a particular object or schema.

372

getActivityStatisticsByService(ServiceName)

Returns statistics about the data handled by a particular adapter service since it was started.

373

getAdapterServiceInformation()

Returns information about the services implemented by this adapter.

374

getComponents() Returns information about the publisher, subscriber and IODescriptor.

375

getConfig() Returns basic configuration information. More specific information is accessed by the more specific methods.

376

getConfigProperties() Returns a list of publishers and subscribers.

377

getConfiguredRFCs() Returns a list of all configured RFC functions.

378

getConnectionStatistics() Returns the state and statistics for all the current connections used by the adapter.

379

getHostInformation() Returns standard and extended application information.

380

getPerfMonSetting() Returns the setting of the perfMon option.

381


Available Microagents | 367

getQueueStatistics() Returns the current count of elements in any internal queue used by the adapter.

382

getRvConfig() Returns information about all TIBCO Rendezvous sessions defined.

383

getStatus() Returns general status information, such as the number of TIBCO Rendezvous messages received and published, the number of errors since the last call, the PID of the application, and more.

384

getThreadStatistics() Returns the operation counts of the current threads.

385

getTraceSinks() Returns information about sinks to which traces currently go.

386

getVersion() Returns the instance ID, application name, version, and date for this adapter instance.

387

_onUnsolictedMsg() Displays alert messages sent to the current adapter.

388

preRegisterListener() Preregisters an anticipated listener. 389

refreshABAPContext() Refreshes the ABAP context held by the adapter connections.

390

resetActivityStatistics() Resets all the counts for the activity statistics.

391

resetConnectionStatistics() Resets all the counts for the connection statistics.

392

resetThreadStatistics() Resets all the counts for the thread statistics.

393

reviewLedger() Returns information retrieved from the ledger file of a certified messaging session for a publisher adapter.

394

Table 24 Microagent Methods (Cont’d)




setTraceSinks() Adds a role or changes the file limit of a previously specified sink.

396

stopApplicationInstance() Stops the running adapter instance. 397

unRegisterListener() Unregisters a currently preregistered listener.

398

Table 24 Microagent Methods (Cont’d)



activateTraceRole() | 369

activateTraceRole()

Activates a mapping of a role to a sink at runtime. This replaces the now-deprecated setTraceSink() TIBCO Hawk method.

Parameters Type Description

Role Name string Name of the role to activate.

Sink Name string Name of the sink for which to activate the role.



deactivateTraceRole()

Deactivates a mapping of a roles to sinks at runtime.


Role Name string Name of the role to activate.

Sink Name string Name of the sink for which to activate the role.


getActivityStatisticsByOperation(Operation) | 371

getActivityStatisticsByOperation(Operation)

Returns the total number of objects processed for all the schemas by each service that is associated with a specified operation. Also, returns the number of success and error objects.

Parameter Type Description

Operation string Type of operation - read or write.

Returns Type Description

Service Name string Name of the service that is associated with the specified operation.

Total string Total number of objects processed for this schema for a publication service.

Total number of objects received for this schema for a subscription service.

Success string The number of objects that were successfully identified for this schema which will be published or written to a file.

Error string The number of objects that were identified for this schema but were not published because the header of the schema failed validation for the publication service, or was written to a file because the schema was not associated with the subscriber for a subscription service.



getActivityStatisticsBySchema(SchemaName)

Returns the total number of objects processed for the given schema by each service that uses the schema. Also, returns the number of success and error objects.


Schema Name string Name of the schema.


Service Name string Name of the service that is associated with the specified schema.

Total string Total number of objects processed for this schema for a publication service.

Total number of objects received for this schema for a subscription service.




getActivityStatisticsByService(ServiceName) | 373

getActivityStatisticsByService(ServiceName)

Returns the total number of objects processed for each of the schemas associated with the specified service. Also, returns the number of success and error objects.


Service Name string Name of the service.


Operation string Type of operation that the service performs.

Schema Name string Name of the schema that is associated with the service.

Total string Number of objects processed for this schema for a publication service.

Number of objects received for this schema for a subscription service.





getAdapterServicesInformation()

Returns information about the services implemented by this adapter. The information is a summary of available adapter services.


Service Name string Name of the service from which to get information. Default is ALL.


Line integer Sequential row number.

Service Name string Name of the service as defined at design-time.

Endpoint Name string Name of the endpoint used for this service.

Type string Type of the endpoint, for example, publisher or subscriber.

Quality of Service

string Quality of service for the endpoint. For example RVCM or JMS Persistent.

Subject string Subject defined for this endpoint.

Class string Class associated with the endpoint.

Number of Messages

integer Number of messages processed for this endpoint.


getComponents() | 375

getComponents()

Returns information about the currently active TIBCO Hawk components such as publishers, subscribers, or timers.


Component Name string Name of the component. If no value is enter, all components display.

Component Type string Any of Publisher, Subscriber, Timer, or IODescriptor. The default value is All.


Instance ID string Name of this adapter instance as defined at design-time.

Adapter Name string Name of the adapter.

Component Name string Name of the component.

Component Type string The name of the TIBCO Adapter SDK class for this component, such as MPublisher, MSubscriber, or MIODescriptorSource. For more information about the class, see your TIBCO Adapter SDK documentation.

Session Name string Name of the session.

Description string Information about this component, for example, time interval, signal type, validating publisher (or subscriber) etc.



getConfig()

Retrieves generic configuration information. More specific configuration information is accessed through separate methods.


Instance ID string Configuration ID of this adapter.


Repository Connection

string URL of the repository used for adapter instance.

Configuration URL

string Location of the adapter project; either a file name or configuration URL.

Command string Command line arguments used to start the adapter.


getConfigProperties() | 377

getConfigProperties()

Returns all attributes and elements for the given repository object.


Property string Name of the property for which elements (tags) and attributes are desired. For example, agentone/startup.

If no value is given, all properties are returned.


Element Name string Repository directory for the property.

Attribute Name string Name of the repository object attribute.

Attribute Value string Value of the repository object attribute.

Line integer Line number in which this property is defined in the project file.



getConfiguredRFCs()

Returns a list of all configured RFC functions.


getConnectionStatistics() | 379

getConnectionStatistics()

Returns the state and statistics for all the current connections used by the adapter.


Connection ID string A unique identification of a particular connection.

Connection Type string A type or key that will match this connection to a thread or queue.

State string Current state: CONNECTED or DISCONNECTED

NumRetries integer Total number of times this connection had to be reestablished.

TotalNumOperations

integer Total number of operations processed by this connection since the adapter started.

CurrentNumOperations

integer Total number of operations processed by this connection since the last reconnection.



getHostInformation()

Return standard and extended application information set. It returns the following information.


Name string Name of the property.

Value string Value of the property.


getPerfMonSetting() | 381

getPerfMonSetting()

Return the setting of the perfMon option. It returns the following information.


Setting string Value of the perfMon option.



getQueueStatistics()

Return the current count of elements in any internal queue used by the adapter. This includes the TIBCO Rendezvous event queues automatically spawned by Rendezvous for each adapter.


QueueID string A unique identification of a particular queue.

QueueType string A type or key that will match this queue to a thread or connection.

QueueCount integer Current number of elements in the queue.

MaxQueueSize integer Maximum number of elements in the queue.


getRvConfig() | 383

getRvConfig()

Returns information about the TIBCO Rendezvous session defined by this adapter. Information about all currently defined sessions is returned if no sessionName is provided.


Session Name string Name of the TIBCO Rendezvous session for which configuration is required (default is all).


Instance ID string The configuration ID of this adapter.


Session Name string Name of the session.

Service string Service parameter for this session.

Daemon string Daemon parameter for this session.

Network string Network parameter for this session.

Synchronous? boolean Returns 1 if this is a synchronous session, 0 otherwise.

Session Type string Type of session; one of M_RV, M_RVCM, or M_RVCMQ.

Certified Name string Name of this certified session.

Ledger File string Ledger file for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions.

CM Timeout string Timeout for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions.



getStatus()

Retrieves basic status information about the adapter.

This information is fairly limited; for more detail, additional methods are provided (getConfig() on page 75 and getRvConfig() on page 77.


Instance ID string Configuration ID for this adapter instance.


Uptime integer Number of seconds since startup.

Messages Received integer Number of TIBCO Rendezvous messages received.

Messages Sent integer Number of TIBCO Rendezvous messages published.

New Errors integer Number of errors since the last call to this method.

Total Errors integer Total number of errors since startup.

Process ID integer Process ID of the application.

Host string Name of host machine on which this adapter is running.


getThreadStatistics() | 385

getThreadStatistics()

Return the operation counts of the current threads.


ThreadID string A unique identification of a particular thread.

ThreadType string A type or key that will match this thread to a queue or connection.

TaskType string Short description of the tasks this thread processes.

TaskCount integer Number of tasks processed by this thread.



getTraceSinks()

Returns information about sinks to which traces currently go.


Sink Name string Name of the sink for which you need information. If no name is specified, information about all sinks is returned. Default is all.

Role Name string Name of the role for which you need information for the specified sink or sinks. Default is all.


Instance ID string Name of this adapter instance as a string.

Adapter Name string Name of the application for this sink.

Sink Name string Name of the sink

Sink Type string Type of this sink. One of fileSink, rvSink, hawkSink, stderrSink.

Roles string Roles this sink supports, as a string. For example “warning, error, debug”.


getVersion() | 387

getVersion()

Retrieves version information for the current application. Two lines may be returned, one for the TIBCO Adapter SDK, one for the adapter.

Returns Description

Instance ID The configuration ID as a string, for example SDK.

Adapter Name Name of the adapter as a string, for example agentone.

Version Version number as a string, for example 1.1.



_onUnsolictedMsg()

Displays all alert messages sent from the adapter or an error if not successful.


preRegisterListener() | 389

preRegisterListener()

Preregister an anticipated listener. Some sending applications can anticipate requests for certified delivery even before the listening applications start running. In such situations, the sender can preregister listeners, so TIBCO Rendezvous software begins storing outbound messages in the sender’s ledger. If the listening correspondent requires old messages, it receives the backlogged messages when it requests certified deliver.

Returns OK if the listener was preregistered successfully, false otherwise.


Session Name string Name of the session that anticipates the listener.

Publisher Name string Name of the component for which the listener should be preregistered.

Listener Session Name

string Name of the listener to preregister.



refreshABAPContext()

Refreshes the ABAP context held by the adapter connections.

Parameters

None

Returns

None


resetActivityStatistics() | 391

resetActivityStatistics()

Resets all the counts for the activity statistics.



resetConnectionStatistics()

Resets all the counts for the connection statistics.


resetThreadStatistics() | 393

resetThreadStatistics()

Resets all the counts for the thread statistics.



reviewLedger()

Returns information retrieved from the ledger file of a TIBCO Rendezvous certified messaging session.

Before invoking this method, ensure that the certified messaging publisher adapter has established a certified delivery agreement with its subscriber agents.


Session Name string Name of the TIBCO Rendezvous session for which ledger information is desired (default is all).

Subject string Name of the subject for which ledger information is desired.


Session Name string Name of the TIBCO Rendezvous CM session to which this information applies.

Subject string Subject name for this session.

Last Sent Message integer Sequence number of the most recently sent message with this subject name.

Total Messages string Total number of pending messages with this subject name.

Total Size integer Total storage (in bytes) occupied by all pending messages with this subject name.

If the ledger contains ten messages with this subject name, then this field sums the storage space over all of them.


string Within each listener submessage, the Listener Session Name field contains the name of the delivery-tracking listener session.


reviewLedger() | 395

Last Confirmed string Within each listener submessage, the Last Confirmed field contains the sequence number of the last message for which this listener session confirmed delivery.

Line integer Row number in ledger file.

UnacknowledgedMessages

integer Number of RVCM messages pending for this listener. The value is computed by subtracting the last sent sequence number from the last acknowledged sequence number.

Returns (Cont’d) Type Description



setTraceSinks()

Adds a role or changes the file limit of a previously specified sink.

Returns OK if successful or an error if not successful.


Sink Name string Name of the sink for which you want to add a role or change the file limit.

Role Name string Name of the role you want to add to this sink (warning, error, debug, or user defined). Default is all.

File Size integer Maximum file size for this sink.

This parameter is ignored if the sink specified by sinkName is not a file sink.


stopApplicationInstance() | 397

stopApplicationInstance()

Stops the specified adapter by calling the internal stop() method. This method returns OK if successful or an error if not successful.



unRegisterListener()

Unregister a currently preregistered listener

This method returns true if the listener was unregistered successfully, false otherwise.


Session Name string Name of the session that anticipates the listener.

Publisher Name string Name of the component for which the listener should be preregistered.


string Name of the listener to unregister.


| 399

Appendix A Trace Messages

This appendix explains the trace messages that are logged to a location specified at configuration time.

Topics


• Trace Message Fields, page 402

• Status Messages, page 405


400 | Appendix A Trace Messages

Overview

Trace messages provide information about adapter activities. The messages are logged to the console where the runtime adapter was started and to a log file. Trace messages can also be redirected to the TIBCO Hawk Display application, or sent to other applications using the TIBCO Rendezvous transport.

Each trace message can include the following fields:

<Timestamp> <Adapter Identifier> <Role> <Category> <Status Code> <Tracking Identifier>

The above fields are explained in Trace Message Fields on page 402. The following diagram shows an example trace message and calls out the fields.

Example Trace Messages

The following trace messages were written during a session where TIBCO Adapter for R/3 received a message from the SAP R/3 system.

The first message indicates that TIBCO Adapter for R/3 has started. The timestamp indicates when the adapter started, and the role indicates that the trace message is informational, which means the activity is normal for the adapter. The category is identified, and the corresponding status code is displayed. The status code indicates that the adapter started successfully.

2003 Jan 24 10:46:10:486 GMT 5 SAPAdapter.SALESORDER-OUT Info [Adapter] AER3-000082 Successful initialization of Adapter

The next set of trace messages indicates the adapter received a message from the SAP R/3 system. The #-0Y--C--DX1ALUbc--4zzzw-TEzzw# tracking identifier included in the trace message uniquely identifies the message. 2003 Jan 24 10:47:18:644 GMT 5 SAPAdapter.SALESORDER-OUT Info [Adapter] AER3-000114 Received invocation request for BAPI_SALESORDER_CREATEFROMDAT1 from SAP R/3 System tracking=#-0Y--C--DX1ALUbc--4zzzw-TEzzw#

2003 Feb 22 20:15:12:937 GMT -8

R/3Adapter.R/3AdapterConfiguration Info [Adapter]

tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

Timestamp

Adapter Identifier Role Category

Status Code

Tracking Identifier

AER3-000114 Received invocation request for.....


Overview | 401



Trace Message Fields

Each trace message includes the following fields:

Table 25 Tracing Fields

Field Name Description

Timestamp Timestamp of occurrence. For example, 2003 Feb 22 20:14:51:718 GMT -8.

Adapter Identifier

Name of the adapter that wrote the trace message. This is a combination of the adapter acronym and adapter configuration name. For example, the application identifier, ADB.publisher1 identifies a TIBCO Adapter for ActiveDatabase service named publisher1.

Role A role can be:

• Info. Indicates normal adapter operation. No action is necessary. A tracing message tagged with Info indicates that a significant processing step was reached and has been logged for tracking or auditing purposes. Only info messages preceding a tracking identifier are considered significant steps.

• Warn. An abnormal condition was found. Processing will continue, but special attention from an administrator is recommended.

• Error. An unrecoverable error occurred. Depending on the error severity, the adapter may continue with the next operation or may stop altogether.

• Debug. A developer-defined tracing message. In normal operating conditions, debug messages should not display.

When configuring the adapter you define what roles should or should not be logged. For example, you may decide not to log Info roles to increase performance.


Trace Message Fields | 403

Category One of the following:

• Adapter. The adapter is processing an event.

• Application. The adapter is interacting with the SAP R/3 system.

• Configuration. The adapter is reading configuration information.

• Database. The adapter is interacting with a database.

• DTA. (Design-time adapter) The trace message if from the DTA.

• Metadata. The adapter is retrieving metadata from the SAP R/3 system.

• Palette. The adapter is interacting with the palette.

• Publisher Service. The publication service is reporting this trace message.

• Request-Response Client Service. The request-response invocation service is reporting this trace message.

• Request-Response Server. The request-response service is reporting this trace message.

• Shutdown. The adapter is shutting down.

• Startup. The adapter is starting.

• Subscription Service. The subscription service is reporting this trace message.

• System. This category is not linked to a specific event process. The trace message may be related to a Windows service related messages, memory allocation, file system error, and so on.

• TibRvComm. The adapter is communicating with TIBCO Rendezvous.

• XML. The adapter is parsing XML documents.

Status Code Unique code for the message and description. Status codes are identified by a unique number and description. If a trace message includes an error or warn role, the status code documentation includes a resolution. See Status Messages on page 405 for details.





Tracking Identifier

A unique identifier that is "stamped" on each message by the originating adapter. The tracking identifier remains in effect from a message’s beginning to its completion as it is exchanged by TIBCO applications. If the adapter is the termination point of the message, the tracking identifier is not displayed in the trace message.

You cannot modify the tracking identifier format or configure what information is displayed.

Application Information

Application-specific information added to the tracking info to trace the message back to its source. Set initially by the originating adapter and carried forward. It is augmented by each intermediate component.




Status Messages | 405

Status Messages

The following table lists all the new error messages introduced in this release. They are sorted in alphabetical order.

Status Code Role Category Resolution

AER3-910003 Startup Error. The command-line parameter(s): configurl, repourl have not been specified

Error Startup Please specify the command-line parameters configURL and repoURL. Refer to User Guide documentation chapter 7

AER3-910005 Startup Error. SDK Error %1 received during initialization. The Repository URL is %2 and the Configuration URL is %3

Error Startup Please verify your repository settings

AER3-910006 Startup Error. SDK Exception %1 occurred while creating a shutdown listener with parameters %2. The Repository URL is %3 and the Configuration URL is %4

Error Startup Please verify your repository settings for validity of configuration for the shut down listener

AER3-910007 Startup Error. Unable to create a connection with the target application %1 using connection parameters %2 and the target application error is %3

Error Startup Please verify your repository settings for validity of connection parameters

AER3-9100012 Startup Error. Unable to create a Custom Hawk Micro Agent Named %1 used for %2

Error Startup Please verify your repository settings for validity of the stop-subscriber session parameters



AER3-940001 Request Response error. Request Response service %1 listening on %2 received unexpected null data in incoming request. Expects event %3. The Repository URL is %4 and the Configuration URL is %5

Error RequestResponse Please check the configuration of the application that is requesting the event and make sure that it matches the inbound event definition for the above Request-Response service. Please refer to User Guide Chapter 4 for details on configuration of Request-Response service

AER3-940005 Request Response error. Request Response service %1 failed to deserialize the received Request to MInstance: Received event on subject %2, event = %3, SDK exception = %4. The Repository URL is %5 and the Configuration URL is %6

Error RequestResponse Please check the configuration of the application that is requesting the event and make sure that it matches the inbound event definition for the above Request-Response service. Please refer to User Guide Chapter 4 for details on configuration of Request-Response service

AER3-940008 Request Response error. Connection error in invocation of Request Response service %1 listening on subject %2. Connection Parameters are %3

Error RequestResponse Check if the end application is up and running. Also verify the connection parameters that are specified in the repository

AER3-940009 Request Response error. Request Response service %1 listening on subject %2 failed due to target application invocation error %3. Target application is %4 and inbound event is %5

Error RequestResponse Please check the validity of the incoming request-data to the Request-Response service




AER3-9400010 Request Response error. Request Response service %1 listening on subject %2 failed to create reply. Error : %3

Error RequestResponse Please verify the data received from the SAP system and make sure it matches the schema associated to the Request-Response service

AER3-920001 Subscription error. Subscription service %1 listening on %2 received an unexpected event of type = %3, Expects event %4. The Repository URL is %5 and the Configuration URL is %6

Error Subscription Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please refer to User Guide Chapter 4 for details on configuration of subscription service

AER3-920002 Subscription error. Subscription service %1 failed to deserialize the event received on subject %2 and SDK exception thrown is %3. The Repository URL is %4 and the Configuration URL is %5


AER3-920003 Subscription error. Subscription service %1 listening on subject %2 received inbound event with null data. The Repository URL is %3 and the Configuration URL is %4





AER3-920007 Subscription error. Subscription service %1 listening on subject %2 could not get the class description of %3. The Repository URL is %4 and the Configuration URL is %5

Error Subscription Please check the repository configuration for this service. Please refer to User Guide Chapter 4 for details on how to configure, run and test the subscription service

AER3-920008 Subscription error. Subscription service %1 listening on subject %2 could not find the mandatory property %3 in class %4. The Repository URL is %5 and the Configuration URL is %6


AER3-9200015 Subscription error. Subscription service %1 listening on subject %2 failed due to target application invocation error %3. Target application is %4

Error Subscription Please verify the structure of the incoming message. Check in the SAP system for more detailed information on the cause of the error

AER3-950001 Request Response Invocation error. Request Response Invocation service %1 with subject as %2 received event from target application %3. It failed while converting event to request, as it could not get the class description for %4. Repository URL is %5 and the Configuration URL is %6

Error RequestResponseInvocation

Please verify the configuration of the Request-Response Invocation Service and check that the schema/class definitions are present in the repository. Please refer to User Guide Chapter 4 for details on how to configure a Request-Response Invocation Service




AER3-950003 Request Response Invocation error. Request Response Invocation service %1 with subject as %2 received event from target application %3. It failed while converting event to request. Repository URL is %5 and the Configuration URL is %6


Please verify the configuration of the Request-Response Invocation Service and check that the schema/class definitions are present in the repository. Please refer to User Guide Chapter 4 for details on how to configure a Request-Response Invocation Service

AER3-950008 Request Response Invocation error. Request Response Invocation service %1 with subject %2 received error while requesting event over the wire. Error %3


Please check repository settings for valid configuration of the Request-Response Invocation endpoint for this service. Please refer to User Guide Chapter 4 for details on setting up a Request-Response Invocation end point and a Request-Response Invocation service

AER3-950009 Request Response Invocation error. Request Response Invocation service %1 with subject %2 received error while requesting event over the wire. Error %3



AER3-9500010 Request Response Invocation error. Request Response Invocation service %1 with subject %2 received null reply while requesting event over the wire


Please check the target application, if it is running or not. Please check the configuration of Request-Response Invocation service




AER3-9500011 Request Response Invocation error. Request Response Invocation service %1 with subject %2 received timeout error while requesting event over the wire



AER3-9500012 Request Response Invocation error. Request Response Invocation service %1 with subject %2 received error while processing reply message. Error %3



AER3-930003 Publication error. Publication service %1 with publishing subject as %2 received event from target application %3. It failed while converting event to MInstance as it could not get the class description for %4. Repository URL is %5 and the Configuration URL is %6’

Error Publication Please verify the configuration of the publication service and check that the schema/class definitions are present in the repository. Please refer to User Guide Chapter 4 for details on how to configure a Publication service




AER3-930006 Publication error. Publication service %1 with publishing subject %2 received the event from target application %3. It failed while converting event to MInstance attribute %4 of class %5 is missing. RepositoryURL is %6 and the ConfigurationURL is %’

Error Publication Please verify the configuration of the publication service and check that the schema definitions are present in the repository. Please refer to User Guide Chapter 4 for details on how to configure a Publication service

AER3-9300014 Publication error. Publication service %1 with publication subject %2 received error while sending event over the wire. Error : %3

Error Publication Please check repository settings for valid configuration of the publish endpoint for this service. Please refer to User Guide Chapter 4 for details on setting up a publish end point and a Publication service

AER3-890006 Connection Error. Adapter stopping due to persistent connection errors to the SAP R/3 system(s)

Error Connection Please check the SAP R/3 system(s) connected to, and restart the adapter

AEADR3-600001 JMS Service Configured. This adapter version does not support JMS services, but one was found. Use the goto button to select it.

Warning Configuration You have configured a service with transport type as JMS. But the AE Version of this adapter instance does not support JMS. You may change the AE Version or make sure that the runtime version is higher than this version




AEADR3-600002 XML Wire Format found. This adapter version does not support XML Wire Format.

Warning Configuration You have configured a service with XML Wire Format. But the AE Version of this adapter instance does not support XML format. You may change the AE Version or make sure that the runtime version is higher than this version

AEADR3-600003 Subscriber in exploded batch mode found. This adapter version does not support Subscriber in Explode Batch Mode.

Warning Configuration You have configured a Subscription service with Exploded Batch Mode. But the AE Version of this adapter instance does not support Subscriber in Exploded Batch Mode. You may change the AE Version or make sure that the runtime version is higher than this version

AEADR3-600004 Connection Retry Mechanism Warning. This adapter version does not suspend services on connection failure. The configured value ’Adapter Termination Criteria’ will be ignored.

Warning Configuration You have configured a service with Connection Retry. But the AE Version of this adapter instance does not suspend services on connection failure. You may change the AE Version or the value of ’Adapter Termination Criteria’ will be ignored




AEADR3-600005 Connection Retry Mechanism Warning. This adapter version does not suspend services on connection failure. The configured values ’Number of Reconnect Attempts Before Suspending Impacted Service(s)’ and ’Adapter Termination Criteria’ will be ignored.

Warning Configuration You have configured a service with Connection Retry. But the AE Version of this adapter instance does not suspend services on connection failure. You may change the AE Version or the value of ’Adapter Termination Criteria’ will be ignored’

AEADR3-600006 Empty Service Found. The Service is not Configured Or Class Reference or Endpoint Reference is Empty.

Warning Configuration You have configured an adapter instance with a service which has no schema associated with it. Such an adapter instance cannot be used at run-time. Make sure that you do not have an empty service before deploying the adapter instance

AEADR3-600007 Absolute Path not Found. Field %1, Palette error. Unable to find specified absolute path. Make sure that you have specified the absolute path correctly.

Error Configuration Absolute path of the Plugin Directory not found. Check the path.

AEADR3-600008 Connection Failure. Test Connection Failed

Information DTA Test Connection to SAP R3 System failed. Please check your connection parameters.

AEADR3-600009 Connection Failure. %1

Information DTA Test Connection to SAP R3 System failed. Please check your connection parameters.

AEADR3-600010 Connection Success. Hostname - %1, System Name - %2, R-3 Release - %3

Information DTA Indicates normal adapter operation. No action necessary.




AEADR3-600011 Error copying Configuration information. Inbound Connection Type does not support copying

Error Configuration You are trying to copy Design-Time parameters to Run-Time Inbound Connection which is not of type Dedicated’.IfyouwanttocopymakesurethatthedefaultinboundconnectiontypeisDedicated.’

AEADR3-600012 Illegal Adapter Instance Name. Adapter Configuration names must have only alphanumeric characters with no embedded spaces and can be up to 80 characters long. \n Please type in a valid name.

Error Configuration Cannot rename the adapter instance. Please provide a valid name. Make sure you have entered alphanumeric characters, no blank spaces, and the name is not more than 80 characters.

AEADR3-600013 Subject Names. Do you wish to regenerate subjects set to previous defaults?

Error Configuration Click Yes to Regenerate

AEADR3-600014 Regenerate Names?. Do you wish to regenerate Subject Names, Connection Names and Session Parameters?

Warning Configuration Click Yes to Regenerate

AEADR3-600015 Replace Resource. The resource %1 is already defined as a type. Do you want to replace it?

Warning Configuration Click OK to continue

AEADR3-600016 Illegal Operation. The new nested name is in conflict with the name of the

Error Configuration Conflicting resource names. Try using a different name.

AEADR3-600017 Please Select an IDOC. You did not make a selection.

Error DTA Please select an IDOC




AEADR3-600018 Please Select an RFC Function. You did not make a selection.

Error DTA Please Select an RFC function

AEADR3-600019 IDOC Fetch Failed. %1

Error DTA No IDOCs were retrieved. Check your connection parameters and your IDOC filter criteria.

AEADR3-600020 RFC Fetch Failed. %1

Error DTA No RFCs were retrieved. Check your connection parameters and your RFC filter criteria.

AEADR3-600021 Reuse Schema Type. Schema for %1 already exists. Do you want to reuse existing schema?

Warning Schema This is a Yes/No option. Select Yes if you want to use the existing schema. Select No if you want to re-download the schema for the SAP R3 system.

AEADR3-600022 Deleting Operation Type. Do you want to delete %1 ?

Warning Configuration Delete confirmation. Select Yes to Delete.

AEADR3-600023 Invalid Value. Field %1, Palette error. This is not a valid value.

Error Configuration You tried to enter an invalid value in the connection parameters

AEADR3-600024 Invalid Value. Palette error. Endpoint Reference cannot have null value.

Error Configuration Endpoint Reference is empty. Please select a valid end-point reference.

AEADR3-600026 Filter Length Exceeded. Palette error. The RFC Filter cannot be more than 30 characters in Length. Please enter a filter value less than 30 characters in length.

Error DTA You have exceeded the filter length. Enter a filter value less than 30 characters in length.




AEADR3-600027 Filter Length Exceeded. Palette error. The RFC Group Filter cannot be more than 26 characters in Length. Please enter a filter value less than 26 characters in length.

Error DTA You have exceeded the filter length. Enter a filter value less than 26 characters in length.

AEADR3-600028 Illegal Operation. Selected Resource Can Not Be Moved

Error Configuration No resolution.

AEADR3-600029 Filter Applied to mandatory segments. You have applied the filter on the following mandatory segment(s) -

Warning Schema You have applied a filter on mandatory segments. Please uncheck the filter on these segments.

AEADR3-600030 Error Occurred. Error Creating Global Variables.

Error Repository Designer encountered error while creating global variables. You may have to manually create global variables in the Global Variables Pane.

AEADR3-600031 Not Found. No IDOCs Retrieved. Check the filter.

Information DTA Check IDOC Filter

AEADR3-600032 Not Found. No RFCs Retrieved. Check the filter.

Information DTA Check RFC Filter

AEADR3-600033 No List. IDoc List could not be retreived-%1’

Information DTA Check IDOC Filter

AEADR3-600034 No List. RFC - BAPI List could not beretreived-%1’

Information DTA Check RFC/BAPI Filter




AEADR3-600035 Error Occurred. Conflicting Services. A Publication Service, having the same Schema, is already configured.

Error Schema You already have a Publication service with the same schema. You cannot configure another service in the same adapter instance.

AEADR3-600036 Error Occurred. Conflicting Services. A Subscription Service, having the same Schema, is already configured.

Error Schema You already have a Subscription service with the same schema. You cannot configure another service in the same adapter instance.

AEADR3-600037 Error Occurred. Conflicting Services. A Request-Response Service, having the same Schema, is already configured.

Error Schema You already have a Request-Response service with the same schema. You cannot configure another service in the same adapter instance.

AEADR3-600038 Error Occurred. Conflicting Services. A Request-Response Invocation Service, having the same Schema, is already configured.

Error Schema You already have a Request-Response Invocation service with the same schema. You cannot configure another service in the same adapter instance.

AEADR3-600039 Download Operation Schema. Schema for operation %1 is already available, Use existing schema?

Warning Schema Click Yes to reuse existing schema. Click No to re-download schema from SAP R3 system.

AEADR3-600040 Regenerate Resources ? Do you want to regenerate endpoint and subject information?

Warning Endpoint Click Yes to regenerate




AEADR3-600041 Regenerate Resources? Do You want to regenerate Subject Names and Session Parameters?

Warning Configuration Click Yes to regenerate

AEADR3-600042 Regenerate Connections. Do You want to regenerate Connection Names?

Warning Configuration Click Yes to regenerate Connection Names.

AEADR3-600043 Error while pasting. Deserialization of Schema Failed.

Error Schema Copy/Paste of schemas failed. Try configuring again.

AEADR3-600044 Error while pasting. Deserialization of R3 Connections Failed.

Error Configuration Copy/Paste of connections failed. Try configuring again.

AEADR3-600045 Error while writing the Meta Url.

Error Configuration Error in Meta URL. Try configuring again.

AEADR3-600046 Inbound TID Management Warning. This adapter version does not support Inbound TID Management.

Warning Configuration You have configured an adapter instance with Inbound TID Management. But the AE Version of this adapter instance does not support Inbound TID Management. You may change the AE Version or make sure that the runtime version is higher than this version

AEADR3-600047 Advanced Logging Warning. This adapter version does not support advanced logging to a file.

Warning Configuration You have configured an adapter instance with advanced logging. But the AE Version of this adapter instance does not support advanced logging to a file. You may change the AE Version or make sure that the runtime version is higher than this version




AEADR3-600048 Confirm Publisher Warning. This adapter version does not support confirm publisher on the inbound side.

Warning Configuration You have configured an adapter instance with advanced logging. But the AE Version of this adapter instance does not support advanced logging to a file. You may change the AE Version or make sure that the runtime version is higher than this version.

AEADR3-600049 Valid destination Warning. This adapter version does not support Validating destination on the inbound side

Warning Configuration You have configured an adapter instance to validate destination on the inbound side. But the AE Version of this adapter instance does not support validating destination on the inbound side. You may change the AE Version or make sure that the runtime version is higher than this version.

AEADR3-600050 Not Checked out. Failed to update Schema. The associated Schema files are not checked out from source control.

Error Configuration Please check out schema files from the source control

AEADR3-600051 Illegal child error occurred while processing connection - %1

Error Configuration Error while processing R3 Connection. Try configuring again.

AEADR3-600052 Name conflict error occurred while processing connection - %1

Error Configuration Error while processing R3 Connection. Try configuring again.

AEADR3-600053 Error occurred while applying changes to connection - %1

Error Configuration Error while applying changes to R3 Connection. Try configuring again.




AEADR3-600054 Not Checked out. Failed to update R3Connections. The connection file is not checked out from source control

Error Configuration Please check out the connection file from source control

AEADR3-600055 Error Renaming Service. Service name must only have alphanumeric characters and must be at most 80 characters long.

Error Configuration Cannot rename the service. Please provide a valid name. Make sure you have entered alphanumeric characters, no blank spaces, and the name is not more than 80 characters.

AEADR3-600056 Global Variables File:Read-Only. Global Variable files needs to be checked out in order to successfully create the adapter.

Error Configuration Please check out Global Variables file from source control

AEADR3-600057 Error During Rename : Read-Only File. The resource %1 could not be renamed. Rename requires the %2 should be checked out. Please checkout the resource and try renaming again. You can select the resource to be checked out by clicking on the Go To Resource button.

Error Configuration Please checkout the resource and try renaming again

AEADR3-600058 Error During Delete : Read-Only File. The resource %1 could not be deleted. Delete requires the %2 should be checked out. Please checkout the resource and try renaming again. You can select the resource to be checked out by clicking on the Go To Resource button.

Error Configuration Please checkout the resource and try deleting again

AEADR3-600059 Error During Creation of Service : Read-Only File. The service can not be created. Creation requires the %1 should be checked out. Please checkout the resource and try creating the service again. You can select the resource to be checked out by clicking on the Go To Resource button.

Error Configuration Please checkout the resource and try creating the service again




The following table lists error messages for which codes have been changed.

AEADR3-600060 Need to Add File to RCS: %1 was created during schema generation. Please ensure that this resource is added to RCS and checked in. Click on the Go To Resource button to select the resource.

Warning Configuration Please ensure that this resource is added to RCS and checked in.


Table 26 Error Messages with Changed Codes

New Message Code

Old Message Code

Severity Cat. Description Resolution

AER3-000000 R3-CORE-APP-8000

INFO AD The request does not contain closure data for operation %1

Indicates normal adapter operation. No action necessary.

AER3-000001 R3-CORE-APP-8001

Error AD Invalid closure data for operation %1

Create a correct instance of RFC_CLOSURE defined in SAPAdapterSchema.x

ml and set it as closure data in the request to be sent to the inbound adapter. To find out more about closure, refer to TIB Adapter SDK documentation and TIBCO 2.0 ActiveEnterprise wire format.

AER3-000002 R3-CORE-APP-8002

Error AP Invalid value for attribute %1 for operation %2

Verify if you are using the correct class descriptions and value specified is valid and no mandatory values are omitted.



AER3-000003 R3-CORE-APP-8003

Error AD Function call is transactional but no TID provided

When you set bTransactional in closure, you must also supply a value for TID.

AER3-000004 R3-CORE-APP-8004

INFO S Adapter application %1 is stopped


AER3-000005 R3-CORE-CFG-1000

Error C Could not find interface description element

This problem might also occur if the configuration file is edited manually and is invalidated in the process. After making any changes to the file make sure that the XML file is well formed. The SML file can be validated by opening it in an XML enabled browser.

AER3-000006 R3-CORE-CFG-1001

Error C %1 not specified for %2

This problem might also occur if the configuration file is edited manually and is invalidated in the process. After making any changes to the file make sure that the XML file is well formed. The file can be validated by opening it in an XML enabled browser.


New Message Code

Old Message Code




AER3-000007 R3-CORE-CFG-1003

INFO C TID management is local

It is advisable to use a remote TIDManager if more than multiple adapters are running in a load balanced manner. This is to ensure that the failed transactions are not executed twice among the load balanced group. This means that it is possible to get duplicate messages if more than one adapters are being run in a load balanced configuration and are setup to do local TID management.

AER3-000008 R3-CORE-CFG-1004

Error C TID file is not specified

Specify the TID file name, attribute "tidFileName" in the adapter instance level Adapter Services

tab.

AER3-000009 R3-CORE-CFG-1005

Error C Timer %1 does not exist

Provide a correct reference to the TIB Adapter SDK timer in the server connection section of the connection manager.

AER3-000010 R3-CORE-CFG-1006

Error C The interface %1 does not specify attribute ’classRef’

Provide a correct reference to the TIBCO Adapter SDK timer in the server connection section of the connection manager


New Message Code

Old Message Code




AER3-000011 R3-CORE-CFG-1007

Error C Invalid producer %1

Provide a correct reference to an TIBCO Adapter SDK producer (publisher).

AER3-000013 R3-CORE-CFG-1009

Error C No RpcClient specified for operation %1

Provide a valid reference to an TIB Adapter SDK RPC Client through "mbRpcClientRef" element in Deployment Descriptions of IDocs.

AER3-000014 R3-CORE-CFG-1010

WARN C Interface %1 does not contain deployment description for IDocs... continuing...

Provide a valid reference to an MBOperation. Also add a reference to the XML document that contains the descriptions for this operation. This is done using the model document tag at the beginning of the configuration file in the document section.

The default class descriptions for MB operations, i.e. UserExitSchema.xml, can also be extended with class description for additional operations.


New Message Code

Old Message Code




AER3-000015 R3-CORE-CFG-1011

INFO C Invalid producer %1; using default producer %2


AER3-000016 R3-CORE-CFG-1012

Error C Invalid consumer component %1

Modify your configuration by defining a consumer name as suggested by the error description.

AER3-000017 R3-CORE-CFG-1013

Error C No components defined in the configuration document

Modify your configuration so that it has at least one component under the ’components’ section.

AER3-000018 R3-CORE-CFG-1014

Error C No connection manager defined in the configuration document

Modify your configuration so that it has a ’connectionManager’ under the ’connectionManagers’ section.

AER3-000019 R3-CORE-CFG-1015

Error C Invalid rpcServer %1 specified for interface %2

Modify your configuration so that it has a ’connectionManager’ under the ’connectionManagers’ section.

AER3-000020 R3-CORE-CFG-1016

Error C The Subscriber Description does not specify consumer reference, skipping ...

Add consumerRef attribute in the configuration.


New Message Code

Old Message Code




AER3-000021 R3-CORE-CFG-1017

Error C Consumer %1 for deployment description %2 does not exist

ConsumerRef must point to a valid subscriber.

AER3-000022 R3-CORE-CFG-1018

WARN C No instance defined for %1; control fields will not be replaced

You must have an instance defined under class instances.

AER3-000023 R3-CORE-CFG-1019

WARN C Invalid reference for attribute consumerRef

ConsumerRef must point to a valid subscriber.

AER3-000024 R3-CORE-FIL-3000

Error S Error while reading directory=%1, filename=%2; %3

Determine the cause from the error description.

AER3-000025 R3-CORE-FIL-3001

WARN S directory=%1, filename=%2; No matching files found

There were no matching files. Check your filenames.

AER3-000026 R3-CORE-FIL-3002

Error S Could not open %1 for reading

The specific file could not be opened. Check permissions.

AER3-000027 R3-CORE-FIL-3003

Error S %1 is unreadable Check whether the file can be opened using a text editor.

AER3-000028 R3-CORE-FIL-3004

WARN S %1 is empty File is empty.

AER3-000029 R3-CORE-FIL-3005

Error S %1 does not contain newline. Perhaps not a text file

The file is not a text file, because it does not contain a new line.


New Message Code

Old Message Code




AER3-000030 R3-CORE-FIL-3006

INFO AD IDoc from file %1 sent in %2 mode


AER3-000031 R3-CORE-IDC-7000

Error AD Unsupported datatype %1

The datatype is unsupported by SDK or SAP or both.

AER3-000032 R3-CORE-IDC-7001

WARN AD Cannot get control record for IDoc

The IDoc does not have a control record. If it’s not intentional, add a control record.

AER3-000033 R3-CORE-IDC-7002

Error AD class name invalid for IDoc

The adapter received an IDoc but could not determine its class. If you are creating the IDoc meant to be consumed by the adapter, ensure that you are creating it correctly.

AER3-000034 R3-CORE-LIB-6000

WARN AD False call to %1 See the error description for more details.

AER3-000035 R3-CORE-LIB-6001

WARN AD Could not generate GUID

Even though a warning, this message is often indicative of a memory-low situation that could severely affect the adapter performance.


New Message Code

Old Message Code




AER3-000036 R3-CORE-LIB-6002

Error AD No connection for %1

The named component does not have a valid connection Manager. Refer also to the description for ’R3-CORE-CFG-1014’.

AER3-000037 R3-CORE-LIB-6003

Error AD Could not create TIDManager

If the problem persists, repeat with remote TID Management.

AER3-000038 R3-CORE-LIB-6004

Error C Could not find default client connection

Modify your configuration so that the login parameters that you specify for ’defaultClient’ are valid and that the Adapter can establish a valid connection to the SAP System.

AER3-000039 R3-CORE-LIB-6005

Error AD No proxy defined to process request for RFC function %1

The Adapter could not create a proxy for the named RFC function. Please look at earlier error messages in the log file(s) for possible causes.

AER3-000040 R3-CORE-LIB-6006

INFO AD Adding RFC function %1

For an inbound configuration, the message means that the Adapter can serve as an RFC Client; for an outbound configuration, the message means that the Adapter can serve as an RFC Server.


New Message Code

Old Message Code




AER3-000041 R3-CORE-LIB-6007

Error AD Unable to create RFC server function %1

Look at earlier error messages in the log file(s) for possible causes.

AER3-000042 R3-CORE-LIB-6008

Error AD Unable to create request proxy for %1


AER3-000043 R3-CORE-LIB-6009

Error AD Unable to create RFC client for %1


AER3-000044 R3-CORE-LIB-6010

Error AD Unable to create function impl for %1


AER3-000045 R3-CORE-LIB-6011

Error AD RFC function initialization failure : %1; function name : %2

Look at the error description for the cause of the failure.

AER3-000046 R3-CORE-LIB-6012

Error AD Cannot create publisher proxy for %1



New Message Code

Old Message Code




AER3-000047 R3-CORE-LIB-6014

Error AP %1 is not a valid structure or table

If the name represents a valid SAP structure (or table), ensure that the repository contains the class definition for this structure (or table). If you are sending data from your custom program(s) to the SAP Adapter, make sure that you’re constructing the data correctly and that you’re using valid classes.

AER3-000048 R3-CORE-LIB-6015

Error AD Unpacking error: Invalid class type for structure %1

Data inappropriate for the named structure. See also R3-CORE-LIB-6014.

AER3-000049 R3-CORE-LIB-6016

Error AD Unpacking error: Invalid class type for table %1

Data inappropriate for the named table. See also R3-CORE-LIB-6014.

AER3-000050 R3-CORE-LIB-6017

Error AP Unpacking error: Row of table %1 is not a structure

Data inappropriate for the named table. See also R3-CORE-LIB-6014.

AER3-000051 R3-CORE-LIB-6018

INFO AD User-defined operation called successfully

The Adapter invoked the user-defined operation successfully.


New Message Code

Old Message Code




AER3-000052 R3-CORE-LIB-6019

Error AD Invalid or no data received from user-defined operation

Check the program that implements the user-defined operation and make sure that it returns data.

AER3-000053 R3-CORE-LIB-6020

Error AD User-defined operation invocation exception; name : %1, data : %2

Ensure that your operation executes without any exception and that it returns valid data to the Adapter.

AER3-000054 R3-CORE-LIB-6021

Error AD User-defined operation invocation timeout

Ensure that the Rpc Server that implements your operation is running and that it is reachable from the Adapter.

AER3-000055 R3-CORE-LIB-6022

Error AD User-defined operation invocation : bad reply received

Ensure that your operation returns valid data to the Adapter.

AER3-000056 R3-CORE-LIB-6023

Error AD User-defined operation invocation exception; name : %1

Ensure that your operation executes without any exception and that it returns valid data to the Adapter.

AER3-000057 R3-CORE-LIB-6024

Error AD The request sent to user-defined operation contains invalid data

If you’re constructing the data to be sent to the user-defined operation, ensure that it’s being constructed correctly.


New Message Code

Old Message Code




AER3-000058 R3-CORE-LIB-6025

Error AD Invalid operation name for IDoc %1

The Adapter found that the IDoc data is arriving from a function other than ’IDOC_INBOUND_ASYNCHRONOUS’ or ’INBOUND_IDOC_PROCESS’.

AER3-000059 R3-CORE-LIB-6026

Error AD Cannot create IDoc parser instance

The error indicates that it could not create a parser, either because of a memory-low problem or because of an earlier error during Adapter initialization.

AER3-000060 R3-CORE-LIB-6027

Error AP Invalid RFC function %1


AER3-000061 R3-CORE-LIB-6028

WARN AD The IDoc %1 could not be exploded

See R3-CORE-LIB-6026.

AER3-000062 R3-CORE-LIB-6029

Error AD Unable to create reply listener for operation %1

See earlier messages in the log file(s) for possible causes.

AER3-000063 R3-CORE-LIB-6030

Error AD RFC invocation timeout for function %1; description : %2

The named RFC function invocation timed out. See error description for more details.


New Message Code

Old Message Code




AER3-000064 R3-CORE-LIB-6031

Error AD RFC invocation bad reply for function %1; description : %2

The named RFC function returned a bad reply. See error description for more details.

AER3-000065 R3-CORE-LIB-6032

Error AD RFC invocation remote exception; name : %1, description : %2

The named RFC function caused a remote exception. See error description for more details.

AER3-000066 R3-CORE-LIB-6033

Error AD Cannot create IDoc parser instance for subscriber %1

The error indicates that it could not create a parser, either because of a memory-low problem or because of an earlier error during Adapter initialization.

AER3-000067 R3-CORE-LIB-6034

WARN AD Invalid MTree data received for subscriber

See earlier error messages in the log file(s) for possible causes.


New Message Code

Old Message Code




AER3-000068 R3-CORE-LIB-6035

Error AD Cannot create IDoc data instance from received IDoc tree

The adapter subscriber received MTree data but the received data could not be converted to an MInstance. Because an MInstance is an MTree bounded by a class, the error implies that the received MTree is incorrect. If it is your application that is sending the offending data to the adapter subscriber, please make sure that your data is valid.

AER3-000069 R3-CORE-LIB-6036

Error AD Cannot implode IDoc %1

Either the adapter encountered a low-memory condition or the received data is incorrect. If it is your application that is sending the offending data to the adapter subscriber, please make sure that your data is valid.

AER3-000070 R3-CORE-LIB-6037

Error AD Cannot get RFC client function %1

Make sure that SAP login parameters are correct and that the subscriber adapter can reach the SAP system. Also check earlier error messages in the log file(s) for possible causes.


New Message Code

Old Message Code




AER3-000071 R3-CORE-LIB-6038

Error AD Cannot get marshaller for RFC client function %1

The subscriber adapter could not get marshaller to convert between adapter data and SAP data, perhaps because of a low-memory problem or because of an error encountered earlier during initialization. Please check earlier error messages in the log file(s) for possible causes.

AER3-000072 R3-CORE-LIB-6039

Error AP Client connection %1 is invalid

Ensure that the login parameters are correct and that the Adapter can reach the SAP system.

AER3-000073 R3-CORE-LIB-6040

Error AP Cannot get RFC connection for client %1

See R3-CORE-LIB-60.

AER3-000074 R3-CORE-LIB-6041

Error AD Operation %1 timed out

Make sure that the RPC Server that corresponds to the named operation is executing and is accessible from the Adapter.

AER3-000075 R3-CORE-LIB-6042

WARN AD Operation %1 returned a bad reply %2

The named operation returned a bad reply. Please look at the error message description for more details.


New Message Code

Old Message Code




AER3-000076 R3-CORE-LIB-6043

Error AD Initialization exception type : %1, operation : %2, description : %3

The named operation returned the named exception. Please look at the error message description for more details.

AER3-000078 R3-CORE-LIB-6045

INFO AD Successfully added RFC function %1

The Adapter successfully added the named RFC function. Depending on the configuration, the adapter can function as an RFC client, RFC Server, or both.

AER3-000079 R3-CORE-LIB-6046

Error AD Unpacking error The Adapter encountered an error either because of low-memory condition or because of an error earlier during the initialization. Please check earlier error messages in the log file(s) for possible causes.

AER3-000080 R3-CORE-LIB-6047

WARN AD Could not create TIBCO RV advisory handlers; exception type : %1, description : %2

The Adapter could not create the license expiry advisories. Look at the error description for more details.


New Message Code

Old Message Code




AER3-000081 R3-CORE-LIB-6048

WARN AD Could not create TIBCO Hawk implants; exception type : %1, description : %2

The adapter could not create TIBCO Hawk implants. Look at the error description for more details.

AER3-000082 R3-CORE-LIB-6049

INFO AD Successful initialization of Adapter


AER3-000083 R3-CORE-LIB-6050

Error AD Unable to create operation request for function : %1, class : %2, rpcClient : %3

The Adapter could not create Operation request for the named function. Look at the error description for more details.

AER3-000084 R3-CORE-LIB-6051

INFO AP Received IDoc Name/Number/Receiving Partner: %1, Count: %2


AER3-000085 R3-CORE-LIB-6052

INFO AD IDoc sent in %1 mode


AER3-000086 R3-CORE-LIB-6053

INFO AD IDoc received in %1 mode


AER3-000087 R3-CORE-LIB-6054

INFO AD IDoc Sent to SAP System


AER3-000088 R3-CORE-LIB-6055

INFO AD IDoc sent as a Business Document


AER3-000089 R3-CORE-LIB-6056

INFO AD IDoc received as a Business Document



New Message Code

Old Message Code




AER3-000090 R3-CORE-LIB-6057

INFO C The Destination %1 in not defined, IDoc is logged to file %2


AER3-000091 R3-CORE-LIB-6058

INFO AD Total IDocs processed: %1


AER3-000092 R3-CORE-LIB-6059

INFO AD The subscriber for this IDoc message could not be determined


AER3-000093 R3-CORE-LIB-6060

INFO AD IDoc Message sequence number %1 confirmed to %2


AER3-000094 R3-CORE-LIB-6061

INFO AD Preparing to send IDoc to client %1


AER3-000095 R3-CORE-LIB-6062

INFO AD IDoc sent to client %1


AER3-000096 R3-CORE-LIB-6064

INFO AD IDoc Message sequence number %1 could not be confirmed to %2, Use pre-registration of subscribers


AER3-000097 R3-CORE-LIB-6065

INFO C IDoc Message could not be confirmed, validation must be turned off, if 10X Publishers used



New Message Code

Old Message Code




AER3-000098 R3-CORE-LIB-6066

INFO AP IDoc RFC Function invoked: %1


AER3-000099 R3-CORE-LIB-6067

INFO AD RFC Function invoked: %1


AER3-000100 R3-CORE-LIB-6068

WARN C User-defined operation: operation not specified, assuming ’transform’

If the default transfer is not desired, name your operation explicitly.

AER3-000101 R3-CORE-LIB-6069

WARN C User-defined operation reference: operationRpcClientRef not specified, operation will not be invoked

The operation requires an rpcClient, specific through operationRpcClientRef. Specify this client.

AER3-000102 R3-CORE-LIB-6070

Error AD TID operation timed out. Make sure that TIDManager is running

Make sure TIDManager is running and is accessible from the Adapter. Also, ensure that subject names match.

AER3-000103 R3-CORE-LIB-6071

INFO AD Adding %1 parameter %2, Type %3


AER3-000104 R3-CORE-LIB-6072

INFO AD Setting up Imports and Exports for RFC function %1


AER3-000105 R3-CORE-LIB-6073

INFO AD RFC function has %1 imports, %2 exports



New Message Code

Old Message Code




AER3-000106 R3-CORE-LIB-6074

INFO AD %1 = { %2 } Indicates normal adapter operation. No action necessary.

AER3-000107 R3-CORE-LIB-6075

INFO AD Number of records in table %1 = %2


AER3-000108 R3-CORE-LIB-6076

INFO AD Invoking function: %1 ...


AER3-000109 R3-CORE-LIB-6077

INFO AD Successfully invoked function: %1


AER3-000110 R3-CORE-LIB-6078

INFO AD Reply sent for function: %1


AER3-000111 R3-CORE-LIB-6079

INFO AD Received reply for: %1 ...


AER3-000112 R3-CORE-LIB-6080

INFO AD Data sent back to SAP R/3 System


AER3-000113 R3-CORE-LIB-6081

INFO AD Performing one way invocation on the server


AER3-000114 R3-CORE-LIB-6082

INFO AD Received invocation request for %1 from SAP R/3 System


AER3-000115 R3-CORE-LIB-6083

INFO AD Performing invocation on the server



New Message Code

Old Message Code




AER3-000116 R3-CORE-LIB-6084

INFO AD Function call is transactional, TID: %1


AER3-000117 R3-CORE-LIB-6085

INFO AD Received invocation request for %1


AER3-000118 R3-CORE-LIB-6086

INFO AD Invoking RFC function %1 in SAP R/3 System


AER3-000119 R3-CORE-LIB-6087

INFO AD Received one way invocation request for %1


AER3-000120 R3-CORE-LIB-6088

INFO AD Invoking transactional RFC function %1 in SAP R/3 System


AER3-000121 R3-CORE-LIB-6089

INFO C Cannot get class descriptions for control record of IDoc class %1


AER3-000122 R3-CORE-LIB-6090

Error AP The IDoc %1 does not contain a control record

Make sure that the IDoc contains a control record.

AER3-000123 R3-CORE-LIB-6091

Error C Cannot get class descriptions for data record of IDoc class %1

During configuration ensure that you’re downloading the class descriptions.

AER3-000124 R3-CORE-LIB-6092

Error AD The received IDoc tree in exploded form is null

Make sure that the Tree (MTree in SDK) is created correctly and corresponds to an IDoc.


New Message Code

Old Message Code




AER3-000125 R3-CORE-LIB-6093

Error C Class descriptions cannot be obtained for received IDoc tree

During configuration ensure that you’re downloading the class descriptions.

AER3-000126 R3-CORE-LIB-6094

Error C %1 is not of a sequence type

The named sequence does not have a valid definition. Check the configuration.

AER3-000127 R3-CORE-LIB-6095

Error C Sequence %1 does not have a contained class description

A sequence is a sequence of objects of type T. The adapter could not determine T, probably because the definitions don’t exist in the configuration.

AER3-000128 R3-CORE-LIB-6096

Error C Sequence %1 for the segment holder could not be obtained

Check configuration and make sure that a valid definition exists for the named sequence.

AER3-000129 R3-CORE-LIB-6097

Error C Segment %1 does not have attribute: %2

The data mentioned contains the named attribute, but the class definition does not. Check the configuration and how the IDoc is being created.

AER3-000130 R3-CORE-LIB-6098

Error C Cannot obtain field class description for IDoc Segment

Check configuration.


New Message Code

Old Message Code




AER3-000131 R3-CORE-LIB-6099

Error AD Cannot get EDIDD header attribute from the fields for segment %1

Check the data. It must include the EDIDD header.

AER3-000132 R3-CORE-LIB-6100

Error C Cannot obtain class description for segment %1 attribute %2

Check the segment name as well as the attribute and make sure that a definition exists in the configuration.

AER3-000133 R3-CORE-LIB-6101

INFO AD The segment instance %1 does not contain attribute %2


AER3-000134 R3-CORE-LIB-6102

INFO AD The default values will be used


AER3-000135 R3-CORE-LIB-6103

INFO AD Segment name: %1 added


AER3-000136 R3-CORE-LIB-6104

Error AD The %1 record sequence does not contain a valid control record

Check the data first. Make any changes. Check the configuration for an appropriate definition.

AER3-000137 R3-CORE-LIB-6105

Error C The %1 record of the IDoc does not have a valid class description

Check the data first. Make any changes. Check the configuration for an appropriate definition.

AER3-000138 R3-CORE-LIB-6106

INFO AD The %1 record does not contain attribute %2



New Message Code

Old Message Code




AER3-000139 R3-CORE-LIB-6107

INFO AD trying to recover the received message ...


AER3-000140 R3-CORE-LIB-6108

INFO AD Subscriber: %1, Exception occurred on receiving the message


AER3-000141 R3-CORE-LIB-6109

Error AD Subscriber: %1, the message could not be recovered


AER3-000142 R3-CORE-LIB-6110

INFO AD Subscriber: %1, The 10X Opaque message type is not supported


AER3-000143 R3-CORE-LIB-6111

INFO AD the received message was recovered


AER3-000144 R3-CORE-LIB-6112

INFO AD The IDoc message received in 10X format does not contain %1field


AER3-000145 R3-CORE-LIB-6113

Error C The class descriptions for IDoc base classes cannot be obtained from the registry

During configuration ensure that you’ve downloaded the class definition.

AER3-000146 R3-CORE-LIB-6114

INFO AD Function called transactionally but Transaction Identifier (TID) not supplied



New Message Code

Old Message Code




AER3-000147 R3-CORE-LIB-6115

Error S Could not open file %1 for writing

File could not be opened. Check permissions and whether you’ve adequate space on your disk.

AER3-000148 R3-CORE-LIB-6116

Error AD CIDocIterator: The IDoc container does not contain any IDocs

Check the log file for any previous errors that may have led to this situation.

AER3-000149 R3-CORE-LIB-6117

Error AD The IDoc %1 does not contain %2

The IDoc does not contain a data record section. Check the IDoc data.

AER3-000150 R3-CORE-LIB-6118

Error AD No control record instance for the %1 IDoc in the packet

The named IDoc does not have a control record. Check the data.

AER3-000151 R3-CORE-LIB-6119

Error AD No data record instance for the %1 IDoc in the packet

The IDoc does not contain a data record section. Check the data.

AER3-000152 R3-CORE-LIB-6120

Error AD %1 record of the data record instance does not contain mandatory attribute DOCNUM

DOCNUM is a mandatory attribute for data record. Check the data and modify it to include DOCNUM.

AER3-000153 R3-CORE-LIB-6121

INFO AD %1 row of the data record instance of the %2 IDoc instance of type %3 could not be obtained



New Message Code

Old Message Code




AER3-000154 R3-CORE-LIB-6122

Error S The IDoc instance could not be written to file, the instance is invalid

The Instance could not be written because it was empty. Check the IDoc data.

AER3-000155 R3-CORE-LIB-6123

Error AD The IDoc does not contain a data record

The IDoc does not contain a data record section. Check the IDoc data.

AER3-000156 R3-CORE-LIB-6124

INFO AD Writing IDOC %1, Number %2 to file: %3


AER3-000157 R3-CORE-LIB-6125

INFO AD Invocation for RFC function %1 still pending


AER3-000158 R3-CORE-LIB-6126

INFO AD Adapters initialization mode:%1


AER3-000159 R3-CORE-LIB-6127

WARN AD Cannot find communication client for TIDManager, TID Management will be local

The configuration does not specify the rpcClient for TIDManager, hence the TID management will be local.

AER3-000160 R3-CORE-LIB-6128

INFO AD Connection: waiting for reply from server ...


AER3-000161 R3-CORE-LIB-6129

INFO AD No component for the RFC call; Exception=%1


AER3-000162 R3-CORE-LIB-6130

INFO AD Active connection is null



New Message Code

Old Message Code




AER3-000163 R3-CORE-LIB-6131

INFO AD Checking for connections


AER3-000164 R3-CORE-LIB-6132

INFO AD Connection disconnected


AER3-000165 R3-CORE-LIB-6133

INFO AD Connection re-established


AER3-000166 R3-CORE-LIB-6134

INFO AD Connection State: Available


AER3-000167 R3-CORE-LIB-6135

INFO AD Connection State: Pending invocation


AER3-000168 --NEW-- INFO AD %1 connection could not be removed


AER3-000169 R3-CORE-LIB-6136

WARN AD Subscriber %1 could not be suspended

The named subscriber could not be suspended. No action necessary.

AER3-000170 R3-CORE-LIB-6137

WARN AD Stop Adapter: Correct consumer reference could not be obtained from deployment description %1, skipping...

The configuration did not specify consumerRef. No action necessary.

AER3-000171 R3-CORE-LIB-6138

INFO AD Adapter is waiting for invocation response before shutdown can proceed...



New Message Code

Old Message Code




AER3-000172 R3-CORE-LIB-6139

INFO AD Adapter stop method called


AER3-000173 R3-CORE-LIB-6141

INFO AD Subscriber %1 suspended


AER3-000174 R3-CORE-LIB-6142

INFO AD Connection Manager %1 stopped


AER3-000175 R3-CORE-LIB-6143

INFO AD Component %1 stopped


AER3-000176 R3-CORE-LIB-6144

INFO AD Deactivating stop scheduler


AER3-000177 R3-CORE-LIB-6145

INFO AD Stopping Adapter %1 instance on host %2


AER3-000178 R3-CORE-LIB-6146

INFO AD Stop notification received via TIBCO RV


AER3-000179 R3-CORE-LIB-6147

Error AD Remote Exception: Exception Name: %1, Exception Data: %2

See the error description for details.

AER3-000180 R3-CORE-RVD-9000

WARN AD ADV_CLASS/ADV_SOURCE/ADV_NAME: %1, ADV_DESC : %2 %3

See the error description for more details.


New Message Code

Old Message Code




AER3-000181 R3-CORE-RVD-9001

Error AD ADV_CLASS/ADV_SOURCE/ADV_NAME: %1, ADV_DESC : %2 %3

The adapter responds ’license expiry’ warning from the daemon with this message.

AER3-000182 R3-CORE-RVD-9002

Error AD ADV_CLASS : %1, ADV_SOURCE : %2, ADV_NAME : %3

The adapter responds ’registration collision’ error from the daemon with this message.

AER3-000183 R3-CORE-SAP-4000

Error AP RFC error; Group : %1, Key : %2, Message : %3

Look at the error description for details about the SAP Exception. Also please check your connection parameters.

AER3-000184 R3-CORE-SAP-4001

Error AP RFC connection invalid for %1

The adapter could not get a valid connection to the SAP system. Please check your login parameters. Also make sure that the adapter can reach the SAP system.

AER3-000185 R3-CORE-SAP-4002

Error AP CallReceive failed for operation %1; exception : %2, RFC error; Group/Key/Message: %3

Look at the error description for details about the SAP Exception.

AER3-000186 R3-CORE-SAP-4003

INFO AP Transaction %1 skipped

The Adapter did not execute this transaction because it was already executed.


New Message Code

Old Message Code




AER3-000187 R3-CORE-SAP-4004

WARN AP Invalid transaction state received from TIDManager for transaction %1

The Adapter received an invalid stated from TIDManager. Check the tidmanager display for possible causes.

AER3-000188 R3-CORE-SAP-4005

WARN AD Failed to %1 Tid The Adapter could not perform the named TID/Manager function. Check the TID/Manager display for possible causes.

AER3-000189 R3-CORE-SAP-4007

Error AP RFC function initialization error for function %1; RFC Error; Group/Key/Message : %2


AER3-000190 R3-CORE-SAP-4008

WARN AD RFC remote function %1 implementation exception %2


AER3-000191 R3-CORE-SAP-4009

Error AP Indirect call error while sending IDoc; RFC Error; Group : %1, Key : %2, Message : %3


AER3-000192 R3-CORE-SAP-4010

Error AP RFC error; Group : %1, Key : %2, Message : %3, Attempt to connect timed out



New Message Code

Old Message Code




AER3-000193 R3-CORE-SAP-4011

Error AD Connection not available for client %1, retrying ...


AER3-000194 R3-CORE-SAP-4012

INFO AD Invalid RFC client connection object for client %1


AER3-000195 R3-CORE-SAP-4013

INFO AD Transaction created %1


AER3-000196 R3-CORE-SAP-4014

INFO AD Transaction skipped %1


AER3-000197 R3-CORE-SAP-4015

INFO AD Transaction committed %1


AER3-000198 R3-CORE-SAP-4016

INFO AD Transaction confirmed %1


AER3-000199 R3-CORE-SAP-4017

INFO AD Transaction rolled back %1


AER3-000200 R3-CORE-SAP-4018

Error AD Failed to update state for transaction %1. Please ensure that the user has write permisions for tidFile.tid

Look at earlier error messages in the log-file(s) for possible causes. One of the reasons for this error could be that, you do not have write permissions for the tidFile.tid


New Message Code

Old Message Code




AER3-000201 R3-CORE-SAP-4019

INFO AD Starting Inbound transaction %1


AER3-000202 R3-CORE-SAP-4020

INFO AD Inbound transaction %1 completed


AER3-000203 R3-CORE-SCH-5000

Error C No class definition exists for %1

The named class is invalid or does not exist. Check the repository to make sure that a valid class exists with that name.

AER3-000204 R3-CORE-SCH-5001

Error C %1 is not a modeled class

The named class is invalid, non-existent, or does not represent a modeled class. Check the repository to make sure that a valid class exists with that name.

AER3-000205 R3-CORE-SCH-5002

Error C No operations defined in class %1

Modify the class definition to include operations.

AER3-000206 R3-CORE-SCH-5003

Error C The operation %1 does not have any parameters

Modify the class definition to include parameters.


New Message Code

Old Message Code




AER3-000207 R3-CORE-SCH-5004

Error C The class %1 does not specify attribute %2

The attribute is invalid for the named class. Check the repository. Re-create the class definition (if you suspect it has been incorrectly created) or modify the class definition to include the named attribute.

AER3-000208 R3-CORE-SCH-5005

Error C Operation description not available for %1

The named operation is invalid or non-existent. Check the repository to make sure that an operation exists with the specified name.

AER3-000209 R3-CORE-SCH-5006

Error C No IDoc operations defined in class %1

The named class does not have IDoc operations defined. Check the repository to make sure that the class definition is correct.

AER3-000210 R3-CORE-SCH-5008

Error C Attribute %1 in class %2 is invalid

Check the configuration.

AER3-000211 R3-CORE-SCH-5009

Error AD Unsupported type %1 for attribute %2 in class %3

The named type is unsupported by SDK or SAP or both.


New Message Code

Old Message Code




AER3-000212 R3-CORE-SCH-5010

Error AD Unexpected %1 : %2; inform technical support

Unexpected error. You cannot determine the cause from the description. Contact technical support: [email protected].

AER3-000213 R3-CORE-SCH-5011

WARN C Control field replacements specify an attribute %1 which does not exist in the control record

Control field replacements in classInstances specify an attribute that does not exist in control record. Check spelling.

AER3-000214 R3-CORE-SDK-2000

Error AD Cannot access class registry

You specified an attribute that does not exist in the control record. Either omit that attribute or replace it with an attribute that exists.

AER3-000215 R3-CORE-SDK-2001

Error AD Subscriber %1 received a message that has invalid wire format

There was an exception in the Adapter upon receive of this message. When you’re using 10x style, follow the configuration requirements given in Chapter 5 on page 109

AER3-000261 --NEW-- INFO AD Using ini file %1 Indicates normal adapter operation. No action necessary.

AER3-000262 --NEW-- INFO AD No program ID defined in the ini file, using destination %1 as program ID



New Message Code

Old Message Code




AER3-000263 --NEW-- INFO AD Using Logon Groups Indicates normal adapter operation. No action necessary.

AER3-000264 --NEW-- INFO AD Using a dedicated connection


AER3-000265 --NEW-- INFO AD Creating a Server connection


AER3-000266 --NEW-- INFO AD Initialized successfully


AER3-000267 --NEW-- INFO AD CREATED %1 Indicates normal adapter operation. No action necessary.

AER3-000268 --NEW-- INFO AD EXECUTED %1 Indicates normal adapter operation. No action necessary.

AER3-000269 --NEW-- INFO AD CONFIRMED %1 Indicates normal adapter operation. No action necessary.

AER3-000270 --NEW-- Error AD Invalid client function specifed in removeClient call

Because this message appears during shutdown, no action is necessary.

AER3-000271 --NEW-- Error C Invalid poolRef name %1

poolRef must point to a valid pool definition.

AER3-000272 --NEW-- Error C Pool reference not provided in Server Component

Provide a value that corresponds to a valid definition.


New Message Code

Old Message Code




AER3-000273 --NEW-- Error AD Invalid Connection for pool %1

Check the pool definitions to ensure that they are valid.

AER3-000274 --NEW-- Error AD Invalid default Connection for pool %1

Check the pool definitions to ensure that they are valid.

AER3-000275 --NEW-- Error C No default session defined

The configuration must either specify a valid value for start up/default session or define at least one rvSession/rvCmSession.

AER3-000276 --NEW-- Error AD Duplicate DEST parameter defined in %1 : %2

Remove duplicate definition.

AER3-000277 --NEW-- Error AD Destination %1 not defined in %2

Define destination given in message.

AER3-000278 --NEW-- INFO AD Received message is written to file %1


AER3-000279 --NEW-- Error AD Exception while initializing adapter; exception type : %1, description : %2

Refer to the description and take the required action.

AER3-000280 --NEW-- Error AD Error: Could not send reply for function: %1

Refer to the accompanying error messages for additional details.


New Message Code

Old Message Code




AER3-000281 --NEW-- Error AD Error while invoking User-defined operation: %1


AER3-000282 --NEW-- Error AD Receive reply failed for: %1


AER3-000283 --NEW-- Error AD Exception during one way invocation of function: %1, Type: %2, Description: %3


AER3-000284 --NEW-- INFO AD Request written to file: %1 for operation: %2


AER3-000285 --NEW-- Error AD Error code: %1, Message: %2

Refer to the description and take the required action.

AER3-000286 --NEW-- INFO C ’userExit’ class does not exist or it does not contain operation %1, operation will not be invoked


AER3-000287 --NEW-- INFO C There is no RpcClient named: %1, operation will not be invoked


AER3-000288 --NEW-- INFO AD Untransformed IDoc data sent



New Message Code

Old Message Code




AER3-000289 --NEW-- INFO AD Performing asynchronous invocation for User-defined function: %1


AER3-000290 --NEW-- WARN C No R/3 client configured for %1, using default-client %2

There is no deployment-description configured for the RFC. If not intentional, ensure that the client is specified in the deployment-descriptions for the RFC.

AER3-000291 --NEW-- INFO AD Received request for logon to SAP R/3 System


AER3-000292 --NEW-- INFO AD Successfully logged-on to SAP R/3 System


AER3-000293 --NEW-- INFO AD Received request for logoff from SAP R/3 System


AER3-000294 --NEW-- INFO AD Successfully logged-off from SAP R/3 System



New Message Code

Old Message Code




AER3-000295 --NEW-- Error AD No session id exists in the logoff request

The sessionID obtained on logging-on to SAP R/3 system through design-time-adapter should be passed in the RFCCLOSURE along with the logoff request to successfully logoff from SAP-R/3 system

AER3-000296 --NEW-- Error AD No logon session exists for the session ID

The sessionID obtained on logging-on to SAP R/3 system through design-time-adapter should be passed in the RFCCLOSURE along with the logoff request to successfully logoff from SAP-R/3 system

AER3-000300 --NEW-- INFO M Created discovery subscriber succesfully using subject %1


AER3-000301 --NEW-- INFO M Attempting to create dynamic connection to SAP R/3 system


AER3-000302 --NEW-- INFO M Attempting to close dynamic connection from SAP R/3 system



New Message Code

Old Message Code




AER3-000303 --NEW-- INFO M Retrieving list of function modules from SAP R/3 system


AER3-000304 --NEW-- INFO M Retrieving schema for IDOC %1 FROM SAP R/3 system


AER3-000305 --NEW-- INFO M Retrieving entries for table %1 FROM SAP R/3 system


AER3-000306 --NEW-- INFO M Retrieving schema for structure/table %1 FROM SAP R/3 system


AER3-000307 -NEW-- INFO M Received unknown operation %1

TIBCO Designer sent an invalid request to the design-time adapter. If problem persists contact technical support: [email protected]

AER3-000308 -NEW-- INFO M Metadata adapter operation failure:%1; operation name : %2

Refer to the surrounding error messages for additional details

AER3-000309 -NEW-- INFO M Retrieving schema for RFC/BAPI %1 from SAP R/3 system



New Message Code

Old Message Code




AER3-000310 -NEW-- ERROR AD Received Error Advisory Message: %1, Subject: %2

This is an error advisory thrown by a TIBCO Infrastructure component. The message %1 is context-sensitive. Report the error to TIBCO Support.

AER3-000400 --NEW-- INFO AD Invalid connection detected. Message : %


AER3-000401 --NEW-- INFO AD %1 RFCServers registered with SAP R/3 system with program-id %2 on GatewayHost %3


AER3-000402 --NEW-- Error AD No session id in request for operation %1

If the request is for an RFC that requires an explicit logon to SAP R/3 system, then the sessionID obtained on logging-on to SAP /3 system has to be passed in the RFCCLOSURE along with the RFC request.

AER3-000403 --NEW-- Error AD Unable to obtain context for implementation of operation %1

Look at earlier error messages in the log-file(s) for possible causes.

AER3-000405 --NEW-- Error AD Invalid session id passed in request for operation %1

The sessionID should be a valid string


New Message Code

Old Message Code




AER3-000406 --NEW-- Error AD Invalid session id passed for operation %1

If the sessionID was obtained after logging-on to the SAP R/3 system, ensure that the sessionID passed in the RFCCLOSURE while invoking a request on the InboundRFC instance is the same as the one obtained. Instead, if the sessionID was obtained for a subsequent BAPI_TRANSACTION_COMMIT call, ensure that the same sessionID was passed with BAPI_TRANSACTION_COMMIT invocation. Also check if the session created for commit/rollback has already timed-out as specified by the ’commitExpiry’ parameter.

AER3-000407 --NEW-- Error AD Invalid call received, connection closed for thread

The adapter received an invalid call from the SAP R/3 system that caused a connection to be closed. Ensure that the adapter connections to SAP R/3 system are alive


New Message Code

Old Message Code




AER3-000408 --NEW-- Error AD Server thread unable to dispatch call, call skipped. message : %1

The adapter entered an invalid state because of an invalid call from the SAP R/3 system. See message description for more details. Ensure that the adapter connections to SAP R/3 system are alive.

AER3-000409 --NEW-- Error AD Server thread unable to dispatch call, connection invalidated

The adapter entered an invalid state because of an invalid call from the SAP R/3 system. See message description for more details. Ensure that the adapter connections with SAP R/3 system are alive.

AER3-000410 --NEW-- WARN AD Server thread exited, message : %1

The adapter encountered an exception condition that caused the server thread to exit. Look at earlier messages in the log-file(s) for possible causes. No resolution necessary

AER3-000411 --NEW-- Error C No poolRef specified for operation %1

The RFC does not have a ’poolRef’ attribute in its deployment description. Ensure that a valid ’poolRef’ is specified for the RFC.


New Message Code

Old Message Code




AER3-000412 --NEW-- INFO AD Obtaining connection for R/3 client %1 for %2


AER3-000413 --NEW-- Error AD The session for commit/rollback timed out for operation %1

Ensure that the BAPI_TRANSACTION_COMMIT call is triggered in the SAP R/3 system before the session for commit/rollback times out as specified by the ’commitExpiry’ parameter

AER3-000414 --NEW-- INFO C No session timeout specified for commit/rollback for operation %1, defaulting to %2 seconds...

The ’commitExpiry’ parameter defaults to 60 seconds if it is not specified. If this value is insufficient, ensure that a higher value is specified for the parameter.

AER3-000415 --NEW-- INFO AD Session timeout for commit/rollback for operation %1 set to %2 seconds


AER3-000417 --NEW-- INFO AD Connection pending commit for operation %1



New Message Code

Old Message Code




AER3-000418 --NEW-- Error AD Invalid client specified : %1

Ensure that a valid client is specified for the RFC/IDoc in their respective deployment descriptions, if any. Else ensure that the ’defaultClient’ attribute specified in client connectionpool is a valid client

AER3-000419 --NEW-- INFO AD Created new thread for RFCServer


AER3-000420 --NEW-- INFO AD Server thread(s) stopped for Component %1


AER3-000421 --NEW-- Error AD No valid connection handle available for server for operation %1

The outbound adapter could not get a valid connection handle to the SAP R/3 system. Look at earlier messages in the log-file(s) for possible causes

AER3-000422 --NEW-- Error C No client specified in deployment description for operation %1

Ensure that a client is configured for the operation

AER3-000423 --NEW-- Error C No poolRef specified for operation %1

Ensure that a poolRef is specified for the operation


New Message Code

Old Message Code




AER3-000424 --NEW-- Error C No default client specified for operation %1

Ensure that a defaultClient is specified for the operation

AER3-000425 --NEW-- Error C Invalid poolRef specified in deployment : %1

Ensure that a valid poolRef is specified in the deployment description for the RFC/IDoc

AER3-000426 --NEW-- INFO AD Thread monitor started for %1 server thread(s)


AER3-000427 --NEW-- Error AD No active connections available in configuration, exiting...

This indicates that all the R/3 systems the adapter is connected to, are down and none of the connections established by the adapter with the R/3 system are active. Ensure that the R/3 systems are up and running.

AER3-000428 --NEW-- WARN C Interface %1 does not contain deployment description for RFCs... continuing...

The adapter could not find deployment descriptions for any RFC. If it is not intentional, ensure that the RFC configuration is correct.


New Message Code

Old Message Code




AER3-000429 --NEW-- WARN C No deployment description available for idoc %1...using default…

The adapter could not find deployment descriptions for the specified IDoc. If it is not intentional, ensure that the IDoc configuration is correct.

AER3-000430 --NEW-- INFO AD Total requests processed : %1


AER3-000431 --NEW-- Error AD Unable to create marshaller for operation %1


AER3-000432 --NEW-- Error AD Unable to clone proxy for operation %1


AER3-000433 --NEW-- Error AD Unable to clone RFC client for %1


AER3-000434 --NEW-- Error AD Unable to clone function implementation for operation %1


AER3-000435 --NEW-- Error AD Unable to create listener for call-operation



New Message Code

Old Message Code




AER3-000436 --NEW-- Error AD Unable to create reply listener for operation %1


AER3-000437 --NEW-- Error AD Unable to clone subscriber implementation


AER3-000438 --NEW-- Error AD Unable to generate transaction-id. message : %1


AER3-000439 --NEW-- Error AD Unable to create implemementation for thread


AER3-000440 --NEW-- Error AD Unable to create server thread


AER3-000441 --NEW-- INFO C TID management is remote


AER3-000442 --NEW-- Error AD Connection context lost. Operation %1 failed


AER3-000443 --NEW-- Error AD Logon to SAP R/3 system failed. message : %1



New Message Code

Old Message Code




AER3-000444 --NEW-- Error AD Error writing to TID file for transaction %1

Ensure that the TID file has write permissions.

AER3-000446 --NEW-- Error AD No active connections in connection-pool %1. All retry attempts exhausted.Connections for this pool deactivated.

Ensure that the R/3 system pointed to by the connection-pool %1 is up and running.

AER3-000447 --NEW-- Error AD No active connections in connection-pool %1. All retry attempts exhausted.Exiting...

This indicates that all the R/3 systems the adapter is connected to, are down and none of the connections established by the adapter with the R/3 system are active. Ensure that the R/3 systems are up and running.

AER3-000448 --NEW-- INFO AD Suspended endpoint component %1

None.

AER3-000449 --NEW-- INFO AD The Application Manager has been flagged to restart on re-establishing connection to R/3.

None.

AER3-000450 --NEW-- INFO AD Created timer to check connectivity to R/3.

None.


New Message Code

Old Message Code




AER3-000451 --NEW-- WARN AD Adapter application will restart now

The adapter is recovering missed messages by performing an internal-restart. Ensure that the adapter has performed a restarted successfully by checking the adapter log files.

AER3-000452 --NEW-- INFO AD Adapter application %1 is restarting on host %2.

None.

AER3-000453 --NEW-- WARN C Invalid control-field replacement attribute %1 skipped.

A control-field name %1 not present in the IDoc’s control record was specified for replacement. Ensure that the field name is one of those defined for the IDoc’s control record.

AER3-000454 --NEW-- INFO AD Performing oneway invocation for User-defined function: %1

None.

AER3-000455 --NEW-- Error C No class description available for explode sequence %1

check the repository under /tibco/public/adapter/SAPAdapter40/<sap version>/IDOCS/ for the class description for class %1


New Message Code

Old Message Code




AER3-000456 --NEW-- Error C No attribute description for explode sequence %1

check the repository for attribute description for explode sequence %1.

AER3-000457 --NEW-- Error AD Operation %1 requires external logon.The request does not contain sessionID in the closure data.

Supply the session-id parameter in the RFCCLOSURE data of the incoming request.


New Message Code

Old Message Code



| 473

Appendix B SAP R/3 Overview

This appendix gives an overview of the SAP R/3 system and descriptions of the interfaces exposed by system.

Topics

• The SAP R/3 Business Application System, page 474

• Exchanging Business Information, page 477


474 | Appendix B SAP R/3 Overview

The SAP R/3 Business Application System

SAP/R3 is a general purpose, transaction-based business application system. Each transaction represents an individual business process — usually seen as a series of screens. Flexibility is achieved using modular business components, which can in turn be combined to develop new modules and transactions. SAP R/3 has a three-layer, client-server-based architecture, as shown in the figure. These layers are explained in sections that follow.

SAP GUI Presentation Server

The top layer is the graphic user interface (GUI). This layer consists of a hierarchy of query-response screens that allow company staff to access, review, and compare day-to-day and longer-term business information, and to control the business through applications that process business data. The SAP GUI graphically presents formatted business data retrieved from the application


The SAP R/3 Business Application System | 475

server, handles the user dialog, and communicates user entries to the Application Server. Categories of business information include office administration, logistics, accounting, and others, as shown in one of the top-level SAP R/3 GUI screens, in the next figure:

The SAP R/3 GUI program accesses the business database server by means of the Application Server layer. Information on many business transactions can be displayed in a report such as the following:

The GUI also provides the interface to control communication of business information between two SAP R/3 systems, and between a SAP R/3 system and an external application, such as the TIBCO Adapter for R/3.

Application Server

The Application Server layer processes the business logic (ABAP/4 programs) relying on data stored in the database and on user input. The programs themselves are also stored in the database. The processes that make up an Application Server run on dedicated, powerful, servers.



The Application Server provides many services to support the user interface layer. In this layer, programs are available to create, capture, configure, and process business data and to present it in a logical and easily assimilated display. Custom business applications written for the specific business entity augment standard SAP R/3 programs.

Database Server

The Database Server holds the relational database and maintains:

• application data, for example SAP records

• customization data, for example ALE customizing

• ABAP/4 business program logic

Each SAP R/3 system has one database and one Database Server. Any of the most widely-used SQL database management applications can be used, including Oracle and Informix.


Exchanging Business Information | 477

Exchanging Business Information

SAP R/3 provides many interfaces to extract and import data to facilitate enterprise-wide integration. The following interfaces are the standard means for exchanging business information between SAP R/3 and other business application systems.

Summary of SAP R/3 Interfaces

• ALE: Application Link Enabling.

This is SAP's middleware to integrate different SAP R/3 systems together to achieve cross-business functionality. ALE facilitates the event driven, asynchronous exchange of information directly out of business transactions or administrative transactions. It provides tools to customize a distribution model and monitoring and management tools.

• BAPI: The Business Objects Repository (BOR) Application Programming Interface.

This API of the SAP Business Framework offers business objects for object-oriented manipulation of business data. The business objects in BOR describe complete business processes. Each BOR object has one or more methods, and not all of its methods are exposed. The collection of all exposed methods of all BOR objects is called the Business API or BAPI.

• RFC: Remote Function Call.

This is the most popular SAP R/3 access technology. This provides the basis to access ALE/IDocs, BAPIs and BOR information. This interface allows non-SAP R/3 and SAP R/3 applications to execute SAP Advanced Business Application Programming (ABAP) functions that have been RFC-enabled. Non-SAP R/3 applications that use this interface behave as RFC client/server programs to SAP R/3.

• EDI: Electronic Data Interchange of Intermediate Documents (EDI/IDoc).

This is the means for communicating business data to and from external partners. It is similar to ALE. EDI provides more customization capabilities, so that data can be communicated to and from specific business partners in a specific manner.

• IDocs: Intermediate Documents.

These are used to transfer data in a business transaction. IDocs encapsulate application data in segment hierarchies. They are used as data containers for both ALE and EDI. They are called intermediate documents because they were originally used with EDI, as SAP's common intermediate structure to



bridge over multiple EDI standards. SAP IDoc data was then mapped to specific EDI standards later in the process. Communication IDocs are created from master IDocs for point-to-point distribution to individual recipients as per an ALE partner profile within ALE customization. There are several hundred IDoc types for application data. Both ALE and EDI have one common feature, once the specific processing is done, the data is automatically sent out of the corresponding operational or administrative transactions (exceptions exist for master data).

The adapter discussed in this document uses ALE/IDoc, RFC, and BAPI interfacing technology to achieve data interchange. Figure 1 shows how ALE serves as the IDoc interface between SAP R/3 systems and non-SAP systems.

Figure 21 R/3 Adapter ALE/IDoc interface

SAP R/3 Application

TIBCO Adapter for R/3

Publisher

Outbound from SAP R/3

TIBCO Adapter for R/3

Subscriber

_________ __________________Comm. IDoc

Inbound to SAP R/3

SAP R/3

Database

_________ __________________Comm. IDoc

ALE Outbound Process

_______ _______ _______Master IDoc

ALE Inbound Process

_______ _______ _______Master IDoc

Non-SAP SystemsTIBCO Environment


Exchanging Business Information | 479

IDoc Structure

The IDoc internal structure serves as a general-purpose communication vehicle to move different kinds of business data. The figure below shows the general structure of an IDoc consisting of a control record, one or more data records, and a status record.

An example of an IDoc type is “ORDER01.” It is used to communicate data describing a purchase order, including purchase order number, buyer, payment terms, amount, etc. There are hundreds of types of predefined IDoc types and at a given site, many variations of the predefined types are used. As shown in the above figure, every type of IDoc has three parts:

• Control Record — The format of the Control Record is identical for all IDoc types. It contains many fields that specify control information, including message ID, the message time, SAP proxy system (logical system), and many others.

• Data Records — A Data Record consists of a fixed administration part and a data part (segment). The number and format of the segments can be different for each IDoc type and can be recursive, which means that a segment can contain other segments.

• Status Record — The Status Record describes the processing stages that an IDoc can pass through, and has an identical format for each IDoc type. Status entries include error and status codes, and state of message processing such as “created”, “sent”, etc.

To determine the syntax of each IDoc type, SAP uses IDoc metadata. The metadata specifies the IDoc segments in a tree structure, with data field characteristics within segments, metadata version, and other information generic to the IDoc type. This metadata is extracted by the TIBCO Designer palette and saved to the project.



RFC/BAPI Structure

Remote Function Calls (RFCs) are implemented in request/reply communication Business Application Programming Interfaces (BAPIs) are standard SAP R/3 business interfaces to BOR, and functionally are similar to RFCs. Schema files are extracted from the SAP system instance using the TIBCO Designer palette and saved to the project.


| 481

Appendix C Frequently Asked Questions

This appendix lists answers to the frequently asked questions.

Topics

• Frequently Asked Questions, page 482


482 | Appendix C Frequently Asked Questions

Frequently Asked Questions

What are the requirements to bring up TIBCO Designer from a UNIX command-line?

TIBCO Designer is a GUI based tool and a UNIX GUI environment is mandatory to run it. You can start TIBCO Designer from the command line.

When starting the adapter, what if the repository is not found?

Start the repository server before starting the adapter. If you are starting a remote repository ensure that TIBCO Administrator Repository edition is installed on the remote location. Ensure that a properly configured .dat file is available in the path specified (local or remote). Ensure that the RepoUrl has been specified accurately in the adapter’s .tra file.

Why does the adapter startup fail?

Ensure that the RepoUrl syntax has been specified accurately in the adapter’s .tra file. Ensure that the path specified for the .tra file is correct.

Why does the adapter startup fail, even after specifying the appropriate dat file?

You must start the repository server before you start the adapter. If it is a remote repository ensure that the RepoUrl syntax has been specified accurately in the adapter’s .tra file. Ensure that the path specified for the .tra file is correct.

When saving an adapter configuration to the project, if an error occurs where is it logged?

TIBCO Designer error messages are logged to the files stderr.log and designer.log under the TIBCO_HOME\Designer\<ver>\logs directory.

When an error occurs in a Subscription Service adapter service, where is it displayed?

Errors that occur in a request-response operation are sent to the client. Errors that occur in a subscription service are logged to a trace file. The log file path and name is set in the .tra file corresponding to the adapter instance. All logs are sent to <install_path>\adapter\<adapter name>\<version>\logs unless otherwise specified.

Why does the adapter fail to respond to a request?

The subject name may be inconsistent. The subject name to which the adapter listens may be different from that of the subject name of the client.


Frequently Asked Questions | 483

Why does the adapter fail to respond to a request after successfully receiving it?

The adapter may fail to respond due to various reasons like errors resulting from class mismatch, records not being available in the target application or, connectivity problems with the target application.

I am subscribing to an IDoc using an inbound instance to post into the R/3 system. What happens to the IDoc if the connection to the R/3 system goes down just before the adapter receives the IDoc or while processing the IDoc ?

On receipt of an IDoc, the subscriber instance checks for validity of the connection to R/3 before posting. If the connection is found to be invalid, the adapter immediately starts a timer to check for connections to R/3 periodically and suspends the IDoc subscriber so that no further messages are received. The IDoc message is not confirmed to the sending system.

When the R/3 system comes up again, the adapter re-establishes connectivity, and restarts itself automatically to receive the unconfirmed IDoc message.

The connection timer’s polling interval is configurable. This recovery mechanism is also available for Inbound oneway RVCM messages.

I have to send sales order information as IDocs to my partner system. The partner is interested in the information coming in just one segment of the IDoc. Do I still have to publish the entire IDoc to the partner?

The publication service of the adapter provides a way to filter irrelevant information from IDocs coming out of the R/3 system at both segment and field levels. This feature allows selective publication of only those segments or fields that the partner is interested in.

A partner profile in our R/3 system is configured to ’collect IDocs’ to push the IDocs out in a batch. Can the adapter also be configured to publish IDocs in batches?

The explode batch format of IDoc publication allows you to bunch and publish IDocs in completely self-describing format in one batch, the size of the batch being equal to the packet size configured in R/3 for the partner profile.

Why does the adapter startup fail, and give the following error, ’Failed to enable CM transport’?

The possibilities of this error are:

• There might be another instance running under the same CM session.

• Permission to create ledger file under the specified directory might be denied.

• The ledger file to be created for the CM session might be corrupted.



Check all these before starting the adapter. If you find a corrupted ledger file, then delete the file. But you might miss some messages.

How can I update my repository, when there is a change in the schema for IDoc in the SAP system, without losing my mappings?

Whenever there is a change in IDoc, the IDoc has to be downloaded again. The configured service for the IDoc should be deleted and recreated with the new IDoc.

If the change in IDoc does not disturb the mapped parameters then the mappings will not be affected. For example, if you add new export parameter to the schema. In your mappings you will be able to find the new export parameter along with the other mappings.

If you delete the parameter being mapped from the schema, then the mapping for the parameter will be lost.

How can I debug my ABAP code when executing the program using the adapter?

The adapter provides an option called ABAP Debug. This flag has to be set to 1 during adapter configuration. See Setting up Client Configuration Options on page 218 for details. Thus once that ABAP program is called, the adapter opens up the SAP GUI, and then you can debug your ABAP code.

How many connections are possible per SAP ID?

Maximum connections per SAP ID should not go above 300. This limit is imposed by SAP. Also SAP licensing is based on user names and not number of connections.

What should I do if I do not want to have a permanent connection to SAP, but would like to have a connection established by the adapter when required?

You can dynamically set up connection to SAP when the adapter receives the message. In case of RFC, you can select the checkbox Logon Required in the adapter services. Hence when that adapter service receives the request, it first establishes connection with SAP before servicing it. You can additionally configure event based connection for RFC/IDOC service of an Inbound adapter. For information regarding its configuration, see Event Driven Inbound Connections on page 348

To use ABAP debug, you should have SAP GUI installed on the machine on which the adapter is being executed.



When sending IDocs from SAP, the adapter does not receive the IDocs but the SAP system shows that the IDocs were sent without any errors. Why isn’t the adapter receiving the IDocs?

This may be because you have more than one adapter listening to the same Program ID. Ensure that each adapter is configured for a separate program ID. To check if your program ID is not used by any other adapter at any given time, in SAP go to transaction sm59. Go to your program ID under TCP/IP, and then click on test connection. As your adapter instance is not up, the test connection should fail, or else there is someone else using the same program ID.

How do I know what version and patch level of the adapter, TRA, and Designer I am using?

For exact TRA build, you can look up the file, version.txt under /tibco/tra/5.1. When you start the adapter, you will see a banner which will give you the adapter version and patch level. When you open the TIBCO Designer, click the Help menu select About. A popup displays the TIBCO Designer version and the build.

How can the Load Balancing feature of the adapter be used on the Outbound side?

For outbound load balancing, TID Manager can be used. To set up TID Manager, during the adapter instance configuration, in the Adapter Services tab of the adapter instance, select TID Management as Remote. For more information on its configuration refer to the TIDManager on page 250. Make sure that you bring up the TID Manager first before your bring up the adapter instances.

How can the Load Balancing feature of the adapter be used on the Inbound side?

For Inbound load balancing, the Distributed Queue feature of the adapter can be used. For more information on configuration and its usage refer to Load Balancing Using Distributed Queue on page 260.

When can I use Remote TID Management?

TID Management can be used to avoid duplication on the Outbound as well as Inbound side when you have more than one adapter instance publishing or subscribing the same IDOCs or tRFCs.

Adapter when processing Latin-2 data, throws up error "Unicode conversion failure: Failed to convert type "ibm-943 " to Unicode - have you defined the env var TIB_ICU_DATA to point to



the directory that contains tibicudata.dat?" Why is the adapter displaying this error?

Please check whether the environment variable TIB_ICU_DATA is set to /tibco/tra/5.1/bin and this directory contains the file, tibciudata.dat. Also check whether the characters being sent to the adapter belongs to the locale set. For UNIX machines appropriate locales should be set as given in the Getting Ready to Run Unicode on UNIX section in Chapter 7 of the TIBCO Adapter for R/3 User’s Guide.

At times the adapter throws ’CPIC Error’ but after some time it continues processing the message. Is this something to worry?

CPIC error usually occurs when the adapter is unable to obtain connection to SAP. This may be due to network overload or glitches. It may be also due to some transient network problems. To verify the same, you can try connecting to SAP from the SAP GUI installed on the same machine on which the adapter is throwing the error.

Adapter gives core dump on HP-UX and AIX machines. Why does this happen?

The adapter requires you to increase the stacksize by setting the same in the adapter properties file. For more information on stack size and its settings, see Multithreading on page 339.

I want to open a Support Call. What information should I include in my request so as to avoid unnecessary delays?

If you are planning to open an SR just for information purpose, then please include the TIBCO Adapter for R/3 version and patch level, the platform on which the adapter is running and the version of SAP system.

If you are opening an SR because you are facing some problems and getting errors, then please do not forget to include the following:

• TIBCO Adapter for R/3 Version and patch level

• The TRA version and patch level

• TIBCO Designer version and patch level

• Platform on which the adapter is being run

• Fresh adapter log files (if error occurs during adapter execution) or Designer Log files and Designer Console Output (if error is occurring during configuration)

• The repository in which you are getting the error and also the adapter properties file (adr3.tra)



• The SAP R/3 version

• Additional information regarding other components like TIBCO IntegrationManager or TIBCO BusinessWorks if acting as source of message to the adapter. Also please include your contact information.


| 489

Appendix D SAP R/3 ALE Configuration

You must enable a SAP R/3 ALE system to publish and subscribe to messages in the TIBCO environment by carrying out appropriate customization. No modifications or additional code is required in the SAP R/3 system itself. This chapter gives an overview of the steps for customizing a SAP R/3 ALE system. It shows the two example configuration processes performed using the SAP R/3 system version 3.1H. (For other SAP versions refer to SAP documentation.)

Topics

• SAP R/3 Graphic User Interface Version 3.1H, page 490


490 | Appendix D SAP R/3 ALE Configuration

SAP R/3 Graphic User Interface Version 3.1H

The following section provides the steps required to customize the SAP R/3 ALE system, using the SAP GUI version 3.1H to operate with the adapter.

• Creating a Logical System for an Adapter Instance

• Creating a Logical System for the Adapter

• Establishing the Distribution Model

• Defining RFC Destinations

• Maintaining Partner Profile

• Defining an Extended IDoc Type:


SAP R/3 Graphic User Interface Version 3.1H | 491

Step 1: Creating a Logical System for an Adapter Instance

The first requirement is to create an ALE Logical System to represent the SAP application. The logical system set up here will be used by the ALE customer distribution model and the outbound partner agreements.

To create a logical system for the adapter, perform the following steps:

1. Log onto the SAP Server.


3. Navigate to

Basic Configuration > Set up logical system > Maintain logical systems



When you double-click the check mark in front of the phrase Maintain logical system the following warning screen appears.



4. Click to continue. The following Change View screen appears:

5. Click New Entries to request the interface used to create a new logical system. An empty New Entries List screen appears.



6. Enter the name of the new application logical system — PUBLISHER is shown below for example — under the column Log.System. You should enter a suitable description under column Short Text.

7. To save the new logical system, click . Then click to return to the Change View screen. Verify the creation of the new logical system by scrolling down the alphabetical list to the new entry.

8. Click to go to the initial screen.



Step 2: Creating a Logical System for the Adapter


2. Navigate to

BasicConfiguration>Set up logical system>Allocate Logical System to the Client

The following Change View screen appears with a list of the current client IDs and corresponding description.



3. Click New Entries. The following New Entries screen appears.



4. Key in the client identification information. The following screen shows an example of a client ID equal to 850.

5. Click to save the new client information.

6. Save the changes.

7. Click to exit.

After completion of this step, you have two logical systems: the one that represents the adapter and the one that is assigned to the client (sending and receiving SAP R/3 system).



Step 3: Establishing the Distribution Model

You have to define which logical message types are to be exchanged between the SAP R/3 ALE system and the adapter. Perform the following steps:


Distribution Customer Model>Maintain customer distribution model directly


2. Click the Maintain customer... line and then click Choose. The following screen appears:

Using the down arrow feature, choose the logical system that is assigned to the client out of which messages are to be sent. Logical system CERMAND850 is shown in the example. You can use the customer model SUBSYSTEMS, create one of your own, or use one that has previously been created.



Click to change (add to) the list of IDoc Message Types. The Model SUBSYSTEMS screen appears.

3. Scroll down to logical system defined for the PUBLISHER.

4. Click on the PUBLISHER logical system name to highlight it and to make it the subject logical system associated with the new IDoc message type that is going to be created.



5. To assign a logical message type to be transferred to the adapter PUBLISHER logical system, click on the Create message type button. The following screen appears:

6. In this screen you need to define the new message type. You can either enter the message type or select it with the down arrow as shown in the figure.

7. Click the Transfer button. This adds the new message type and returns you to the Model SUBSYSTEMS screen. In this screen, you can check that the new message type has been added.



8. To add other message types to the logical system, repeat step 5 through step 7. When all the message types have been added, the list of message types associated with the logical system will appear as follows:

9. Click to save the transaction and click to exit.

Figure 22 summarizes the set up of the client distribution model as set up for the TIBCO Adapter for R/3 publication service.

Figure 22 Client Distribution Model



Step 4: Defining RFC Destinations

An RFC destination allows the SAP R/3 system to call service functions in the R/3 Outbound Adapter configured as an IDoc Publisher. RFC uses TCP/IP to interface with the IDoc Publisher. One or more RFC destinations for IDoc publisher processes have to be defined. Usually, only one RFC destination is used. Multiple IDoc publisher processes can be load balanced by an R/3 gateway via a single RFC destination. Multiple destinations can be useful when different destinations are to be used for different ports. The ports are in turn used for different message types.

1. Run the sale transaction and navigate to,

Communication>Define RFC Destination>TCP/IP connections




2. Now create a new TCP/IP RFC destination by clicking on the Create button. The following RFC Destination window appears:



3. In the RFC Destination window, specify the adapter logical system you created as the RFC destination (PUBLISHER, for example), choose T (TCP/IP connection) as the connection type, enter any suitable description, Language E for English. The following window is an example of a new RFC destination entry:

4. Save when all entries are complete. On the next window, click Registration and specify the Program ID.

When using the RFC destination you must ensure that the Program ID defined here matches the Program ID specified in the adapter instance. See Configuring Default Server Connection on page 222.



5. When the entries are complete, as shown in the following example window, save them.

After specifying the configuration, the connection can be tested by selecting Test Connection. Make sure that the R/3 Outbound IDoc Publisher is already running and configured properly before testing.



Step 5: Maintaining Partner Profile


Communication>Manual Maintenance of Partner Profiles>Define Port

2. Position the cursor on Transactional RFC and click create.

3. Click New entries on the next screen. Enter some description for the new port, and under Logical Destination enter the name of the previously defined RFC destination.



If multiple logical message types are used in your environment, it is a good idea to define different ports for different message types or for groups of message types. The ports can initially all be mapped to the same RFC destination. Later, additional RFC destinations can be introduced and the mapping can be changed as needed.

An outbound partner profile must be defined for each logical message type that is to be sent on TIBCO Rendezvous. The outbound partner profile defines the message syntax to be used for the logical message type, the transfer mode, the port to send to, and the workflow parameters (where error notifications are to be sent etc.).

4. Run transaction "sale" and work through the hierarchy displayed to

Communication > Manual Maintenance of Partner Profiles > Maintain Partner Profile

5. On the following screen, enter the name (“Partn. number”) you gave the logical system representing the software bus and LS as the partner type (“Partn. type”).



6. Select Outbound Parameters.

7. Enter the appropriate port that you have defined previously. For near real-time communication between SAP R/3 and the R/3 Adapter Publisher, set the Output mode to Transfer IDoc immed. With this option, the package size (Pack. size) does not matter, but a value must be specified, nevertheless.

8. In some scenarios it might be desired to use batch mode to use communication resources more sparingly. For Batch Mode, set Output mode to Collect IDocs and set the package size (Pack. size) to the number of IDocs to send in a batch.

9. Under IDoc type, enter one of the IDoc types that are suitable for the logical message type (SISCSO in the above example). This completes the partner profile.



Step 6: Defining an Extended IDoc Type

SAP R/3 makes basic IDoc types available for use with SAP processes. You can create extensions to a basic IDoc type using the procedure described in this section.

1. To create an IDoc extension, initiate transaction WE30. The Develop IDoc Types screen is displayed. An example of this screen is shown below:

2. Set the Extension radio button as shown below to indicate that you are going to create an extension to an existing IDoc type.

3. Enter the name of your IDoc extension in the ObjectName text box. Note that names used by SAP are case insensitive. See the following example.



4. Click the Create icon (folded paper) or enter the function F5 key to proceed with extension creation. The Create extension screen is displayed, as shown below.

5. Set the Create new radio button. This step associates the new extension with a basic IDoc type. This is done by entering the name of a basic IDoc type, such as DEBMAS03, in the text entry box labeled Linked basic type, as shown in the following example.

If you do not remember the exact name of the basic type, you can select it from a list displayed when you click on the down arrow to the right of the text entry box. When you have entered the basic IDoc type, enter a description in the Description box. When your entries are complete, click the check mark to proceed with the extension creation.

6. The following Create extension screen is displayed. This screen shows the initial default segments contained in the new IDoc extension, as defined by



the basic IDoc type (DEBMAS03 in the example). Add segments using this screen.

7. For example, you can add a second child segment to segment E1KNA1L by highlighting the current child segment and clicking .

8. An information screen is displayed as shown in the following example. Click

to acknowledge the information.



9. The Attribute Maintenance screen is displayed as in the following example. Enter a valid existing segment type, such as ZZMARCM show in the example screen. Also enter values for the Minimum and Maximum Number of segments allowable. Click to execute.

10. The Create Extension screen is displayed again with the new child segment as shown in the example below. Save the new IDoc extension.



11. The Create Object Directory Entry screen is displayed as shown in the following example. Enter the Development class that you wish to associate with the new IDoc extension.

12. For example, ZCA0 could be selected as the Development class.

13. Once you save, the Change Request screen is displayed, as shown in the following example.

14. Click to execute the change request. This completes the creation of the IDoc extension.


| 515

Appendix E Wireformat Backward Compatibility

This appendix describes wireformat backward compatibility.

Topics

• Backward Compatible RV Message Specification, page 516


516 | Appendix E Wireformat Backward Compatibility

Backward Compatible RV Message Specification

The R/3 Publisher Adapter receives IDocs from an SAP R/3 system and converts them into TIBCO Rendezvous messages, which are then published on TIBCO Rendezvous. The R/3 Subscriber Adapter listens for (subscribes to) these messages, receives the data, converts it to IDocs, which are then posted to the receiving SAP R/3 system.

This R/3 Adapter supports two different types of message formats for backward compatibility. They are briefly described below. The section that follows elaborates on the formats.

• SAPCIF: The IDoc is first converted into SAP Certified Intermediate Format and then packed into an RV message. This RV message contains the IDoc header data followed by IDoc data in SAPCIF format. All the fields present in SAPIDOCOPAQUE message type are present in SAPCIF, except that the message values are presented in the form of name-value pairs. Each IDoc is packed into a separate RV message.

• BATCHED: This format is provided to support more efficient handling of IDocs in groups or “batches.” In batch mode one or more IDocs can be sent in a packet by the SAP R/3 system to the R/3 Adapter Publisher. All the IDocs received in the packet are added to a single RV message. The RV message is appended with IDoc header information followed by the packet of IDoc data. In batch mode, even if only one IDoc is sent, the R/3 Adapter still handles the RV message creation as if the IDoc were in a packet. Note that if the “PutEndOfLineInIDOC” is set to 1 in the adapter Publisher configuration file, the Publisher will put a line-feed character at the end of each row of IDoc control and data records before publishing them to TIBCO Rendezvous.

Message FieldsIn all three message types the IDoc data is packed in the RV message as ASCII text that is further divided into fields. Some of the fields must be present in all IDocs and others are present for particular IDoc types.

The following table summarizes the message field format requirements for version 1.0.x.

IDoc Field Name RV Message Type CIF Batched

SAPIDocType RVMSG_STRING X

SAPIDocRel RVMSG_STRING X


Backward Compatible RV Message Specification | 517

SAPIDocEnc RVMSG_UINT X X

SAPIDocMsga RVMSG_STRING X X

SAPIDocTableName RVMSG_STRING X X

EOLPresent RVMSG_BOOLEAN X

NUMBEROFIDOCS RVMSG_UINT X

a. If compression is enabled, the Rendezvous message type is RVMSG_OPAQUE



The fields are describes below.

Field Name:SAPIDocType

Type: RVMSG_STRING

Length: Variable

Valid values: Valid IDoc types e.g. “MATMAS02” or “CREMAS01” or “SISCSO01” etc.

Description: The IDocTYPE parameter of the control record of an IDoc. It specifies the IDoc Type.

Required?: Yes.

Field Name: SAPIDocRel

Type: RVMSG_STRING

Length: 3 bytes

Valid values: Three-byte SAP release indicator; e.g. “31H” or “40B” or “31G” etc.

Description: The SAP R/3 system release from where the IDoc originated.

Required?: Yes.

Field Name: SAPIDocNo

Type: RVMSG_STRING

Length: 16 bytes

Valid values: Positive number represented as string and appropriately padded with zeros, e.g. “0000000000152674”

Description: The unique IDoc number assigned by SAP R/3 to IDoc in ALE (Application Link Enabling) communication layer, when it is being sent to the server program (Publisher Adapter).

Required?: Yes.

Field Name: SAPIDocSize

Type: RVMSG_UINT

Length: The size of an RVMSG_UINT


Backward Compatible RV Message Specification | 519

Description: The size of an ASCII IDoc data string in number of bytes.

Required?: Yes.

Field Name: SAPIDocEnc

Type: RVMSG_UINT


Valid values: 0 (SAPCIF) or 1(SAPIDOCOPAQUE format) or 2 (BATCHED)

Description: The encoding format in which the IDoc is being transmitted.

Required?: Yes.

Field Name: SAPIDocTableName

Type: RVMSG_STRING

Length: Variable

Valid values: “EDI_DC” or “EDI_DC40”

Description: Control field table name. The string in this field is either “EDI_DC” to indicate the data is from SAP version 3.x or “EDI_DC40” to indicate the data is from SAP version 4.x.

Required?: Yes.



Field Name: EOLPresent

Type: RVMSG_BOOLEAN

Length: 1 byte

Valid values: 1 for true, 0 for not true

Description: In a message containing BATCH IDOCs, the IDOCs individual lines, of control records and data records can be combined and sent as one continuous chunk of ASCII data without any line breaks. In such a case the EOLPresent is equal to 0. When each line is separated from other by a line break EOLPresent is equal to 1

Required?: In Batch IDocs only.

Field Name: NUMBEROFIDOCS

Type: RVMSG_UINT


Valid values: A count greater than zero.

Description: The number of IDOCs transmitted in a batch

Required?: In Batch IDocs only.

Field Name: SAPIDocMsg

Type: RVMSG_STRING

Length: Variable

Description: The ASCII IDoc data that is sent in the RV message. The IDoc data begins with the IDoc type indicator followed in sequence by IDoc release indicator, the control record, and a number of data records. Each of the indicator or record types is terminated by end of line symbol. The valid lengths for control record and data record for IDoc versions 3.1H and lower are 464 (+1 for end of line) and 1055 (+1 for end of line) respectively. The valid lengths for IDoc versions 4.0B and later are 524 (+1 for end of line) and 1063 (+1 for end of line) respectively for control and data records.


TIBCO Software Inc. End User License Agreement | 521

TIBCO Software Inc. End User License AgreementREAD THIS END USER LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING THE SOFTWARE, YOU AGREE TO BE BOUND BY THIS AGREEMENT. IF YOU DO NOT AGREE TO THESE TERMS, DO NOT DOWNLOAD OR INSTALL THE SOFTWARE AND RETURN IT TO THE VENDOR FROM WHICH IT WAS PURCHASED. RETURNS BY THE ORIGINAL PURCHASER WITHIN THIRTY (30) DAYS OF THE PURCHASE DATE WILL RECEIVE A FULL REFUND.

Upon your acceptance as indicated above, the following shall govern your use of the Software except to the extent all or any portion of the Software (a) is subject to a separate written agreement, (b) includes a separate "click-on" license agreement as part of the download or installation process, or (c) is provided by a third party under the terms set forth in an Addenda at the end of this Agreement, in which case the terms of such addenda shall control over inconsistent terms with regard to such portion(s).

License Grant. The Software is the property of TIBCO or its licensors and is protected by copyright and other laws. While TIBCO continues to own the Software, TIBCO hereby grants to Customer a limited, non-transferable, non-exclusive, license to use the number of Permitted Instances set forth in the Ordering Document, in machine-readable, object code form and solely for Customer’s internal business use.

Restrictions. Customer agrees not to (a) make more copies than the number of Permitted Instances plus a reasonable number of backups; (b) provide access to the Software to anyone other than employees, contractors, or consultants of Customer; (c) sublicense, transfer, assign, distribute to any third party, pledge, lease, rent, or commercially share the Software or any of Customer’s rights under this Agreement (for the purposes of the foregoing a change in control of Licensee is deemed to be an assignment); (d) use the Software for purposes of providing a service bureau, including, without limitation, providing third-party hosting, or third-party application integration or application service provider-type services, or any similar services; (e) use the Software in connection with ultrahazardous activities, or any activity for which failure of the Software might result in death or serious bodily injury to Customer or a third party; or (f) directly or indirectly, in whole or in part, modify, translate, reverse engineer, decrypt, decompile, disassemble, make error corrections to, create derivative works based on, or otherwise attempt to discover the source code or underlying ideas or algorithms of the Software.

Beta and Evaluation Licenses. Notwithstanding the foregoing, if the Software is being provided for demonstration, beta testing, or evaluation purposes, then Customer agrees (a) to use the Software solely for such purposes, (b) that the Software will not be used or deployed in a production environment, and (c) that such use shall automatically terminate upon the earlier of thirty days from the date Customer receives the right to install the Software, or Customer’s receipt of notice of termination from TIBCO.

Technical Support. Provided Customer has paid applicable support fees (not included with Software fees unless separately listed), TIBCO shall provide support for generally available TIBCO Software on an annual basis commencing on the Purchase Date, as follows ("Support"): Customer shall designate at TIBCO’s support website https://support.tibco.com/eSupport/newuser.html, the number of technical support contacts permitted under the level of Support purchased (contacts are changeable upon 48-hours prior written notice to TIBCO). Each contact may contact TIBCO for problem

resolution during TIBCO’s published support hours corresponding to the level of Support fees paid.

Upon notice from a contact of a Software problem which can be reproduced at a TIBCO support facility or via remote access to Customer’s facility, TIBCO shall use reasonable efforts to correct or circumvent the problem according to its published support objectives. TIBCO reserves the right to make changes only to the most currently available version. TIBCO will use reasonable efforts to support the previously released version of the Software for a maximum of six months.

TIBCO shall have no obligation to support the Software (i) for use on any computer system running other than the operating system software for which the Software is approved (as set forth in the Software documentation) and licensed hereunder, or (ii) if Customer has modified or authorized a third party to modify the Software. TIBCO shall have no obligation to modify any version of the Software to run with any new versions of any operating system, or any other third party software or hardware. If Customer purchases Support for any Software, Customer must purchase the same level of Support for all copies of the Software for which it is licensed.

Support may be extended for one-year periods on the anniversary of each Purchase Date at the standard amounts set forth in its price list, for as long as TIBCO offers Support. Customer may reinstate lapsed support for any then currently supported Software by paying all Support fees in arrears and any applicable reinstatement fee. Upgrades, patches, enhancements, bug fixes, new versions and/or new releases of the Software provided from time to time under Support shall be used only as replacements to existing Permitted Instances, and shall not be deemed to increase that number, and use thereof shall be governed by the terms of this Agreement, except for the first paragraph of the Limited Warranty and any right of return or refund.

Consulting Services. Customer may request additional services ("Services") either in an Ordering Document, or by a separate mutually executed work order, statement of work or other work-request document incorporating this Agreement (each, a "Work Order"). Unless otherwise expressly agreed to in a Work Order, all Services and any work product therefrom shall be (a) performed on a time and materials basis, plus meals, lodging, travel, and other expenses reasonably incurred in connection therewith, (b) deemed accepted upon delivery, and (c) exclusively owned by TIBCO (except for confidential information of Customer identified to TIBCO in the Ordering Document), including all right, title and intellectual property or other right or interest therein. Each Work Order is intended to constitute an independent and distinct agreement of the parties, notwithstanding that each shall be construed to incorporate all applicable provisions of this Agreement. Specific to TIBCO training services, additional information regarding courses, registration, restrictions or limitation can be found at TIBCO’s website at http://www.tibco.com/services/education under Education Programs. Fees for Services shall be due and payable in United States dollars net 30 from the date of TIBCO’s invoice.

Limited Warranty. If Customer obtained the Software directly from TIBCO, then TIBCO warrants that for a period of thirty (30) days from the Purchase Date: (i) the media on which the Software is furnished will be free of defects in materials and workmanship under normal use; and (ii) the Software will substantially conform to its published specifications. This limited warranty extends only to the original Customer hereunder. Customer’s sole and exclusive remedy and the


522 | TIBCO Software Inc. End User License Agreement

entire liability of TIBCO and its suppliers under this limited warranty will be, at TIBCO’s option, repair, replacement, or refund of the Software and applicable Support fees, in which event this Agreement shall terminate upon payment thereof.

This warranty does not apply to any Software which (a) is licensed for beta, evaluation, testing or demonstration purposes for which TIBCO does not receive a license fee, (b) has been altered or modified, except by TIBCO, (c) has not been installed, operated, repaired, or maintained in accordance with instructions supplied by TIBCO, (d) has been subjected to abnormal physical or electrical stress, misuse, negligence, or accident, or (e) is used in violation of any other term of this Agreement. Customer agrees to pay TIBCO for any Support or Services provided by TIBCO related to a breach of the foregoing on a time, materials, travel, lodging and other reasonable expenses basis. If Customer obtained the Software from a TIBCO reseller or distributor, the terms of any warranty shall be as provided by such reseller or distributor, and TIBCO provides Customer no warranty with respect to such Software.

EXCEPT AS SPECIFIED IN THIS LIMITED WARRANTY, THE SOFTWARE, SUPPORT AND SERVICES ARE PROVIDED "AS IS", ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS, AND WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, SATISFACTORY QUALITY OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE, ARE HEREBY EXCLUDED TO THE EXTENT ALLOWED BY APPLICABLE LAW. NO WARRANTY IS MADE REGARDING THE RESULTS OF ANY SOFTWARE, SUPPORT OR SERVICES OR THAT THE SOFTWARE WILL OPERATE WITHOUT ERRORS, PROBLEMS OR INTERRUPTIONS, OR THAT ERRORS OR BUGS IN THE SOFTWARE WILL BE CORRECTED, OR THAT THE SOFTWARE’S FUNCTIONALITY OR SERVICES WILL MEET CUSTOMER’S REQUIREMENTS. NO TIBCO DEALER, DISTRIBUTOR, AGENT OR EMPLOYEE IS AUTHORIZED TO MAKE ANY MODIFICATIONS, EXTENSIONS OR ADDITIONS TO THIS WARRANTY.

Indemnity. If Customer obtained the Software from TIBCO directly, then TIBCO shall indemnify Licensee from and against any final judgment by a court of competent jurisdiction, including reasonable attorneys’ fees, that the unmodified TIBCO Software infringes any patent issued by the United States, Canada, Australia, Japan, or any member of the European Union, or any copyright, or any trade secret of a third party; provided that TIBCO is promptly notified in writing of such claim, TIBCO has the exclusive right to control such defense and/or settlement, and Licensee shall provide reasonable assistance (at TIBCO’s expense) in the defense thereof. In no event shall Licensee settle any claim, action or proceeding without TIBCO’s prior written approval. In the event of any such claim, litigation or threat thereof, TIBCO, at its sole option and expense, shall (a) procure for Licensee the right to continue to use the TIBCO Software or (b) replace or modify the TIBCO Software with functionally equivalent software. If such settlement or modification is not commercially reasonable (in the reasonable opinion of TIBCO), TIBCO may cancel this Agreement upon sixty days prior written notice to Licensee, and refund to Licensee the unamortized portion of the license fees paid to TIBCO by Licensee based on a five-year straight-line depreciation. This Section states the entire liability of TIBCO with respect to the infringement of any Intellectual Property rights, and Licensee hereby expressly waives any other liabilities or obligations of TIBCO with respect thereto. The foregoing indemnity shall not apply to the extent any infringement could have been avoided by use of the then-current release.

Limitation of Liability. EXCEPT AS PROVIDED UNDER INDEMNITY OR RESULTING FROM A BREACH OF CONFIDENTIALITY (THE "EXCLUDED MATTERS"), IN NO EVENT WILL EITHER PARTY BE LIABLE FOR ANY LOST DATA, LOST REVENUE, LOST PROFITS, DAMAGE TO REPUTATION, BUSINESS INTERRUPTION, OR ANY OTHER INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL, PUNITIVE, EXEMPLARY OR ANY SIMILAR TYPE DAMAGES ARISING OUT OF THIS AGREEMENT, THE USE OR THE INABILITY TO USE THE SOFTWARE, OR THE PROVISION OF ANY SUPPORT OR SERVICES, EVEN IF A PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. EXCEPT FOR THE EXCLUDED MATTERS, IN NO EVENT SHALL A PARTY BE LIABLE TO THE OTHER, WHETHER IN CONTRACT, TORT (INCLUDING ACTIVE OR PASSIVE NEGLIGENCE), BREACH OF WARRANTY, CLAIMS BY THIRD PARTIES OR OTHERWISE, EXCEED THE PRICE PAID BY CUSTOMER UNDER THE APPLICABLE ORDERING DOCUMENT.

THE FOREGOING LIMITATIONS SHALL APPLY EVEN IF THE ABOVE-STATED REMEDY OR LIMITED WARRANTY FAILS OF ITS ESSENTIAL PURPOSE. BECAUSE SOME STATES OR JURISDICTIONS DO NOT ALLOW LIMITATION OR EXCLUSION OF CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO CUSTOMER.

Confidentiality. "Confidential Information" means the terms of this Agreement; all information marked by the disclosing party as proprietary or confidential; any provided software, related documentation or related performance test results derived by Licensee; and any methods, concepts or processes utilized in provided software or related documentation. Confidential Information shall remain the sole property of the disclosing party and shall not be disclosed to any non-Authorized User without the prior written consent of the disclosing party. If Confidential Information is communicated orally, such communication shall be confirmed as "Confidential" in writing within thirty days of such disclosure. The parties agree to protect the Confidential Information of the other in the same manner it protects the confidentiality of similar information and data of its own (and at all times exercising at least a reasonable degree of care). Except with respect to the Software, items will not be deemed Confidential Information if (i) available to the public other than by a breach of an agreement with TIBCO, (ii) rightfully received from a third party not in breach of any obligation of confidentiality, (iii) independently developed by one party without use of the Confidential Information of the other; (iv) known to the recipient at the time of disclosure (other than under a separate confidentiality obligation); or (v) produced in compliance with applicable law or court order, provided the other party is given reasonable notice of the same. Both parties agree to indemnify the other for any damages the other may sustain resulting from their unauthorized use and/or disclosure of the other’s Confidential Information. Such damages shall include reasonable expenses incurred in seeking both legal and equitable remedies. To the extent required by law, at Customer’s request, TIBCO shall provide Customer with the interface information needed to achieve interoperability between the Software and another independently created program, on payment of TIBCO’s applicable fee. Customer agrees to observe obligations of confidentiality with respect to such information.

Export. Software, including technical data, is subject to U.S. export control laws, including the U.S. Export Administration Act and its associated regulations, and may be subject to export or import regulations in other countries. Customer agrees to comply strictly with all such regulations and agrees to obtain all necessary licenses to export, re-export, or import Software.


TIBCO Software Inc. End User License Agreement | 523

Government Use. If the Customer is an agency, department, or other entity of the United States Government ("Government"), the use, duplication, reproduction, release, modification, disclosure or transfer of the Software, or any related documentation of any kind, including technical data or manuals, is restricted in accordance with Federal Acquisition Regulation ("FAR") 12.212 for civilian agencies and Defense Federal Acquisition Regulation Supplement ("DFARS") 227.7202 for military agencies. The Software is commercial computer software and commercial computer software documentation. Use of the Software and related documentation by the Government is further restricted in accordance with the terms of this Agreement, and any modification thereto.

Orders. An Ordering Document shall be deemed accepted only by issuance of a TIBCO invoice and solely for purposes of administrative convenience. None of the terms of the Ordering Document (other than the Software product name, number of Permitted Instances, level of Support, description of Services, and fees due in connection therewith) shall apply for any reason or purpose whatsoever, regardless of any statement on any Ordering Document to the contrary, unless countersigned by an officer of TIBCO. This Agreement constitutes the entire agreement between the parties with respect to the use of the Software, Support and Services, and supersedes all proposals, oral or written, and all other representations, statements, negotiations and undertakings relating to the subject matter hereof. All orders of Software, Support or Services by Customer from TIBCO shall be deemed to occur under the terms of this Agreement (with or without reference to this Agreement), unless expressly superseded by a signed written Agreement between the parties. Software shall be delivered electronically (unless physical shipment is specifically set forth in an Ordering Document), and such delivery shall occur upon e-mail of download information to Licensee at the email address set forth in the Ordering Document or as otherwise provided by Customer to TIBCO. Physical deliveries (if applicable) of Software and documentation which typically accompanies the Software on delivery shall be on CD-ROM, FOB TIBCO, and delivery shall occur by depositing the CD-ROM with TIBCO’s overnight carrier (at no charge to Customer).

Term and Termination. Support or Services may be terminated: (a) by either party upon a default of the other, such default remaining uncured for fifteen days from written notice from the non-defaulting party; (b) upon the filing for bankruptcy or insolvency of the other party, (c) by either party upon prior written notice at least sixty days prior to the end of any annual Maintenance period; or (d) by Licensee (for Services), upon ten days prior written notice. Termination of Support or Services shall not terminate this Agreement. Customer may terminate this Agreement in its entirety at any time by destroying all copies of the Software. Upon termination of this Agreement in its entirety, for any reason, Customer must cease using and return or destroy all copies of the Software. Customer’s obligation to pay accrued charges and any fees due as of the date of termination, as well as the sections entitled "Confidentiality", "Limited Warranty" and "Limitation of Liability" shall survive any such termination.

Authority. You hereby represent and warrant that you have full power and authority to accept the terms of this Agreement on behalf of Customer, and that Customer agrees to be bound by this Agreement.

General. Fees on the Ordering Document (all to be paid on the latter of thirty days from Invoice by TIBCO or the date set forth in the Ordering Document) do not include sales, use, withholding, value-added or similar taxes, and Customer agrees to pay the same, excluding therefrom taxes related to TIBCO’s income and corporate franchise tax. Customer agrees to pay all reasonable costs incurred (including reasonable attorneys’ fees) in collecting past due amounts under this Agreement. Except as set forth in the Section entitled

"Limited Warranty" all fees paid under or in connection with this Agreement are non-refundable and no right of set-off exists. All payments of fees due shall be made in U.S. dollars, net 30 from Purchase Date, or, for any other amounts coming due hereafter, net 30 from TIBCO’s invoice. A service charge of one and one-half percent per month will be applied to all invoices that are not paid on time. Licensee agrees to pay all sales, use, value-added, withholding, excise and any other similar taxes or government charges, exclusive of TIBCO’s income taxes. No delay in the performance of any obligation by either party, excepting all obligations to make payment, shall constitute a breach of this Agreement to the extent caused by force majeure. Customer hereby grants TIBCO and its independent auditors the right to audit Customer’s compliance with this Agreement. If any portion of this Agreement is found to be void or unenforceable, the remaining provisions shall remain in full force and effect. This Agreement shall be governed by and construed in accordance with the laws of the State of California, United States of America, as if performed wholly within the state and without giving effect to the principles of conflict of law. The state and/or federal courts in San Francisco, California, USA, shall have exclusive jurisdiction of any action arising out of or relating to this Agreement. The United Nations Convention on Contracts for the International Sale of Goods is excluded from application hereto. If any portion hereof is found to be void or unenforceable, the remaining provisions of this Agreement shall remain in full force and effect.

Definitions. In connection with this Agreement, the following capitalized terms shall have the following meaning: "Agreement" means this End User License Agreement; "Connection" for the TIBCO Software product TIBCO Enterprise for JMS - Full Edition means a TIBCO Enterprise for JMS client connection to the TIBCO Enterprise for JMS server for the purpose of sending or receiving messages and for the purposes of the TIBCO Software products TIBCO SmartSockets and TIBCO SmartMQ software products, a Connection means any network protocol link established with such TIBCO Software (directly or indirectly) to any other entity, including but not limited to software, firmware or hardware; "Customer" means the original purchaser or licensee of the Software and any permitted successors and assigns; "Developer" means one user/developer of a TIBCO Software product for use in Development; "Development" means used for software development purposes only; "Enterprise" means an unlimited number of Permitted Instances for a period of one year from the Purchase Date (unless otherwise set forth in the Ordering Document), at which time existing licenses convert to perpetual and Customer may not thereafter deploy additional Permitted Instances, and in any event, shall (during the one-year unlimited deployment period) exclude any entity which acquires, is acquired by, merged into, or otherwise combined with Customer. Customer hereby agrees to provide TIBCO with notice of the number of Permitted Instances deployed at the end of such one-year period within thirty days thereafter; "Fab" means unlimited use for shop-floor manufacturing applications at a Site; "Workstation" shall mean a single end-user computer that is generally intended to be accessed by one person at a time; "Ordering Document" means any purchase order or similar document or agreement requesting Software, Support or Services; "Permitted Instance(s)" means the number of copies of Software running on a Server Instance, Workstation, User, or Development basis, on a designated Platform, as set forth in an Ordering Document, including, without limitation, Enterprise, Site and Fab licensing; "Platform" means the operating system set forth in an Ordering Document; "Purchase Date" means the date the Ordering Document is accepted by TIBCO; "Server Instance" means a computer with 1 CPU (unless otherwise set forth in the Ordering Document) performing common services for multiple machines; "Site" means an unlimited number of Permitted Instances at a specific physical address set forth in the Ordering Document (or, in the absence of any address, at Customer’s corporate headquarters);


524 | TIBCO Software Inc. End User License Agreement

"Software" means the software products listed in an Ordering Document (except as provided in the second paragraph hereof), in whole and in part, along with their associated documentation; "TIBCO" means TIBCO Software Inc.; and "Named User" means the number of named users with access to the Software.

Special Product Provisions. TIBCO BusinessPartner: Customer may sublicense to third parties ("Partners") up to the total Number of Copies of TIBCO BusinessPartner, provided that for every such sublicense, the Number of Copies Customer is licensed to use shall be reduced by the same number, and provided further that prior to delivery of TIBCO BusinessPartner to a Partner, such Partner agrees in writing (a) to be bound by terms and conditions at least as protective of TIBCO as the terms of this Agreement, (b) that TIBCO BusinessPartner be used solely to communicate with Customer’s implementation of TIBCO BusinessConnect, and (c) for such Partner to direct all technical support and Maintenance questions directly to Customer. Customer agrees to keep records of the Partners to which it distributes TIBCO BusinessPartner, and to provide TIBCO the names thereof (with an address and contact name) within sixty days of the end of each quarter. Third Party Software: Use of any other third-party software identified by its company and/or product name or otherwise designated in Licensee’s Ordering Document (collectively "Third Party Software") is subject solely to the terms and conditions of the click-wrap or shrink-wrap license agreement included with the Third Party Software products, and for which TIBCO shall be an intended third-party beneficiary of same. TIBCO shall have no obligation whatsoever in connection with the Third Party Software (including, without limitation, any obligation to provide maintenance or support) and the provision of Third Party Software is accomplished solely as an accommodation and in lieu of Customer purchasing a license to Third Party Software directly from the third party vendor. Embedded/Bundled Products: Some TIBCO Software embeds or bundles other TIBCO Software (e.g., TIBCO InConcert bundles TIBCO Rendezvous). Use of such embedded or bundled TIBCO Software is solely to enable the functionality of the TIBCO Software licensed on the Cover Page, and may not be used or accessed by any other TIBCO Software, or for any other purpose. Open Source Software: If Licensee uses Open Source software in conjunction with the TIBCO Software, Licensee must ensure that its use does not (i) create, or purport to create, obligations of use with respect to the TIBCO Software, or (ii) grant, or purport to grant, to any third party any rights to or immunities under TIBCO’s intellectual property or proprietary rights in the TIBCO Software. You also may not combine the TIBCO Software with programs licensed under the GNU General Public License ("GPL") in any manner that could cause, or could be interpreted or asserted to cause, the TIBCO Software or any modifications thereto to become subject to the terms of the GPL.

Copyright (c) 1994-2003 TIBCO Software Inc. ALL RIGHTS RESERVED.

ADDENDA: Third Party License Agreements

NOTICE: Included with the TIBCO Software is certain source and/or object code software developed and licensed by third parties ("Third Party Software"). Third Party Software is licensed and supported exclusively under the terms and conditions of the license terms which accompany such Third Party Software, as set forth next.


Third Party Software License Agreements | 525

Third Party Software License Agreements

The Apache Software License, Version 1.1

Copyright (c) 1999 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

4. The names "Xerces", "Xalan" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected]. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

* THIS SOFTWARE IS PROVIDED ‘ ‘AS IS’’ AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

* This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, Lotus Development Corporation., http://www.lotus.com. For more information on the Apache Software Foundation, please see <http://www.apache.org/>./

The Apache Software License, Version 1.1

Copyright (c) 1999 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment:

"This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

4. The names "Xalan" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].

5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED ‘ ‘AS IS’’ AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, Lotus Development Corporation., http://www.lotus.com. For more information on the Apache Software Foundation, please see <http://www.apache.org/>.

W3C IPR SOFTWARE NOTICE

Copyright 2000 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

The DOM bindings are published under the W3C Software Copyright Noticeand License. The software license requires "Notice of any changes ormodifications to the W3C files, including the date changes were made."

Consequently, modified versions of the DOM bindings must document that they do not conform to the W3C standard; in the case of the IDL binding, the pragma prefix can no longer be ’w3c.org’; in the case of the Java binding, the package names can no longer be in the ’org.w3c’ package.


526 | Third Party Software License Agreements

Note: The original version of the W3C Software Copyright Notice and License could be found at http://www.w3.org/Consortium/Legal/copyright-software-19980720

Copyright 1994-2000 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/

This W3C work (including software, documents, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to use, copy, and modify this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications, that you make:

1.The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.

2.Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, a short notice of the following form (hypertext is preferred, text is permitted) should be used within the body of any redistributed or derivative code: "Copyright [$date-of-software] World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/"

3.Notice of any changes or modifications to the W3C files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any

associated documentation will at all times remain with copyright holders.

International Business Machines Corporation

This product includes software developed by International Business Machines Corporation. Copyright (c) International Business Machines. All rights reserved.

The terms of IBM Public License Version 1.0 apply to the TIBCO End User License Agreement. Any provisions in this License Agreement which differ from the terms of the IBM Public License Version 1.0 are

offered by TIBCO Software Inc., alone, and not by any other party. In the event provisions of this License Agreement differ from the terms of the IBM Public License Version 1.0, you may obtain the ICU source code by sending email to [email protected].

"IBM Public License Version 1.0

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS IBM PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT’S ACCEPTANCE OF THIS AGREEMENT.

1. DEFINITIONS

"Contribution" means: a) in the case of International Business Machines Corporation ("IBM"), the Original Program, and b) in the case of each Contributor, i) changes to the Program, and ii) additions to the Program; where such changes and/or additions to the Program originate from and are distributed by that particular Contributor. A Contribution ’originates’ from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor’s behalf. Contributions do not include additions to the Program which: (i) are separate modules of software distributed in conjunction with the Program under their own license agreement, and (ii) are not derivative works of the Program. "Contributor" means IBM and any other entity that distributes the Program.

"Licensed Patents " mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.

"Original Program" means the original version of the software accompanying this Agreement as released by IBM, including source code, object code and documentation, if any.

"Program" means the Original Program and Contributions. "Recipient" means anyone who receives the Program under this Agreement, including all Contributors.

2. GRANT OF RIGHTS

a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and such derivative works, in source code and object code form.

b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in source code and object code form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.

c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or



otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to distribute the Program, it is Recipient’s responsibility to acquire that license before distributing the Program.

d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.

3. REQUIREMENTS A Contributor may choose to distribute the Program in object code form under its own license agreement, provided that: a) it complies with the terms and conditions of this Agreement; and b) its license agreement: i) effectively disclaims on behalf of all Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose; ii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; iii) states that any provisions which differ from this Agreement are offered by that Contributor alone and not by any other party; and iv) states that source code for the Program is available from such Contributor, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange. When the Program is made available in source code form: a) it must be made available under this Agreement; and b) a copy of this Agreement must be included with each copy of the Program.

Each Contributor must include the following in a conspicuous location in the Program: Copyright ? {date here}, International Business Machines Corporation and others. All Rights Reserved. In addition, each Contributor must identify itself as the originator of its Contribution, if any, in a manner that reasonably allows subsequent Recipients to identify the originator of the Contribution.

4. COMMERCIAL DISTRIBUTION Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who include the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense. For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor’s responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other

Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.

5. NO WARRANTY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.

6. DISCLAIMER OF LIABILITY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. GENERAL

If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable. If Recipient institutes patent litigation against a Contributor with respect to a patent applicable to software (including a cross-claim or counterclaim in a lawsuit), then any patent licenses granted by that Contributor to such Recipient under this Agreement shall terminate as of the date such litigation is filed. In addition, If Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient’s patent(s), then such Recipient’s rights granted under Section 2(b) shall terminate as of the date such litigation is filed. All Recipient’s rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient’s rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient’s obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive. IBM may publish new versions (including revisions) of this Agreement from time to time. Each new version of the Agreement will be given a distinguishing version number.

The Program (including Contributions) may always be distributed subject to the version of the Agreement under which it was received.



In addition, after a new version of the Agreement is published, Contributor may elect to distribute the Program (including its Contributions) under the new version. No one other than IBM has the right to modify this Agreement. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved.

This Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights to a jury trial in any resulting litigation."

Sun Microsystems, Inc. Binary Code License Agreement

READ THE TERMS OF THIS AGREEMENT AND ANY PROVIDED SUPPLEMENTAL LICENSE TERMS (COLLECTIVELY "AGREEMENT") CAREFULLY BEFORE OPENING THE SOFTWARE MEDIA PACKAGE. BY OPENING THE SOFTWARE MEDIA PACKAGE, YOU AGREE TO THE TERMS OF THIS AGREEMENT. IF YOU ARE ACCESSING THE SOFTWARE ELECTRONICALLY, INDICATE YOUR ACCEPTANCE OF THESE TERMS BY SELECTING THE "ACCEPT" BUTTON AT THE END OF THIS AGREEMENT. IF YOU DO NOT AGREE TO ALL THESE TERMS, PROMPTLY RETURN THE UNUSED SOFTWARE TO YOUR PLACE OF PURCHASE FOR A REFUND OR, IF THE SOFTWARE IS ACCESSED ELECTRONICALLY, SELECT THE "DECLINE" BUTTON AT THE END OF THIS AGREEMENT.

1. LICENSE TO USE. Sun grants you a non-exclusive and non-transferable license for the internal use only of the accompanying software and documentation and any error corrections provided by Sun (collectively "Software"), by the number of users and the class of computer hardware for which the corresponding fee has been paid.

2. RESTRICTIONS. Software is confidential and copyrighted. Title to Software and all associated intellectual property rights is retained by Sun and/or its licensors. Except as specifically authorized in any Supplemental License Terms, you may not make copies of Software, other than a single copy of Software for archival purposes. Unless enforcement is prohibited by applicable law, you may not modify, decompile, or reverse engineer Software. You acknowledge that Software is not designed, licensed or intended for use in the design, construction, operation or maintenance of any nuclear facility. Sun disclaims any express or implied warranty of fitness for such uses. No right, title or interest in or to any trademark, service mark, logo or trade name of Sun or its licensors is granted under this Agreement.

3. LIMITED WARRANTY. Sun warrants to you that for a period of ninety (90) days from the date of purchase, as evidenced by a copy of the receipt, the media on which Software is furnished (if any) will be free of defects in materials and workmanship under normal use. Except for the foregoing, Software is provided "AS IS". Your exclusive remedy and Sun’s entire liability under this limited warranty will be at Sun’s option to replace Software media or refund the fee paid for Software.

4. DISCLAIMER OF WARRANTY. UNLESS SPECIFIED IN THIS AGREEMENT, ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

5. LIMITATION OF LIABILITY. TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In no event will Sun’s liability to you, whether in contract, tort (including negligence), or otherwise, exceed the amount paid by you for Software under this Agreement. The foregoing limitations will apply even if the above stated warranty fails of its essential purpose.

6. Termination. This Agreement is effective until terminated. You may terminate this Agreement at any time by destroying all copies of Software. This Agreement will terminate immediately without notice from Sun if you fail to comply with any provision of this Agreement. Upon Termination, you must destroy all copies of Software.

7. Export Regulations. All Software and technical data delivered under this Agreement are subject to US export control laws and may be subject to export or import regulations in other countries. You agree to comply strictly with all such laws and regulations and acknowledge that you have the responsibility to obtain such licenses to export, re-export, or import as may be required after delivery to you.

8. U.S. Government Restricted Rights. If Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government’s rights in Software and accompanying documentation will be only as set forth in this Agreement; this is in accordance with 48 CFR 227.7201 through 227.7202-4 (for Department of Defense (DOD) acquisitions) and with 48 CFR 2.101 and 12.212 (for non-DOD acquisitions).

9. Governing Law. Any action related to this Agreement will be governed by California law and controlling U.S. federal law. No choice of law rules of any jurisdiction will apply.

10. Severability. If any provision of this Agreement is held to be unenforceable, this Agreement will remain in effect with the provision omitted, unless omission would frustrate the intent of the parties, in which case this Agreement will immediately terminate.

11. Integration. This Agreement is the entire agreement between you and Sun relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification of this Agreement will be binding, unless in writing and signed by an authorized representative of each party.

JAVA(TM) INTERFACE CLASSES JAVA API FOR XML PROCESSING (JAXP), VERSION 1.1 SUPPLEMENTAL LICENSE TERMS

These supplemental license terms ("Supplemental Terms") add to or modify the terms of the Binary Code License Agreement (collectively, the "Agreement"). Capitalized terms not defined in these Supplemental Terms shall have the same meanings ascribed to them in the Agreement. These Supplemental Terms shall supersede any inconsistent or conflicting terms in the Agreement, or in any license contained within the Software.



1. Software Internal Use and Development License Grant. Subject to the terms and conditions of this Agreement, including, but not limited to Section 3 (Java(TM) Technology Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive, non-transferable, limited license to reproduce internally and use internally the binary form of the Software, complete and unmodified, for the sole purpose of designing, developing and testing your Java applets and applications ("Programs").

2. License to Distribute Software. In addition to the license granted in Section 1 (Software Internal Use and Development License Grant) of these Supplemental Terms, subject to the terms and conditions of this Agreement, including but not limited to Section 3 (Java Technology Restrictions), Sun grants you a non-exclusive, non-transferable, limited license to reproduce and distribute the Software in binary form, provided that you (i) distribute the Software complete and unmodified and only bundled as part of your Programs, (ii) do not distribute additional software intended to replace any component(s) of the Software, (iii) do not remove or alter any proprietary legends or notices contained in the Software, (iv) only distribute the Software subject to a license agreement that protects Sun’s interests consistent with the terms contained in this Agreement, and (v) agree to defend and indemnify Sun and its licensors from and against any damages, costs, liabilities, settlement amounts and/or expenses (including attorneys’ fees) incurred in connection with any claim, lawsuit or action by any third party that arises or results from the use or distribution of any and all Programs and/or Software.

3. Java Technology Restrictions. You may not modify the Java Platform Interface ("JPI", identified as classes contained within the "java" package or any subpackages of the "java" package), by creating additional classes within the JPI or otherwise causing the addition to or modification of the classes in the JPI. In the event that you create an additional class and associated API(s) which (i) extends the functionality of the Java platform, and (ii) is exposed to third party software developers for the purpose of developing additional software which invokes such additional API, you must promptly publish broadly an accurate specification for such API for free use by all developers. You may not create, or authorize your licensees to create additional classes, interfaces, or subpackages that are in any way identified as "java", "javax", "sun" or similar convention as specified by Sun in any naming convention designation.

4. Trademarks and Logos. You acknowledge and agree as between you and Sun that Sun owns the SUN, SOLARIS, JAVA, JINI, FORTE, STAROFFICE, STARPORTAL and iPLANET trademarks and all SUN, SOLARIS, JAVA, JINI, FORTE, STAROFFICE, STARPORTAL and iPLANET-related trademarks, service marks, logos and other brand designations ("Sun Marks"), and you agree to comply with the Sun Trademark and Logo Usage Requirements currently located at http://www.sun.com/policies/trademarks. Any use you make of the Sun Marks inures to Sun’s benefit.

5. Source Code. Software may contain source code that is provided for reference purposes pursuant to the terms of this Agreement. Source code may not be redistributed unless expressly provided for in this Agreement. Portions of this download are governed by the Apache Source Code License and are identified in the Readme file. A copy of the Apache License is supplied with the Apache Source Code.

6. Termination for Infringement. Either party may terminate this Agreement immediately should any Software become, or in either party’s opinion be likely to become, the subject of a claim of infringement of any intellectual property right.

For inquiries please contact: Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California 94303

Microstar Software.

Portions of this Software may include software provided by Microstar Software. Copyright (c) 1997, 1998 by Microstar Software. All rights reserved.


| 531

Index

Symbols

_onUnsolictedMsg() 388

A

ABAP Debug 220activateTraceRole() 369Adapter Application 3Adapter Command Line Options in TIBCO

ActiveEnterprise 317Adapter Components 3Adapter components 3Adapter Configuration 111Adapter Properties File 306add message type 74Adding a Client Connection 208Adding a Connection Reference 205Adding a Server Connection 221Adding Adapter Services 144Adding Adapter Services Automatically 145Adding an Active Connection 203Adding Connections to an Adapter 201Administrator’s Checklist 24Advanced Features 17After installing a TIBCO BusinessWorks compliant

adapter, subsequent adapter installations do not ask for the location? Is there a problem with the installation? 482

agents 360ALE

generating Partner Profiles 79in partner profile 82parameters for Output mode 508

ALE configurationoutbound parameters 508

ALE/IDoc Interface 2

alerts 360API xxApplication Link Enabling - Intermediate Documents

(ALE/IDoc) 7Application Server 475assign logical system to the client 72Assigning an Active Connection to an Adapter 207Assigning CMQ Name - Inbound Load-balanced

Instance 263Assigning Dynamic Filenames to File Sinks - Inbound

Load-balanced Instance 264, 267Available Microagents 365

B

Backward Compatible RV Message Specification 516BAPI 7BAPI Transactional Support 17Basic Steps for Configuring and Using the Adapter 90batch mode

IDocs 508Before Starting 90Business Application Programming Interface (BAPI) 7

C

Certified Messaging, RVCM 15Class Microagent Name field, adapter 135Client Connection with Load Balancing 212Client Connection with saprfc.ini file 214Client Distribution Model 75, 501clientvar property 307command line arguments 376Completed Gateway Options Dialog Box 356


532 | Index

componentsretrieving through TIBCO Hawk 375

Configuration and Design Components 3configuration file

logical system specification 69, 494configure SAP instance

to run on two systems 353Configuring a Remote Adapter 277Configuring a User Exit for a Publication Service 230Configuring a User exit for a Subscription Service 241Configuring Advanced Publisher Options 230Configuring Advanced Request-Response Invocation

Options 241Configuring Client Connection with Load

Balancing 212Configuring Client Connection with saprfc.ini

File 214Configuring Dedicated Application Server Client

Connection 210Configuring Default Server Connection 222Configuring Dynamic Subjects 21Configuring Multiple Connections for Inbound

Instance 241Configuring Multiple Connections for Outbound

Instance 246Configuring Request-Response Invocation

Service 184Configuring Request-Response Service 191Configuring Schema for Adapter Services 191Configuring Server Connection with saprfc.ini 224Configuring Valid Destinations 21, 200conversion 285create Request window 70Creating a Project for the Adapter 90Customer Support xxii

D

Data Chunking 18Database Server 476DATS 286deactivateTraceRole() 370debugging 220

Dedicated Application Server Client Connection 210Default Mode “Exploded” 158Default Server Connection 222define Port 80define RFC destination 76Defining a TIBCO Hawk Session 137Deploying the Run-time Adapter 306Deploying the Run-time Adapter in TIBCO

BusinessWorks 306Distributed Queue, RVDQ 15distribution model 73documents related xvi

E

Enter Change Request window 70error

publisher application is not running 99Event Driven Inbound Connection 18Event Driven Inbound Connections 348Example 115, 147, 149, 150, 155, 164, 166, 171, 175, 180,

183, 186, 190, 204, 206, 211, 213, 215, 218, 223, 225, 258

Registering an RFC Server Program Example 228Example 1 162, 172, 192Example 2 194Exchanging Business Information 477

F

fault tolerance 290Features 14Find RFC Destinations Screen 354Frequently Asked Questions 481, 482

G

Gateway Host 356Gateway Options 355


Index | 533

Gateway Service 356Generate Partner Profiles 79getActivityStatisticsByOperation 371getActivityStatisticsByOperation(Operation) 371getActivityStatisticsBySchema(SchemaName) 373getActivityStatisticsByService 373getActivityStatisticsByService(ServiceName) 373getAdapterServicesInformation() 374getComponents Hawk method 375getComponents() 375getConfig() 376

Hawk method 377getConfigProperties() 377getConnectionStatistics() 399getHostInformation() 380getQueueStatistics() 382getRvConfig() 383getStatus() 384getThreadStatistics() 399Getting Ready to Run Unicode 280Getting Started with Adapter Configuration 90getTraceSinks() 386getVersion() 387

H

Handling Large Internal Tables from SAP R/3 325Hawk methods

getComponents 375getConfig() 377reviewLedger 394stopApplicationInstance 320, 397unRegisterListener 398

HTTP 312HTTPS 312

URLfile 314

I

Identifying the Publication Mode 155

IDocBatch Mode 508records contained 157structure 479

IDoc Filtering 17, 328IDoc in native RFC table format 157IDoc in uncompressed “exploded” format 159IDoc Structure 479IDocs

compressed form 158exploded format 159metadata 158versions supported 156

IDocs Tab 147Inbound 286Inbound BAPI Transactional Support 331installation

Windows NT 25Installing and Running the Adapter as a Service on

Microsoft Windows 318Invoking BAPIs/RFCs Using Transactional Semantics

in SAP R/3 336Invoking Microagent Methods 363

L

ledger fileretrieving information through TIBCO Hawk 394

listenersunregistering through TIBCO Hawk 398

Load Balancing 260load balancing 291local repository locator string 316locator string 316Log File field, adapter 131Log Info field, adapter 132log on

to SAP server 491Log to Standard field, adapter 131Logical Process Architecture 6


534 | Index

logical systemadapter application 74, 497associated with the IDoc message type 499client (sending and receiving SAP system) 74, 497correspondence to keyword in the publisher config-

uration file 69, 494creating 69, 493

for SAP client 72required 74saving new 72, 494two required 497verify creation 494verifying creation 70, 72

M

maintaindistribution model 73logical systems 68Partner Profile 82

MBCS 285mbstowcs() 286message

adding type to logical system 501assigning type for transfer to adapter 500defining new type 500

Message Fields 516Messaging 15microagent methods supported 366Microagent Session field, adapter 135Mode "Exploded Batch" 159Mode “10Xbatched” 160Mode “10Xcif” 159, 160Mode “Exploded” 158Mode “none” 156model view

adding message type 74Monitoring the Adapter 25Multiple Application Servers 348Multiple Inbound Configurations 262Multiple Program IDs 341Multithreading 20, 339Multithreading with Distributed Queues 340

N

NUMC 286

O

obfuscation 306Outbound 286outbound parameters in ALE 508outbound partner profile

maintain 82, 507set up 82, 507

Output mode in ALE configuration 508Overview 277, 278, 360, 400

P

partner profileRFC port 80

password property 307preRegisterListener() 389Procedure 334, 353Product Overview 3Program ID 78, 504Publication Service 9, 152Publication Service typical flow diagram 9Publishing IDocS on Dynamic Subjects 237

R

R/3 474R3 Connections Folder Hierarchy 201Recovery Mechanism 359related documents xviRemote Function Call (RFC) 7Replacing Control Fields 21, 239Request-Response Invocation Service 13, 175Request-Response Service 11, 184resetActivityStatistics() 399


Index | 535

resetConnectionStatistics() 393resetThreadStatistics() 393reviewLedger Hawk method 394reviewLedger() 394RFC

define transactional ports 80RFC call 286RFC Destination RFCTEST Screen 354RFC Destinations 353RFC Interface 2RFC Trace 220RFC/BAPI Structure 480RFCs/BAPIs Tab 149Running an Adapter Instance on Two SAP R/3 Sys-

tems with Single Connection 353Running the TIDManager 319Runtime Adapter Components 3Run-time adapter components 3RV xxRVCM xxRVCMQ Session Attributes 261RVDQ xx

S

sale transaction 68, 72, 491Sample saprfc.ini Files 228Sample Scenario 334, 353SAP

application server 475client identification 497connection error 99database server 476error message 99

SAP ALE R/3 Configuration 489SAP GUI Presentation Server 474SAP Language Support 278SAP R/3 Graphic User Interface Version 3.1H 490SAP R/3 Interface Overview 2SAP R/3 Interfaces and TIBCO Adapter for R/3 7SAP R/3 Overview 2, 473SAP R/3 Releases 3.x 148SAP R/3 Releases 4.x 148

SAP serverGUI/Presentation Server 474log on 491logging on 68, 72

saprfc.ini Server Connection 224Saving the Project 196schema

examples of use 24xml 157

Schema Support 24Select Gateway Host and Gateway Service Dialog

Box 356Select Gateway Options Pull-down Menu 355Selecting Client Connection Type 208Selecting Server Connection Type 221Services Offered by the Adapter 9Setting Adapter Configuration Options 139Setting Adapter Design-Time Connection Options 139Setting Adapter Run-Time Options 200Setting Adapter Standard Logging Options 140Setting Advanced Client Options 218Setting Client Connection Advanced Options 216Setting Inbound Instance Options 139Setting Inbound/Outbound Instance Options 139Setting Outbound Instance Options 139Setting Publisher Configuration Options 152Setting Server Connection Advanced Options 226Setting Subscriber Configuration Options 175Setting TIDManager Configuration Options 253Setting TIDManager Logging Options 254Setting TIDManager Monitoring Options 256Setting TIDManager Run-Time Options 257Setting up Active Connection Configuration

Options 203Setting up Client Configuration Options 218Setting up Connection Reference Options 205setTraceSinks() 396SHIFT-JIS 285Single Inbound Configuration 263Single Outbound Instance 265Standard Microagent Name field, adapter 135Starting and Stopping the Design-time Adapter 306Starting and Stopping the Run-time Adapter 306Starting the Run-time Adapter 302Starting TIBCO Hawk Software 361


536 | Index

Steps for Configuring Inbound Load-Balanced Instances 260

Steps for Configuring Outbound Load-balanced Instances 265

stopApplicationInstance Hawk method 320, 397stopApplicationInstance() 397stopping applications 320, 397Stopping the Run-time Adapter 303Stopping the TIDManager 320Subscription Service 10, 167

typical flow diagram 10Subscription Service - Using Distributed Queue 260Summary of SAP R/3 Interfaces 477Support for Multiple Application Servers 19

T

TCP connections 76Terminating the Test 107Test Connection Button 357The Auto-Discovery Process 362The SAP R/3 Business Application System 474TIBCO Adapter for R/3

ALE IDoc interface 478components 6

TIBCO Hawkenterprise monitor components 360interrogating microagents 363microagents available 365

TIBCO Rendezvous 311TIBCO Run-time Agent 3TIDManager 250TIDManager Service 5TIME 286tracing 220TYPC 286Typical Publication Service Flow 9Typical Request-Response Invocation Service Flow 13Typical Request-Response Service Flow 11Typical Subscription Service Flow 10

U

unRegisterListener Hawk method 398unRegisterListener() 398URL 316URLfile accessed via HTTPS 314Use Advanced Logging field, adapter 130Use SAPGUI 220User Exits 22username property 307Using a Dedicated Application Server to Connect

Example 229Using Global Variables 272Using Logon Groups to Connect an RFC Client to SAP

Example 228

W

wcstombs() 286What are the requirements to bring up TIBCO

Designer from a UNIX command-line? 482What is TRA? 482When an error occurs in a Subscription Service

adapter service, where is it displayed? 482When saving an adapter configuration to the project, if

an error occurs where is it logged? 482When starting the adapter, what if the repository is not

found? 482Why does the adapter fail to respond to a request after

succesfully receiving it? 483Why does the adapter fail to respond to a request? 482Why does the adapter startup fail, even after specify-

ing the appropriate DAT file? 482Why does the adapter startup fail? 482Why does the connection to the Design-Time Adapter

fail? 482Why is the adapter unable to discover any domains on

the network even though the TIBCO Business-Works administration server is up and running? 482

Windows NTinstallation 25


Index | 537

wire formatheader information 160

Wireformat Backward Compatibility 515


538 | Index
