Rocket U2 Clients and APIs

Transcription

1 Rocket U2 Clients and APIs Using the JDBC Driver for UniData and UniVerse Version July 2014 UCC JDBC-UG-01

2 Notices Edition Publication date: July 2014 Book number: UCC JDBC-UG-01 Product version: JDBC Driver for UniData and UniVerse Copyright Rocket Software, Inc. or its affiliates All Rights Reserved. Trademarks Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go to: All other products or services mentioned in this document may be covered by the trademarks, service marks, or product names of their respective owners. Examples This information might contain examples of data and reports. The examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. License agreement This software and the associated documentation are proprietary and confidential to Rocket Software, Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance with the terms of such license. Note: This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when exporting this product. 2

3 Corporate information Rocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks, and compliance; database servers and tools; business information and analytics; and application development, integration, and modernization. Website: Rocket Global Headquarters 77 4th Avenue, Suite 100 Waltham, MA USA To contact Rocket Software by telephone for any reason, including obtaining pre-sales information and technical support, use one of the following telephone numbers. Country Toll-free telephone number United States Australia Belgium Canada China France Germany Italy Japan Netherlands New Zealand South Africa United Kingdom Contacting Technical Support The Rocket Customer Portal is the primary method of obtaining support. If you have current support and maintenance agreements with Rocket Software, you can access the Rocket Customer Portal and report a problem, download an update, or find answers in the U2 Knowledgebase. To log into the Rocket Customer Portal or to request a Rocket Customer Portal account, go to In addition to using the Rocket Customer Portal to obtain support, you can send to u2support@rocketsoftware.com or use one of the following telephone numbers. Country Toll-free telephone number North America United Kingdom/France +44(0) or +44(0) Europe/Africa +44 (0) Australia or +61 (0) New Zealand

4 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Table of Contents Table of Contents Chapter 1 Chapter 2 Chapter 3 Chapter 1: Introduction to JDBC Driver for UniData and UniVerse What is JDBC What is a JDBC driver Overview of JDBC JDBC for UniData and UniVerse architecture Chapter 2: Installing and setting up the JDBC driver for UniData and UniVerse Hardware and software requirements Installing the JDBC driver for UniData and UniVerse Installing on Windows platforms Installing on UNIX Connection pooling License considerations Migrating to Rocket U2 JDBC applications Java package names Access URLs Connection properties Function names Chapter 3: Accessing UniData data Verifying that UniRPC is running UCI connection timeout configuration Making UniData accounts accessible Tracing events Presenting data in JDBC accessible format Data types Multivalued and multi-subvalued data C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCTOC.fm (booktoc.template) July 11, :33 pm

5 Chapter 4 Chapter 5 Chapter 4: Accessing UniVerse data Accessing UniVerse tables and files Tables Files Multivalued data The TABLES rowset The UniVerse server administration menu Making files visible to JDBC applications Making files visible Updating the File Information Cache Removing file visibility COLUMNS rowset Association keys Table and column names containing special characters Delimited identifiers Making UniVerse data meaningful to JDBC SQL data types Length of character string data Empty-null mapping Validating and fixing tables and files Scalar functions Chapter 5: Programming with JDBC Loading the JDBC driver for UniData and UniVerse Creating a connection Format of database URLs Accessing database MetaData Querying the database Mapping data types Data conversion Handling errors Handling transactions Isolation levels JDBC 2.0 optional package support Tuning the connection pool Using encryption wallets Restrictions and limitations Unsupported data types Unsupported methods Table of Contents 5

6 Chapter 6 Chapter 7 Chapter 8 Chapter 6: JDBC scrollable cursors JDBC scrollable cursors Creating a scrollable cursor Methods for moving the cursor Connection URL parameters Example Chapter 7: JDBC for UniData and UniVerse code examples UniJDBC example program - list file UniJDBC short examples Select example UniJDBC prepared statement example UniJDBC callable statement example UniJDBC DatabaseMetaData example Chapter 8: Using SSL with JDBC Overview of SSL technology Software requirements Configuring the database server for SSL Creating a secure connection Managing keys and certificates for a JDBC client Importing CA certificates into a JDBC client trustfile Establishing the connection Generating client certificates Managing keyfile and trustfile for the proxy server Using the JDBC Driver for UniData and UniVerse

7 Chapter 1: Introduction to JDBC Driver for UniData and UniVerse Chapter 1 What is JDBC What is a JDBC driver Overview of JDBC JDBC for UniData and UniVerse architecture C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH01TOC.fm July 11, :33 pm

