Crystal Reports 10. Overview. Contents. Configuring JDBC (JNDI) Connectivity

Transcription

1 Overview This technical brief discusses configuring JDBC (JNDI) connectivity in Crystal Reports 10. Contents INTRODUCTION... 2 BACKGROUND... 2 What is Java Database Connectivity?...2 What is Java Naming and Directory Interface?...2 How Crystal Reports works with JDBC (JNDI)...2 INITIAL CONFIGURATION...3 THE CRDB_JAVASERVER.INI FILE...3 PATH variable...4 CLASSPATH variable...4 IORFileLocation variable...5 JDBC connection properties...5 JNDI connection properties...5 CONFIGURING CRYSTAL REPORTS FOR JDBC...6 Specifying the path to the database JAR files...6 Configuring JDBC in Crystal Reports...6 CONFIGURING CRYSTAL REPORTS FOR JNDI...9 Configuring CRDB_JavaServer.ini for JNDI...9 Configuring JNDI in Crystal Reports...11 FINDING MORE INFORMATION...14 Configuring Java Naming and Directory Interface (JNDI) on the Server- Side...14 Configuring JNDI and JDBC Data Sources /15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 1

2 Introduction This technical brief discusses how to configure the Crystal Reports Designer to use JDBC (JNDI) connectivity. JDBC (JNDI) connectivity is available in Crystal Reports 10 (and later) Professional, Developer, and Advanced editions, as well as in version 9.2 (and later) of the Crystal Reports Designer for Borland JBuilder and BEA WebLogic. Background What is Java Database Connectivity? Java Database Connectivity (JDBC) is the industry standard for database connectivity between the Java programming language and a wide range of databases and other tabular data sources, such as spreadsheets and flat files. JDBC provides methods and properties that allow the Java language to perform SQL operations on the databases to which it connects. It is included in the J2SE (Java 2 Standard Edition) and J2EE (Java 2 Enterprise Edition) SDKs. What is Java Naming and Directory Interface? The Java Naming Directory Interface (JNDI) provides an Application Programming Interface (API) that makes naming and directory functionality available to Java applications. For example, the API allows Java applications to access directory services as LDAP, NDS, DNS, and NIS. JNDI uses J2EE technologies to organize and locate components in a distributed computing environment. For the purposes of this technical brief, JNDI refers to a type of data source. This data source is created on J2EE-compliant web application servers, and is used as a server-side connection to a specific database. How Crystal Reports works with JDBC (JNDI) The Crystal Reports Designer uses a Java engine called the CRDBJavaServer to process Java-based requests. CRDBJavaServer reads the CRDB_JavaServer.ini properties file to locate the Java SDK, the database drivers, and any other information that the Crystal Reports Designer requires to process the Java-based task. After reading the properties file, the CRDBJavaServer creates temporary files (.ior files) that the Crystal Reports Designer uses to connect to the appropriate database. NOTE CRDBJavaServer requires access to J2SE 1.4.x (and later). 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 2

3 Initial Configuration Before Crystal Reports is able to connect to a database, a JDBC (JNDI) connection must be configured as follows: 1. Download and install Sun JDK version (or later) from the following location: 2. If you are using Crystal Reports 10, complete these steps to download and install the JDBC (JNDI) drivers (these drivers are not part of the Crystal Reports 10 product installation): i. Click the following link and download the drivers: Download Windows JDBC, XML and DB2 Unicode Drivers - all languages ii. Extract the files to a temporary folder. iii. Double-click the Setup.exe file and complete the installation steps. 3. Ensure that you have the corresponding JDBC database drivers on hand for the database and version that you are using. Where you place the database drivers on your computer depends on the connection type you are using. The CRDB_JavaServer.ini File Now that the initial configuration has been completed, the next step is to set up the CRDB_JavaServer.ini file. The CRDB_JavaServer.ini file is a configuration file that is needed by the Crystal Reports Designer to initialize the properties needed to use JDBC (JNDI) connectivity. In a default installation, this file is found at the following location: C:\Program Files\common files\crystal decisions\2.5\bin Here is a sample of the file contents, with the configurable portions of the file discussed in the following sections: [Common] PATH = ${JAVA_HOME}/bin CLASSPATH = C:\Program Files\Common Files\Crystal Decisions\2.5\bin\CRDBJavaServer.jar;${CLASSPATH} IORFileLocation = ${TEMP} JavaServerTimeout = 1800 JVMMaxHeap = JVMMinHeap = /15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 3

