C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCTITL.

fm
March 8, 2010 1:38 pm

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta
Beta Beta Beta Beta

Using the IBM JDBC

Driver for UniData and
UniVerse

UDT-720-JDBC-1
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCTITL.fm
March 8, 2010 1:38 pm

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

Notices
Edition
Publication date: June 2008
Book number: UDT-720-JDBC-1
Product version: UniData 7.2

Copyright
© Rocket Software, Inc. 1988-2008. All Rights Reserved.

Trademarks
The following trademarks appear in this publication:

Trademark Trademark Owner

Rocket Software™ Rocket Software, Inc.

Dynamic Connect® Rocket Software, Inc.

RedBack® Rocket Software, Inc.

SystemBuilder™ Rocket Software, Inc.

UniData® Rocket Software, Inc.

UniVerse™ Rocket Software, Inc.

U2™ Rocket Software, Inc.

U2.NET™ Rocket Software, Inc.

U2 Web Development Environment™ Rocket Software, Inc.

wIntegrate® Rocket Software, Inc.

Microsoft® .NET Microsoft Corporation

Microsoft® Office Excel®, Outlook®, Word Microsoft Corporation

Windows® Microsoft Corporation

Windows® 7 Microsoft Corporation

Windows Vista® Microsoft Corporation

Java™ and all Java-based trademarks and logos Sun Microsystems, Inc.

UNIX® X/Open Company Limited

ii Using the IBM JDBC Driver for UniData and UniVerse

The above trademarks are property of the specified companies in the United States,
other countries, or both. All other products or services mentioned in this document
may be covered by the trademarks, service marks, or product names as designated
by the companies who own or market them.

License agreement
This software and the associated documentation are proprietary and confidential to
Rocket Software, Inc., are furnished under license, and may be used and copied only
in accordance with the terms of such license and with the inclusion of the copyright
notice. This software and any copies thereof may not be provided or otherwise made
available to any other person. No title to or ownership of the software and associated
documentation is hereby transferred. Any unauthorized use or reproduction of this
software or documentation may be subject to civil or criminal liability. The information
in the software and documentation is subject to change and should not be construed
as a commitment by Rocket Software, Inc.
Restricted rights notice for license to the U.S. Government: Use, reproduction, or
disclosure is subject to restrictions as stated in the “Rights in Technical Data-
General” clause (alternate III), in FAR section 52.222-14. All title and ownership in
this computer software remain with Rocket Software, Inc.

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.
Please be aware: Any images or indications reflecting ownership or branding of the
product(s) documented herein may or may not reflect the current legal ownership of
the intellectual property rights associated with such product(s). All right and title to
the product(s) documented herein belong solely to Rocket Software, Inc. and its
subsidiaries, notwithstanding any notices (including screen captures) or any other
indications to the contrary.

Contact information
Rocket Software
275 Grove Street Suite 3-410
Newton, MA 02466-2272
USA
Tel: (617) 614-4321 Fax: (617) 630-7100
Web Site: www.rocketsoftware.com

Using the IBM JDBC Driver for UniData and UniVerse iii
Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta
Table of
Contents

Table of Contents

Chapter 1 Introduction to IBM JDBC Driver for UniData and UniVerse

What is JDBC . . . . . . . . . . . . . . . . . . . . 1-4
What is a JDBC Driver . . . . . . . . . . . . . . . . . 1-6
Overview of JDBC. . . . . . . . . . . . . . . . . . . 1-7
IBM JDBC for UniData and UniVerse Architecture . . . . . . . . 1-8

Chapter 2 Installing and Setting Up the IBM JDBC Driver for UniData
and UniVerse
Hardware and Software Requirements . . . . . . . . . . . . 2-3
Installing the IBM JDBC Driver for UniData and UniVerse . . . . . . 2-5
Installing on Windows Platforms. . . . . . . . . . . . . 2-5
Installing on UNIX . . . . . . . . . . . . . . . . . 2-6

Chapter 3 Accessing UniData Data

Verifying That UniRPC Is Running . . . . . . . . . . . . . 3-3
UCI Connection Timeout Configuration . . . . . . . . . . 3-4
Making UniData Accounts Accessible . . . . . . . . . . . . 3-5
Tracing Events . . . . . . . . . . . . . . . . . . 3-5
Presenting Data in JDBC–Accessible Format . . . . . . . . . . 3-7
Data Types . . . . . . . . . . . . . . . . . . . 3-7
Multivalued and Multi-Subvalued Data . . . . . . . . . . 3-7

Chapter 4 Accessing UniVerse Data

Accessing UniVerse Tables and Files . . . . . . . . . . . . . 4-3
Tables . . . . . . . . . . . . . . . . . . . . . 4-3
Files. . . . . . . . . . . . . . . . . . . . . . 4-4
Multivalued Data . . . . . . . . . . . . . . . . . 4-4
The TABLES Rowset . . . . . . . . . . . . . . . . 4-5
The UniVerse Server Administration Menu . . . . . . . . . . . 4-10
Making Files Visible to JDBC Applications . . . . . . . . . . . 4-12

:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCTOC.fm (bookTOC.template)

 Making Files Visible. . . . . . . . . . . . . . . . . 4-12
Restricting File Visibility . . . . . . . . . . . . . . . 4-13
Updating the File Information Cache . . . . . . . . . . . 4-14
Removing File Visibility . . . . . . . . . . . . . . . 4-16
COLUMNS Rowset . . . . . . . . . . . . . . . . . 4-18
Association Keys . . . . . . . . . . . . . . . . . . 4-19
Table and Column Names Containing Special Characters. . . . . . . 4-22
Delimited Identifiers. . . . . . . . . . . . . . . . . 4-22
Making UniVerse Data Meaningful to JDBC. . . . . . . . . . . 4-23
SQL Data Types . . . . . . . . . . . . . . . . . . 4-23
Length of Character String Data . . . . . . . . . . . . . 4-24
Empty-Null Mapping . . . . . . . . . . . . . . . . 4-26
Validating and Fixing Tables and Files . . . . . . . . . . . 4-26
Scalar Functions . . . . . . . . . . . . . . . . . . 4-29

Chapter 5 Programming with JDBC

Loading the IBM JDBC Driver for UniData and UniVerse . . . . . . 5-3
Creating a Connection . . . . . . . . . . . . . . . . . . 5-4
Format of Database URLs . . . . . . . . . . . . . . . 5-5
Accessing Database MetaData . . . . . . . . . . . . . . . 5-7
Querying the Database . . . . . . . . . . . . . . . . . 5-8
Mapping Data Types . . . . . . . . . . . . . . . . . . 5-9
Data Conversion . . . . . . . . . . . . . . . . . . 5-10
Handling Errors . . . . . . . . . . . . . . . . . . . . 5-11
Handling Transactions. . . . . . . . . . . . . . . . . . 5-12
Isolation Levels . . . . . . . . . . . . . . . . . . 5-13
JDBC 2.0 Optional Package Support . . . . . . . . . . . . . 5-14
Tuning the Connection Pool . . . . . . . . . . . . . . 5-18
Restrictions and Limitations . . . . . . . . . . . . . . . . 5-22
Unsupported Data Types . . . . . . . . . . . . . . . 5-22
Unsupported Methods . . . . . . . . . . . . . . . . 5-22

Chapter 6 JDBC Scrollable Cursors

JDBC Scrollable Cursors . . . . . . . . . . . . . . . . . 6-2
Creating a Scrollable Cursor . . . . . . . . . . . . . . 6-2
Methods for Moving the Cursor . . . . . . . . . . . . . 6-3
Connection URL Parameters. . . . . . . . . . . . . . . . 6-4
Example . . . . . . . . . . . . . . . . . . . . . . 6-5

Table of Contents v
 Chapter 7 IBM for UniData and UniVerse JDBC Code Examples
UniJDBC Example Program - List File . . . . . . . . . . . . 7-3
UniJDBC Short Examples . . . . . . . . . . . . . . . . 7-7
Select Example . . . . . . . . . . . . . . . . . . 7-7
UniJDBC Prepared Statement Example . . . . . . . . . . 7-9
UniJDBC Callable Statement Example . . . . . . . . . . 7-10
UniJDBC DatabaseMetaData Example . . . . . . . . . . 7-11

vi Using the IBM JDBC Driver for UniData and UniVerse

 Chapter

Introduction to IBM JDBC

Driver for UniData and 1
UniVerse
What is JDBC. . . . . . . . . . . . . . . . . . . . 1-4
What is a JDBC Driver . . . . . . . . . . . . . . . . . 1-6
Overview of JDBC . . . . . . . . . . . . . . . . . . 1-7
IBM JDBC for UniData and UniVerse Architecture . . . . . . . . 1-8

:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH01TOC.fm

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH01.fm
3/8/10

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 IBM JDBC
Driver for UniData and UniVerse uses it to expose UniData and UniVerse extended
relational data. This manual also describes how to configure the IBM JDBC Driver
for UniData and UniVerse, and provides information about the JDBC functionality
that it supports. From this information, developers can design JDBC-based applica-
tions that can access and manipulate data in UniData and UniVerse data stores.

The IBM 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, “Introduction to IBM 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, “Installing and Setting Up the IBM JDBC Driver for UniData
and UniVerse,” describes how to install and configure the driver.
„ 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: IBM recommends 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, “Accessing UniVerse Data,” describes how to make data in
UniVerse schemas and accounts accessible to JDBC applications.
„ Chapter 5, “Programming with JDBC,” describes how the IBM JDBC
Driver for UniData and UniVerse supports the JDBC API.
„ Chapter 6, “JDBC Scrollable Cursors,” describes how to use scrollable
cursors with the IBM JDBC Drive for UniData and UniVerse.

1-2 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

„ Chapter 7, “IBM for UniData and UniVerse JDBC Code Examples,”

contains example programs for the IBM JDBC Driver for UniData and
UniVerse.

1-3
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH01.fm
3/8/10

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 appli-
cation 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 Description

java.sql.CallableStatement Interface used to execute stored procedures.

java.sql.Connection Interface used to establish a connection to a

database. SQL statements run within the context of
a connection.

java.sql.DatabaseMetaData Interface used to return information about the

database.

java.sql.Driver Interface used to locate the driver for a particular

database management system.

java.sql.PreparedStatement Interface used to send pre-compiled SQL

statements to the database server and obtain results.

java.sql.ResultSet Interface used to process the results returned from

executing an SQL statement.

java.sql.ResultSetMetaData Interface used to return information about the

columns in a ResultSet object.

java.sql.Statement Interface used to send static SQL statements to the

database server and obtain results.

java.sql.Date Subclass of java.util.Date used for the SQL DATE

data type.

java.sql.DriverManager Class used to manage a set of JDBC drivers.

1-4 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

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 Description

java.sql.DriverPropertyInfo Class used to discover and supply properties to a

connection.

java.sql.Time Subclass of java.util.Date used for the SQL TIME

data type.

java.sql.TimeStamp Subclass of java.util.Date used for the SQL

TIMESTAMP data type.

java.sql.Types Class used to define constants that are used to