8 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH01.fm 7/14/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta This manual provides an overview of JDBC technology and how the JDBC Driver for UniData and UniVerse uses it to expose UniData and UniVerse extended relational data. This manual also describes how to configure the JDBC Driver for UniData and UniVerse, and provides information about the JDBC functionality that it supports. From this information, developers can design JDBC-based applications that can access and manipulate data in UniData and UniVerse data stores. The JDBC Driver for UniData and UniVerse is an implementation of the JDBC 1.0 specification with limited functionality supported for the JDBC 2.0 specification. This manual is organized in the following way: Chapter 1, Chapter 1: Introduction to JDBC Driver for UniData and UniVerse, introduces you to key concepts about JDBC, and shows you how JDBC fits in with other components in an enterprise network. This chapter also provides you with the hardware and software requirements for clients and servers that use JDBC. Chapter 2, Chapter 2: Installing and setting up the JDBC driver for UniData and UniVerse, describes how to install and configure the driver. Chapter 3, Chapter 3: Accessing UniData data, describes how to make accounts in UniData databases accessible to JDBC applications and how to normalize multivalued and multi-subvalued data in UniData. Use this manual in conjunction with Using VSG and the Schema API. It describes: Visual Schema Generator (VSG) A Windows based Graphical User Interface (GUI) tool for making data in UniData accessible to first normal form (1NF) applications. Schema API An application programming interface (API) that consists of a series of UniBasic subroutines designed to accomplish the same tasks as VSG. Note: We recommend that you use VSG to prepare files because it is easier and faster to use than the Schema API. It performs several processes automatically. You might want to use the Schema API if you have a large number of files. Chapter 4, Chapter 4: Accessing UniVerse data, describes how to make data in UniVerse schemas and accounts accessible to JDBC applications. 1-2 Using the JDBC Driver for UniData and UniVerse

9 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH01.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Chapter 5, Chapter 5: Programming with JDBC, describes how the JDBC Driver for UniData and UniVerse supports the JDBC API. Chapter 6, Chapter 6: JDBC scrollable cursors, describes how to use scrollable cursors with the JDBC Drive for UniData and UniVerse. Chapter 7, Chapter 7: JDBC for UniData and UniVerse code examples, contains example programs for the JDBC Driver for UniData and UniVerse. 1-3

10 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH01.fm 7/14/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta What is JDBC Java database connectivity (JDBC) is the JavaSoft specification of a standard application programming interface (API) that allows Java programs to access database management systems. The JDBC API consists of a set of interfaces and classes written in the Java programming language. Using these standard interfaces and classes, programmers can write applications that connect to databases, send queries written in structured query language (SQL), and process the results. The JDBC API is consistent with the style of the core Java interfaces and classes, such as java.lang and java.awt. The following table describes the interfaces, classes, and exceptions that make up the JDBC API. Interface, Class, or Exception java.sql.callablestatement java.sql.connection java.sql.databasemetadata java.sql.driver java.sql.preparedstatement java.sql.resultset java.sql.resultsetmetadata java.sql.statement java.sql.date Description Interface used to execute stored procedures. Interface used to establish a connection to a database. SQL statements run within the context of a connection. Interface used to return information about the database. Interface used to locate the driver for a particular database management system. Interface used to send pre-compiled SQL statements to the database server and obtain results. Interface used to process the results returned from executing an SQL statement. Interface used to return information about the columns in a ResultSet object. Interface used to send static SQL statements to the database server and obtain results. Subclass of java.util.date used for the SQL DATE data type. 1-4 Using the JDBC Driver for UniData and UniVerse

11 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH01.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Interface, Class, or Exception java.sql.drivermanager java.sql.driverpropertyinfo java.sql.time java.sql.timestamp java.sql.types java.sql.string java.sql.datatruncation java.sql.sqlexception java.sql.sqlwarning Description Class used to manage a set of JDBC drivers. Class used to discover and supply properties to a connection. Subclass of java.util.date used for the SQL TIME data type. Subclass of java.util.date used for the SQL TIMESTAMP data type. Class used to define constants that are used to identify standard SQL data types, such as VARCHAR, INTEGER, and DECIMAL. Class used to identify long text data types such as LVARCHAR. Exception thrown or warning reported when data has been truncated. Exception that provides information about a database error. Warning that provides information about a database warning. Since JDBC is a standard specification, one Java program that uses the JDBC API can connect to any database management system (DBMS), as long as a driver exists for that particular DBMS. For more information about the JDBC API, visit the JavaSoft Web Site at: 1-5

