JDBC Database Access

BMC Software Confidential

JDBC database access

URL:Date: 20-Mar-2014 07:11

https://docs.bmc.com/docs/pages/viewpage.action?pageId=258511519

JDBC database access BMC Software Confidential

Page of 2 23

Table of Contents1 Configuring the AR System JDBC driver in DbVisualizer _________________________________________ 4

1.1 To configure the AR System JDBC driver _________________________________________________ 41.2 To create a database connection _______________________________________________________ 5

1.2.1 To test the database connection in DbVisualizer version 9.x and later ______________________ 62 Configuring the AR JDBC driver in Squirrel SQL client __________________________________________ 8

2.1 To configure the AR JDBC driver _______________________________________________________ 82.2 To create a database connection ______________________________________________________ 10

3 Configuring the AR System JDBC driver in Crystal Reports ______________________________________ 113.1 To configure the AR System JDBC driver ________________________________________________ 113.2 Limitations of using the AR System JDBC driver in Crystal Reports ____________________________ 14

4 Sample of configuring the AR JDBC driver in a Java program ____________________________________ 154.1 Sample Java program ______________________________________________________________ 15

5 Optional parameters for the AR System JDBC driver ___________________________________________ 176 Enabling logging for the AR JDBC driver ____________________________________________________ 19

6.1 To enable logging for the AR JDBC driver _______________________________________________ 197 Limitations of the AR System JDBC driver ___________________________________________________ 208 Known issues ________________________________________________________________________ 21


Page of 3 23

The Java Database Connectivity (JDBC) standard is a connectivity solution that enables JDBC clients tocommunicate with BMC Remedy AR System. The AR JDBC driver provides read-only access to data defined inBMC Remedy AR System forms, which can be accessed through standard SQL queries. This section discusses theuse of AR JDBC driver to provide additional functionality with other applications.

The AR JDBC driver does not provide direct access to the underlying relational database. Instead, the AR JDBCdriver communicates with the AR System server, which in turn communicates with the underlying relationaldatabase as shown in the following figure.

Many JDBC clients are available. The AR JDBC driver provides extended functionality with Crystal Reports,DbVisualizer, and Squirrel SQL client.

The following topics are provided:

Configuring the AR System JDBC driver in DbVisualizer (see page 4)Configuring the AR System JDBC driver in Squirrel SQL clientConfiguring the AR System JDBC driver in Crystal Reports (see page 11)Sample of configuring the AR System JDBC driver in a Java programOptional parameters for the AR System JDBC driver (see page 17)Enabling logging for the AR System JDBC driverLimitations of the AR System JDBC driver (see page 20)Known issues (see page 21)


Page of 4 23

1.

2. 3.

4.

1 Configuring the AR System JDBC driver inDbVisualizerYou can configure the AR System JDBC driver in DbVisualizer and use the driver to create a database connection.

To configure the AR System JDBC driver (see page 4)To create a database connection (see page 5)

1.1 To configure the AR System JDBC driverDownload and install DbVisualizer from .http://www.dbvis.com/download/For installation instructions, see the appropriate DbVisualizer documentation.Open DbVisualizer.To create a new driver, click .Tools > Driver Manager

In the Driver Manager dialog box, click .


Page of 5 23

5.

6.

1. 2. 3. 4.

In the Driver File Paths area, click to load the following AR System JDBC driver JAR files:\ARSystem\Arserver\api\lib\com.bmc.arsys.jdbc- -SNAPSHOT.jarVerNum\ARSystem\Arserver\api\lib\arapi .jarVerNum( represents the release version number).VerNum

Click .

After the driver is configured, the driver name appears with a green check mark in the list.Driver Name

1.2 To create a database connectionOpen DbVisualizerClick the tab.DatabasesRight-click and select .Connections Click new database connectionIn the Use Connection Wizard dialog box, click .No wizard


Page of 6 23

5.

6.

1.

a. b.

2.

