.

How-to Guide SAP NetWeaver 04

How To Install and Configure External Drivers for the JDBC & JMS Adapters
Version 3.01 March 2006

Applicable Releases: SAP NetWeaver 04 SPS9 and above

 Copyright 2006 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, and Informix are trademarks or registered trademarks of IBM Corporation in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or regis tered trademarks of W3C , World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MaxDB is a trademark of MySQL AB, Sweden. SAP, R/3, mySAP, mySAP.com, xApps, xApp, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data

contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. These materials are provided as is without a 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. SAP shall not be liable for damages of any kind including without limitation direct, special, indirect, or consequential damages that may result from the use of these materials. SAP does not warrant the accuracy or completeness of the information, text, graphics, links or other items contained within these materials. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third party web pages nor provide any warranty whatsoever relating to third party web pages. SAP NetWeaver How-to Guides are intended to simplify the product implementation. While specific product features and procedures typically are explained in a practical business context, it is not implied that those features and procedures are the only approach in solving a specific business problem using SAP NetWeaver. Should you wish to receive additional information, clarification or support, please refer to SAP Consulting. Any software coding and/or code lines / strings (Code) included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAP intentionally or grossly negligent.

Introduction...........................................................................................................1 1.1 Limitations ....................................................................................................1 1.2 Example JDBC Drivers.................................................................................1 1.3 Troubleshooting............................................................................................1 2 The Step-By-Step Solution...................................................................................2 2.1 Introduction and Prerequisites......................................................................2 2.2 Creating or Getting aii_af_jmsproviderlib.sda...............................................2 2.2.1 Getting an Existing aii_af_jmsproviderlib.sda.......................................3 2.2.2 Creating an Empty aii_af_jmsproviderlib.sda .......................................3 2.3 Adding Driver JARs to aii_af_jmsproviderlib.sda..........................................3 2.4 Deploying aii_af_jmsproviderlib.sda on the J2EE Engine ............................4 3 Appendix ..............................................................................................................6 3.1 Driver Tool Command Line Options .............................................................6 3.1.1 Creating an Empty aii_af_jmsproviderlib.sda .......................................6 3.1.2 Adding Jars to the SDA ........................................................................6 3.1.3 Deleting JARs from the SDA ................................................................7 3.1.4 Checking SDA Integrity ........................................................................7 3.2 Manual Modification of aii_af_jmsproviderlib.sda .........................................8 3.3 Complete provider.xml Descriptor ..............................................................10