12 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH01.fm 7/14/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta What is a JDBC driver This section discusses the JDBC API specification definition of JDBC drivers. For more information, see The JDBC API consists of a set of classes and interfaces written in the Java programming language that provide a standard API for database developers, and makes it possible to write robust database applications using an all-java API. A JDBC driver implements these interfaces and classes for a particular DBMS vendor. A Java program that uses the JDBC API loads the specified driver for a particular DBMS before it actually connects to a database. The JDBC Driver- Manager class then sends all JDBC API calls to the loaded driver. There are four types of JDBC drivers: 1. JDBC-ODBC bridge plus ODBC driver (also called Type 1): This type of driver translates JDBC API calls into ODBC calls that are then passed to the ODBC driver. ODBC binary code, and in many cases database client code, must be loaded on each client machine that uses this driver. As a result, this kind of driver is most appropriate on a corporate network where client installations are easily managed, or for application server code written in Java in a three tier architecture. 2. Native-API, partly java driver (also called Type 2): This kind of driver converts JDBC API calls into DBMS-specific client API calls. Like the bridge driver, this type of driver requires that some binary code be loaded on each client computer. 3. JDBC-Net, pure-java driver (also called Type 3): This driver translates JDBC calls into a DBMS-independent net protocol, which is then translated to a DBMS protocol by a server. 4. Native-Protocol, pure-java driver (also called Type 4): This type of driver converts JDBC API calls directly into the DBMS-specific network protocol without a middle tier. This allows the client applications to connect directly to the database server. The JDBC Driver for UniData and UniVerse is a Type 4, Native-Protocol, driver. 1-6 Using the JDBC Driver for UniData and UniVerse

13 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH01.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Overview of JDBC The JDBC Driver for UniData and UniVerse enables JDBC applications to connect to the UniData and UniVerse Relational Database Management Systems (RDBMS). The JDBC Driver for UniData and UniVerse is a Type 4 or Native Protocol type driver and is an implementation of the JDBC 1.0 specification with support for some 2.0 functionality. A JDBC application sends a connection request to the JDBC Driver for UniData and UniVerse. The driver receives the request, and establishes a connection to the UniData or UniVerse RDBMS. Then the JDBC application can access the RDBMS. When the process is complete, the JDBC application sends a disconnection request to the JDBC Driver for UniData and UniVerse, and disconnects from the RDBMS. In order to access the data from a JDBC application, the data must conform to the 1NF standard, or be normalized. UniVerse dynamically normalizes its own data. For more information, see Chapter 4, Chapter 4: Accessing UniVerse data. UniData also normalizes its own data, but you must prepare the data for it to do so. To prepare the data, you must use VSG, a GUI tool that generates schema on UniData files, or the Schema API. For more information about using VSG or the Schema API, see Chapter 3, Chapter 3: Accessing UniData data, and Using VSG and the Schema API. 1-7

14 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH01.fm 7/14/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta JDBC for UniData and UniVerse architecture JDBC Application JDBC Driver UniRPC UniData RDBMS UniVerse RDBMS 1-8 Using the JDBC Driver for UniData and UniVerse

15 Chapter 2: Installing and setting up the JDBC driver for UniData and UniVerse Chapter 2 Hardware and software requirements Installing the JDBC driver for UniData and UniVerse Installing on Windows platforms Installing on UNIX Connection pooling License considerations Migrating to Rocket U2 JDBC applications Java package names Access URLs Connection properties Function names C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH02TOC.fm July 11, :33 pm

16 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH02.fm 7/15/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta This chapter describes how to prepare both a client and server machine to run JDBC for UniData and UniVerse. 2-2 Using the JDBC Driver for UniData and UniVerse

17 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH02.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Hardware and software requirements The following lists provide the hardware and software requirements for client and server machines that use the JDBC for UniData and UniVerse. Client requirements JDBC 2.0 Extended Feature Support is required for U2 Connection Pooling. The JDBC 2.0 Optional Support package can be downloaded from and contains the following required libraries: fscontext.jar jdbc2_0-stdext.jar jndi.jar providerutil.jar Windows Client IBM-compatible personal computer (PC) attached to a network. Windows 2003, XP, or later Approximately 20 MB of free disk space. A minimum of 64 MB of random access memory (RAM). TCP/IP. Java 1.6 or greater must be installed. If you intend to use U2 JDBC connection pooling, you must have a sufficient number of connection pooling licenses. Every time a JDBC connection is made, a connection pooling license is consumed. The number of connection pooling licenses available must be at least as large as the specified number of minimum pooled connections, as defined in the U2_CPM_INIT_POOLSIZE parameter. 2-3

18 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH02.fm 7/15/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta To use connection pooling with JCDBC to access U2 databases, you need the following libraries from the UniDK tool kit: asjava.zip asjava_p.zip* unijdbc.jar * The asjava_p.zip file is required if proxy connections are needed. JRE/JDK version 1.6. UNIX Client Java 1.6 or greater must be installed Server requirements UNIX, Windows 2003, XP, or later TCP/IP. Either of the following U2 Relational Database servers: UniData 6.0 or later UniVerse 10.0 or later 2-4 Using the JDBC Driver for UniData and UniVerse