Click the tab and enter the following details:Object ViewIn the field, enter a name for your database.NameIn the field, enter the type of the database. For example, your database can be of Database type

type.GenericIn the field, enter the name of the AR System JDBC Driver. For example, ARJDBCDriver.Driver(JDBC)In the field, enter the database URL in this format: Database URL

.jdbc:arserver://:;user=;password=For example, .jdbc:arserver://localhost:5000;user=Demo;password=In the field, enter the user name.Database UseridIn the field, enter the password.Database Password

Click .Connect

A connection to the database is established.

1.2.1 To test the database connection in DbVisualizer version 9.x and laterIn addition to the above steps, perform the following configuration changes to run commands using theSQLCommander.

Open the file located in the DbVisualizer installation folder in a text editorresources/dbvis-custom.prefs and add the following on a new row:

dbvis.generic.-ConnectionValidationSelect=select 1 from UserORdbvis.generic.-ConnectionValidationSelect=disabled

Restart DbVisualizer, connect it to the database, and try again.


Page of 7 23

Note

The above step is important because in DbVisualizer 9.x and later versions, for generic JDBC drivers, youmust run a simple query to test the database connection. You can either run a simple query as shown instep a or disable this feature as shown in step b.


Page of 8 23

1.

2. 3.

2 Configuring the AR JDBC driver in Squirrel SQLclientYou can configure the AR JDBC driver in Squirrel SQL client and use the driver to establish a databaseconnection.

To configure the AR System JDBC driver (see page )To create a database connection (see page 10)

2.1 To configure the AR JDBC driverDownload and install Squirrel SQL client from .http://squirrel-sql.sourceforge.net/For installation instructions, see the appropriate Squirrel SQL documentation.Start Squirrel SQL.Click the tab.Drivers


Page of 9 23

4.

5.

6.

7. 8.

Click

to add a new driver.

In the Add Driver dialog box, enter the following information:In the field, enter the name of the driver. For example, ARServerJDBCNameIn the field, enter the URL of the AR System server to connect to using this format: Example URL

.jdbc:arserver://:;user=;password=For example, jdbc:arserver://localhost:5000;user=Demo; password=In the field, enter the website URL.Website URL

In the tab, click to load the following JAR files located in the Extra Class Path Add folder:\Arserver\api\lib

com.bmc.arsys.jdbc- -SNAPSHOT.jarVerNumarapi .jarVerNum( represents the release version number.)VerNum

Click and ensure that the is correctly populated in the field.List Drivers Class Name Class NameClick . The name of the driver appears in the list of the drivers on the left.OK


Page of 10 23

1. 2.

3.

4. 5.

The driver is now configured successfully.

2.2 To create a database connectionClick the tab.AliasesClick

to add a new alias.

In the Add Alias dialog box, enter the following details:In the field, enter the name of the AR System server.NameIn the field, enter the name of the AR JDBC driver that you have configured. For moreDriverinformation, see To configure the AR JDBC driver.In the field, enter the URL of the AR System server to connect to.URLIn the field, enter the user name.User NameIn the field, enter the password.Password

Click to test the database connection.TestClick if the connection is successfully established.OK

You are now ready to use the AR JDBC driver in Squirrel SQL.


Page of 11 23

1.

2.

3. 4.

5. 6.

3 Configuring the AR System JDBC driver inCrystal ReportsYou can configure the AR System JDBC driver in Crystal Reports and use the driver to establish a databaseconnection. The driver is tested with Crystal Reports versions 2011 and 2013.

To configure the AR System JDBC driver (see page 11)Limitations of using the AR System JDBC driver in Crystal Reports (see page 14)

3.1 To configure the AR System JDBC driverCopy the following files to the folder of your Crystal Reports installation:/lib/external

\Arserver\api\lib\com.bmc.arsys.jdbc- -SNAPSHOT.jarVerNum\Arserver\api\lib\arapi .jarVerNum

Ensure that the following files located in the folder are added to the\Arserver\api\libclasspath:

com.bmc.arsys.jdbc- -SNAPSHOT.jarVerNumarapi .jarVerNumlog4j- .jarVerNum( represents the release version number)VerNum

Open the file that is shipped with your Crystal Reports installation.CRConfig.xmlIn the node available under the node, add entries for the JAR files that you copied in Step 1.Ensure that you specify the full path of the JAR file.Start Crystal Reports.When you create a new report, a pop-up dialog box prompts you to select a connection.


Page of 12 23

7. Click and click the node.Create New Connection JDBC(JNDI)


Page of 13 23

8. a.

b.

c.

d.

e.

In the Connection dialog box that opens, do the following:In the field, enter the URL of the AR System server to connect to.Connection URLUse the following format for the URL:

.jdbc:arserver://:;user=;password=For example, jdbc:arserver://localhost:5000;user=Demo;password=In the field, enter the name of the driver class. For example, enter Database Classname

, which is the class name of the AR System JDBC driver.com.bmc.arsys.jdbc.core.DriverOptionally, you can also enter a name for this connection.Click .Next

In the Connection Information dialog box, enter the User ID and Password of the AR System serverconnection.Ensure that the field is blank.DatabaseClick .Finish

A new database connection is created. You can now use the connection to browse the objects in the BMCRemedy AR System Catalog and create a report from the forms and fields that you have selected.


Page of 14 23

3.2 Limitations of using the AR System JDBC driver in CrystalReports

If a field value is null when queried, Crystal Reports generates the following error:Failed to retrieve data from the database.: Not implemented

Workaround: Query the form data after adding some test data to the null fields. For example, youmight substitute null values in a form with and then query.NULL


Page of 15 23

4 Sample of configuring the AR JDBC driver in aJava programYou can configure the AR JDBC driver in a Java program and use that code to establish a database connection.You can then use the connection to browse the objects in the BMC Remedy AR System Catalog and create areport from the forms and fields that you have selected.

4.1 Sample Java program

package com.bmc.test;

import java.sql.Connection;import java.sql.DriverManager;import java.sql.ResultSet;import java.sql.SQLException;import java.sql.Statement;