identify standard SQL data types, such as
VARCHAR, INTEGER, and DECIMAL.

java.sql.String Class used to identify long text data types such as

LVARCHAR.

java.sql.DataTruncation Exception thrown or warning reported when data

has been truncated.

java.sql.SQLException Exception that provides information about a

database error.

java.sql.SQLWarning 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:
http://java.sun.com/

1-5
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH01.fm
3/8/10

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 http://java.sun.com/docs/books/jdbc/intro.html.

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 IBM JDBC Driver for UniData and UniVerse is a Type 4, Native-Protocol,
driver.

1-6 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

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 IBM JDBC Driver for UniData and UniVerse enables JDBC applications to connect
to the UniData and UniVerse Relational Database Management Systems (RDBMS).

The IBM 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 IBM 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 IBM 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,
“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, “Accessing UniData Data,” and Using VSG and the Schema API.

1-7
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH01.fm
3/8/10

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

IBM JDBC for UniData and UniVerse

Architecture

JDBC Application

IBM JDBC
J Driver

UniRPC

UniData UniVerse
DBMS
RDBMS DBMS
RDBMS

1-8 Using the IBM JDBC Driver for UniData and UniVerse
 0

Chapter

Installing and Setting Up

the IBM JDBC Driver for 2
UniData and UniVerse
Hardware and Software Requirements . . . . . . . . . . . . 2-3
Installing the IBM JDBC Driver for UniData and UniVerse . . . . . 2-5
Installing on Windows Platforms . . . . . . . . . . . . 2-5
Installing on UNIX. . . . . . . . . . . . . . . . . 2-6

:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH02TOC.fm

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH02.fm
3/8/10

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 IBM
JDBC for UniData and UniVerse.

2-2 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

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 IBM JDBC for UniData and UniVerse.

Client Requirements

Windows Client
„ IBM-compatible personal computer (PC) attached to a network.
„ Either of the following operating systems:
„ Windows platforms NT 4.0 (Service Pack #6) or later (for example,
Windows 2000, Windows XP, and so forth)
„ Approximately 20 MB of free disk space.
„ A minimum of 64 MB of random access memory (RAM).
„ TCP/IP.
„ Java 1.2 or greater must be installed.
„ If you wish to use any of the extended options from the JDBC 2.0 Optional
API, such as connecting through a data source or the use of connection
pooling, you must obtain an implementation of the Java Directory and
Naming Interface (JNDI). You need to download and install the JDBC
Optional Package from Javasoft, which includes a required import package
(javax.sql.*) for any JDBC application making use of the Optional API.
Also required are the JNDI 1.2.1 class libraries (javax.naming.*), which you
can download if you are not using JDK 1.3 or higher. If you are using JDK
1.3 or higher, the JNDI libraries are included.

UNIX Client
„ Java 1.2 or greater must be installed

Server Requirements
„ UNIX, Windows NT or higher (for example, Windows 2000, Windows XP,
and so forth).
„ TCP/IP.

2-3
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH02.fm
3/8/10

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

„ Either of the following IBM Relational Database servers:

„ UniData 6.0 or later
„ UniVerse 10.0 or later

2-4 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

Installing the IBM JDBC Driver for UniData

and UniVerse

Installing on Windows Platforms

1. If you are installing the IBM 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 1.
3. 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:\IBM\UniClient\UniDK\jdbc\lib\unijdbc.jar;C
:\IBM\UniClient\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.
Note: If you want to make connections using the DataSource or
ConnectionPoolDataSource objects, you must also install the JDBC 2.0 Optional
Package. You also need an implementation of the Java Naming and Directory
Interface (JNDI). You can acquire these from Sun Microsystems’ web site.
http://java.sun.com/products/jdbc
http://java.sun.com/products/jndi
See Chapter 5,“JDBC 2.0 Optional Package Support,” for more information.

2-5
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH02.fm
3/8/10

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
/uojskd/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 IBM 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 IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

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 IBM 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
 Chapter

Accessing UniData Data

3
Verifying That UniRPC Is Running . . . . . . . . . . . . . 3-3
UCI Connection Timeout Configuration . . . . . . . . . . 3-4
Making UniData Accounts Accessible . . . . . . . . . . . . 3-5
Tracing Events . . . . . . . . . . . . . . . . . . 3-5
Presenting Data in JDBC–Accessible Format . . . . . . . . . . 3-7
Data Types . . . . . . . . . . . . . . . . . . . 3-7
Multivalued and Multi-Subvalued Data . . . . . . . . . . 3-7

:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH03TOC.fm

C:\Program
Files\Adobe\FrameMaker8\UniData

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
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH03.fm
3/8/10

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/ud72/bin/udsrvd * TCP/IP 0 3600

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:\IBM\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\ud72\bin\udsrvd.exe * TCP/IP 0 3600

3-3 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

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\IBM\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 connec-
tions. 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 81015. 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 864000 (the number of “seconds” in 24
hours). The line could appear as follows:

udserver /usr/ud72/bin/udsrvd * TCP/IP 0 864000

3-4
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH03.fm
3/8/10

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\IBM\UniData\7.2. 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\test72
UDTACCT=d:\disk2\test72\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 IBM support personnel to help troubleshoot
problems. You can define trace levels for database entries in the ud_database file.

3-5 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

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/ud71/include.

The following UNIX example shows a tracing level setting for a database named
dbase3:
DATABASE=dbase3
UDTHOME=/disk1/ud71
UDTACCT=/home/username/test
TRACE_LEVEL=3