19 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH02.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Installing the JDBC driver for UniData and UniVerse Installing on Windows platforms 1. If you are installing the JDBC Driver for UniData and UniVerse from a CD-ROM, load the disc into the CD-ROM drive. 2. A menu appears on the screen. Select UniDK. The installation wizard prompts for several options. When presented with which components of the UniDK you wish to install, make sure you select both the JDBC and UniObjects For Java options. Click Next. Note: If you already have a version of the UniDK installed, the installation process prompts to Repair, Modify or Remove the installation of the UniDK. Select Remove to uninstall the existing version. Once you have uninstalled the older version of the UniDK, return to step When the installation has completed, you will be prompted to restart your computer. Close all other programs, then click Yes. 4. You must now set the CLASSPATH environment variable to include UniJDBC.jar and asjava.zip. Open a Command Prompt session. At the prompt, type: set CLASSPATH=C:\U2\UniDK\jdbc\lib\unijdbc.jar;C:\U2\UniDK\ uojsdk\lib\asjava.zip;%classpath% Note that the path used in this example is from a default UniDK installation. If you chose to install the UniDK in a different path, you will need to adjust your CLASSPATH accordingly. 2-5

20 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH02.fm 7/15/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Installing on UNIX The following section describes how to install JDBC on UNIX systems. The JDBC client and database server are on the same machine If you plan to run your JDBC client on the same machine that is running the UniData or UniVerse database server, follow the instructions below. A standard installation of either the UniData or UniVerse database servers includes the required files for JDBC. They are located in the unishared directory. After the database server has been installed, type the following command. cat /.unishared This command tells you the path to the unishared directory. The JDBC files located in this directory have the following structure: /unishared /jdbc/docs/unijdbcjavadoc.zip /jdbc/lib/unijdbc.jar /jdbc/samples/jdbcsample.zip /uojsdk/lib/asjava.zip Another required file, asjava.zip is located in the UniObjects for Java installation in the path shown above. The files and their functions are as follows: unijdbc.jar - The main driver file for the U2 Driver for UniData and UniVerse. asjava.zip - Contains required libraries for UniJDBC and UniObjects for Java unijdbcjavadoc.zip - The javadoc for the UniJDBC driver code. jdbcsample.zip - A sample UniJDBC program for reference. Set your classpath environment variable to include unijdbc.jar and asjava.zip. For example, enter the following command when using ksh: export CLASSPATH=/unishared/jdbc/lib/unijdbc.jar:/unishared/uojsdk/lib/as java.zip:$classpath 2-6 Using the JDBC Driver for UniData and UniVerse

21 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH02.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta The JDBC Client and Database Server are on Different Machines If you plan to run your JDBC on a UNIX machine other than the one where UniData or UniVerse are installed, you must copy the unijdbc.jar and asjava.zip files to the client machine, and set the classpath accordingly. Refer to the Installing on Windows platforms on page 2-5 or Installing on UNIX on page 2-6 for the location of these files on Windows and UNIX installations, respectively. After you copy the files to your UNIX client machine, you must set your classpath. See the Installing the JDBC driver for UniData and UniVerse on page 2-5 for further details about setting the classpath. Once you copy the files and set the classpath, you are ready to get started. 2-7

22 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH02.fm 7/15/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Connection pooling U2 supports connection pooling with several client APIs including U2 JDBC, UniObjects for Java, and UniObjects for.net. The term connection pooling refers to the technology that pools permanent connections to data sources for multiple threads to share. It improves application performance by saving the overhead of making a fresh connection each time one is required. Instead of physically terminating a connection when it is no longer needed, connections are returned to the pool and an available connection is given to the next thread with the same credentials. You can activate connection pooling in your program, or activate it through a configuration file. License considerations The actual size of a connection pool depends on the pooling licenses available on the server. For example, if you set a connection pool to a minimum size of 2 and a maximum size of 100, and you have 16 licenses available, the maximum connection pool size will be 16. If you only have 1 license available, the U2 database does not create the connection pool at all, since the minimum size of 2 cannot be met. Note: U2 connection pool licenses are not application specific, and the number of licenses consumed in one application affects the number of licenses available for all U2 applications. For example, if you have 10 connection pooling licenses and use three license in your JDBC application, only seven licenses will remain for any other U2 client applications that use connection pooling. 2-8 Using the JDBC Driver for UniData and UniVerse

23 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH02.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Migrating to Rocket U2 JDBC applications Beginning at the July 2014 release of the Rocket U2 Common Clients and APIs, the Rocket U2 JDBC driver has been rebranded and no longer contains any IBM references. Migrating your existing U2 JDBC applications requires making a few small changes to the following: Java package names Access URLs Connection properties Function names 2-9