4 [CRDB_JDBC] CacheRowSetSize = 100 JDBCURL = JNDIURL = JDBCUserName = JDBCDriverName = JNDIUserName = JNDIConnectionFactory = JNDIInitContext = GenericJDBCDriverBehavior = DB2 [CRDB_XML] PREREADNBYTE = 5000 CacheRowSetSize = 100 XMLLOCALURL = SCHEMALOCALURL = XMLHTTPURL = SCHEMAHTTPURL = USETEMPFile = TRUE PATH variable PATH = ${JAVA_HOME}/bin The PATH variable defines the path to the Java SDK you are using for the JDBC (JNDI) connection. By default, the PATH variable is set to ${JAVA_HOME}/bin. CLASSPATH variable CLASSPATH = C:\Program Files\Common Files\Crystal Decisions\2.5\bin\CRDBJavaServer.jar ;${CLASSPATH} The CLASSPATH variable specifies the location of the CRDBJavaServer.jar file, database JAR files (required for JDBC connectivity), and the web application server JAR files (required for JNDI connectivity). NOTE Enclose the path in double quotation marks if it contains spaces. If you have any issues when trying to create a JDBC or JNDI connection in Crystal Reports, verify that the physical paths are correct in the.ini file and the environment variables. 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 4

5 IORFileLocation variable IORFileLocation = ${TEMP} The IORFileLocation variable defines the path to where the temporary files (.ior) are written. The.ior files are generated by the CRDBJavaServer to enable the Crystal Reports Designer to determine how to connect to the database. By default, the IORFileLocation variable is set to the same folder as the Temp environment variable. Ensure that.ior files are able to be written to this folder, otherwise, the JDBC (JNDI) connection will fail. JDBC connection properties JDBCURL specifies the database provider URL for your database. JDBCUserName specifies the username for your database. JDBCDriverName specifies the database driver for your provider. These JDBC connection properties may be set either in the CRDB_JavaServer.ini file or in the Crystal Reports Designer as described in the section Configuring JDBC in Crystal Reports. JNDI connection properties JNDIURL specifies the provider URL for your web application server. JNDIUserName specifies the username for your web application server (if there is one). JNDIConnectionFactory specifies the driver that your web application server uses to create its JNDI connections. JNDIInitContext specifies the context in which your JNDI data source resides on your web server. These JNDI connection properties may be set in the CRDB_JavaServer.ini file or in the Crystal Reports Designer as described in the section Configuring JNDI in Crystal Reports. The next step is to configure the CRDB_JavaServer.ini file to enable the Crystal Reports Designer to connect through JDBC (JNDI). 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 5

6 Configuring Crystal Reports for JDBC Specifying the path to the database JAR files To ensure that the Crystal Reports Designer is able to locate the necessary database drivers for a JDBC connection, configure the CRDB_JavaServer.ini file as the following example demonstrates (Microsoft SQL Server 2000 is used as the example database): 1. Open the CRDB_JavaServer.ini file for editing. 2. Set the PATH environment variable to the location of the Sun JDK. By default, it is set to ${JAVA_HOME}/bin. You have the option of using a fully qualified physical path to your JDK bin folder. 3. Obtain the appropriate database JAR files. For SQL Server, the database JAR files required are msbase.jar, msutil.jar and mssqlserver.jar. NOTE These JAR files may be found by clicking this link and searching for "SQL Server 2000 Driver for JDBC Service Pack". 4. Deploy the database JAR files to your computer. For example, create a folder called sqlserverjars in the root of your C:\ drive and copy the JAR files to this folder. 5. In the CRDB_JavaServer.ini file, set the value of the CLASSPATH variable to the path to the database JAR files. For example: PATH = ${JAVA_HOME}/bin CLASSPATH = C:\Program Files\Common Files\Crystal Decisions\2.5\bin\CRDBJavaServer.jar ; C:\sqlserverjars\msbase.jar; C:\sqlserverjars\msutil.jar; C:\sqlserverjars\mssqlserver.jar; ${CLASSPATH} NOTE Note that the path to CRDBJavaServer.jar is enclosed in double quotation marks because the path contains spaces. Proceed to the next section to set the connection properties in the Crystal Reports Designer. Configuring JDBC in Crystal Reports You have the option of modifying an existing report or creating a report that uses a JDBC connection. The following steps demonstrate how to create a report that uses a JDBC connection to a Microsoft SQL Server 2000 database: 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 6

7 1. In Crystal Reports, click the New button. The Crystal Reports Gallery dialog box appears. 2. Click As a Blank Report and then click OK. The Database Expert dialog box appears. 3. Expand the Create New Connection folder (see Figure 1). Figure 1 Database Expert Dialog Box 4. Double-click JDBC (JNDI). The JDBC (JNDI) dialog box appears (see Figure 2). 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 7

8 Figure 2 JDBC (JNDI) Connection Dialog Box 5. Type the properties for your database connection. The Connection URL is your database provider URL. The Database Classname is the database driver. NOTE The connection URL and database classname is unique for each database provider, therefore, consult your database documentation for more information. 6. Click Next. The JDBC (JNDI) Connection Information dialog box appears (see Figure 3). 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 8