public class SampleJDBCTest {

/** * @param args */ public static void main(String[] args) { try

{ // Load the database driver Class.forName( "com.bmc.arsys.jdbc.core.Driver" ) ; // Get a connection to the AR Server Connection conn = DriverManager.getConnection("jdbc:arserver://:;user=;password="); Statement st = conn.createStatement(); ResultSet rs = st.executeQuery("select * from "); while (rs.next()) { //Iterate results here } } catch(SQLException e) { e.printStackTrace(); } catch(ClassNotFoundException e) { e.printStackTrace(); }


Page of 16 23

}}


Page of 17 23

5 Optional parameters for the AR System JDBCdriverWhen establishing a database connection by using the AR System JDBC driver, you can use the following optionalparameters as part of the connection string:

Parameter Description

modeIf you set the mode to classic (for example, ), form and field names do not display specialmode=classiccharacters, such as ! % & * () - + = : ; \ " ' ? / . , These characters are replaced with underscore ( _ )characters.

Note

Starting with JDBC driver 1.0.1, the default mode is classic.

If you want the original table names and column names to be displayed, set the mode to new (for example, ) in the database URL.mode=new

Note

BMC recommends you to use for better performance.mode=new

useLabel If you set the value to true, (for example, ), field labels are displayed instead of field names.useLabel=True

locale If you set a locale (for example, locale=ja_JP), the values of the drop-down lists and radio buttons are displayedbelonging to the specified locale. If used with , the labels are displayed pertaining to the localeuseLabel=trueselected.

replaceDotsInObjectNames If you set the value to true (for example, ), the spaces and periods in the fieldreplaceDotsInObjectNames=truenames are replaced with hyphens (-).

diaryDescendingOrder If you set the value to true (for example, ), diary entries made against an entry arediaryDescendingOrder=truesorted in the descending order of time.

logging If you set the value to true, (for example, ), the AR System JDBC driver logs the output messages inlogging=truethe file that is specified in the file. For more information, see ARJDBCLog.properties Enabling logging for the AR

.System JDBC driver

timeZone Use this parameter to pass the time zone to the AR System server. For example, timeZone=America/New_York

authString Use this parameter to pass a valid SSO token along with the user name. For example, authString=""

Note

This mode is available from AR System JDBC driver version 1.0.2 onwards.


Page of 18 23

Parameter Description

Sample connection string format:

jdbc:arserver://:;user=;locale=;useLabel=;diaryDescendingOrder=;logging=;authString=


Page of 19 23

1.

2.

3.

6 Enabling logging for the AR JDBC driverThis topic explains how to enable logging for the AR JDBC driver.

6.1 To enable logging for the AR JDBC driverWhen establishing a database connection, set the value of the parameter to in thelogging trueconnection string.For more information, see Optional parameters for the AR JDBC driver.Place the file in one of the following locations:ARJDBCLog.properties

In the same folder as that of the process which has loaded the AR JDBC driver.This is used to debug third-party tools such as Squirrel SQL client or Crystal Reports.In the same folder as that of the AR JDBC driver JAR file.For example, place the file in the ARJDBCLog.properties

folder.\ARSystem\Arserver\api\libIn the folder that is referred by the java.io.tmpdir environment variable. If step 1 has been performedand the log file is not found in the locations previously mentioned, the file isARJDBCLog.propertiesread from the directory specified by the java.io.tmpdir environment variable.

Note

If this environment variable is not found, create a variable named java.io.tmpdir and specifya value indicating where you want to place the file.ARJDBCLog.properties

Edit the file to specify file names for the and ARJDBCLog.properties arjdbc_query.log arjdbc_misc.logsettings.For example, the contents of the file might look similar to the following:ARJDBCLog.properties

# log settings for AR JDBC Driver# To enable logging, place this file in # 1. same folder as that of the process which has loaded AR JDBC driver # 2. same folder as that AR JDBC JAR # 3. folder pointed by env variable named "java.io.tmpdir"# Change the location of below mentioned log file names as appropriatearjdbc_query.log=C:/query.logarjdbc_misc.log=C:/info.log


Page of 20 23

7 Limitations of the AR System JDBC driverThis topic lists the limitations of the AR System JDBC driver.

Data insertions or updates are not supported.Subqueries and clauses such as , , , , are not supported.UNION UNION ALL EXISTS INTERSECT MINUSROWNUM and parameters are not supported.TOPPERCENTUse of with an aggregate function is not supported. For example, the query DISTINCT select

is not supported.count(DISTINCT `Integer Field`) FROM JDBCTestFormAA query containing only two values is not supported. For example, the query Select Submitter FROM

is not supported.JDBCTestFormA where 1 = 2Queries with a construct must follow the ANSI syntax. The following query is not supported:JOINSelect TableA.column1, TableB.column2 from TableA, TableB where TableA.column3 =TableB.column3Queries containing , , , and are not supported.FULL NATURAL CROSS JOIN SELF JOINConnecting by using DataSource (JNDI) is not supported.SQL error codes are not supported.None of the PL-SQL or T-SQL functions are supported.Case insensitivity of form and field names is not supported.Currency and Diary fields are not allowed in aggregate functions and in , , and ORDER BY GROUP BY

clauses.DISTINCTFor queries containing the clause, only the % operator is supported.LIKESelection fields such as drop-down, option button, check box, and Currency fields work only with or = operators.Diary field works only with the clause.LIKEYou cannot use selection fields (drop-down, option button, check box), Currency field, and Diary field inqueries containing and clauses.ORDER BY GROUP BYA PreparedStatement with parameter replacement is not supported. For example, the query select *

is not supported.from Form A where `Request ID` =?The AR System JDBC driver is not tested with Business Objects XI version 3.1.Cannot handle column names that have special characters, such as Employee's"-Details if the mode is .newFor more information, see .Optional parameters for the AR System JDBC driver (see page 17)

For information on limitations of using the AR System JDBC driver in Crystal Reports, see Limitations of using the.AR System JDBC driver in Crystal Reports (see page 14)


Page of 21 23

8 Known issuesThis topic lists some of the common issues that you encounter when working with AR System JDBC driver.

Issue description

When you connect to AR System server using JDBC driver in DbVisualizer, the following error message might appear:

14:00:07 [ERROR pool-5-thread-1 ApiConfig.] Default settings are used since we could not load the configfrom file Cannot locate configuration source arsys_base.xml

Workaround:

Ignore this error message as this is the message from the API.

You might receive the following error message when you configure the JDBC driver in DbVisualizer or if you are logging on to AR System for the firsttime:

Exception caught opening stream to URL java.io.IOException: Cannot run program "regedit": CreateProcess error=740,The requested operation requires elevation.

Workaround:

Run DbVisualizer as an administrator. If you do not have admin permissions, the functioning of the JDBC driver is not affected.

When you run queries using DbVisualizer, you might receive the following error:

The database connection has been lost. Re-establish database connection for

Workaround:See .To test the database connection in DbVisualizer version 9.x and later (see page 6)


Page of 22 23

Copyright 2005-2007, 2009-2014 BMC Software, Inc. Copyright 2011-2014 BladeLogic, Inc.

BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., areregistered with the U.S. Patent and Trademark Office, and may be registered or pending registration in othercountries. All other BMC trademarks, service marks, and logos may be registered or pending registration in theU.S. or in other countries. All other trademarks or registered trademarks are the property of their respectiveowners.

BladeLogic and the BladeLogic logo are the exclusive properties of BladeLogic, Inc. The BladeLogic trademark isregistered with the U.S. Patent and Trademark Office, and may be registered or pending registration in othercountries. All other BladeLogic trademarks, service marks, and logos may be registered or pending registration inthe U.S. or in other countries. All other trademarks or registered trademarks are the property of their respectiveowners.

AIX, DB2, and IBM are trademarks or registered trademarks of International Business Machines Corporation in theUnited States, other countries, or both.

IT Infrastructure Library is a registered trademark of the Office of Government Commerce and is used here byBMC Software, Inc., under license from and with the permission of OGC.

ITIL is a Registered Trade Mark of the Office of Government Commerce in the United Kingdom and othercountries.

Linux is the registered trademark of Linus Torvalds.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of theirrespective owners.

SAP is the trademark of SAP AG in Germany and in several other countries.

UNIX is the registered trademark of The Open Group in the US and other countries.

The information included in this documentation is the proprietary and confidential information of BMC Software,Inc., its affiliates, or licensors. Your use of this information is subject to the terms and conditions of the applicableEnd User License agreement for the product and to the proprietary and restricted rights notices included in theproduct documentation.

Restricted rights legendU.S. Government Restricted Rights to Computer Software. UNPUBLISHEDRIGHTS RESERVED UNDER THECOPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software bythe U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time totime. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA.Any contract notices should be sent to this address.

BMC Software Inc.2101 CityWest Blvd, Houston TX 77042-2827, USA


Page of 23 23

713 918 8800Customer Support: 800 537 1813 or contact your local support center

Configuring the AR System JDBC driver in DbVisualizerTo configure the AR System JDBC driverTo create a database connectionTo test the database connection in DbVisualizer version 9.x and later

Configuring the AR JDBC driver in Squirrel SQL clientTo configure the AR JDBC driverTo create a database connection

Configuring the AR System JDBC driver in Crystal ReportsTo configure the AR System JDBC driverLimitations of using the AR System JDBC driver in Crystal Reports

Sample of configuring the AR JDBC driver in a Java programSample Java program

Optional parameters for the AR System JDBC driverEnabling logging for the AR JDBC driverTo enable logging for the AR JDBC driver

Limitations of the AR System JDBC driverKnown issues

Documents

JDBC Database Access