24 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH02.fm 7/15/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Java package names U2 JDBC com.ibm.u2.jdbc Rocket U2 JDBC com.rs.u2.jdbc Java package name migration Access URLs U2 JDBC * jdbc:ibm-u2://host[:portnum]/account[{? ;}name=(value) [;name=(value)]... ] Rocket U2 JDBC * jdbc:rs-u2://host[:portnum]/account[{? ;}name=(value) [;name=(value)]... ] * jdbc:ibmu2:dsname/account[{? ;}name=(value ) [;name=(value)]... ] * jdbc:rsu2:dsname/account[{? ;}name=(value) [;name=(value)]... ] Access URL migration Connection properties U2 JDBC IBM_CPM_MAX_CONNECTIONS IBM_CPM_INIT_POOLSIZE IBM_CPM_MAX_POOLSIZE IBM_CPM_MIN_POOLSIZE IBM_CPM_AGELIMIT IBM_CPM_MIN_AGELIMIT IBM_CPM_SERVICE_INTERVAL Rocket U2 JDBC U2_CPM_MAX_CONNECTIONS U2_CPM_INIT_POOLSIZE U2_CPM_MAX_POOLSIZE U2_CPM_MIN_POOLSIZE U2_CPM_AGELIMIT U2_CPM_MIN_AGELIMIT U2_CPM_SERVICE_INTERVAL IBM_CPM_PC_REFRESH_MODE Connection property migration U2_CPM_PC_REFRESH_MODE 2-10 Using the JDBC Driver for UniData and UniVerse

25 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH02.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Function names U2 JDBC public void setibm_cpm_max_- CONNECTIONS( int limit) public void setibm_cpm_max_connections( int limit) public int getibm_cpm_max_connec- TIONS() public int getibm_cpm_max_connections() public void setibm_cp- M_INIT_POOLSIZE (int init) public void setibm_cpm_init_poolsize (int init) public int getibm_cpm_init_poolsize() public int getibm_cpm_init_poolsize() public void setibm_cpm_max- _POOLSIZE(int max) public void setibm_cpm_max- _poolsize(int max) public int getibm_cpm_max_poolsize() public int getibm_cpm_max_poolsize() public void setibm_cp- M_MIN_POOLSIZE( int min) public void setibm_cpm_min_poolsize( int min) Rocket U2 JDBC public void setu2_cpm_max_con- NECTIONS( int limit) public void setu2_cpm_max_connections( int limit) public int getu2_cpm_max_connections() public int getu2_cpm_max_connections() public void setu2_cp- M_INIT_POOLSIZE (int init) public void setu2_cpm_init_poolsize (int init) public int getu2_cpm_init_poolsize() public int getu2_cpm_init_poolsize() public void setu2_cpm_max- _POOLSIZE(int max) public void setu2_cpm_max- _poolsize(int max) public int getu2_cpm_max_poolsize() public int getu2_cpm_max_poolsize() public void setu2_cp- M_MIN_POOLSIZE( int min) public void setu2_cpm_min_poolsize( int min) public int getibm_cpm_min_poolsize() public int getu2_cpm_min_poolsize() Function name migration 2-11

26 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH02.fm 7/15/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta U2 JDBC public int getibm_cpm_min_poolsize() public void setibm_cpm_min_age- LIMIT( long agelimit) public void setibm_cpm_min_agelimit( long agelimit) public long getibm_cpm_min_agelimit() public long getibm_cpm_min_agelimit() public void setibm_cpm_agelimit( long agelimit) public void setibm_cpm_agelimit( long agelimit) public long getibm_cpm_agelimit() public long getibm_cpm_agelimit() public void setibm_cpm_pc_re- FRESH_MODE(int method) public void setibm_cpm_pc_refresh_mode(int method) public int getibm_cpm_pc_refresh_mode() public int getibm_cpm_pc_refresh_mode() Rocket U2 JDBC public int getu2_cpm_min_poolsize() public void setu2_cpm_min_age- LIMIT( long agelimit) public void setu2_cpm_min_agelimit( long agelimit) public long getu2_cpm_min_agelimit() public long getu2_cpm_min_agelimit() public void setu2_cpm_agelimit( long agelimit) public void setu2_cpm_agelimit( long agelimit) public long getu2_cpm_agelimit() public long getu2_cpm_agelimit() public void setu2_cpm_pc_re- FRESH_MODE(int method) public void setu2_cpm_pc_refresh_mode(int method) public int getu2_cpm_pc_refresh_mode() public int getu2_cpm_pc_refresh_mode() public void setibm_cpm_ser- VICE_INTERVAL(long interval) public void setu2_cpm_service_in- TERVAL(long interval) Function name migration 2-12 Using the JDBC Driver for UniData and UniVerse

27 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH02.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta U2 JDBC public void setibm_cpm_service_interval(long interval) public long getibm_cpm_service_interval() Rocket U2 JDBC public void setu2_cpm_service_interval(long interval) public long getu2_cpm_service_interval() public long getibm_cpm_service_interval() public long getu2_cpm_service_interval() Function name migration 2-13