3-6
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH03.fm
3/8/10

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 (NF2 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 IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

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.

IBM recommends 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
 Chapter

Accessing UniVerse Data

4
Accessing UniVerse Tables and Files . . . . . . . . . . . . 4-3
Tables . . . . . . . . . . . . . . . . . . . . . 4-3
Files . . . . . . . . . . . . . . . . . . . . . 4-4
Multivalued Data . . . . . . . . . . . . . . . . . 4-4
The TABLES Rowset . . . . . . . . . . . . . . . . 4-6
The UniVerse Server Administration Menu . . . . . . . . . . 4-10
Making Files Visible to JDBC Applications . . . . . . . . . . 4-12
Making Files Visible . . . . . . . . . . . . . . . . 4-12
Restricting File Visibility . . . . . . . . . . . . . . . 4-13
Updating the File Information Cache . . . . . . . . . . . 4-14
Removing File Visibility . . . . . . . . . . . . . . . 4-16
COLUMNS Rowset . . . . . . . . . . . . . . . . 4-18
Association Keys . . . . . . . . . . . . . . . . . 4-19
Table and Column Names Containing Special Characters . . . . . . 4-22
Delimited Identifiers . . . . . . . . . . . . . . . . 4-22
Making UniVerse Data Meaningful to JDBC . . . . . . . . . . 4-23
SQL Data Types . . . . . . . . . . . . . . . . . 4-23
Length of Character String Data . . . . . . . . . . . . 4-25
Empty-Null Mapping . . . . . . . . . . . . . . . . 4-26
Validating and Fixing Tables and Files . . . . . . . . . . 4-26
Scalar Functions . . . . . . . . . . . . . . . . . 4-29

:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04TOC.fm

C:\Program
Files\Adobe\FrameMaker8\UniData

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, “Installing and Setting
Up the IBM JDBC Driver for UniData and UniVerse.”

4-2
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

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 appli-
cations. 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 4-12.

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 IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

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 appli-
cation 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 automati-
cally 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
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

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

99101 12345 5/25/99 HINGE 200

BOLT 650

99102 98765 6/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

99101 12345 5/25/99

99102 98765 6/10/99

ORDERS 1NF Table

The ORDERNUM and PART columns are the two columns that make up the
ORDERS_ITEMS key.

ORDERNUM PART QTY

99101 HINGE 200

99101 BOLT 650

99102 BOLT 50
ORDERS 1NF Table

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.

4-5 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

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 DEPEN-
DENTS, 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 dynamically-normalized 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.

Example 2
Suppose the above account is made into a schema named USA. Suppose two tables
called CITIES and STATES are then created where CITIES has only single-valued
columns and STATES has an association called COUNTIES.

4-6
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

The TABLES rowset now includes the following returned information.

Schema Name Table Name Table Type

<null value> EMPS TABLE

<null value> EMPS_DEPENDENTS TABLE

<null value> DEPTS TABLE

USA CITIES TABLE

USA STATES TABLE

USA STATES_COUNTIES TABLE

Example 2: TABLES Rowset Information

This shows that:

„ Tables have a schema name, unlike files.

„ An association appears as a dynamically-normalized 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 association.

Example 3
Suppose an SQL view called STATEVIEW is created in another schema (called
JOESCHEMA) with the following SQL statement:
CREATE VIEW STATEVIEW AS SELECT * FROM USA.STATES;

While still connected to the original account, the JDBC application sees the following
information returned in the TABLES rowset.

Schema Name Table Name Table Type

<null value> EMPS TABLE

<null value> EMPS_DEPENDENTS TABLE

<null value> DEPTS TABLE

USA CITIES TABLE

Example 3: TABLES Rowset Information

4-7 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Schema Name Table Name Table Type

USA STATES TABLE

USA STATES_COUNTIES TABLE

JOESCHEMA STATEVIEW VIEW

JOESCHEMA STATEVIEW_COUNTIES VIEW

Example 3: TABLES Rowset Information (Continued)
This shows that:

„ Tables and views in other schemas appear in the TABLES rowset.

„ Views and their dynamically-normalized associations and multivalued
columns have the table type VIEW.

Example 4
Suppose the account JOESCHEMA mentioned above contains a UniVerse file called
JOEFILE that has not been made visible. Suppose a JDBC application connects to
JOESCHEMA and requests the TABLES rowset. This rowset includes the following
information.

Schema Name Table Name Table Type

USA CITIES TABLE

USA STATES TABLE

USA STATES_COUNTIES TABLE

JOESCHEMA STATEVIEW VIEW

JOESCHEMA STATEVIEW_COUNTIES VIEW

Example 4: TABLES Rowset Information

This shows:

„ Files in other accounts (such as EMPS) do not appear in the TABLES

rowset.
„ Files in the account to which the JDBC application is connected (such as
JOEFILE) do not appear if they have not been made visible.

4-8
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

Example 5
The UniVerse SQL catalog tables also appear in the TABLES rowset. Their table type
is SYSTEM TABLE.

Schema Name Table Name Table Type

CATALOG UV_ASSOC SYSTEM TABLE

CATALOG UV_COLUMNS SYSTEM TABLE

CATALOG UV_COLUMNS_ACOL_NO SYSTEM TABLE

CATALOG UV_COLUMNS_AMC SYSTEM TABLE

CATALOG UV_SCHEMA SYSTEM TABLE

CATALOG UV_TABLES SYSTEM TABLE

Example 5: TABLES Rowset Information

4-9 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

The UniVerse Server Administration Menu

You can use the UniVerse Server Administration menu on the server system to
perform certain administrative functions that may facilitate access to your UniVerse
data from JDBC applications. These functions include making UniVerse files in an
account visible to JDBC, and detecting data anomalies in a table or file. Tasks
described later in this chapter use selections that appear on this menu.

To display the menu:

1. Log on to the server system as root on UNIX or as an Administrator on

platforms.
2. Invoke UniVerse and log to the HS.ADMIN account. This account is in a
subdirectory named HS.ADMIN in the UV account directory.
3. Type the command: HS.ADMIN.

The UniVerse Server Administration menu appears, as shown in the following

example.

UniVerse Server Administration

1. List activated accounts

2. Show UniVerse ODBC Config configuration for an account
3. Activate access to files in an account
4. Deactivate access to files in an account
5. Run HS.SCRUB on a File/Table
6. Update File Information Cache in an account

Which would you like? ( 1 - 6 )

4-10
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

1. To exit the menu, press ENTER.

The following table describes the selections that appear on the UniVerse
Server Administration menu.

Menu Selection Description

1. List activated accounts Lists UniVerse accounts whose files have been made
visible to JDBC. When a JDBC application is
connected to such an account, the account’s files are
included in the TABLES rowset.

2. Show UniVerse ODBC Config Does not apply to JDBC.

configuration for an account

3. Activate access to files in an Makes files in a UniVerse account visible to JDBC so

account that when a JDBC application is connected to this
account, its files are included in the TABLES rowset.

4. Deactivate access to files in an Removes JDBC visibility from files in a UniVerse

account account. This reverses the actions of making files
visible.

5. Run HS.SCRUB on a File/Table Analyzes the data in a table or file, and lets you
optionally correct anomalous data.

6. Update File Information Cache Updates this account’s .hs_fileinfo file to reflect the
in an account current state of all files in the account.
UniVerse Server Administration Menu Selections

4-11 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Making Files Visible to JDBC Applications

For JDBC applications, it is necessary to make files visible unless all of the data of
interest is stored in UniVerse tables. This is because files that are not tables are not
included in the TABLES rowset unless the JDBC application is connected to an
account whose files have been made visible.

Making Files Visible

Complete the following steps to make files in a UniVerse account visible to JDBC
Applications:

1. On the UniVerse Server Administration menu, choose the third selection

(Activate access to files in an account).
2. When prompted, enter either the full path of the UniVerse account (on
Windows platforms, start with the drive letter, such as D:) or the account
name as listed in the UV.ACCOUNT file.
3. Repeat steps 1 and 2 for each account whose files you want to make visible.
4. To exit the UniVerse Server Administration menu, press ENTER.

The process of making files visible does the following:

„ Scans the dictionaries of all non-system files named in the VOC, finding all
associations and unassociated multivalued columns.
„ Writes an @EMPTY.NULL X-record in each file dictionary.
„ Writes S or M in field 5 of A- and S-descriptors.
„ Creates Q-pointers in the VOC for files comprising multiple data files.
„ Creates an HS_FILE_A000HS_FILE_A000 file in the account.
„ Creates a file information cache (.hs_fileinfo) under the account’s directory,
which contains a compressed list of all 1NF file names in the account and is
used by the JDBC Driver to rapidly construct the TABLES rowset whenever
a Java application requests it to do so.
„ Updates the UV.ACCOUNT file to indicate that the files in the account have
been made visible.

4-12
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

Restricting File Visibility

When you make an account’s files visible to JDBC, the HS_FILE_A000 file is
created in the account, as stated in the previous section. This file contains records for
non-SQL files referenced by F- and Q-pointers in the account’s VOC file. The
following table shows the format and initial contents of the HS_FILE_A000 file.

FILENAME (Record ID) ACCESS (Field 1)

HS_DEFAULT READ_WRITE
&DEVICE& NONE
. .
. .
. .
VOC NONE
VOCLIB NONE
Initial Contents of HS_FILE_A000

You can edit the HS_FILE_A000 file to control which files in the account are visible
to JDBC applications.

The IDs of records in the HS_FILE_A000 file are the names of the files whose access
you want to control. Each record has one field (ACCESS), which contains one of the
following values:

„ READ_WRITE
„ READ
„ NONE

If the ACCESS field for a file is set to READ, this is treated the same as
READ_WRITE for JDBC.

The HS_FILE_A000 file contains a special record called HS_DEFAULT which con-
trols default access to all files in the account. When you first make files visible, the
HS_DEFAULT record is set to READ_WRITE and the records for UniVerse system
files (APP.PROGS, BASIC.HELP, ERRMSG, UV.ACCOUNT, DICT.DICT,
NEWACC, and so forth) are set to NONE (no access).

To remove visibility from a few selected files and leave the rest visible to JDBC, add
a record to HS_FILE_A000 for each restricted file, with the ACCESS field set to
NONE.

4-13 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

To make just a few files in an account visible to JDBC, change the ACCESS field in
the HS_DEFAULT record from READ_WRITE to NONE, and then add selected
files whose ACCESS field is READ_WRITE.

If you change the contents of the HS_FILE_A000 file, you must then update the file
information cache for your changes to take effect. For information about updating the
file information cache, see the next section.

Updating the File Information Cache

After an account’s files have been made visible, if the following types of change are
made to the account’s files, the changes are not automatically reflected in the
TABLES rowset:

„ Adding, changing, or deleting F- or Q-pointers in the VOC file.

„ Creating or deleting UniVerse files.
„ Adding, changing, or deleting associations or unassociated multivalued
column definitions in file dictionaries.
„ Restricting access to selected files by changing the contents of the
HS_FILE_A000 file.

These types of change are not reflected in the TABLES rowset until the account’s file
information cache is updated.

You can update the file information cache using the UniVerse Server Administration
menu or the HS.UPDATE.FILEINFO command.

Complete the following steps to update the file information cache using the menu:

1. On the UniVerse Server Administration menu, choose the sixth selection

(Update File Information Cache in an account).
2. When prompted, enter either the full path of the UniVerse account (on
Windows platforms, start with the drive letter, for example, D:) or enter the
account name as listed in the UV.ACCOUNT file.
3. Repeat steps 1 and 2 for each account you want to update.
4. To exit the UniVerse Server Administration menu, press ENTER.

To update the file information cache using the HS.UPDATE.FILEINFO command:

1. Log to the desired UniVerse account.

4-14
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

2. At the system prompt, enter the command HS.UPDATE.FILEINFO.

The process of updating an account’s file information cache executes the
following tasks:
„ Scans the dictionaries of all non-system files named in the VOC,
finding all associations and unassociated multivalued columns.
„ Rewrites the file information cache (.hs_fileinfo) under the account’s
directory, based on the above dictionary information and the contents
of the HS_FILE_A000 file.

Warning: The file information cache is for internal use only and should not be
modified. Any changes to the cache can cause unpredictable behavior and can make
UniVerse files in the account inaccessible to JDBC applications.

Example
Suppose account MYACCOUNT contains the following files:

„ STATES, which has an association called CITYZIPS.

„ EMPS, which has multi-valued (unassociated) columns DEPENDENTS
and PHONES.
„ OCEANS, which has only singlevalued columns.

After the files in this account are made visible, the TABLES rowset lists the
following tables.

Schema Name Table Name Table Type

<null value> STATES TABLE

<null value> STATES_CITYZIPS TABLE

<null value> EMPS TABLE

<null value> EMPS_DEPENDENTS TABLE

<null value> EMPS_PHONES TABLE

<null value> OCEANS TABLE

TABLES Rowset for MYACCOUNT

4-15 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Suppose you now make the following changes in MYACCOUNT:

„ Delete file STATES.

„ Remove column DEPENDENTS from the dictionary of EMPS.
„ Create a VOC entry called EMPLOYEES that refers to the same data
file and file dictionary as does EMPS.
„ Create a new file CONTINENTS that has only singlevalued columns.
„ Add a record to HS_FILE_A000, whose key is OCEANS and whose
ACCESS field is set to NONE.

These changes are not immediately reflected in the TABLES rowset, but after
MYACCOUNT’s file information cache is updated, the TABLES rowset lists the
following information.

Schema Name Table Name Table Type

<null value> EMPS TABLE

<null value> EMPS_PHONES TABLE

<null value> EMPLOYEES TABLE

<null value> EMPLOYEES_PHONES TABLE

<null value> CONTINENTS TABLE

Updated TABLES Rowset for MYACCOUNT

Removing File Visibility

Complete the following steps to make files in a UniVerse account invisible to JDBC:

1. On the UniVerse Server Administration menu, choose the fourth selection

(Deactivate access to files in an account).
2. When prompted, enter either the full path of the UniVerse account (on
Windows platforms, start with the drive letter, for example, D:) or the
account name as listed in the UV.ACCOUNT file.
3. Repeat steps 1 and 2 for each account whose files you want to make
invisible.
4. To exit the UniVerse Server Administration menu, press ENTER.

4-16
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

Making files invisible executes the following tasks:

„ Deletes the HS_FILE_A000 file in the account.

„ Deletes the file information cache (.hs_fileinfo) under the account’s
directory.
„ Updates the UV.ACCOUNT file to indicate that files in this account are not
visible.

4-17 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Accessing Columns in UniVerse Tables and

Files
As explained earlier, NF2 data in UniVerse appears as 1NF tables to a JDBC appli-
cation. You can access all columns defined in the dictionaries of these NF2 files
(including tables and views). In addition to stored-data columns, A JDBC application
can access I-descriptors and correlatives (as read-only columns).

Some JDBC applications are written as general-purpose programs that determine a

list of visible columns by requesting a COLUMNS rowset. The COLUMNS rowset
for any visible 1NF table describes all columns returned by the following statement:
SELECT * FROM tablename;

Columns other than those returned in the COLUMNS rowset may be accessible by
JDBC applications, since "SELECT *" does not always return all columns defined in
the dictionary.

COLUMNS Rowset
A JDBC application can request a COLUMNS rowset, which provides a list of
column characteristics. Each row in the COLUMNS rowset includes the following
information:

„ Schema name
„ Table name
„ Column name
„ Column position
„ Data type
„ Precision
„ Scale

For UniVerse tables, and all multivalued columns within them, columns listed in the
COLUMNS rowset are defined by the dictionary’s @SELECT phrase (if it exists), or
are defined as the columns created by CREATE TABLE (and possibly modified by
ALTER TABLE) if there is no @SELECT phrase.

4-18
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

For files, and for associations and unassociated multivalued columns within them,
columns listed in the COLUMNS rowset are defined by the dictionary’s @SELECT
phrase (if it exists). If there is no @SELECT phrase, the contents of the COLUMNS
rowset are defined by the dictionary’s @ phrase (if it exists). If neither an @SELECT
phrase nor an @ phrase exists, only the record ID (@ID) appears in the COLUMNS
rowset.

For more information about the @SELECT and @ phrases, see UniVerse Adminis-
tration for DBAs.

Association Keys
UniVerse tables have primary keys. UniVerse files have record IDs. Primary keys and
record IDs are unique identifiers for each row (record) of data in a table or file.

Because JDBC shows associations and unassociated multivalued columns as 1NF

tables, they also require a set of unique identifiers that serve as primary keys. These
keys are called association keys.

When you create a UniVerse table or file, you can define one or more association
columns as the association key, but you do not have to. If you do not, UniVerse SQL
generates a virtual column called @ASSOC_ROW containing unique values that,
combined with the primary keys or record IDs of the base table, become the associ-
ation keys for the 1NF table generated from the association.

For detailed information about defining association keys, see UniVerse SQL Admin-
istration for DBAs and the UniVerse SQL Reference.

Example
The file EMPS is defined with columns EMPNUM, NAME, DEPTNUM, DEPEN-
DENTS, and PHONES, where DEPENDENTS and PHONES are unassociated
multivalued columns. Suppose this file contains the following employees.

EMPNUM NAME DEPTNUM DEPENDENTS PHONES

4456 GONZALES 97 SUSAN 555-876-4041

FREDERICA

4901 HURLBUT 58 555-245-1000

EMPS File

4-19 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

EMPNUM NAME DEPTNUM DEPENDENTS PHONES

555-245-1456

6511 RICHARDS 58 HELEN 400-765-4321

ALFRED 400-765-9010

SAMUEL
EMPS File
This table will appear to JDBC as three 1NF tables called EMPS,
EMPS_DEPENDENTS, and EMPS_PHONES.

The EMPS 1NF table has column EMPNUM as its key.

EMPNUM NAME DEPTNUM

4456 GONZALES 97

4901 HURLBUT 58

6511 RICHARDS 58
EMPS NF1 Table

The EMPS_DEPENDENTS 1NF table has a key consisting of two columns:

EMPNUM and @ASSOC_ROW.

EMPNUM DEPENDENTS @ASSOC_ROW

4456 SUSAN 1

4456 FREDERICA 2

6511 HELEN 1

6511 ALFRED 2

6511 SAMUEL 3
EMPS_DEPENDENTS 1NF Table

4-20
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

The EMPS_PHONES 1NF table also has a two-column key consisting of EMPNUM
and @ASSOC_ROW.

EMPNUM PHONES @ASSOC_ROW

4456 555-876-4041 1

4901 555-245-1000 1

4901 555-245-1456 2

6511 400-765-4321 1

6511 400-765-9010 2
EMPS_PHONES 1NF Table

4-21 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Table and Column Names Containing

Special Characters
Some UniVerse table and column names can contain special characters such as period
(.) or at-sign (@). These names can cause difficulty with some JDBC applications
unless they are enclosed in double quotation marks.

Delimited Identifiers
UniVerse supports an ANSI-SQL feature called "delimited identifiers." This means
that any identifier (table name, column name, index name, constraint name, and so
forth) can be enclosed in double quotation marks to avoid ambiguity in the syntax of
an SQL statement. This is particularly useful in the case of UniVerse table and
column names that contain the period (.) character.

The following example shows a SELECT statement that contains column and table
names delimited by double-quotation marks:
SELECT "MY.COLUMN" FROM SCHEMAX."MY.TABLE";

4-22
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

Making UniVerse Data Meaningful to JDBC

This section describes tasks you may need to perform on the UniVerse server to make
particular kinds of UniVerse data meaningful to JDBC applications:

„ Define SQL data types for data in UniVerse files.

„ Define the length of character string data in UniVerse files.
„ Set up empty-null mapping.
„ Validate and fix data in data files and dictionaries that cause SQL and JDBC
problems.

SQL Data Types

To fine-tune or define data type, precision, and scale values for columns and
I-descriptors in files, you can edit the DATATYPE field of the corresponding
dictionary entry (field 8 in D- and I-descriptors, field 6 in A- and S-descriptors). This
is especially important for character data in which the display width defined in the
dictionary may be much larger or smaller than the largest data values in the file. The
HS.SCRUB utility can automatically make these adjustments based on the data
found. For more information about HS.SCRUB, see “Validating and Fixing Tables
and Files” on page 4-26.

4-23 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

If the DATATYPE field is empty, UniVerse determines a column’s SQL data type by
examining its conversion code and format specifications. The UniVerse server
reports this SQL data type to JDBC applications in the COLUMNS rowset. If the
UniVerse-generated SQL data type is inappropriate for the actual data in the column,
you can specify the correct SQL data type in the DATATYPE field of the column’s
dictionary entry. For some data types, the SQL data type syntax is different between
dictionary specifications and UniVerse SQL statements (for example, CREATE
TABLE) as noted in the following table. Square brackets indicate optional
parameters.

Dictionary Syntax UniVerse SQL Syntax Notes

CHAR [ ACTER ] [,n] CHAR [ ACTER ] [(n)] n = number of characters

DEC [ IMAL ] [,p[,s]] DEC [ IMAL ] [(p[,s])] p = precision s = scale

FLOAT[,p] FLOAT[(p)] p = precision

NUMERIC[,p[,s]] NUMERIC[(p[,s])] p = precision s = scale

VARCHAR[, n] VARCHAR[(n)] n = number of characters

SQL Data Type Syntax

Note the syntactic differences regarding the use of parentheses and commas.

The DATE, DOUBLE PRECISION, INT [ EGER ], REAL, SMALLINT, and TIME
data type syntax is identical for dictionaries and UniVerse SQL.

You can specify the SQL data type for any column, real or virtual, in a UniVerse file.
You need not specify the SQL data type for any column of a table defined by the
CREATE TABLE or CREATE VIEW statement, but you may want to specify the
SQL data type for other columns in the table (such as I-descriptors) that are not
defined in the SICA. You cannot modify the SQL data type for columns defined in
the SICA, and UniVerse ignores the dictionary definitions for these columns. For
more information about the SICA and UniVerse tables, see UniVerse SQL Adminis-
tration for DBAs manual and the UniVerse SQL User Guide.

Length of Character String Data

In JDBC, every character column has either a fixed length or a maximum length. This
column length is called its precision and is reported in the COLUMNS rowset.

The precision of a character column is determined from one of the following:

4-24
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

„ For a column in a UniVerse file, the precision is defined by the data type
specified in the DATATYPE field of the column’s dictionary definition. If
the data type is not defined, the FORMAT field of the dictionary defines the
precision.
„ For a column defined by a CREATE TABLE or ALTER TABLE statement,
the precision is defined by the column definition, which is stored in the
table’s SICA.
„ For a column in a view, the precision is defined by the CREATE VIEW
statement or by the precision of the column specified by the SELECT
statement that creates the view.
„ For a column added to a table’s dictionary (such as an I-descriptor), the
precision is defined by the data type specified in the DATATYPE field of the
column’s dictionary definition. If the data type is not defined, the FORMAT
field of the dictionary defines the precision.

You can use the HS.SCRUB utility to examine a file’s data and write appropriate data
types in the DATATYPE field of the dictionary definitions for character-string
columns. For information about HS.SCRUB, see “Validating and Fixing Tables and
Files” on page 4-26.

The actual number of characters in a UniVerse character column can be greater than
its precision. JDBC retrieves such extra characters, up to a limit. The number of bytes
of character data that JDBC retrieves from a character column is the smallest of:

„ The number of bytes of data the column actually contains.

„ The number of bytes of data that UCI can fetch. This is controlled by the
UCI configuration parameters MAXFETCHBUFF and
MAXFETCHCOLS, defined in the uci.config file.

If your fetch buffer is not large enough to hold all the character data that the JDBC
application retrieves, it generates a truncation warning.

The actual number of characters in a UniVerse character column can be less than its
precision. Unlike some DBMSs, UniVerse does not automatically pad CHAR(n)
columns on the right with spaces. If you insert the value "abc " (with two trailing
spaces) into a CHAR(10) column, the column contains only five characters, not 10.

Your application and data source must agree on a consistent way to treat trailing
spaces in a CHAR(n) column. Generally, it is better to treat CHAR(n) columns as if
they were VARCHAR columns with no space padding.

4-25 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Empty-Null Mapping
UniVerse files use empty strings in much the same way tables use null values. Unfor-
tunately, empty strings in numeric or date columns cause data conversion errors in
JDBC, making these columns almost inaccessible to some JDBC applications. To
make files with empty values accessible to JDBC applications, the UniVerse server
provides empty-null mapping, converting empty values in UniVerse files to null
values in JDBC application buffers, and vice versa.

To activate empty-null mapping for a UniVerse table or file, add an X-descriptor

named @EMPTY.NULL to the dictionary. To turn off empty-null mapping, delete the
@EMPTY.NULL entry from the dictionary.

The third selection (Activate access to files in an account) on the UniVerse Server
Administration menu enables empty-null mapping in all files in the account by
creating @EMPTY.NULL dictionary entries.

Validating and Fixing Tables and Files

Use the HS.SCRUB utility to scan data in a table or file and fix data and dictionary
problems that can cause SQL and JDBC difficulties. The HS.SCRUB utility performs
the following tasks:

„ Reports data anomalies.

„ Saves a select list of record IDs of problem records.
„ Writes appropriate data types in the DATATYPE field of the dictionary’s
column definitions.
„ Adjusts dictionary entries to accommodate bad data, such as nonnumeric
values in numeric, date, and time columns, which can lead to adjusting the
column type to CHARACTER.
„ Adds an @EMPTY.NULL record to the dictionary.
„ Adds an @SELECT record to the dictionary.
„ Fixes the data in the file, optionally saving a copy of the original file.

The @EMPTY.NULL Record

HS.SCRUB adds an @EMPTY.NULL record to the table or file dictionary if all the
following conditions are met:

4-26
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

„ The dictionary does not already include an @EMPTY.NULL record.

„ The data contains empty values.
„ Modification of the dictionary is enabled (FIX, AUTOFIX, AUTOFIX
DICT).

For information about empty-null mapping, see “Empty-Null Mapping” on page 4-

26.

The @SELECT Record

HS.SCRUB adds an @SELECT record to the file dictionary (but not to a table
dictionary) if both of the following conditions are met:

„ The dictionary does not already include an @ or @SELECT record.

„ Modification of the dictionary is enabled (FIX, AUTOFIX, AUTOFIX
DICT).

For information about @SELECT records, see UniVerse SQL Administration for
DBAs.

Running the HS.SCRUB Utility

To run the HS.SCRUB utility, choose the fifth selection (Run HS.SCRUB on a
File/Table) on the UniVerse Server Administration menu, or use the HS.SCRUB
command described in the next section.

If you use the HS.SCRUB utility on a File/Table selection, the system prompts you
to enter either the full path of the UniVerse account (for Windows platforms, start
with the drive letter, such as D:) or the account name as listed in the UV.ACCOUNT
file. Press ENTER to see a list of UniVerse accounts whose files have been made
visible to JDBC.

Next the system prompts you to enter the name of the table or file you want to analyze
or change. After you enter a file name, the system prompts you to enter the mode of
operation. Enter one of the following at the Mode prompt:

„ To generate a report without modifying the table or file, press ENTER

„ FIX
„ AUTOFIX
„ AUTOFIX DICT

4-27 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

„ AUTOFIX DATA

The next subsection describes these modes.

Using the HS.SCRUB Command

To use the HS.SCRUB command, log to the UniVerse account containing the table
or file you want to analyze.

The syntax of the HS.SCRUB command is as follows:

HS.SCRUB file name [ FIX | AUTOFIX [ DICT | DATA ] ]

where file name is the name of the file or table to analyze.

The following table describes each parameter of the syntax.

Parameter Description

FIX Puts HS.SCRUB in interactive mode, in which the system prompts you to
resolve any anomalies following the analysis.

AUTOFIX Puts HS.SCRUB in automatic mode; anomalies are corrected with the
default action that would have been presented to the user. If you do not
specify DICT or DATA with the AUTOFIX option, HS.SCRUB resolves
anomalies in both the data file or table and its dictionary.

DICT Indicates that HS.SCRUB resolves only those anomalies associated with
the file’s or table’s dictionary.

DATA Indicates that HS.SCRUB resolves only those anomalies associated with
the file’s or table’s data.
HS.SCRUB Parameters

When neither FIX nor AUTOFIX is specified, HS.SCRUB only reports anomalies.
No data or dictionary items are modified.

4-28
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

Scalar Functions
The following table lists UniVerse JDBC support of scalar functions.

Function Supported

String ASCII No

CHAR No

CONCAT Yes

DIFFERENCE No

INSERTa Yes

LCASE Yes

LEFT Yes

LENGTH Yes

LOCATE No

LTRIM Yes

REPEAT No

REPLACE No

RIGHT1 Yes

RTRIM Yes

SOUNDEX No

SPACE No

SUBSTRING Yes

UCASE Yes

Numeric ABS No

ACOS No
UniVerse JDBC Support of Scalar Functions

4-29 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Function Supported

ASIN No

ATAN No

ATAN2 No

CEILING No

COS No

COT No

DEGREES Yes

EXP No

FLOOR No

LOG No

LOG10 No

MOD No

PI Yes

POWER No

RADIANS Yes

RAND No

ROUND No

SIGN No

SIN No

SQRT No

TAN No

TRUNCATE No

Time and Date CURDATE No

CURTIME No
UniVerse JDBC Support of Scalar Functions (Continued)

4-30
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH04.fm
3/8/10

Function Supported

DAYNAME No

DAYOFMONTH No

DAYOFWEEK No

DAYOFYEAR No

HOUR No

MINUTE No

MONTH No

MONTHNAME No

NOW No

QUARTER No

SECOND No

TIMESTAMPADD No

TIMESTAMPDIFF No

WEEK No

YEAR No

System DATABASE Yes

IFNULL No

USER Yes

Conversion CONVERTb Yes

UniVerse JDBC Support of Scalar Functions (Continued)

4-31 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

a. INSERT and RIGHT may evaluate their arguments more than once,
consequently you cannot use a parameter marker as an argument to
these functions, and you must watch out for side effects if you use an I-
descriptor.
b. UniVerse JDBC supports the same conversions that UniVerse SQL
CAST supports.

An example of a call to a scalar function is as follows:

SELECT * FROM UV_SCHEMA
WHERE SCHEMA_NAME = {fn DATABASE()};

JDBC implies that no scalar functions can take an arithmetic expression or a

parameter marker as an argument. UniVerse JDBC tolerates violations of this rule,
but in the future it may optionally trap them and generate an error message.

4-32
 Chapter

Programming with JDBC

5
Loading the IBM JDBC Driver for UniData and UniVerse. . . . . . 5-3
Creating a Connection . . . . . . . . . . . . . . . . . 5-4
Format of Database URLs . . . . . . . . . . . . . . 5-5
Accessing Database MetaData . . . . . . . . . . . . . . 5-7
Querying the Database . . . . . . . . . . . . . . . . . 5-8
Mapping Data Types . . . . . . . . . . . . . . . . . 5-9
Data Conversion . . . . . . . . . . . . . . . . . 5-10
Handling Errors . . . . . . . . . . . . . . . . . . . 5-11
Handling Transactions . . . . . . . . . . . . . . . . . 5-12
Isolation Levels . . . . . . . . . . . . . . . . . . 5-13
JDBC 2.0 Optional Package Support . . . . . . . . . . . . 5-14
Tuning the Connection Pool . . . . . . . . . . . . . . 5-18
Restrictions and Limitations . . . . . . . . . . . . . . . 5-22
Unsupported Data Types . . . . . . . . . . . . . . . 5-22
Unsupported Methods . . . . . . . . . . . . . . . . 5-22

:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05TOC.fm

C:\Program
Files\Adobe\FrameMaker8\UniData

This chapter explains the IBM-specific information you need to use the IBM JDBC
Driver for UniData and UniVerse to connect to your database.

5-2
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

Loading the IBM JDBC Driver for UniData

and UniVerse
To load the IBM JDBC Driver for UniData and UniVerse, use the Class.forName()
method, passing it the value com.ibm.u2.UniJDBCDriver, as shown in the following
example:
try {
Class.forName(“com.ibm.u2.jdbc.UniJDBCDriver”);
} catch (Exception e) {
}

The Class.forName() method loads the IBM implementation of the Driver class,
UniJDBCDriver. The UniJDBCDriver class then creates an instance of the driver and
registers it with the DriverManager class.

Once you load the IBM JDBC Driver for UniData and UniVerse, you are ready to
connect to the database.

5-3 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Creating a Connection
To create a connection to a UniData or UniVerse database, use the
DriverManager.getConnection() method. This method creates a Connection object,
which is later used to create and send SQL statements to the database, and then
process the results.

The DriverManager class keeps track of the available drivers and handles connection
requests between appropriate drivers and databases. The url parameter of the getCon-
nection() method is a database URL that specifies the host name, port number and
account path. These are the required properties defined in the table below. An
optional second parameter to the getConnection() method, property, is the property
list defined in the following table.

The full syntax of the connection string is defined as:

jdbc:ibm-u2://<host>[:<port>]/<account>[[;name=value]...]

The required properties for the connection string are listed in the following table.

Database
URL
Variable Description

host The host machine where the database server is running.

port The port number of the UniRPC server running on the host. The
default port number is 31438.

account The full path to the account.

5-4
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

The optional connection properties for the connection string are listed in the
following table.

Database URL
Variable Description

user User logon name for host system.

password Password for logon.

dbmstype The database type to which you will be connecting. Must be UniData or
UniVerse. The default setting is UniVerse.

network Specifies the network used to access the sql server. The default value is
TCP/IP.

proxyhost The host name for the proxy server being used.

proxyport The port number of the proxy server. The default value is 31448.

Format of Database URLs

There are two ways to connect to a SQL server through the IBM JDBC Driver for
UniData and UniVerse. The first method is defined by the JDBC 1.0 specification,
and uses the URL connection string.

The following example shows a database URL that connects to the UniData demo
account, demo:
try {
Class.forName("com.ibm.u2.jdbc.UniJDBCDriver");
String sUrl = "jdbc:ibm-
u2://localhost/d:/ibm/ud60/demo;dbmstype=UNIDATA";
Connection con = DriverManager.getConnection(sUrl,"user",
"pass");
}
catch (Exception e) {

5-5 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Another method of creating a JDBC connection is through the use of a DataSource

object and is defined by the JDBC 2.0 Optional Package API. The two DataSource
interfaces are com.ibm.u2.jdbcx.UniJDBCDataSource and
com.ibm.u2.jdbcx.UniJDBCPoolConnectionDataSource. For more information
on these types of JDBC connections, see “JDBC 2.0 Optional Package Support” on
page 5-14.

5-6
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

Accessing Database MetaData

To access information about a UniData or UniVerse database, use the JDBC API
DatabaseMetaData interface. The IBM JDBC Driver for UniData and UniVerse
supports most of the DatabaseMetaData methods.

For some methods returning a ResultSet object, for example Database-

MetaData.getTables(), UniData and UniVerse handle system tables differently, and
thus will return different results.

In UniVerse, the getSchemas() method returns the schema names available in the
database information and which accounts are accessible by JDBC. In UniData, the
getSchemas() method returns the owner of every table in the account to which you
are connected.

The getTables() method contains SQL tables and database files which are accessible
by JDBC.

The getColumns() method contains columns of SQL tables and files which are acces-
sible by JDBC.

Note: When calling DatabaseMetaData methods on UniData Files, null should be

passed as the parameter whenever a schema name is requested.
When calling DatabaseMetaData methods on UniVerse Files, null should be passed
as the parameter whenever a schema name is requested. For UniVerse Tables, where
schemas are supported, the name of the schema should be used.

See “Restrictions and Limitations” on page 5-22 for a list of methods that are not
supported by the IBM JDBC Driver for UniData and UniVerse and should not be
used in your Java program.

5-7 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Querying the Database

The IBM JDBC Driver for UniData and UniVerse complies with the JDBC API
specification for sending queries to a database and retrieving the results. The driver
supports most of the methods of the Statement, PreparedStatement,
CallableStatement, ResultSet, and ResultSetMetaData interfaces.

The Statement interface allows most of the eligible SQL statements to be executed,
according to the syntax of SQL statements supported by UniData and UniVerse SQL
servers. See “Restrictions and Limitations” on page 5-22 for a list of the unsupported
Statement methods

The PreparedStatement interface allows users to prepare a statement once and

subsequently execute it multiple times. The interface can take parameters presented
by ’?’, and must be bound with specific values before execution.

The CallableStatement interface is implemented by a UniData or UniVerse BASIC

program. Each callable statement can have multiple parameters with type INPUT,
OUTPUT, and INPUT_OUTPUT. The return value can be carried in the OUTPUT
and INPUT_OUTPUT parameters. All of the parameters are of VARCHAR data
type.

The ResultSetMetaData interface will return each column’s definition. For a map of
supported data types between UniData, UniVerse, and JDBC, see “Mapping Data
Types” on page 5-9.

5-8
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

Mapping Data Types

This section discusses mapping issues between data types defined in a Java program,
and the data types supported by the UniData and UniVerse database servers. In
particular, it covers the following two topics:

„ Mapping between JDBC API data types and UniData and UniVerse data
types.
„ ResultSet.getXXX() methods supported by the IBM JDBC Driver for
UniData and UniVerse.

The following table shows the UniData and UniVerse data types to which each JDBC
API data type maps. See “Restrictions and Limitations” on page 5-22 for a list of
unsupported data types.

JDBC API Data Type UniData Data Type UniVerse Data Type

BIGINT INTEGER INTEGER

BIT BIT BIT

CHAR CHAR CHAR

DATE DATE DATE

DECIMAL DECIMAL DECIMAL

DOUBLE DOUBLE PRECISION DOUBLE PRECISION

FLOAT FLOAT FLOAT

LONGVARCHAR VARCHAR VARCHAR

NUMERIC INTEGER NUMERIC

REAL REAL REAL

SMALLINT SMALLINT INTEGER

TIME TIME TIME

TINYINT INTEGER INTEGER

VARCHAR VARCHAR VARCHAR

5-9 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Data Conversion
Since UniData and UniVerse store all of their data types as strings, their respective
SQL servers will translate any column data that does not match to their data types to
NULL. Using a UniData or UniVerse data type that maps to a JDBC data type, such
as BIT, will work as long as the data stays within the range of the SQL server’s data
range.

Date and Time Data

When retrieving date and time data with ResultSet.getDate() and
ResultSet.getTime(), the data being retrieved should be stored in the database in
internal date or time format. If the data is instead stored as a date or time string, it is
safest to retrieve the data with ResultSet.getString(), and explicitly convert it to a
Date or Time object as needed.

5-10
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

Handling Errors
IBM JDBC Driver for UniData and UniVerse error and warning messages (excep-
tions) can be generated from both the server and driver (client) sides.

All of the server side errors and warning messages contain SQLSTATE code and
original message text, whereas the driver side errors and warning messages may
contain vendor code, SQLSTATE code, and original message text.

Note: Run-time errors occuring in UniBasic and UVBasic subroutines are not
automatically propogated to the JDBC application. You can define an out parameter
for the subroutine to notify the JDBC application of UniBasic or UVBasic errors. The
JDBC application can then check the status of this paramter after calling the
subroutine.

5-11 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Handling Transactions
When you create a new Connection object, autocommit is set to true by default. This
means that when a statement is sent to the server, a COMMIT statement is automat-
ically executed. The autocommit mode can be set to true or false by calling the
Connection.setAutoCommit() method. The syntax is as follows:
Connection.setAutoCommit(true)
Connection.setAutoCommit(false)

If autocommit is set to false, the IBM JDBC Driver for UniData and UniVerse starts
a new transaction as soon as the next statement is sent to the database server. This
transaction lasts until a COMMIT or ROLLBACK statement is issued by the user. If
the user has already started a transaction by executing setAutoCommit(false), and
then calls setAutoCommit(false) again, the existing transaction continues unchanged.
In order for the connection to the database or database server to be dropped, the Java
program must explicitly terminate the transaction by issuing either a COMMIT or a
ROLLBACK statement.

While inside a transaction, if the Java program sets autocommit mode on, the IBM
JDBC Driver for UniData and UniVerse will roll back the current transaction before
it actually turns autocommit mode on.

If a COMMIT statement is sent to a database that has been created with logging, and
autocommit mode is on, the database server returns the error -255 : not in
transaction . This is true whether the statement was sent with the
Connection.commit() method, or directly with an SQL statement. This is true
because there is currently no user transaction started.

When you explicitly send a COMMIT statement to the database server in a database
created in ANSI mode, the statement commits an empty transaction. The system does
not return an error since the database server automatically starts a transaction before
it executes the statement. This is true if there is no user transaction currently open.

5-12
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

Isolation Levels
UniData and Universe support the following isolation levels:

„ TRANSACTION_READ_UNCOMMITTED
„ TRANSACTION_READ_COMMITTED
„ TRANSACTION_REPEATABLE_READ
„ TRANSACTION_SERIALIZABLE

When changing the isolation level in manual transaction mode, the new isolation
level does not take effect until the current transaction has been committed or rolled
back.

5-13 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

JDBC 2.0 Optional Package Support

The IBM JDBC Driver for UniData and UniVerse supports the following interfaces
defined in the JDBC Extended Optional Package:
javax.sql.DataSource
javax.sql.ConnectionPoolDataSource

Their corresponding implementation class names are:

com.ibm.u2.jdbcx.UniJDBCDataSource
com.ibm.u2.jdbcx.UniJDBCConnectionPoolDataSource

Connecting Through a DataSource Object

Connecting through a DataSource object is the preferred means of establishing a
connection to a data source. For information about how and why to use a DataSource
object, see the JDBC 2.0 Standard Extension Specification provided by Sun Micro-
systems, available from the following Web site:
http://java.sun.com/products/jdk/1.2

In order to create a connection with the DataSource object, you must have the appro-
priate JNDI (Java Naming and Directory Interface) installed and configured for your
application. For more information on JNDI, go to:

http://java.sun.com/products/jndi

In the following steps for creating a DataSource object:

„ The variable ds refers to a DataSource object.

„ The logical name for the DataSource object is myDS.

5-14
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

Deploying a DataSource Object

Complete the following steps to deploy a DataSource object:

1. Instantiate a UniJDBCDataSource object.

2. Configure the parameters appropriately:

ds.setServerHost(“myServer”);
ds.setAccount(“myAccount”);
3. Now you must register the DataSource object by using the JNDI to map a
logical name to the DataSource object.

Context ctx = new InitialContext();

ctx.bind(“myDS”, ds);

Now you can use the DataSource Object as shown in the following example:
Connection con = null;

try {

Context ctx = new InitialContext();

DataSource ds = (DataSource)ctx.lookup("myDS");

con = ds.getConnection("user", "pass");

// use the connection

} catch (Exception e) {

// exception-handling code

} finally {

if (con != null) con.close();

5-15 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Connecting Through a Pooled Connection DataSource

Object
Certain JDBC applications may demand higher performance and scalability. This can
be achieved by obtaining your connection to the database server through a
DataSource object that references a ConnectionPoolDataSource object. By using this
interface, the IBM JDBC Driver for UniData and UniVerse keeps a connection in a
pool to be reused, rather than returning it to the database server to be terminated.
Whenever a connection is requested, the driver obtains the connection from the pool,
avoiding the overhead of having the server close and reopen a connection.

In situations where the application services frequent connection requests, using the
ConnectionPoolDataSource can significantly improve performance.

For more information on implementing the DataSource or

ConnectionPoolDataSource objects, see the JDBC 2.0 Standard Extension Specifi-
cation provided by Sun Microsystems, available at:
http://java.sun.com/products/jdk/1.2/docs/guide/jdbc/index.html

In the following steps for creating a ConnectionPoolDataSource object:

„ The variable cpds refers to a ConnectionPoolDataSource object.

„ The JNDI logical name for the ConnectionPoolDataSource object is
myCPDS.
„ The variable ds refers to a DataSource object.
„ The logical name for the DataSource object is DS_Pool
Note: When a UniVerse JDBC connection is closed by an application, there is a slight
delay in releasing the license associated with that connection. As a result, brief
intervals may occur where there are more "consumed licenses" than there are active
connections. On rare occasions, if the UniVerse system is running near the number
of total available lincenses, this may cause a connection attempt to be refused, if a
previously consumed license has not yet been released.

5-16
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

Deploying a ConnectionPoolDataSource Object

Complete the following steps to deploy a ConnectionPoolDataSource object:

1. Instantiate a UniJDBCConnectionPoolDataSource object.

2. Configure the following parameters appropriately:
cpds.setServerHost(“myServer”);
cpds.setAccount(“myAccount”);
cpds.setUser(“myUsername”);
cpds.setPassword(“myPassword”);
cpds.setUniJDBCCPMMaxConnections(-1);
cpds.setUniJDBCCPMInitPoolsize(0);
cpds.setUniJDBCCPMMinPoolsize(2);
cpds.setUniJDBCCPMMaxPoolsize(8);
cpds.setUniJDBCCPMServiceInterval(100);
cpds.setUniJDBCCPMAgelimit(7200);
cpds.setUniJDBCCPMMinAgelimit(3600);

Note: The username and Password parameters must be set in order for the
InitPoolsize parameter to take affect.
3. Now you must register the ConnectionPoolDataSource object by using the
JNDI to map a logical name to the ConnectionPoolDataSource object.
Context ctx = new InitialContext();
ctx.bind(“myCPDS”cpds,);
4. Now instantiate a UniJDBCDataSource object.
5. You must associate this DataSource object with the logical name you regis-
tered for the ConnectionPoolDataSource object:
ds.setDataSourceName(“myCPDS”);
6. Register the DataSource object using the JNDI interface:
Context ctx = new InitialContext();
ctx.bind(“DS_Pool”,ds);

5-17 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Now you can use the DataSource object, as shown in the following example:
Connection con = null;

try {

Context ctx = new InitialContext();

DataSource ds = (DataSource)ctx.lookup("DS_pool");

con = ds.getConnection("user", "pass");

// use the connection

} catch (Exception e) {

// exception-handling code

} finally {

if (con != null) con.close();

Once a pooled DataSource is properly registered, as demonstrated in the previous

step-by-step example, the syntax for using it is the same as for a non-pooled
datasource. It is however, important to explicitly close the connection in a final block
to ensure that the connection is returned to the pool after use.

Tuning the Connection Pool

There are eight properties that you can change to adjust how Connection Pooling
works in your application. The application programmer or an administrator can
change these values in the deployment phase. These properties are defined in the
following table.

5-18
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

The following table lists the available parameters for the

ConnectionPoolDataSource object.

Defaul
Parameter Description t

IBM_CPM_INIT_POOLSIZE Allows you to specify the initial number 0

of connections to be allocated for the
pool when the ConnectionPoolData-
Source object is first instantiated and
the pool is initialized. This parameter
should be set if your application
requires numerous connections when
the ConnectionPoolDataSource object
is first instantiated. To obtain the value,
call getUniJDBCCPMInitPoolSize().
To set the value, call
setUniJDBCCPMInitPoolSize().

IBM_CPM_MAX_CONNECTIONS This parameter enables you to specify -1

the maximum number of physical
connections that the DataSource object
can obtain from the server, excluding
those returned to the server. A setting of
-1 allows for an unlimited number of
connections. To obtain the value, call
getUniJDBCCPMMaxConnections().
To set the value, call setUniJDBCCPM-
MaxConnections(int limit).

IBM_CPM_MINPOOLSIZE This parameter enables you to specify 0

the minimum number of connections to
maintain in the pool. See the
UniJDBC_CPM_MIN_AGELIMIT
parameter for information about what to
do when this minimum number of
connections kept in the pool has
exceeded the age limit. To obtain the
value, call getUniJDBCCPMMin-
PoolSize(). To set the value, call
setUniJDBCCPMMinPoolSize(int
min).

5-19 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Defaul
Parameter Description t

IBM_CPM_MAX_POOLSIZE This parameter enables you to specify None

the maximum number of connections to
maintain in the pool. When the pool
reaches this size, all connections are
returned to the server. To obtain the
value, call getUniJDBCCPMMax-
PoolSize(). To set the value, call
etUniJDBCCPMMaxPoolSize(int
max).

IBM_CPM_AGELIMIT This parameter enables you to specify -1

the time, in seconds, that a free
connection is kept in the free connection
pool. A setting of -1 allows the connec-
tions to be retained until the client
terminates. To obtain the value, call
getUniJDBCCPMAgeLimit(). To set
the value, call setUniJDBCCPMAge-
Limit(long limit).

5-20
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

Defaul
Parameter Description t

IBM_CPM_MIN_AGELIMIT This parameter enables you to specify -1

the additional time, in seconds, that a
connection in the free connection pool
will be retained when no connection
requests have been received. A setting
of -1 allows a minimum of connections
to be retained until the client terminates.
To obtain the value, call getUniJDBC-
CPMMinAgeLimit(). To set the value,
call setUniJDBCCPMAgeMin-
Limit(long limit).

IBM_CPM_SERVICE_INTERVAL This parameter enables you to specify 50

the pool service frequency, in milli-
seconds. Pool service activity includes
adding free connections if the number of
free connections falls below the
minimum value and removing free
connections. To obtain the value, call
getUniJDBCCPMServiceInterval(). To
set the value, call getUniJDBCCPMSer-
viceInterval (long interval).

IBM_CPM_PC_REFRESH_MODE This parameter enables you to specify 11

the connection refreshing mode when a
pooled connection is returned to the
pool. There are 3 settings for this
parameter.
1 - The connection will be reused. With
this setting, the statements on the
connection will be closed, and trans-
action mode will be switched back to
"auto". However, be aware that other
properties are inherited, such as BASIC
"COMMON" variables.
3 - The connection will be closed and
reestablished.
11 - The connection will be closed and
reestablished by a helper thread.

5-21 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Restrictions and Limitations

Unsupported Data Types

The IBM JDBC Driver for UniData and UniVerse does not support the following data
types:

„ java.sql.Types.ARRAY
„ java.sql.Types.BINARY
„ java.sql.Types.BLOB
„ java.sql.Types.CLOB
„ java.sql.Types.DISTINCT
„ java.sql.Types.JAVA_OBJECT
„ java.sql.Types.LONGVARBINARY
„ java.sql.Types.NULL
„ java.sql.Types.REF
„ java.sql.Types.STRUCT
„ java.sql.Types.TIMESTAMP
„ java.sql.Types.VARBINARY

Unsupported Methods
The IBM JDBC Driver for UniData and UniVerse does not support the following
JDBC functionality:

The following methods of the Statement interface are not supported.

„ Statement.addBatch(string)
„ Statement.cancel()
„ Statement.clearBatch()
„ Statement.executeBatch()

The following methods of the PreparedStatement interface are not supported.

„ PreparedStatement.addBatch()

5-22
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH05.fm
3/8/10

„ PreparedStatement.setArray(int, java.sql.Array)
„ PreparedStatement.setBlob(int, java.sql.Blob)
„ PreparedStatement.setCharacterStream(int, java.io.Reader)
„ PreparedStatement.setClob(int, java.sql.Clob)
„ PreparedStatement.setRef(int, java.sql.Ref)

The following methods of the Connection interface are not supported.

„ Connection.getCatalog
„ Connection.setCatalog
„ Connection.getTypeMap
„ Connection.setTypeMap

The following methods of the DatabaseMetaData interface are not supported.

„ DatabaseMetaData.getProcedures(String catalog, String

schemaPattern,String procedureNamePattern)
„ DatabaseMetaData.getProcedureColumns(String catalog,
StringschemaPattern, String procedureNamePattern, String
columnNamePattern)
„ DatabaseMetaData.getCatalogs()
„ DatabaseMetaData.getColumnPrivileges(String catalog, String schema,
String table, String columnNamePattern)
„ DatabaseMetaData.getTablePrivileges(String catalog, String schemaP-
attern, String tableNamePattern)
„ DatabaseMetaData.getBestRowIdentifier(String catalog, String schema,
String table, int scope, boolean nullable)
„ DatabaseMetaData.getVersionColumns(String catalog, String schema,
String table)
„ DatabaseMetaData.getImportedKeys(String catalog, String schema, String
table)
„ DatabaseMetaData.getExportedKeys(String catalog, String schema, String
table)
„ DatabaseMetaData.getCrossReference(String primaryCatalog, String
primarySchema, String primaryTable, String foreignCatalog, String
foreignSchema, String foreignTable)

5-23 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

„ DatabaseMetaData.getIndexInfo(String catalog, String schema, String

table, boolean unique, boolean approximate)
„ DatabaseMetaData.getUDTs(String catalog, String schemaPattern, String
typeNamePattern, int[] types)

The following methods of the ResultSet interface are not supported.

„ ResultSet.getCharacterStream(int)
„ ResultSet.getCharacterStream(String)

The following method of the ResultSetMetaData interface is not supported.

„ ResultSetMetadata.getColumnClassName(int)

5-24
 Chapter

JDBC Scrollable Cursors

6
JDBC Scrollable Cursors . . . . . . . . . . . . . . . . 6-2
Creating a Scrollable Cursor . . . . . . . . . . . . . . 6-2
Methods for Moving the Cursor. . . . . . . . . . . . . 6-3
Connection URL Parameters . . . . . . . . . . . . . . . 6-4
Example . . . . . . . . . . . . . . . . . . . . . 6-5

:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH06TOC.fm

C:\Program
Files\Adobe\FrameMaker8\UniData

JDBC Scrollable Cursors

When you execute an SQL statement on the server that has the potential of returning
multiple rows, these rows are presented to the Java application one row at a time in
an object called ResultSet. Prior to this release, UniVerse and UniData could only
view these rows in a forward, sequential manner, from the first row to the last row.

At this release, scrollable cursors are introduced in UniJDBC. Scrollable cursors

allow the program to move forward or backward, or jump directly to a specific row.
UniVerse and UniData do not allow updates to the ResultSet. The ResultSet is a
snapshot taken at the time the statement was executed.

Creating a Scrollable Cursor

The following three UniJDBC statements can return a result set:
Statement stmt =
con.createStatement(resultSetType,resultSetConcurrency)

PreparedStatement pstmt =
con.prepareStatement(sql,resultSetType,resultSetConcurrency)

CallableStatement cstmt =
con.prepareCall(sql,resultSetType,resultSetConcurrency)

resultSetType
The resultSetType parameter can be one of the types described in the following table.

resultSetType Description

TYPE_FORWARD_ONLY The cursor can only move forward in the result set.

TYPE_SCROLL_INSENSITIVE The resultSet is scrollable, but insensitive to

changes made by others.
resultSetType

resultSetConcurrency
The only valid valid for the resultSetConcurrency parameter is
CONCUR_READ_ONLY, for a resultSet object that can not be updated.

6-2
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH06.fm
3/8/10

Methods for Moving the Cursor

You can call one of the methods described in the following table to move the cursor.

Method Description

srs.afterLast() Move the cursor to the position after the last row, so the
following previous() method points to the last row.

srs.beforeFirst() Moves the cursor to the position before the first row.

srs.next() Moves the cursor to the next row.

srs.previous() Moves the cursor to the previous row.

srs.absolute(n) Moves the cursor to the n row.

srs.absolute(-n) Moves the cursor back n rows from the end of the result set.

srs.relative(n) Moves the cursor forward n rows from the current cursor
position.

srs.relative(-n) Moves the cursor back n rows from the current cursor position.
Methods for Moving the Cursor

Determining the Cursor Position

Use the following method to determine the cursor position:
rowNum = srs.getRow()

6-3 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Connection URL Parameters

The following table describes the connection URL parameters for use with scrollable
cursors.

Parameter Description

MAX_SCROLLABLE_CACHE_ The maximum number of rows the scrollable

CURSOR_ROWS cache can contain. If you specify
-1, there can be unlimited rows.

MAX_SCROLLABLE_CACHE_ In kilobytes, the maximum memory space one

CURSOR_SPACE_IN_MEMORY scrollable cache can consume. If you specify 0,
all rows must be stored on disk. If you specify -
1, the space is unlimited. The default is 256K.

MAX_SCROLLABLE_CACHE In kilobytes, the maximum disk space one scrol-

CURSOR_SPACE_ON_DISK lable cursor can consume. If you specify 0, no
disk storing is allowed. If you specify -1, the
space is unlimited. The default value is 0.

TEMPORARY_DIRECTORY The temporary directory for the URL parameter.

If you do not specify this parameter, UniJDBC
uses the value defined in the system properties
sheet.
Connection URL Parameters

6-4
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH06.fm
3/8/10

Example
The following example illustrates creating a scrollable cursor.
========================================================================
Example - Select
========================================================================
import java.sql.*;

public class UniJDBCExSelect {

public static void main(String[] argv) {

try {
String MyHost = "localhost";
String MyAccount = "HS.SALES";
String userid = "username";
String passwd = "password";

// generate URL
String url = "jdbc:ibm-u2://" + MyHost + "/" + MyAccount ;

// Load driver and connect to server

Class.forName("com.ibm.u2.jdbc.UniJDBCDriver");
Connection con = DriverManager.getConnection(url, userid, passwd);

// Execute an SQL Query

String sql = "select @ID, CITY, STATE, ZIP, PHONE CUSTOMER ORDER";
Statement stmt = con.createStatement(
ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY);

ResultSet rs = stmt.executeQuery ( sql );

rs.absolute(10);
System.out.println(“pos = “ + rs.getRow + “@ID = “
+ rs.getString(@ID”));

rs.relative(-2) ;
System.out.println(“pos = “ + rs.getRow + “@ID = “
+ rs.getString(@ID”));

rs.next() ;
System.out.println(“pos = “ + rs.getRow + “@ID = “
+ rs.getString(@ID”));

rs.previous() ;
System.out.println(“pos = “ + rs.getRow + “@ID = “
+ rs.getString(@ID”));

rs.close() ;
stmt.close() ;
System.out.println( “End of SC query test.”) ;
con.close();

}
catch ( SQLException e ) {
System.out.println("Ex-Message :" + e.getMessage());

6-5 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

System.out.println("Ex-Code :" + e.getErrorCode()) ;

System.out.println("Ex-SQLState:" + e.getSQLState() );
System.out.println("Ex-Next :" + e.getNextException() );
e.printStackTrace() ;
}
catch ( Exception e) {
System.out.println("Exception caught:"+e) ;
e.printStackTrace() ;
}
}
}

6-6
 Chapter

IBM for UniData and

UniVerse JDBC Code 7
Examples
UniJDBC Example Program - List File . . . . . . . . . . . . 7-3
UniJDBC Short Examples . . . . . . . . . . . . . . . . 7-7
Select Example . . . . . . . . . . . . . . . . . . 7-7
UniJDBC Prepared Statement Example . . . . . . . . . . 7-9
UniJDBC Callable Statement Example . . . . . . . . . . 7-10
UniJDBC DatabaseMetaData Example . . . . . . . . . . 7-11

:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH07TOC.fm

C:\Program
Files\Adobe\FrameMaker8\UniData

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

This chapter provides some sample programs with comments throughout, describing
the use of some of the methods of the IBM JDBC Driver for UniData and UniVerse.

This Chapter contains the following sections:

„ “UniJDBC Example Program - List File” - This program shows a step-by-

step example for connecting to the server, loading the driver and executing
several SQL statements.
„ “UniJDBC Short Examples” - This section contains examples for executing
an SQL statement, a prepared SQL statement, a Callable statement and how
to access DataBase Metadata,.

These examples are available in the \jdbc\samples directory of the UniDK

installation.

7-2
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH07.fm
3/8/10

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

UniJDBC Example Program - List File

import java.sql.*;
import java.io.*;

/**
* A sample program to test the IBM JDBC Driver for UniData and UniVerse.
*/
public class jdbcsample {

public static void main(String[] argv)

{
try {
BufferedReader in = new BufferedReader(new
InputStreamReader(System.in));

System.out.println("\n\nThis is the JDBC sample program");

System.out.println("~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~");
System.out.println("\nThis program connects to a U2 account (schema)");
System.out.println("and lists the CUSTOMER file.");

//---------------------------
// Connect to the U2 server
//---------------------------

// Obtain path to the server account

System.out.println("\nEnter destination account name: ");
String account = in.readLine();

// Get user name

System.out.println("Enter valid server User Name: ");
String userid = in.readLine();

// Get password
System.out.println("Enter password for user: ");
String passwd = in.readLine();

// Get host machine name

System.out.println("Enter host machine name(localhost or machine
name): ");
String host = in.readLine();

// Get database type

System.out.println("Enter the dbmstype: UNIDATA or UNIVERSE");
String dbmstype = in.readLine();

// generate URL
String url = "jdbc:ibm-
u2://"+host+"/"+account+"?dbmstype="+dbmstype;

//Load driver and connect to server

Class.forName("com.ibm.u2.jdbc.UniJDBCDriver");
Connection con = DriverManager.getConnection(url, userid, passwd);

System.out.println("\n*--- Connection successful ---*\n");

//------------------------

7-3 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

// First example
//------------------------
System.out.println("1. Select from CUSTOMER -----------------------
-");
testQuery( con ) ;

//------------------------
// Second example
//------------------------
System.out.println("2. Transaction test ---------------------------
-");
testRollback( con ) ;

con.close();
} catch ( SQLException e ) {
System.out.println("Ex-Message :" + e.getMessage());
System.out.println("Ex-Code :" + e.getErrorCode()) ;
System.out.println("Ex-SQLState:" + e.getSQLState());
System.out.println("Ex-Next :" + e.getNextException());
e.printStackTrace() ;
System.gc();
} catch ( Exception e) {
System.out.println("Exception caught:"+e) ;
e.printStackTrace() ;
}
}

/**
* Select something from CUSTOMER table.
* @param con The JDBC connection object.
*/
public static void testQuery(Connection con)
throws SQLException
{
Statement stmt = con.createStatement();
String sql = "select @ID, CITY, STATE, ZIP, PHONE from CUSTOMER";

// Execute the SELECT statement

ResultSet rs = stmt.executeQuery(sql);

// Get result of first five records

System.out.println("list selected columns for the first five
records:");
int i = 1;
while (rs.next() && i < 6)
{
System.out.println("\nRecord "+ i +" :");
System.out.println("@ID : " + rs.getString(1));
System.out.println("CITY :" + rs.getString(2));
System.out.println("STATE :" + rs.getString(3));
System.out.println("ZIP : " + rs.getString(4));
System.out.println("PHONE :" + rs.getString(5));
i++;
}

rs.close();
stmt.close() ;
System.out.println("\n*--- QUERY test is done successful ---*\n");
}

7-4
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH07.fm
3/8/10

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

/**
* Transaction test. It will:
* (1) begin a transaction
* (2) update STATE of CUSTOMER to CA
* (3) re-read that record to show the update
* (4) roll the transaction back
* (5) re-read that record to show original value
* @param con The JDBC connection object.
*/
static public void testRollback(Connection con)
throws SQLException
{
System.out.println("\nThis section will:");
System.out.println("(1) begin a transaction");
System.out.println("(2) update STATE of CUSTOMER to CA");
System.out.println("(3) re-read that record to show the update");
System.out.println("(4) roll the transaction back");
System.out.println("(5) re-read that record to show original value\n");

// Set isolation level and start a transaction

con.setTransactionIsolation(
java.sql.Connection.TRANSACTION_READ_COMMITTED);
con.setAutoCommit( false );

// Update the CUSTOMER file

String sql = "update CUSTOMER set STATE = ’CA’ where @ID = ’2’;";
Statement stmt = con.createStatement();

int rows = stmt.executeUpdate(sql);

System.out.println(rows + " rows updated.");

stmt.close();

//Read the record to show the update

String lsql = "SELECT STATE FROM CUSTOMER WHERE @ID = ?;";
PreparedStatement pstmt = con.prepareCall(lsql);

pstmt.setString(1, "2");
ResultSet rs = pstmt.executeQuery() ;

while (rs.next())
{
System.out.println("updated STATE is " + rs.getString(1));
}
pstmt.close();

//Rollback the transation

con.rollback() ;
System.out.println("\nTransaction is rollbacked.\n");

//re-Read the record to show original value

pstmt = con.prepareCall(lsql);

pstmt.setString(1, "2");
rs = pstmt.executeQuery() ;

while (rs.next())
{
System.out.println("original STATE is " + rs.getString(1));
}

7-5 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

pstmt.close() ;

System.out.println("\n*--- Transaction test is done successful ---

*\n");
}
}

7-6
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH07.fm
3/8/10

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

UniJDBC Short Examples

Select Example
========================================================================
Example - Select
========================================================================

import java.sql.*;

public class UniJDBCExSelect {

public static void main(String[] argv) {

try {
String MyHost = "localhost";
String MyAccount = "HS.SALES";
String userid = "username";
String passwd = "password";

// generate URL
String url = "jdbc:ibm-u2://" + MyHost + "/" + MyAccount ;

// Load driver and connect to server

Class.forName("com.ibm.u2.jdbc.UniJDBCDriver");
Connection con = DriverManager.getConnection(url, userid, passwd);

// Execute an SQL Query

Statement stmt = con.createStatement();
String sql = "select @ID, CITY, STATE, ZIP, PHONE from CUSTOMER";
ResultSet rs = stmt.executeQuery(sql);
int i = 1;
while (rs.next()) {
System.out.println("\nRecord "+ i +" :");
System.out.println("@ID : " + rs.getString("@ID"));
System.out.println("CITY :" + rs.getString("CITY"));
System.out.println("STATE :" + rs.getString("STATE"));
System.out.println("ZIP : " + rs.getString("ZIP"));
System.out.println("PHONE :" + rs.getString("PHONE"));
i++;
}
rs.close();
stmt.close() ;
con.close();
}
catch ( SQLException e ) {
System.out.println("Ex-Message :" + e.getMessage());
System.out.println("Ex-Code :" + e.getErrorCode()) ;
System.out.println("Ex-SQLState:" + e.getSQLState() );
System.out.println("Ex-Next :" + e.getNextException() );
e.printStackTrace() ;
}
catch ( Exception e) {
System.out.println("Exception caught:"+e) ;
e.printStackTrace() ;
}

7-7 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

}
}

7-8
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH07.fm
3/8/10

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

UniJDBC Prepared Statement Example

========================================================================
Example - Prepared Statement
========================================================================

import java.sql.*;

public class UniJDBCExPrepStmt {

public static void main(String[] argv) {

try {
String MyHost = "localhost";
String MyAccount = "HS.SALES";
String userid = "username";
String passwd = "password";

// generate URL
String url = "jdbc:ibm-u2://" + MyHost + "/" + MyAccount ;

// Load driver and connect to server

Class.forName("com.ibm.u2.jdbc.UniJDBCDriver");
Connection con = DriverManager.getConnection(url, userid, passwd);

// Execute prepared SQL statement

String sql = "update CUSTOMER set CITY= ?,STATE= ?, "
+ "PHONE = ’(603)555-3212’ WHERE @ID = ’1’";
PreparedStatement stmt = con.prepareCall(sql);
stmt.setString(1, "Concord");
stmt.setString(2, "NH");
int rows = stmt.executeUpdate() ;
System.out.println( rows + " rows updated.") ;
stmt.close() ;
con.close();
}
catch ( SQLException e ) {
System.out.println("Ex-Message :" + e.getMessage());
System.out.println("Ex-Code :" + e.getErrorCode()) ;
System.out.println("Ex-SQLState:" + e.getSQLState() );
System.out.println("Ex-Next :" + e.getNextException() );
e.printStackTrace() ;
}
catch ( Exception e) {
System.out.println("Exception caught:"+e) ;
e.printStackTrace() ;
}
}
}

7-9 Using the IBM JDBC Driver for UniData and UniVerse
C:\Program
Files\Adobe\FrameMaker8\UniData

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

UniJDBC Callable Statement Example

========================================================================
Example - Callable Statement
========================================================================

import java.sql.*;

public class UniJDBCExCallStmt {

public static void main(String[] argv) {

try {
String MyHost = "localhost";
String MyAccount = "HS.SALES";
String userid = "username";
String passwd = "password";

// generate URL
String url = "jdbc:ibm-u2://" + MyHost + "/" + MyAccount ;

// Load driver and connect to server

Class.forName("com.ibm.u2.jdbc.UniJDBCDriver");
Connection con = DriverManager.getConnection(url, userid, passwd);

// Execute Callable statement

// Note: HS.OLEDBACCTS is a globally calaloged BASIC program,
// and so requires the asterisk in front of the name.
// locally catalogued programs do not require the asterisk
String sql = "call *HS.OLEDBACCTS(?)";
CallableStatement stmt = con.prepareCall( sql );
stmt.registerOutParameter(1, -1);
ResultSet rs = stmt.executeQuery();
System.out.println( "HS.OLEDBACCTS returns : " + stmt.getString( 1
));
rs.close();
stmt.close();
con.close();
}
catch ( SQLException e ) {
System.out.println("Ex-Message :" + e.getMessage());
System.out.println("Ex-Code :" + e.getErrorCode()) ;
System.out.println("Ex-SQLState:" + e.getSQLState() );
System.out.println("Ex-Next :" + e.getNextException() );
e.printStackTrace() ;
}
catch ( Exception e) {
System.out.println("Exception caught:"+e) ;
e.printStackTrace() ;
}
}
}

7-10
C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\JDBC\JDBCCH07.fm
3/8/10

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

UniJDBC DatabaseMetaData Example

========================================================================
Example - DatabaseMetaData
========================================================================

import java.sql.*;

public class UniJDBCExGetPrimKeys {

public static void main(String[] argv) {

try {
String MyHost = "localhost";
String MyAccount = "HS.SALES";
String MySchema = null;
String MyTable = "CUSTOMER";
String userid = "username";
String passwd = "password";

// generate URL
String url = "jdbc:ibm-u2://" + MyHost + "/" + MyAccount ;

// Load driver and connect to server

Class.forName("com.ibm.u2.jdbc.UniJDBCDriver");
Connection con = DriverManager.getConnection(url, userid, passwd);

// get Database Metadata

DatabaseMetaData dbmetadata = con.getMetaData();
ResultSet rs = dbmetadata.getPrimaryKeys(null, MySchema, MyTable);
while( rs.next()) {
for( int i=1; i<=5; i++ ) {
System.out.println("Column["+i+"]="+rs.getString(i)) ;
}
}
rs.close();
con.close();
}
catch ( SQLException e ) {
System.out.println("Ex-Message :" + e.getMessage());
System.out.println("Ex-Code :" + e.getErrorCode()) ;
System.out.println("Ex-SQLState:" + e.getSQLState() );
System.out.println("Ex-Next :" + e.getNextException() );
e.printStackTrace() ;
}
catch ( Exception e) {
System.out.println("Exception caught:"+e) ;
e.printStackTrace() ;
}
}
}

7-11 Using the IBM JDBC Driver for UniData and UniVerse