1 Introduction
A business scenario involving communication with a database or a messaging system that uses the SAP XI 3.0 Adapter Framework requires additional drivers to be installed on the SAP Web AS J2EE Engine. These external drivers, which are provided as Java archives (JARs) by the respective vendor of the database or messaging system, are required to operate the JDBC and JMS adapters. To use these drivers with the adapters on the SAP J2EE server, you must deploy them. For this purpose, the Adapter Engine installation provides the aii_af_jmsproviderlib.sda archive, to which you add the respective driver files. This guide assumes that SAP XI 3.0 is completely installed with the Integration Server or Partner Connectivity Kit. The step-by-step guide also assumes Microsoft Windows as the operating system. 1.1 Limitations This document only deals with the installation of type 4 JDBC drivers and JMS drivers that do not require any platform-specific native binaries. If you want to install type 2 JDBC drivers or JMS drivers that require native libraries, there are additional steps that you must follow. For more information, see SAP Note 850116. 1.2 Example JDBC Drivers The following list outlines which drivers you need to deploy for various specific database management or messaging systems, namely Oracle, Microsoft SQL Server, and IBM MQ Series: Oracle 9i and Oracle 10g: ojdbc14.jar Microsoft SQL Server: msbase.jar, mssqlserver.jar, msutil.jar IBM MQ Series 5.2: com.ibm.mq.jar; com.ibm.mqjms.jar IBM MQ Series 5.3: com.ibm.mq.jar; com.ibm.mqbind.jar, com.ibm.mqjms.jar, connector.jar Important: Rather than relying on the list above, or if you want to connect to a DBMS or messaging system from a different vendor, contact your vendor for more information about the required drivers. The driver JARs listed above are examples and are subject to change without notice. The respective vendors are responsible for the drivers, which are neither shipped nor licensed by SAP. 1.3 Troubleshooting If you encounter problems while configuring your adapter channels, the first source to look for additional information is the adapter monitor in the Runtime Workbench (RWB): Choose Component Monitoring, display all components, choose the Adapter Engine you are working on (Adapter Engine on the Integration Server or a non-central Adapter Engine), choose Adapter Monitoring, and finally, select the specific adapter type you want (JMS and JDBC adapters are under the namespace http://sap.com/xi/XI/System. To see the adapters channels and their state, click the adapter type). To be able to access the adapter monitor page, users must be assigned the monitoring role.

-1-

2 The Step-By-Step Solution

The installation of a driver for the JDBC or JMS adapter involves three steps, each of which is described in detail below: 1. Get the existing aii_af_jmsproviderlib.sda file from your SAP XI installation (if you already have JDBC or JMS drivers deployed) or create a new empty one (Section 2.2). 2. Add any new JARs to the aii_af_jmsproviderlib.sda archive (Section 2.3). 3. Deploy the aii_af_jmsproviderlib.sda archive to the J2EE Engine by using SAP Deployment Manager (SDM) (Section 2.4). Important: This process requires you to restart the J2EE Engine. You need to take this into account when scheduling your deployment. 2.1 Introduction and Prerequisites To facilitate the creation of the aii_af_jmsproviderlib.sda file, the utility SAP XI 3.0 JDBC/JMS Driver Tool is packaged with this guide. This driver tool automatically adds the driver JAR files to the SDA and modifies the SDAs provider.xml descriptor. The following section describes the steps necessary to build the SDA using this utility. Details on how to manually complete the steps that are performed automatically by the driver tool are available in Appendix 3.1.1. The driver tool is a Java-based command line utility. You need a Java 1.4.2 virtual ma1 chine (VM) installed for the tool to function correctly. A batch file wrapper , drivertool.bat, is included to simplify using the tool. This batch file wrapper requires you to set the environment variable JAVA_HOME to the base directory of your JRE directory (that is, the directory where java.exe is located without the bin subdirectory, for example, C:\Program Files\jre1.4.2_09). Before continuing with this step-by-step guide, place the included driver tool files drivertool.bat and drivertool.jar in a directory of your choice. To access the command from the command prompt, either use the current directory or add the directory to the search path. The following steps are performed from the Windows command prompt, so open a new command prompt window before proceeding. The files drivertool.bat and drivertool.jar are provided with this How-to guide as a .zip file. Note: The software available with this How-To Guide is not intended for productive operation. Note the details in the copyright statement at the beginning of this document. 2.2 Creating or Getting aii_af_jmsproviderlib.sda If you previously deployed any JDBC or JMS drivers using aii_af_jmsproviderlib.sda, you need to locate this SDA file if you want to keep the previously deployed drivers (see Section 2.2.1). Otherwise, you need to create an empty aii_af_jmsproviderlib.sda file instead (see Section 2.2.2). Important: If you are not sure whether any JDBC or JMS drivers have already been deployed, follow the instructions in Section 2.2.1.

If you have a UNIX operating system, you cannot use this batch file wrapper. You need to invoke Java directly instead: java jar drivertool.jar <parameters>
-2-

2.2.1

Getting an Existing aii_af_jmsproviderlib.sda

On your SAP XI installation, locate the following file and copy it to a working directory of your choice: /usr/sap/<SID>/DVEBMGS<SYSNO>/SDM/root/origin/ sap.com/com.sap.aii.af.jmsproviderlib/SAP AG/3.0.0220040608173429.0000/aii_af_jms providerlib .sda
2.2.2 Creating an Empty aii_af_jmsproviderlib.sda

We will now create an empty aii_af_jmsproviderlib.sda file as a starting point by invoking drivertool.bat with the Create command line option:
C:\>drivertool create SAP XI 3.0 JDBC/JMS Driver Tool. Version 1.0.1615 Copyright (C) 2005 SAP AG. All rights reserved. Successfully created aii_af_jmsproviderlib.sda.

Important: If you use an empty aii_af_jmsproviderlib.sda as a starting point, any previously deployed JDBC and JMS drivers will be lost and JDBC/JMS channels referencing these drivers will stop working. 2.3 Adding Driver JARs to aii_af_jmsproviderlib.sda In this step, we add the individual JDBC/JMS driver JAR files to aii_af_jmsproviderlib.sda. You use the add command line switch to do this. In the example below, we use Oracle and Microsoft SQL Server JDBC drivers. Other drivers are added in the same way. Before running the command, make sure that all required JARs are located in the current directory along with the aii_af_jmsproviderlib.sda file. Note: In the following example, the backslash (\) represents a line continuation character, that is, it indicates you must enter the complete command line on one single line.
C:\>drivertool add aii_af_jmsproviderlib.sda msbase.jar \ mssqlserver.jar msutil.jar ojdbc14.jar SAP XI 3.0 JDBC/JMS Driver Tool. Version 1.0.1615 Copyright (C) 2005 SAP AG. All rights reserved. Adding driver JAR(s) to aii_af_jmsproviderlib.sda: msbase.jar - OK mssqlserver.jar - OK msutil.jar - OK ojdbc14.jar - OK Writing changes to SDA. This may take a while, so please be patient. Successfully created aii_af_jmsproviderlib.sda.

The aii_af_jmsproviderlib.sda file is now ready for deployment on your J2EE server. This deployment is described in the next section.

-3-

2.4 Deploying aii_af_jmsproviderlib.sda on the J2EE Engine SDA Selection 1. Start the SDM GUI using the RemoteGUI.bat command (Windows) or the RemoteGUI.sh command (UNIX). 2. Log on using your SDM password (and optionally user) and navigate to the Deployment tab page. 3. Choose the icon and select the aii_af_jmsproviderlib.sda file you just created.

1. The SDA to be deployed is now displayed in the archive list.

Deployment Configuration 1. To display the Deployment Configuration, click the up arrow in the lower right corner of the window. 2. Select Update deployed SDAs/SCAs that have any version. 3. Choose Next to proceed.

-4-

Deployment 1. Choose Next. The SDM is Ready to Deploy screen is displayed. 2. Make sure this screen shows com.sap.aii.af.jmsproviderlib in the left-hand list. 3. Choose Start to begin the deployment.

1. SDM now requests you to confirm the J2EE server restart. Choose Yes to confirm. This starts the deployment step, which takes a few minutes to complete.

Deployment Completion 1. Choose Confirm to complete the deployment process. The SDA has now been deployed in the J2EE servers file system. You can verify this by inspecting the directory /usr/sap/<SID>/DVEBMGS<SYSNO> /j2ee/cluster/server0/bin/ext/com.sap .aii.af.jmsproviderlib, where you will find all JAR files you previously added to the SDA.

-5-

3 Appendix
3.1 Driver Tool Command Line Options The driver tool is a command-line-based utility to modify the aii_af_jmsproviderlib.sda SDA. If you invoke drivertool.bat without any parameters, a list of supported command line options is returned:
C:\>drivertool SAP XI 3.0 JDBC/JMS Driver Tool. Version 1.0.1615 Copyright (C) 2005 SAP AG. All rights reserved. DISCLAIMER: This program is provided "as is" without warranty of any kind. Usage: drivertool drivertool drivertool drivertool add check create delete <DriverSDA> <JARFile1> [JarFile2] [...] <DriverSDA> [DriverSDA] <DriverSDA> <JARFile1> [JarFile2] [...]

Each of the options is explained in detail below.

3.1.1 Creating an Empty aii_af_jmsproviderlib.sda

Syntax drivertool create [DriverSDA] This command creates an empty aii_af_jmsproviderlib.sda file. If you omit the optional DriverSDA name, the default aii_af_jmsproviderlib.sda is used. If the target file already exists, you are asked to confirm overwriting the existing file. Example drivertool create
C:\>drivertool create SAP XI 3.0 JDBC/JMS Driver Tool. Version 1.0.1615 Copyright (C) 2005 SAP AG. All rights reserved. Successfully created aii_af_jmsproviderlib.sda. 3.1.2 Adding Jars to the SDA

Syntax drivertool add <DriverSDA> <JARFile1> [JarFile2] [...] This command adds one or multiple JAR files JARFile1, JarFile2, , JARFilen to the specified SDA DriverSDA. Example drivertool add aii_af_jmsproviderlib.sda ojdbc14.jar driver.jar This example adds the JARs ojdbc14.jar and driver.jar to the aii_af_jmsproviderlib.sda SDA.

-6-

C:\>drivertool add aii_af_jmsproviderlib.sda ojdbc14.jar driver.jar SAP XI 3.0 JDBC/JMS Driver Tool. Version 1.0.1615 Copyright (C) 2005 SAP AG. All rights reserved. Adding driver JAR(s) to aii_af_jmsproviderlib.sda: ojdbc14.jar - OK driver.jar - OK Writing changes to SDA. This may take a while, so please be patient. 3.1.3 Deleting JARs from the SDA

Syntax drivertool delete <DriverSDA> <JARFile1> [JarFile2] [...] This command deletes one or multiple JAR files JARFile1, JarFile2, , JARFilen from the specified SDA DriverSDA. Example drivertool delete aii_af_jmsproviderlib.sda ojdbc14.jar driver.jar This example deletes the JARs ojdbc14.jar and driver.jar from the SDA aii_af_jmsproviderlib.sda.
C:\> drivertool delete aii_af_jmsproviderlib.sda ojdbc14.jar driver.jar SAP XI 3.0 JDBC/JMS Driver Tool. Version 1.0.1615 Copyright (C) 2005 SAP AG. All rights reserved. Deleting driver JAR(s) from aii_af_jmsproviderlib.sda: ojdbc14.jar - OK driver.jar - OK Writing changes to SDA. This may take a while, so please be patient. 3.1.4 Checking SDA Integrity

Syntax drivertool check <DriverSDA> This command checks the integrity of the SDA DriverSDA, that is, it verifies that all JARs included in the SDA are listed in provider.xml and the other way round. It also prints a list of the JAR files contained in the SCA. Example drivertool check aii_af_jmsproviderlib.sda This checks the integrity of the SDA aii_af_jmsproviderlib.sda.

-7-

C:\>drivertool check aii_af_jmsproviderlib.sda SAP XI 3.0 JDBC/JMS Driver Tool. Version 1.0.1615 Copyright (C) 2005 SAP AG. All rights reserved. Checking consistency of aii_af_jmsproviderlib.sda: The SDA aii_af_jmsproviderlib.sda contains the following correctly registered driver JARs: ojdbc14.jar driver.jar SDA validation successful.

3.2 Manual Modification of aii_af_jmsproviderlib.sda The SDA file format required for the deployment is basically a Zip-file format that contains additional text files, called descriptors, which describe the deployable library content (the JAR files packed in the SDA). Therefore, adding a JAR file to the archive means adding the JAR file with a Zip tool, and adding its name to the <jars> element in the provider.xml file contained in the SDA. For the latter, you need to unzip the provider.xml file from the SDA, add the name to the correct section, and zip it again to the archive with the correct path information. Preparation 1. Copy the aii_af_jmsproviderlib.sda file from the directory /usr/sap/<SID>/ DVEBMGS<SYSNO>/SDM/root / origin/sap.com/com.sap.aii.af. jmsproviderlib/SAP AG/3.0.20040112154003. 0000 to a directory of your choice. 2. Unzip the file aii_af_jmsproviderlib.sda to an empty directory. Make sure you preserve the Zip files directory structure. 3. Verify that the following two subdirectories have been created in the directory you chose: META-INF server

-8-

Editing the Provider Descriptor 1. The provider.xml descriptor must be edited in order to reference the JAR files to be added to the SDA. 2. Open the provider.xml file in a text editor of your choice.

<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE provider-descriptor SYSTEM \ "library.provider.dtd"> <provider-descriptor> <display-name> com.sap.aii.af.jmsproviderlib </display-name> <component-name> com.sap.aii.af.jmsproviderlib </component-name> <major-version> 3 </major-version> <minor-version> 0 </minor-version> <micro-version> 0 </micro-version> <provider-name> sap.com </provider-name> <references> <reference type="library" \ strength="weak">jms</reference> </references> <jars> </jars> </provider-descriptor> <jars> <jar-name>ojdbc14.jar</jar-name> <jar-name>msbase.jar</jar-name> <jar-name>mssqlserver.jar</jar-name> <jar-name>msutil.jar</jar-name> </jars>

3. Add the vendor-specific JAR file names to the provider.xml file, between the tags <jars></jars> and save it. A complete example provider.xml file is supplied in Section 3.3. Driver Preparation 1. Copy the driver JAR files to the same directory to which you previously extracted the SDA.

-9-

Zip Directory 1. Zip the directory containing your JAR files including the METAINF and server subdirectories. Choose aii_af_jmsproviderlib.sda as the Zip file name. Make sure that you preserve the directory names. Important: If you are using WinZIP, make sure you do NOT use the Maximum (enhanced deflate) compression method. SDM will not be able to read SDA files compressed using this compression method. Result 1. The resulting SDA file should have a structure similar to the structure in the example provided to the right. Note: It is particularly important that the server and META-INF directories exist.

3.3

Complete provider.xml Descriptor

<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE provider-descriptor SYSTEM "library.provider.dtd"> <provider-descriptor> <display-name> com.sap.aii.af.jmsproviderlib </display-name> <component-name> com.sap.aii.af.jmsproviderlib </component-name> <major-version> 3 </major-version> <minor-version> 0 </minor-version> <micro-version> 0 </micro-version> <provider-name> sap.com </provider-name> <references>
- 10 -

<reference type="library" strength="weak">jms</reference> </references> <jars> <jar-name>ojdbc14.jar</jar-name> <jar-name>msbase.jar</jar-name> <jar-name>mssqlserver.jar</jar-name> <jar-name>msutil.jar</jar-name> </jars> </provider-descriptor>

- 11 -

www.sdn.sap.com/irj/sdn/howtoguides