9 Figure 3 - JDBC (JNDI) Connection Information Dialog Box 7. Type your database user ID and password, and then in the Database list, click the database you wish to access. 8. Click the Finish button. The Database Expert appears with all the tables available to your report. 9. Complete the remaining steps to create your report. Configuring Crystal Reports For JNDI Configuring CRDB_JavaServer.ini for JNDI To ensure that the Crystal Reports Designer is able to locate the necessary database drivers for a JNDI connection, configure the CRDB_JavaServer.ini file as the following example demonstrates (Microsoft SQL Server 2000 and BEA WebLogic are used): 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 9

10 1. Open the CRDB_JavaServer.ini file for editing. 2. Set the value of the PATH variable to the fully qualified physical path to the BEA WebLogic JDK bin folder. Alternatively, you may also use the Sun JDK that was installed previously. In this case, set the value of the PATH variable to ${JAVA_HOME}/bin or to the fully qualified physical path to the Sun JDK bin folder. 3. Add the physical path to the weblogic.jar file to the CLASSPATH variable to ensure that Crystal Reports recognizes the JNDI data sources on your WebLogic server. 4. Set the value of the JNDIConnectionFactory property to the driver that initializes the database connection for your JNDI data source. For WebLogic, the driver is weblogic.jndi.wlinitialcontextfactory. For other web servers, refer to your web server documentation. NOTE The other properties, such as JNDIURL, JNDIInitContext, and JNDIUserName may be set in the CRDB_JavaServer.ini file or in Crystal Reports. In this example, they will be set in Crystal Reports. 5. Below is an example of the contents of the CRDB_JavaServer.ini file: PATH = C:\bea\jdk141_05\bin CLASSPATH = C:\sqlserverjars\msbase.jar; C:\sqlserverjars\mssqlserver.jar; C:\sqlserverjars\msutil.jar; "C:\Program Files\Common Files\Crystal Decisions\2.5\bin\CRDBJavaServer.jar"; C:\bea\weblogic81\server\lib\weblogic.jar; ${CLASSPATH} JNDIURL = JDBCUserName = JDBCDriverName = JNDIUserName = JNDIConnectionFactory = weblogic.jndi.wlinitialcontextfactory JNDIInitContext = Now you are ready to set the properties for your JNDI connection in the Crystal Reports Designer. 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 10

11 Configuring JNDI in Crystal Reports You have the option of modifying an existing report or creating a report that uses a JDBC connection. The following steps demonstrate how to create a report that uses a JNDI data source on a BEA WebLogic 8.1 web application server: 1. In Crystal Reports, click the New button. The Crystal Reports Gallery dialog box appears. 2. Click As a Blank Report and then click OK. The Database Expert dialog box appears. 3. Expand the Create New Connection folder (see Figure 4). Figure 4 Database Expert Dialog Box 4. Double-click JDBC (JNDI). The JDBC (JNDI) Connection dialog box appears (see Figure 5). 5. Click JNDI Connection and then type the corresponding properties for your JNDI connection: JNDI Provider URL for WebLogic is t3://<server_name>:<port_number>. JNDI Username and JNDI Password are specific to the WebLogic server. Initial Context is the context in which your JNDI connection resides on your web server. A single forward slash refers to the root context. 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 11

12 Figure 5 JDBC (JNDI) Connection Dialog Box 6. Click Next. The JDBC (JNDI) Connection Information dialog box appears (see Figure 6). 7. Click the data source you wish to use for your report. 8. Click the Finish button. The Database Expert appears with all the tables available to your report. 9. Complete the remaining steps to create your report. 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 12

13 Figure 6 - JDBC (JNDI) Connection Information Dialog Box 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 13

14 Finding More Information For more information on configuring server side JNDI connections for Crystal Reports, refer to the following technical briefs: Configuring Java Naming and Directory Interface (JNDI) on the Server-Side jndi_server_side.pdf.asp Configuring JNDI and JDBC Data Sources a_sources.pdf.asp For more information and resources, refer to the product documentation and visit the support area of the web site at Business Objects owns the following U.S. patents, which may cover products that are offered and sold by Business Objects: 5,555,403, 6,247,008 B1, 6,578,027 B2, 6,490,593 and 6,289,352. Business Objects, the Business Objects logo, Crystal Reports, and Crystal Enterprise are trademarks or registered trademarks of Business Objects SA or its affiliated companies in the United States and other countries. All other names mentioned herein may be trademarks of their respective owners. Product specifications and program conditions are subject to change without notice. Copyright 2005 Business Objects. All rights reserved. 3/15/2005 9:54 AM Copyright 2005 Business Objects. All rights reserved. Page 14