28 Chapter 3: Accessing UniData data Chapter 3 Verifying that UniRPC is running UCI connection timeout configuration Making UniData accounts accessible Tracing events Presenting data in JDBC accessible format Data types Multivalued and multi-subvalued data C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH03TOC.fm July 11, :33 pm

29 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH03.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta This chapter describes how to access data in UniData tables and files. You must perform the following tasks: Verify that the UniRPC daemon (for UNIX systems) or the UniRPC service (for Windows platforms) is running. Make UniData accounts accessible to JDBC applications. Present the data in UniData in a format that is accessible to JDBC applications. 3-2

30 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH03.fm 7/15/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Verifying that UniRPC is running When JDBC requests a connection to the UniData UCI server, the UniRPC facility starts the server (udserver) process, which runs on the machine where the database resides. Before you use JDBC, make sure that UniRPC is running. On UNIX systems, you can verify whether UniRPC is running by entering the following command: ps -ef grep unirpc If you need to start UniRPC for UNIX, use the UniData startud command. For more information, see Administrative Supplement for APIs included with both the UniData and UniVerse documentation sets. On Windows platforms, you can verify whether UniRPC is running by double-clicking the Services icon on the Windows Control Panel. The Services dialog box appears. If UniRPC is running, it appears in the list of services with the status Started. If UniRPC is not running, you can start it from the Services dialog box. UniRPC is installed automatically when you install UniData. On UNIX systems, the UniRPC services file (unirpcservices) contains an entry that is similar to the following example: udserver /usr/ud73/bin/udsrvd * TCP/IP The unirpcservices file is located, by default, on the UCI server in the.../unishared/unirpc directory. This directory is located in a path that is parallel with the udthome directory. For example, if the path to udthome is /disk1/udthome, the path to the unirpcservices file is /disk1/unishared/unirpc. On Windows platforms, the unirpcservices file is located on the UCI server in the following default path: x:\u2\unishared\unirpc where x is the drive on which the software is installed. It contains an entry that is similar to the following example: udserver C:\usr\ud73\bin\udsrvd.exe * TCP/IP Using the JDBC Driver for UniData and UniVerse

31 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH03.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Your unishared directory might not be located in the default path. To determine its actual location on UNIX systems, enter: cat /.unishared This provides the path for the unishared directory. For Windows platforms, you can find the path for unishared by looking in the system registry in \HKEY_LOCAL_MACHINE\SOFTWARE\Rocket Software\unishared. When the client system requests a connection to a UCI server, the local UniRPC daemon or service uses the unirpcservices file to verify that the client can start the requested server (in this case, udserver). With the Server edition of UniData, each JDBC connection to a UniData UCI server consumes one UniData license. With the Workstation, Workgroup, or Enterprise edition of UniData, device licensing enables each client system to establish up to ten connections to the UCI server from one device while consuming only one database license regardless of whether more than one user login is used to make the connections. For more information about device licensing, see Installing and Licensing UniData Products and the Administrative Supplement for APIs. UCI connection timeout configuration The sixty-minute default inactivity timeout value (3600) for UCI connections can be too short. If users leave JDBC connections open, but the connections remain inactive for longer than sixty minutes, they could receive UniRPC error code To increase this timeout value, use any text editor to modify the unirpcservices file (for the path to this file, see Verifying that UniRPC is running on page 3-3). Note: To edit the unirpcservices file, you must have root privileges on UNIX or Administrator privileges on Windows platforms. For example, to set the connection timeout delay to 24 hours, in the line starting with udserver, change the right-most number to (the number of seconds in 24 hours). The line could appear as follows: udserver /usr/ud73/bin/udsrvd * TCP/IP

32 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH03.fm 7/15/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Making UniData accounts accessible UniData databases are organized into accounts. A JDBC application connects to a UniData account and can access the files there. You optionally can define the account as a database in the ud_database file on the server machine. You can specify the account under the account property of the connection URL. If you want to access an account that has a UDTHOME directory different than the default UDTHOME directory, you must include a definition for that account in the ud_database file on the server machine. For UNIX systems, this file is located in the /usr/udnn/include path, where nn is the release of UniData you are running. For Windows platforms, it is located in \udthome\include. You can find the path for udthome by looking in the system registry under \HKEY_LOCAL_MACHINE\SOFTWARE\Rocket Software\UniData\7.3. Use any text editor to modify the ud_database file. Note: To determine your default UniData home directory, use the UNIX env command. The results of this command include the default setting for the UDTHOME environment variable. The following Windows example shows an entry in the ud_database file for a database named db2: DATABASE=db2 UDTHOME=d:\disk2\test73 UDTACCT=d:\disk2\test73\testacct. In the ud_database file entry, the UDTHOME parameter is optional. You should include it only when the UDTHOME directory is different than the default UDTHOME directory. Tracing events By using the tracing feature, you can create logs of events between clients and the database through the server. Logs enable U2 support personnel to help troubleshoot problems. You can define trace levels for database entries in the ud_database file. 3-5 Using the JDBC Driver for UniData and UniVerse

33 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH03.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta The following table describes the valid trace levels and the associated information that is written to the trace log. Trace Level Description 0 Includes all fatal error information. 1 Includes all UCI commands in addition to the information provided by trace level 0. 2 Includes parameter information and column descriptions in addition to the information provided by trace levels 0 and 1. 3 Includes data values in addition to the information provided by trace levels 0, 1, and 2. Trace Levels The trace log is named udsrv_database.processid where database is the database name (for example, db2) and processid is the process number ID. By default, it is located in your temporary directory (typically, /tmp for UNIX; x:\temp for platforms). For UNIX, you can find the location of the trace log file in the TMP parameter in the udtconfig file under /usr/ud73/include. The following UNIX example shows a tracing level setting for a database named dbase3: DATABASE=dbase3 UDTHOME=/disk1/ud73 UDTACCT=/home/username/test TRACE_LEVEL=3 3-6

34 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH03.fm 7/15/14 Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Presenting data in JDBC accessible format Data in UniData is organized differently from the way JDBC expects it to be organized. Two areas in which the data differs from what JDBC expects are: Data types Multivalued and multi-subvalued data Data types UniData does not define data types for data contained in its files. On the other hand, JDBC expects data types for all data. In addition, data in UniData can be of variable length, but JDBC expects data to have either a fixed or a maximum length. To make the data look more like what JDBC expects, you must use VSG or the Schema API. Multivalued and multi-subvalued data JDBC expects data to be organized in first normal form (1NF) format. Although some files could be in 1NF format, which means that only one value is stored in each column of each row, many UniData files have columns that store multiple values in the columns of a row (NF 2 format). To instruct UniData SQL to present data in 1NF format, you must use VSG or the Schema API. VSG or the Schema API create views and subtables that present multivalued and multi-subvalued data in 1NF format. These views and subtables do not duplicate data, but merely instruct UniData SQL to normalize data before returning it to the application. JDBC passes the 1NF data to the Java application in the form of rowsets. Visual Schema Generator and the Schema API There are two ways to create 1NF views and subtables to instruct UniData SQL to present data in UniData in a JDBC accessible format: VSG Schema API 3-7 Using the JDBC Driver for UniData and UniVerse

35 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH03.fm Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta VSG is a Windows-based graphical user interface (GUI) tool that makes UniData files accessible to other applications through JDBC. It enables you to create, delete, and modify UniData SQL subtables and views. VSG also enables you to set ANSI privileges (security) for tables, subtables, and views. VSG guides data administrators through the process of defining the 1NF subtables and views that represent the extended relations by visually presenting all available configuration options. It also translates conversion specifications for UniData to SQL data types. VSG performs logical error checking through every step of the schema generation process. The Schema API consists of a series of UniBasic subroutines designed to accomplish the same normalization tasks as VSG. We recommend that you use VSG to prepare files because it is easier and faster to use than the Schema API. It performs several processes automatically. You might want to use the Schema API if you have a large number of files (in this case, several VSG processes take several minutes to complete) or you deploy data files with your applications. For more information about using VSG or the Schema API, see Using VSG and the Schema API. 3-8

36 Chapter 4: Accessing UniVerse data Chapter 4 Accessing UniVerse tables and files Tables Files Multivalued data The TABLES rowset The UniVerse server administration menu Making files visible to JDBC applications Making files visible Updating the File Information Cache Removing file visibility COLUMNS rowset Association keys Table and column names containing special characters Delimited identifiers Making UniVerse data meaningful to JDBC SQL data types Length of character string data Empty-null mapping Validating and fixing tables and files Scalar functions C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH04TOC.fm July 11, :33 pm

37 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH04.fm This chapter describes how to access data in UniVerse tables and files. The following data is always accessible to a JDBC application connected to a UniVerse account: All UniVerse tables on the system. All non-sql UniVerse files defined in the VOC file of the current account. In this chapter, the word tables refers to UniVerse tables defined by the CREATE TABLE statement, and views defined by the CREATE VIEW statement. The word files refers to non-sql UniVerse files that are created by the CREATE.FILE command. The term JDBC table refers to any table or file, real or virtual, that is accessible to JDBC applications. Before a JDBC application attempts to connect to a UniVerse data source, the UniRPC daemon (for UNIX systems) or the UniRPC service (for Windows platforms) must be running on the server system. For information about setting up data sources, see Chapter 2, Chapter 2: Installing and setting up the JDBC driver for UniData and UniVerse. 4-2

38 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH04.fm 7/15/14 Accessing UniVerse tables and files A JDBC application connects to a UniVerse account (which can be a schema) and can access all tables on the system and all files defined in the VOC file of that account. Sometimes a JDBC application connected to UniVerse gets a list of JDBC tables by requesting a TABLES rowset. This rowset lists: All tables on the system. Files defined in the current account s VOC file that have been made visible to JDBC. Virtual tables (dynamically normalized multivalued data) within the above. We refer to the JDBC tables listed in the TABLES rowset as visible to JDBC applications. Although all SQL tables on the system are, by definition, visible, non-sql files that have not been made visible are not included in the TABLES rowset. For information about how to make files visible in an account, see Making files visible to JDBC applications on page Tables When connected to a UniVerse account, a JDBC application can access all tables on the system. If connected to a UniVerse schema, the JDBC application can reference tables in that schema by using unqualified table names in SQL statements. All other tables on the system can be referenced using table names qualified by the appropriate schema name. Example 1 In this example the JDBC application is connected to schema HR. If table EMPLOYEES is in schema HR, you can reference it simply as EMPLOYEES. If view EMPLOYEES is in schema DENVER, you must reference it as DENVER.EMPLOYEES. 4-3 Using the JDBC Driver for UniData and UniVerse

39 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH04.fm Example 2 In this example, the JDBC application is connected to account SALES that is not a schema. In this case, you must reference table EMPLOYEES (in schema HR) and view EMPLOYEES (in schema DENVER) as HR.EMPLOYEES and DENVER.EMPLOYEES respectively. Files A JDBC application can access files that are defined in the VOC file of the account to which the JDBC application is connected. Because some JDBC applications are written to access only tables listed in the TABLES rowset, as a practical matter UniVerse files may not be usable unless they have been made visible for that account. For example, if a JDBC application connects to an account whose files have been made visible, all files defined in the account s VOC file, except for system files (such as &SAVEDLISTS&) and UV/Net files, are visible. The JDBC application can reference the files using the file names in the VOC. The account does not need to be a schema. On the other hand, if a JDBC application connects to an account whose files have not been made visible, no files appear in the TABLES rowset. However, the JDBC application can still access files defined in the account s VOC file. Multivalued data JDBC applications expect data to be organized relationally in first normal form (1NF). Although some UniVerse tables and files are in first normal form, which means only one value is stored in each column of each row, many UniVerse tables and files have columns that store multiple values. UniVerse always presents multivalued data to JDBC in first normal form (1NF), and JDBC passes it to the java applications in the form of rowsets. UniVerse automatically normalizes its tables and files by a process called dynamic normalization. This means that a file containing multivalued data appears to JDBC as several 1NF tables, each consisting of singlevalued data only. 4-4

40 C:\Users\awaite\Documents\U2Doc\Clients\Source\JDBC\JDBCCH04.fm 7/15/14 Example The table ORDERS is defined with columns ORDERNUM, CUSTNUM, DATE, PART, and QTY. PART and QTY are multivalued and make up an association called ITEMS. The association key is PART. Suppose this table contains the following orders. ORDERNUM CUSTNUM DATE PART QTY /25/99 HINGE 200 BOLT /10/99 BOLT 50 ORDERS Table This file appears to JDBC as two 1NF tables called ORDERS and ORDERS_ITEMS. The ORDERNUM column is the ORDERS key. ORDERNUM CUSTNUM DATE /25/ /10/99 ORDERS 1NF Table The ORDERNUM and PART columns are the two columns that make up the ORDERS_ITEMS key. ORDERNUM PART QTY HINGE BOLT BOLT 50 ORDERS 1NF Table 4-5 Using the JDBC Driver for UniData and UniVerse

41 C:\Users\awaite\Documents\U2Doc\ Clients\Source\JDBC\JDBCCH04.fm The TABLES rowset A JDBC application can request a TABLES rowset that includes all tables and visible files. For each table and visible file, this rowset includes schema name, table name, and table type. Table type can be TABLE, VIEW, or SYSTEM TABLE. Example 1 Suppose the JDBC application is connected to a UniVerse account that is not a schema, and suppose the account contains two files called EMPS and DEPTS. EMPS and DEPTS are not tables. EMPS has one multivalued column called DEPENDENTS, and DEPTS has no multivalued columns. Files in this account have been made visible. Suppose there is another UniVerse account whose files have been made visible, which contains a file called OTHERFILE. If the JDBC application requests the TABLES rowset, it includes the following information. Schema Name Table Name Table Type <null value> EMPS TABLE <null value> EMPS_DEPENDENTS TABLE <null value> DEPTS TABLE Example 1: TABLES Rowset Information This shows that: Any files listed in the TABLES rowset must be in the account to which the JDBC application is connected (OTHERFILE does not appear). Files listed in the TABLES rowset have a null value for the schema name. A multivalued column appears as a separate dynamicallynormalized table whose type is TABLE and whose name is composed of the original file s name followed by an underscore and the name of the column. 4-6