You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafodion.apache.org by db...@apache.org on 2016/05/05 23:39:34 UTC
[03/22] incubator-trafodion git commit: JDBCT$ Programmer's Reference
Guide
JDBCT$ Programmer's Reference Guide
New guide. Added missing SPJ Guide file.
Project: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/commit/c2116c2b
Tree: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/tree/c2116c2b
Diff: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/diff/c2116c2b
Branch: refs/heads/master
Commit: c2116c2b3dd857be5cd28160e0f18d2daca73140
Parents: e5dcfc1
Author: Gunnar Tapper <gt...@esgyn.local>
Authored: Fri Apr 29 00:13:43 2016 -0600
Committer: Gunnar Tapper <gt...@esgyn.local>
Committed: Fri Apr 29 00:13:43 2016 -0600
----------------------------------------------------------------------
docs/jdbct4ref_guide/pom.xml | 297 +++
.../src/asciidoc/_chapters/about.adoc | 174 ++
.../src/asciidoc/_chapters/accessing.adoc | 910 ++++++++
.../asciidoc/_chapters/avoiding_mismatch.adoc | 106 +
.../src/asciidoc/_chapters/code_examples.adoc | 56 +
.../src/asciidoc/_chapters/compliance.adoc | 386 ++++
.../src/asciidoc/_chapters/introduction.adoc | 53 +
.../src/asciidoc/_chapters/lob_data.adoc | 553 +++++
.../src/asciidoc/_chapters/lob_management.adoc | 288 +++
.../src/asciidoc/_chapters/messages.adoc | 1943 ++++++++++++++++++
.../asciidoc/_chapters/properties_detail.adoc | 959 +++++++++
.../asciidoc/_chapters/properties_overview.adoc | 245 +++
.../src/asciidoc/_chapters/tracing_logging.adoc | 195 ++
docs/jdbct4ref_guide/src/asciidoc/index.adoc | 74 +
docs/jdbct4ref_guide/src/images/lob_tables.jpg | Bin 0 -> 16241 bytes
.../src/resources/acknowledgements.txt | 38 +
.../src/resources/source/blob_example.java | 202 ++
.../src/resources/source/clob_example.java | 200 ++
.../src/asciidoc/_chapters/sample_spjs.adoc | 6 +-
docs/spj_guide/src/asciidoc/index.adoc | 3 +-
.../src/resources/source/create_demo.sql | 14 +
21 files changed, 6698 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/c2116c2b/docs/jdbct4ref_guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/jdbct4ref_guide/pom.xml b/docs/jdbct4ref_guide/pom.xml
new file mode 100644
index 0000000..413710e
--- /dev/null
+++ b/docs/jdbct4ref_guide/pom.xml
@@ -0,0 +1,297 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <!--
+* @@@ START COPYRIGHT @@@
+*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied. See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*
+* @@@ END COPYRIGHT @@@
+-->
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.apache.trafodion</groupId>
+ <artifactId>jdbct4-ref-guide</artifactId>
+ <version>${env.TRAFODION_VER}</version>
+ <packaging>pom</packaging>
+ <name>Trafodion JDBC Type 4 Programmer's Reference Guide</name>
+ <description>This document describes how to use the JDBC Type 4 Driver.</description>
+ <url>http://trafodion.incubator.apache.org</url>
+ <inceptionYear>2015</inceptionYear>
+
+ <parent>
+ <groupId>org.apache.trafodion</groupId>
+ <artifactId>trafodion</artifactId>
+ <version>1.3.0</version>
+ <relativePath>../../pom.xml</relativePath>
+ </parent>
+
+
+ <licenses>
+ <license>
+ <name>The Apache Software License, Version 2.0</name>
+ <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+ <distribution>repo</distribution>
+ <comments>A business-friendly OSS license</comments>
+ </license>
+ </licenses>
+
+ <organization>
+ <name>Apache Software Foundation</name>
+ <url>http://www.apache.org</url>
+ </organization>
+
+ <issueManagement>
+ <system>JIRA</system>
+ <url>http://issues.apache.org/jira/browse/TRAFODION</url>
+ </issueManagement>
+
+ <scm>
+ <connection>scm:git:http://git-wip-us.apache.org/repos/asf/incubator-trafodion.git</connection>
+ <developerConnection>scm:git:https://git-wip-us.apache.org/repos/asf/incubator-trafodion.git</developerConnection>
+ <url>https://git-wip-us.apache.org/repos/asf?p=incubator-trafodion.git</url>
+ <tag>HEAD</tag>
+ </scm>
+
+ <ciManagement>
+ <system>Jenkins</system>
+ <url>https://jenkins.esgyn.com</url>
+ </ciManagement>
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <asciidoctor.maven.plugin.version>1.5.2.1</asciidoctor.maven.plugin.version>
+ <asciidoctorj.pdf.version>1.5.0-alpha.11</asciidoctorj.pdf.version>
+ <asciidoctorj.version>1.5.4</asciidoctorj.version>
+ <rubygems.prawn.version>2.0.2</rubygems.prawn.version>
+ <jruby.version>9.0.4.0</jruby.version>
+ </properties>
+
+ <repositories>
+ <repository>
+ <id>rubygems-proxy-releases</id>
+ <name>RubyGems.org Proxy (Releases)</name>
+ <url>http://rubygems-proxy.torquebox.org/releases</url>
+ <releases>
+ <enabled>true</enabled>
+ </releases>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </repository>
+ </repositories>
+
+ <dependencies>
+ <dependency>
+ <groupId>rubygems</groupId>
+ <artifactId>prawn</artifactId>
+ <version>${rubygems.prawn.version}</version>
+ <type>gem</type>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.jruby</groupId>
+ <artifactId>jruby-complete</artifactId>
+ <version>${jruby.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctorj</artifactId>
+ <version>${asciidoctorj.version}</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>de.saumya.mojo</groupId>
+ <artifactId>gem-maven-plugin</artifactId>
+ <version>1.0.10</version>
+ <configuration>
+ <!-- align JRuby version with AsciidoctorJ to avoid redundant downloading -->
+ <jrubyVersion>${jruby.version}</jrubyVersion>
+ <gemHome>${project.build.directory}/gems</gemHome>
+ <gemPath>${project.build.directory}/gems</gemPath>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>initialize</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-resources-plugin</artifactId>
+ <version>2.7</version>
+ <configuration>
+ <encoding>UTF-8</encoding>
+ <attributes>
+ <generateReports>false</generateReports>
+ </attributes>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <version>${asciidoctor.maven.plugin.version}</version>
+ <dependencies>
+ <dependency>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctorj-pdf</artifactId>
+ <version>${asciidoctorj.pdf.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctorj</artifactId>
+ <version>${asciidoctorj.version}</version>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <sourceDirectory>${basedir}/src</sourceDirectory>
+ </configuration>
+ <executions>
+ <execution>
+ <id>generate-html-doc</id>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <phase>site</phase>
+ <configuration>
+ <doctype>book</doctype>
+ <backend>html5</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <outputDirectory>${basedir}/target/site</outputDirectory>
+ <requires>
+ <require>${basedir}/../shared/google-analytics-postprocessor.rb</require>
+ </requires>
+ <attributes>
+ <!-- Location of centralized stylesheet -->
+ <stylesheet>${basedir}/../shared/trafodion-manuals.css</stylesheet>
+ <project-version>${env.TRAFODION_VER}</project-version>
+ <project-name>Trafodion</project-name>
+ <project-logo>${basedir}/../shared/trafodion-logo.jpg</project-logo>
+ <project-support>user@trafodion.incubator.apache.org</project-support>
+ <docs-url>http://trafodion.incubator.apache.org/docs</docs-url>
+ <build-date>${maven.build.timestamp}</build-date>
+ <google-analytics-account>UA-72491210-1</google-analytics-account>
+ </attributes>
+ </configuration>
+ </execution>
+ <execution>
+ <id>generate-pdf-doc</id>
+ <phase>site</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <doctype>book</doctype>
+ <backend>pdf</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <outputDirectory>${basedir}/target</outputDirectory>
+ <attributes>
+ <pdf-stylesdir>${basedir}/../shared</pdf-stylesdir>
+ <pdf-style>trafodion</pdf-style>
+ <icons>font</icons>
+ <pagenums/>
+ <toc/>
+ <idprefix/>
+ <idseparator>-</idseparator>
+ <project-version>${env.TRAFODION_VER}</project-version>
+ <project-name>Trafodion</project-name>
+ <project-logo>${basedir}/../shared/trafodion-logo.jpg</project-logo>
+ <project-support>user@trafodion.incubator.apache.org</project-support>
+ <docs-url>http://trafodion.incubator.apache.org/docs</docs-url>
+ <build-date>${maven.build.timestamp}</build-date>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ <!-- Rename target/site/index.pdf to client-install-guide.pdf -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <version>1.8</version>
+ <inherited>false</inherited>
+ <executions>
+ <execution>
+ <id>populate-release-directories</id>
+ <phase>post-site</phase>
+ <configuration>
+ <target name="Populate Release Directories">
+ <!-- The website uses the following organization for the docs/target/docs directory:
+ - To ensure a known location, the base directory contains the LATEST version of the web book and the PDF files.
+ - The know location is docs/target/docs/<document>
+ - target/docs/<version>/<document> contains version-specific renderings of the documents.
+ - target/docs/<version>/<document> contains the PDF version and the web book. The web book is named index.html
+ -->
+ <!-- Copy the PDF file to its target directories -->
+ <copy file="${basedir}/target/index.pdf" tofile="${basedir}/../target/docs/jdbct4ref_guide/JDBCT4_Reference_Guide.pdf" />
+ <copy file="${basedir}/target/index.pdf" tofile="${basedir}/../target/docs/${project.version}/jdbct4ref_guide/JDBCT4_Reference_Guide.pdf" />
+ <!-- Copy the Web Book files to their target directories -->
+ <copy todir="${basedir}/../target/docs/jdbct4ref_guide">
+ <fileset dir="${basedir}/target/site">
+ <include name="**/*.*"/> <!--All sub-directories, too-->
+ </fileset>
+ </copy>
+ <copy todir="${basedir}/../target/docs/${project.version}/jdbct4ref_guide">
+ <fileset dir="${basedir}/target/site">
+ <include name="**/*.*"/> <!--All sub-directories, too-->
+ </fileset>
+ </copy>
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+ <!-- Included because this is required. No reports are generated. -->
+ <reporting>
+ <excludeDefaults>true</excludeDefaults>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ <version>2.8</version>
+ <reportSets>
+ <reportSet>
+ <reports>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ </plugins>
+ </reporting>
+
+ <distributionManagement>
+ <site>
+ <id>trafodion.incubator.apache.org</id>
+ <name>Trafodion Website at incubator.apache.org</name>
+ <!-- On why this is the tmp dir and not trafodion.incubator.apache.org, see
+ https://issues.apache.org/jira/browse/HBASE-7593?focusedCommentId=13555866&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13555866
+ -->
+ <url>file:///tmp</url>
+ </site>
+ </distributionManagement>
+</project>
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/c2116c2b/docs/jdbct4ref_guide/src/asciidoc/_chapters/about.adoc
----------------------------------------------------------------------
diff --git a/docs/jdbct4ref_guide/src/asciidoc/_chapters/about.adoc b/docs/jdbct4ref_guide/src/asciidoc/_chapters/about.adoc
new file mode 100644
index 0000000..69bf91d
--- /dev/null
+++ b/docs/jdbct4ref_guide/src/asciidoc/_chapters/about.adoc
@@ -0,0 +1,174 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied. See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+= About This Document
+
+This document describes how to use the {project-name} JDBC Type 4 Driver (subsequently called the Type 4 driver).
+This driver provides Java applications running on a foreign platform with JDBC access to {project-name}.
+
+
+== Intended Audience
+This {project-name} JDBC Type 4 Driver Programmer's Reference Guide is for
+experienced Java programmers who want to access {project-name} SQL
+databases.
+
+This document assumes you are already familiar with the Java
+documentation, which is located at http://docs.oracle.com/en/java/.
+
+== New and Changed Information
+This is a new manual.
+
+== Notation Conventions
+This list summarizes the notation conventions for syntax presentation in this manual.
+
+* UPPERCASE LETTERS
++
+Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required.
++
+```
+SELECT
+```
+
+* lowercase letters
++
+Lowercase letters, regardless of font, indicate variable items that you supply. Items not enclosed in brackets are required.
++
+```
+file-name
+```
+
+<<<
+* [ ] Brackets
++
+Brackets enclose optional syntax items.
++
+```
+DATETIME [start-field TO] end-field
+```
++
+A group of items enclosed in brackets is a list from which you can choose one item or none.
++
+The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines.
++
+For example:
++
+```
+DROP SCHEMA schema [CASCADE]
+DROP SCHEMA schema [ CASCADE | RESTRICT ]
+```
+
+* { } Braces
++
+Braces enclose required syntax items.
++
+```
+FROM { grantee [, grantee ] ... }
+```
++
+A group of items enclosed in braces is a list from which you are required to choose one item.
++
+The items in the list can be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines.
++
+For example:
++
+```
+INTERVAL { start-field TO end-field }
+{ single-field }
+INTERVAL { start-field TO end-field | single-field }
+```
+* | Vertical Line
++
+A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces.
+```
+{expression | NULL}
+```
+
+* … Ellipsis
++
+An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times.
++
+```
+ATTRIBUTE[S] attribute [, attribute] ...
+{, sql-expression } ...
+```
++
+An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times.
++
+For example:
++
+```
+expression-n ...
+```
+
+* Punctuation
++
+Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown.
++
+```
+DAY (datetime-expression)
+@script-file
+```
++
+Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must type as shown.
++
+For example:
++
+```
+"{" module-name [, module-name] ... "}"
+```
+
+<<<
+* Item Spacing
++
+Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma.
++
+```
+DAY (datetime-expression) DAY(datetime-expression)
+```
++
+If there is no space between two items, spaces are not permitted. In this example, no spaces are permitted between the period and any other items:
++
+```
+myfile.sh
+```
+
+* Line Spacing
++
+If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line.
++
+This spacing distinguishes items in a continuation line from items in a vertical list of selections.
++
+```
+match-value [NOT] LIKE _pattern
+ [ESCAPE esc-char-expression]
+```
+
+<<<
+== Comments Encouraged
+We encourage your comments concerning this document. We are committed to providing documentation that meets your
+needs. Send any errors found, suggestions for improvement, or compliments to {project-support}.
+
+Include the document title and any comment, error found, or suggestion for improvement you have concerning this document.
+
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/c2116c2b/docs/jdbct4ref_guide/src/asciidoc/_chapters/accessing.adoc
----------------------------------------------------------------------
diff --git a/docs/jdbct4ref_guide/src/asciidoc/_chapters/accessing.adoc b/docs/jdbct4ref_guide/src/asciidoc/_chapters/accessing.adoc
new file mode 100644
index 0000000..7a6a647
--- /dev/null
+++ b/docs/jdbct4ref_guide/src/asciidoc/_chapters/accessing.adoc
@@ -0,0 +1,910 @@
+////
+/**
+ *@@@ START COPYRIGHT @@@
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * @@@ END COPYRIGHT @@@
+ */
+////
+
+[[accessing-project-name-sql-databases]]
+= Accessing {project-name} SQL Databases
+
+[[data-sources]]
+== Data Sources
+
+The term *data source* logically refers to a database or other data
+storage entity. A JDBC (client) data source is physically a Java object that
+contains properties such as the URL of the physical database, the
+catalog to use when connecting to this database, and the schema to use
+when connecting to this database. The JDBC data source also contains
+methods for obtaining a JDBC connection to the underlying database.
+
+[[jdbc-data-source-client-side]]
+=== JDBC Data Source (client-side)
+
+All JDBC data source classes implement either the `javax.sql.DataSource`
+interface or the `javax.sql.ConnectionPoolDataSource` interface. The Type
+4 driver data source classes are `org.trafodion.t4jdbc.HPT4DataSource` and
+`org.trafodion.t4jdbc.HPT4ConnectionPoolDataSource`. (These classes are
+defined by the JDBC 3.0 specification.)
+
+Typically, a user or system administrator uses a tool to create a data
+source, and then registers the data source by using a JNDI service
+provider. At run time, a user application typically retrieves the data
+source through JNDI, and uses the data source's methods to establish a
+connection to the underlying database.
+
+A DataSource object maps to an instance of a database. In the Type 4
+driver product, the DataSource object acts as an interface between the
+application code and the database and enables connection with an DCS
+data source.
+
+[[security]]
+== Security
+
+Clients connect to the {project-name} platform with a valid user name
+and ID, using standard JDBC 3.0 APIs. An application can make multiple
+connections using different user IDs, and creating different Connection
+objects.
+
+The Type 4 driver provides for user name and password authentication.
+The password is encrypted with a proprietary algorithm provided by DCS.
+
+NOTE: There is no secure wire communication such as SSL provided for the
+communication between Type 4 driver and the {project-name} platform.
+
+<<<
+[[connection-by-using-the-datasource-interface]]
+== Connection by Using the DataSource Interface
+
+The `javax.sql.DataSource` interface is the preferred way to establish a
+connection to the database because this interface enhances the application
+portability. Portability is achieved by allowing the application to use a
+logical name for a data source instead of providing driver-specific information
+in the application. A logical name is mapped to a `javax.sql.DataSource`
+object through a naming service that uses the Java Naming and Directory
+Interface (JNDI). Using this DataSource method is particularly recommended
+for application servers.
+
+When an application requests a connection by using the `getConnection` method
+in the `DataSource`, then the method returns a `Connection` object.
+
+A `DataSource` object is a factory for `Connection` objects. An object that
+implements the `DataSource` interface is typically registered with a JNDI
+service provider.
+
+[[overview-of-tasks-to-deploy-datasource-objects]]
+=== Overview of Tasks to Deploy DataSource Objects
+
+Before an application can connect to a `DataSource` object, typically
+the system administrator deploys the `DataSource` object so that
+the application programmers can start using it.
+
+Data source properties are usually set by a system administrator using
+a GUI tool as part of the installation of the data source. Users to
+the data source do not get or set properties. Management tools can get
+at properties by using introspection.
+
+Tasks involved in creating and registering a database object are:
+
+1. Creating an instance of the `DataSource` class.
+2. Setting the properties of the `DataSource` object.
+3. Registering the `DataSource` object with a naming service that uses
+the Java Naming and Directory Interface (JNDI) API.
+
+An instance of the `DataSource` class and the `DataSource` object
+properties are usually set by an application developer or system
+administrator using a GUI tool as part of the installation of the
+data source. If you are using an installed data source, then see
+<<programmatically-creating-an-instance-of-the-datasource-class, Programmatically Creating an Instance of the DataSource Class>>.
+
+The subsequent topics show an example of performing these tasks programmatically.
+
+For more information about using data sources, see https://docs.oracle.com/javase/tutorial/jdbc/basics/sqldatasources.html[Connecting with DataSource Objects]
+in the https://docs.oracle.com/javase/tutorial/jdbc/TOC.html[JDBC(TM) Database Access: Table of Contents] documentation
+or other information available in the field.
+
+<<<
+[[datasource-object-properties]]
+=== DataSource Object Properties
+
+A `DataSource` object has properties that identify and describe the actual
+data source that the object represents. These properties include such
+information as the URL (the primary IP address or host name of the database),
+the database schema and catalog names, the location of the database server,
+the name of the database, and so forth.
+
+For details about Type 4 driver properties that you can use with the `DataSource` object, see <<type-4-driver-properties,Type 4 Driver Properties>>.
+
+[[programmatically-creating-an-instance-of-the-datasource-class]]
+=== Programmatically Creating an Instance of the DataSource Class
+
+A JDBC application can set `DataSource` properties programmatically and
+register with a DataSource object. To get or set `DataSource` object properties programmatically, use the
+appropriate getter or setter methods on the `HPT4DataSource` object or
+the `HPT4ConnectionPoolDataSource` object.
+
+*Example*
+
+[source, java]
+----
+HPT4DataSource temp = new HPT4DataSource() ;
+temp.setCatalog( "Seabase" ) ;
+----
+
+In the following example, the code fragment illustrates the methods that a
+`DataSource` object `ds` needs to include if the object supports the
+`serverDataSource` property `ds.setServerDataSource( "my_server_datasource" )`.
+In this example, the code shows setting properties for the `HPT4DataSource` object
+to use the Type 4 driver to access a {project-name} database:
+
+[source, java]
+----
+HPT4DataSource ds = new HPT4DataSource() ;
+
+ds.setUrl( "jdbc:hpt4jdbc://<primary IP addr or host name>:18650/" );
+ds.setCatalog( "Seabase" ) ;
+ds.setSchema( "myschema" ) ;
+ds.setUser( "gunnar" ) ;
+ds.setPassword( "my_userpassword" ) ;
+
+// Properties relevant for Type 4 connection pooling.
+// Set ds.setMaxPoolSize(-1) for turning OFF connection pooling
+ds.setMaxPoolSize( "10000" ) ;
+ds.setMinPoolSize( "1000" ) ;
+
+// Properties relevant for Type 4 statement pooling.
+// Set ds.setMaxStatement(0) for turning statement pooling OFF
+// Statement pooling is enabled only when connection pooling is
+// enabled.
+ds.setMaxStatements( "7000" ) ;
+----
+
+This technique essentially builds a properties file. For more information,
+see <<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+[[programmatically-registering-the-datasource-object]]
+=== Programmatically Registering the DataSource Object
+
+In the following example, the code shows how to register, programmatically,
+the `HPT4DataSource` object `ds` that was created using the preceding code with JNDI.
+
+[source, java]
+----
+java.util.Hashtable env = new java.util.Hashtable() ;
+env.put( Context.INITIAL_CONTEXT_FACTORY, "Factory class name here" ) ;
+
+javax.naming.Context ctx = new javax.naming.InitialContext( env ) ;
+ctx.rebind( "myDataSource", ds ) ;
+----
+
+[[retrieving-a-datasource-instance-by-using-jndi-and-connecting-to-the-data-source]]
+=== Retrieving a DataSource Instance by Using JNDI and Connecting to the Data Source
+Typically, the JDBC application looks up the data source JNDI name from a
+context object. Once the application has the `DataSource` object, then the application
+does a `getConnection()` call on the data source and gets a connection.
+
+The steps that JDBC application does to connect to and use the data source associated
+with the database are listed below together with the application code to perform the
+operation.
+
+1. Import the packages.
++
+[source, java]
+----
+import javax.naming.* ;
+import java.sql.* ;
+import javax.sql.DataSource ;
+----
+
+2. Create the initial context.
++
+[source, java]
+----
+Hashtable env = new Hashtable() ;
+env.put( Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.fscontext.RefFSContextFactory" ) ;
+try
+{
+ Context ctx = new InitialContext( env ) ;
+}
+catch( ... )
+{
+...
+}
+----
++
+<<<
+3. Look up the JNDI name associated with the data source `myDataSource`, where `myDataSource`
+is the logical name that will be associated with the real-world data source - server.
++
+[source, java]
+----
+DataSource ds = (DataSource)ctx.lookup( "myDataSource" ) ;
+----
+
+4. Create the connection using the data source.
++
+[source, java]
+----
+con = ds.getConnection() ;
+----
+
+5. Do work with the connection. The following statements are just a simple example.
++
+[source, java]
+----
+stmt = con.createStatement() ;
+try
+{
+ stmt.executeUpdate( "drop table tdata" ) ;
+}
+catch ( SQLException e ) {}
+----
+
+[[specifying-the-properties-file-that-configures-the-data-source]]
+=== Specifying the Properties File that Configures the Data Source
+
+To use the properties file method to configure a `DataSource` object, the properties
+file must exist on disk and contain the `property_name=property_value` pairs that
+configure the data source.
+See <<creating-and-using-a-properties-file, Creating and Using a Properties File>>
+for more information about creating this file.
+
+When the JDBC application makes the connection, then the application should
+pass the properties file as a command-line parameter:
+
+```
+java -Dhpt4jdbc.properties=<path of properties file on disk>
+```
+
+[[connection-by-using-the-drivermanager-class]]
+== Connection by Using the DriverManager Class
+
+The `java.sql.DriverManager` class is widely used to get a connection, but
+is less portable than the `DataSource` class. The `DriverManager` class
+works with the Driver interface to manage the set of drivers loaded.
+When an application issues a request for a connection using the
+`DriverManager.getConnection` method and provides a URL, the `DriverManager`
+finds a suitable driver that recognizes this URL and obtains a database
+connection using that driver.
+
+`org.trafodion.t4jdbc.HPT4Driver` is the Type 4 driver class that
+implements the `java.sql.Driver` interface.
+
+<<<
+[[loading-and-registering-the-driver]]
+=== Loading and Registering the Driver
+
+Before connecting to the database, the application loads the Driver
+class and registers the Type 4 driver with the DriverManager class in
+one of the following ways:
+
+* Specifies the Type 4 driver class in the `-Djdbc.drivers` option in the
+command line of the Java program:
++
+```
+-Djdbc.drivers=org.trafodion.t4jdbc.HPT4Driver
+```
+
+* Uses the `Class.forName` method programmatically within the application:
++
+[source, java]
+----
+Class.forName("org.trafodion.t4jdbc.HPT4Driver")
+----
+
+* Adds the Type 4 driver class to the `java.lang.System` property
+`jdbc.drivers` property within the application:
++
+```
+jdbc.drivers=org.trafodion.t4jdbc.HPT4Driver
+```
+
+<<<
+[[establishing-the-connection]]
+=== Establishing the Connection
+
+The `DriverManager.getConnection` method accepts a string containing a
+Type 4 driver URL. The JDBC URL for the Type 4 driver is
+
+```
+jdbc:hpt4jdbc://<ip addr or host name>:3700/[:][property=value[;property2=value2]...]
+```
+
+[cols="40%,60%", options="header"]
+|===
+| Parameter | Usage
+| `<ip addr or host name>` | The primary IP address or host name for the {project-name} database.
+| `37800` | The port number for the {project-name} SQL database.
+| `property = value` and `property2=value2` | Specifies a Type 4 driver property name-property value pair. The pairs must be separated by a
+semicolon (`;`). For example, `T4LogLevel=ALL;T4LogFile=temp1.log`.
+|===
+
+For information about the properties file, see <<type-4-driver-properties,Type 4 Driver Properties>>.
+
+To establish a connection, the JDBC application can use this code:
+
+[source, java]
+----
+Class.forName( "org.trafodion.t4jdbc.HPT4Driver" ) ; //loads the driver
+
+String url = "jdbc:hpt4jdbc://<database primary IP address>:37800/"
+
+Connection con = DriverManager.getConnection( url, "userID", "Passwd" ) ;
+----
+
+The variable con represents a connection to the data source that can be
+used to create and execute SQL statements.
+
+[[guidelines-for-connections-using-the-driver-manager]]
+=== Guidelines for Connections Using the Driver Manager
+
+* The Type 4 driver defines a set of properties that you can use to
+configure the driver. For detailed information about these properties,
+see <<type-4-driver-properties,Type 4 Driver Properties>>.
+* Java applications can specify the properties in these ways (listed in
+the order of precedence):
++
+1. Using the `java.util.Properties` parameter in the `getConnection` method of DriverManager class.
+
+2. Using the database URL in the `DriverManager.getconnection` method, where the URL is:
++
+```
+jdbc:hpt4jdbc://<ip addr or host name>:37800/:property=value
+```
++
+`<ip addr or host name>` is the primary IP address or host name for the {project-name} database.
++
+<<<
+3. Using a properties file for the JDBC driver. The properties file is
+passed as a command-line parameter. The format to enter the properties
+file in the command line is:
++
+```
+-Dhpt4jdbc.properties=<path of properties file on disk>
+```
++
+For example, `-Dhpt4jdbc.properties=C:\temp\t4props`
++
+For information about the properties file, see <<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+4. Using JDBC properties with the `-D` option in the command line. If
+used, this option applies to all JDBC connections using the
+`DriverManager` within the Java application. The format in the command
+line is:
++
+```
+-Dhpt4jdbc.property_name=<property value>
+```
++
+For example, `-Dhpt4jdbc.maxStatements=1024`
+
+<<<
+[[connection-pooling]]
+== Connection Pooling
+
+The Type 4 driver provides an implementation of connection pooling,
+where a cache of physical database connections are assigned to a client
+session and reused for the database activity. If connection pooling is
+active, connections are not physically closed. The connection is
+returned to its connection pool when the `Connection.close()` method is
+called. The next time a connection is requested by the client, the
+driver will return the pooled connection, and not a new physical
+connection.
+
+* The connection pooling feature is available when the JDBC application
+uses either the `DriverManager` class or `DataSource` interface to obtain a
+JDBC connection. The connection pool size is determined by the
+`maxPoolSize` property value and `minPoolSize` property value.
+
+* By default, connection pooling is disabled. To enable connection
+pooling, set the maxPoolSize property to an integer value greater than 0
+(zero).
+
+* Manage connection pooling by using these Type 4 driver properties:
+
+** `maxPoolSize` under <<maxpoolsize-property, maxpoolsize Property>>
+** `minPoolSize` under <<minpoolsize-property, minPoolSize Property>>
+** `initialPoolSize` under <<initialpoolsize-property, initialPoolSize Property>>
+** `maxStatements` under <<maxstatements-property, maxStatements Property>>
+
+* When used with the DriverManager class, the Type 4 driver has a
+connection-pool manager that determines which connections are pooled
+together by a unique value for these combination of properties:
++
+```
+url
+catalog
+schema
+username
+password
+serverDataSource
+```
++
+Therefore, connections that have the same values for the combination of
+a set of properties are pooled together.
++
+NOTE: The connection-pooling property values used at the first
+connection of a given combination are effective throughout the life of
+the process. An application cannot change any of these property values
+after the first connection for a given combination.
+
+<<<
+[[statement-pooling]]
+== Statement Pooling
+
+The statement pooling feature allows applications to reuse the
+PreparedStatement object in the same way that they can reuse a
+connection in the connection pooling environment. Statement pooling is
+completely transparent to the application.
+
+[[guidelines-for-statement-pooling]]
+=== Guidelines for Statement Pooling
+
+* To enable statement pooling, set the `maxStatements` property to an
+integer value greater than 0 and enable connection pooling. For more
+information, see <<initialpoolsize-property, initialPoolSize Property>> and
+<<connection-pooling, Connection Pooling>>.
+
+* Enabling statement pooling for your JDBC applications might
+dramatically improve the performance.
+
+* Explicitly close a prepared statement by using the `Statement.close`
+method because `PreparedStatement` objects that are not in scope are also
+not reused unless the application explicitly closes them.
+
+* To ensure that your application reuses a `PreparedStatement`, call
+either of these methods:
+
+** `Statement.close method`: called by the application.
+** `Connection.close method`: called by the application. All the
+`PreparedStatement` objects that were in use are ready to be reused when
+the connection is reused.
+
+[[troubleshooting-statement-pooling]]
+=== Troubleshooting Statement Pooling
+
+Note the following Type 4 driver implementation details if you are
+troubleshooting statement pooling:
+
+* The Type 4 driver looks for a matching `PreparedStatement` object in the
+statement pool and reuses the `PreparedStatement`. The matching criteria
+include the SQL string, catalog, current schema, current transaction
+isolation, and result set holdability.
++
+If the Type 4 driver finds the matching `PreparedStatement` object, then the
+driver returns the same `PreparedStatement` object to the application for reuse
+and marks the `PreparedStatement` object as in use.
+
+* The algorithm, _earlier used are the first to go_, is used to make
+room for caching subsequently generated `PreparedStatement` objects when
+the number of statements reaches the `maxStatements` limit.
+
+* The Type 4 driver assumes that any SQL CONTROL statements in effect at
+the time of execution or reuse are the same as those in effect at the time
+of SQL compilation.
++
+If this condition is not true, then reuse of a `PreparedStatement` object might
+result in unexpected behavior.
+
+* Avoid recompiling to yield performance improvements from statement
+pooling. The SQL executor automatically recompiles queries when certain conditions are met.
+Some of these conditions are:
+
+** A run-time version of a table has a different redefinition timestamp
+than the compile-time version of the same table.
+
+** An existing open operation on a table was eliminated by a DDL or SQL
+utility operation.
+
+** The transaction isolation level and access mode at execution time is
+different from that at the compile time.
+
+* When a query is recompiled, then the SQL executor stores the recompiled query;
+therefore, the query is recompiled only once until any of the previous conditions
+are met again.
+
+* The Type 4 driver does not cache `Statement` objects.
+
+[[thread-safe-database-access]]
+== Thread-Safe Database Access
+
+In the Type 4 driver, API layer classes are implemented as
+instance-specific objects to ensure thread safety:
+
+* `HPT4DataSource.getConnection()` is implemented as a synchronized method
+to ensure thread safety in getting a connection.
+
+* Once a connection is made, the `Connection` object is instance-specific.
+
+* If multiple statements are run on different threads in a single
+connection, then statement objects are serialized to prevent data corruption.
+
+[[update-where-current-of-operations]]
+== "Update . . . Where Current of" Operations
+
+The fetch size on a `ResultSet` must be 1 when performing an
+`update . . . where current of` _cursor_ SQL statement.
+
+If the value of the fetch size is greater than 1, the result of the
+`update . . . where current` of operation might be one of the following:
+
+* An incorrect row might be updated based on the actual cursor position.
+
+* An SQLException might occur because the cursor being updated might
+have already been closed.
+
+The following is an example of setting a result set's fetch size to 1
+and executing an `update . . . where current` of _cursor_ SQL statement.
+
+[source, java]
+----
+ResultSet rs ;
+ ...
+
+ rs.setFetchSize( 1 ) ;
+ String st1 = rs.getCursorName() ;
+
+ Statement stmt2 =
+ connection.createStatement( ResultSet.TYPE_FORWARD_ONLY
+ , ResultSet.CONCUR_UPDATABLE
+ ) ;
+ stmt2.executeUpdate( "UPDATE cat2.sch2.table1
+ SET j = 'update row' WHERE CURRENT OF "
+ + st1
+ ) ;
+----
+
+[[infostats-command-for-obtaining-query-costs]]
+== INFOSTATS Command for Obtaining Query Costs
+
+The INFOSTATS command reports the roll-up costs of a particular query.
+INFOSTATS is a pass-through command that collects statistics for a
+prepared statement. Statistics are returned to the JDBC application as a
+result set as soon as the prepare is finished. The result set has these
+columns:
+
+[cols="30%,70%",options="header" ]
+|===
+| Column | Description
+| `Query ID (SQL_CHAR)` | The unique identifier for the query.
+| `CPUTime (SQL_DOUBLE)` | An estimate of the number of seconds of processor time it might take to execute the instructions for this query. A value of 1.0 is 1 second.
+| `IOTime (SQL_DOUBLE)` | An estimate of the number of seconds of I/O time (seeks plus data transfer) to perform the I/O for this query.
+| `MsgTime (SQL_DOUBLE)` | An estimate of the number of seconds it takes for the messaging for this query. The estimate includes the time for the number of local and remote
+messages and the amount of data sent.
+| `IdleTime (SQL_DOUBLE)` | An estimate of the maximum number of seconds to wait for an event to happen for this query. The estimate includes the amount of time to open
+a table or start an ESP process.
+| `TotalTime (SQL_DOUBLE)` | Estimated cost associated to execute the query.
+| `Cardinality (SQL_DOUBLE)` | Estimated number of rows that will be returned.
+|===
+
+<<<
+[[use-of-the-infostats-command]]
+=== Use of the INFOSTATS Command
+
+The INFOSTATS command can only be used with PreparedStatement objects.
+The syntax is:
+
+```
+INFOSTATS cursor_name
+```
+
+where `cursor_name` is the name of the prepared statement. If the cursor name is case-sensitive,
+then enclose it in single quotes.
+
+To get the cursor name, use the `getStatementLabel()` method that is
+defined for the {project-name} JDBC Type 4 driver with class:
+
+[source, java]
+----
+org.trafodion.t4jdbc.HPT4PreparedStatement: public String
+getStatementLabel() ;
+----
+
+*Considerations*
+
+* You can use INFOSTATS in these methods only:
++
+[source, java]
+----
+java.sql.Statement.executeQuery(String sql)
+java.sql.Statement.execute(String sql)
+----
+
+* `setCursorName` is not supported with INFOSTATS.
+
+* If you invoke INFOSTATS incorrectly, the Type 4 driver issues this error:
++
+```
+Message: INFOSTATS command can only be executed
+ by calling execute(String sql) method.
+ Sqlstate HY000
+ Sqlcode 29180
+```
+
+<<<
+*Example of INFOSTATS*
+
+[source, java]
+----
+Statement s = conn.createStatement( ) ;
+
+HPT4PreparedStatement p =
+ (HPT4PreparedStatement)conn.prepareStatement(
+ "SELECT * FROM t WHERE i = ?" ) ;
+
+boolean results = s.execute( "INFOSTATS " + p.getStatementLabel() ) ;
+
+if ( results )
+{
+ ResultSet rs = s.getResultSet( ) ;
+
+ while ( rs.next( ) )
+ {
+ //process data
+ }
+}
+----
+
+*Sample Output*
+
+```
+QueryID: MXID001001128212016369912348191_16_SQL_CUR_9829657
+CPUTime: 0.09975778464794362
+IOTime: 0.10584000146627659
+MsgTime: 0.09800000134418951
+IdleTime: 0.09800000134418951
+TotalTime: 0.10584000146627659
+Cardinality: 100.0
+```
+
+<<<
+[[internationalization-support]]
+== Internationalization Support
+
+[[when-string-literals-are-used-in-applications]]
+=== When String Literals Are Used in Applications
+
+Internationalization support in the driver affects the handling of
+string literals. The Type 4 driver handles string literals in two
+situations.
+
+1. When the driver processes an SQL statement. For example,
++
+[source, java]
+----
+Statement stmt = connection.getStatement() ;
+
+stmt.execute( "SELECT * FROM table1 WHERE col1 = 'abcd'" ) ;
+----
+
+2. When the driver processes JDBC parameters. For example,
++
+[source, java]
+----
+PreparedStatement pStmt = connection.prepareStatement(
+ "SELECT * FROM table1 WHERE col1 = ?" ) ;
+pStmt.setString( 1, "abcd" ) ;
+----
+
+To convert a string literal from the Java to an array of bytes for
+processing by the {project-name}, the Type 4 driver uses
+the column type in the database.
+
+[[controlling-string-literal-conversion-by-using-the-character-set-properties]]
+=== Controlling String Literal Conversion by Using the Character-Set Properties
+
+The Type 4 driver provides character-set mapping properties. These
+properties allow you to explicitly define the translation of internal
+SQL character-set formats to and from the Java string Unicode (`UnicodeBigUnmarked`)
+encoding.
+
+The Type 4 driver provides character-set mapping properties through key
+values as shown in the following table.
+
+[cols="50%,50%",options="header" ]
+|===
+| Key | Default Value
+| `ISO88591` | `ISO88591_1`
+| `KANJI` | `SJIS`
+| `KSC5601` | `EUC_KR`
+|===
+
+<<<
+A description of these character sets appears in table below, which
+summarizes the character sets supported by {project-name}.
+
+[cols="25%,35%,40%",options="header" ]
+|===
+| {project-name} Character Set | Corresponding Java Encoding Set^1^ | Description
+| ISO88591 | ISO88591_1 | Single-character, 8-bit character-data type ISO88591 supports English and other Western European languages.
+|===
+
+^1^ Canonical Name for `java.io` and `java.lang` API.
+
+For detailed information, see <<iso88591-property, ISO88591 Property>>.
+
+[[using-the-character-set-properties]]
+==== Using the Character-Set Properties
+
+The `java.sql.PreparedStatement` class contains the methods `setString()`
+and `setCharacterStream()`. These methods take a String and Reader
+parameter, respectively.
+
+The `java.sql.ResultSet` class contains the methods `getString()` and
+`getCharacterStream()`. These methods return a String and Reader, respectively.
+
+[[retrieving-a-column]]
+===== Retrieving a Column
+
+When you retrieve a column as a string (for example, call the
+`getString()` or `getCharacterStream` methods), the Type 4 driver uses the
+character-set mapping property key to instantiate a String object (where
+that key corresponds to the character set of the column).
+
+*Example*
+
+The following `SQL CREATE TABLE` statement creates a table that has an
+`ISO88591` column.
+
+[source, sql]
+----
+CREATE TABLE t1 ( c1 CHAR(20) CHARACTER SET ISO88591 ) ;
+----
+
+The JDBC program uses the following java command to set the ISO88591
+property and issues the `getString()` method.
+
+[source, java]
+----
+java -Dhpt4jdbc.ISO88591=SJIS test1.java
+
+// The following method invocation returns a String object, which
+// was created using the "SJIS" Java canonical name as the charset
+// parameter to the String constructor.
+String s1 = rs.getString( 1 ) ; // get column 1 as a String
+----
+
+[[setting-a-parameter]]
+===== Setting a Parameter
+
+When you set a parameter by using a String (for example, call the
+`setString()` method), the Type 4 driver uses the key's value when
+generating the internal representation of the String (where that
+key corresponds to the character set of the column). The
+character-set parameter to the String `getBytes` method is the Java
+Canonical name that corresponds to the column's character set.
+
+*Example*
+
+The following `SQL CREATE TABLE` statement creates a table
+that has an ISO88591 column:
+
+```
+CREATE TABLE t1 ( c1 CHAR(20) CHARACTER SET ISO88591) ;
+> java -DISO88591=SJIS test1.java
+```
+
+The following method invocation sets column one of `stmt` to the String
+"abcd" where "abcd" is encoded as SJIS. The charset parameter to the
+String `getBytes` method is SJIS `stmt.setString( 1, "abcd" ) ;`.
+
+[[controlling-what-happens-on-an-exception]]
+==== Controlling What Happens on an Exception
+
+You can use the `translationVerification` property to explicitly define
+the behavior of the driver if the driver cannot translate all or part of
+an SQL parameter. The value portion of the property can be `TRUE` or
+`FALSE`. (The default value is `FALSE`).
+
+If the `translationVerification` property's value is `FALSE` and the driver
+cannot translate all or part of an SQL statement, then the translation is
+unspecified. In most cases, the characters that are untranslatable are
+encoded as ISO88591 single-byte question marks (`'?'` or `0x3F`). No
+exception or warning is thrown.
+
+If the `translationVerification` property's value is TRUE and the driver
+cannot translate all or part of an SQL statement, then the driver throws an
+`SQLException` with the following text:
+
+```
+Translation of parameter to {0} failed. Cause: {1}
+```
+
+where `{0}` is replaced with the target character set and `{1}` is
+replaced with the cause of the translation failure.
+
+For more information, see
+<<translationverification-property, translationVerification Property>>.
+
+<<<
+[[localizing-error-messages-and-status-messages]]
+=== Localizing Error Messages and Status Messages
+
+The Type 4 driver supports Internationalization through resource bundles
+for localized error messages and status messages. The driver uses a set
+of static strings from a property file to map error messages and status
+messages to their textual representation.
+
+[[file-name-format-for-the-localized-messages-file]]
+==== File-Name Format for the Localized-Messages File
+
+The property file that has the messages must have a file name in the
+form:
+
+```
+HPT4Messages_xx.properties
+```
+
+where `xx` is the locale name. The locale name is defined by the current
+default locale or by the language property.
+
+The Type 4 driver is shipped with an error messages and status messages
+property file that contains the textual representation of errors and
+status messages for the English locale. The file is named
+`HPT4Messages_en.properties`.
+
+[[localized-message-string-format]]
+==== Localized-Message String Format
+
+A localized message file contains strings in the form:
+
+```
+message=message_text
+```
+
+*Example*
+
+```
+driver_err_error_from_server_msg=An error was returned from the server.
+Error: {0} Error detail: {1}
+```
+
+where the `message` is `driver_err_error_from_server_msg`. The
+`message_text` is: `An error was returned from the server. Error: {0} Error detail: {1}`
+
+The pattern `{n}` in `message_text`, where `n` equals 1, 2, 3, and
+so forth, is a placeholder that is filled in at run time by the Type 4
+driver. Any translation must include these placeholders.
+
+<<<
+[[procedure-to-create-a-localized-message-file]]
+==== Procedure to Create a Localized-Message File
+
+1. Extract the `HPT4Messages_en.properties file`, which is in the
+`hpt4jdbc.jar file`.
++
+*Example*
++
+From a UNIX prompt, use the jar Java tool: `jar -x HPT4Messages_en.properties < hpt4jdbc.jar`
+
+2. Copy the file.
+
+3. Edit the file and replace the English text with the text for your locale.
+
+4. Save the file, giving it a file name that meets the naming
+requirements described under
+<<file-name-format-for-the-localized-messages-file, File-Name Format for the Localized-Messages File>>.
+
+5. Put the file in a directory anywhere in the class path for running the JDBC application.
+
+The new messages file can be anywhere in the class path for running the
+user application.
+
+At run time, if driver cannot read the messages property file, the
+driver uses the `message` portion of the property as the text of the
+message. For a description of the message portion, see the
+<<localized-message-string-format, Localized-Message String Format>>.
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/c2116c2b/docs/jdbct4ref_guide/src/asciidoc/_chapters/avoiding_mismatch.adoc
----------------------------------------------------------------------
diff --git a/docs/jdbct4ref_guide/src/asciidoc/_chapters/avoiding_mismatch.adoc b/docs/jdbct4ref_guide/src/asciidoc/_chapters/avoiding_mismatch.adoc
new file mode 100644
index 0000000..8d40e10
--- /dev/null
+++ b/docs/jdbct4ref_guide/src/asciidoc/_chapters/avoiding_mismatch.adoc
@@ -0,0 +1,106 @@
+////
+/**
+ *@@@ START COPYRIGHT @@@
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * @@@ END COPYRIGHT @@@
+ */
+////
+
+[[avoiding-driver-server-version-mismatch]]
+= Avoiding Driver-Server Version Mismatch
+
+The {project-name} JDBC type 4 driver described in this
+document can connect only with an version-equivalent platform
+(server). It cannot connect with an earlier version platform.
+
+To make a connection with the {project-name} platform, JDBC clients,
+through the driver, connect with the {project-name} database
+connectivity service (DCS) on the {project-name} platform. In some
+situations, {project-name} JDBC clients need to make connections to
+older-version platforms (servers) from the same client boxes.
+To make a connection, the driver version
+must be compatible with the {project-name} platform version.
+
+NOTE: The DCS release version and {project-name} platform release
+version are always the same.
+
+
+[[compatible-versions]]
+== Compatible Versions
+
+Ensure that you install the driver version that is compatible with the
+{project-name} platform version.
+
+
+[cols=",",options="header" ]
+|===
+| Driver version | Compatible versions of the {project-name} platform
+| {project-name} Release 2.0 driver | All versions up to, but not including, {project-name} Release 2.2
+| {project-name} Release 2.1 driver | All versions up to, but not including, {project-name} Release 2.2
+| {project-name} Release 2.2 driver | {project-name} Release 2.2 and later versions
+|===
+
+If a compatible version is not installed, you can obtain the software to
+download from the {project-name} download site.
+
+[[considerations-for-mixed-version-jdbc-clients-connecting-to-project-name-platforms]]
+== Considerations for Mixed-Version JDBC Clients Connecting to {project-name} Platforms
+
+On the client platform, you can install multiple versions of the
+{project-name} JDBC type 4 driver to connect to {project-name}
+platforms of different platform versions.
+
+* Assuming you have installed the Release 2.2 {project-name} JDBC type
+4 driver on your workstation and set up the client environment, the 2.2
+driver's classes are set your java CLASSPATH.
+* To connect to a Release 2.1 or 2.0 server ({project-name} platform)
+from the same client machine, you must load the 2.1 driver by making
+sure that it is in your java CLASSPATH.
+* Connecting to both a 2.1 and 2.2 server from the same application at
+the same time is not possible.
+* A given application must use either the 2.2 driver or the 2.1 driver
+when launched. The only way to switch is to reload the application when
+pointing to a new CLASSPATH that contains a different driver.
+
+[[version-mismatch-error-message]]
+== Version Mismatch Error Message
+
+If an {project-name} JDBC client attempts to connect to an invalid DCS
+version, the driver returns the error:
+
+```
+SQLCODE: 29162
+SQLSTATE S1000
+
+Error text:
+
+Unexpected programming exception has been found: <errortext>. Check
+the server event log on node <logfile_location> for details.
+```
+
+* <errortext> is the error text from the server.
+* <logfile_location> is the location of the log file.
+
+Additional error text returned only by a Release 2.2 server, but displayed by any version driver:
+
+```
+Version Mismatch: Client Version is: Pre R2.2.0 Server Version is:
+R2.2.0 Server vproc is:
+
+T7969N25_10AUG07_N25_AS_0613 ERROR
+```
+
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/c2116c2b/docs/jdbct4ref_guide/src/asciidoc/_chapters/code_examples.adoc
----------------------------------------------------------------------
diff --git a/docs/jdbct4ref_guide/src/asciidoc/_chapters/code_examples.adoc b/docs/jdbct4ref_guide/src/asciidoc/_chapters/code_examples.adoc
new file mode 100644
index 0000000..b8471e3
--- /dev/null
+++ b/docs/jdbct4ref_guide/src/asciidoc/_chapters/code_examples.adoc
@@ -0,0 +1,56 @@
+////
+/**
+ *@@@ START COPYRIGHT @@@
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * @@@ END COPYRIGHT @@@
+ */
+////
+
+[[sample-programs-accessing-clob-and-blob-data]]
+= Sample Programs Accessing CLOB and BLOB Data
+
+This appendix shows two working programs.
+
+[[sample-program-accessing-clob-data]]
+== Sample Program Accessing CLOB Data
+
+This sample program shows operations that can be performed through the
+Clob interface or through the PreparedStatement interface. The sample
+program shows examples of both interfaces taking a variable and putting
+the variable's value into a base table that has a CLOB column.
+
+You can access the source at: http://trafodion.apache.org/docs/jdbct4ref_guide/resources/source/clob_example.java
+
+[source, java]
+----
+include::{sourcedir}/clob_example.java[CLOB Example]
+----
+
+[[sample-program-accessing-blob-data]]
+== Sample Program Accessing BLOB Data
+
+This sample program shows the use of both the Blob interface and the
+PreparedStatement interface to take a byte variable and put the
+variable's value into a base table that has a BLOB column.
+
+You can access the source at: http://trafodion.apache.org/docs/jdbct4ref_guide/resources/source/blob_example.java
+
+[source, java]
+----
+include::{sourcedir}/blob_example.java[BLOB Example]
+----
+
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/c2116c2b/docs/jdbct4ref_guide/src/asciidoc/_chapters/compliance.adoc
----------------------------------------------------------------------
diff --git a/docs/jdbct4ref_guide/src/asciidoc/_chapters/compliance.adoc b/docs/jdbct4ref_guide/src/asciidoc/_chapters/compliance.adoc
new file mode 100644
index 0000000..25eedf1
--- /dev/null
+++ b/docs/jdbct4ref_guide/src/asciidoc/_chapters/compliance.adoc
@@ -0,0 +1,386 @@
+////
+/**
+ *@@@ START COPYRIGHT @@@
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * @@@ END COPYRIGHT @@@
+ */
+////
+
+[[type-4-driver-compliance]]
+= Type 4 Driver Compliance
+
+[[compliance-overview]]
+== Compliance Overview
+
+The Type 4 driver conforms where applicable to the JDBC
+3.0 API specification. However, this driver differs from the JDBC
+standard in some ways. This subsection describes the JDBC methods that
+are not supported, the methods and features that deviate from the
+specification, and features that are {project-name} extensions to the JDBC standard.
+JDBC features that conform to the specification are not described in this subsection.
+
+In addition, this chapter lists features of {project-name} SQL that are not supported by the {project-name} JDBC Type 4 driver, other
+unsupported features, and restrictions.
+
+[[unsupported-features]]
+== Unsupported Features
+
+These methods in the java.sql package throw an SQLException with the
+message `Unsupported feature - <method-name>`:
+
+[cols="65%,35%", options="header"]
+|===
+| Method | Comments
+| `CallableStatement.getArray(int parameterIndex)` +
+`CallableStatement.getArray(String parameterName)` +
+`CallableStatement.getBlob(int parameterIndex)` +
+`CallableStatement.getBlob(String parameterName)` +
+`CallableStatement.getClob(int parameterIndex)` +
+`CallableStatement.getClob(String parameterName)` +
+`CallableStatement.getObject(int parameterIndex, Map map)` +
+`CallableStatement.getObject(String parameterName, Map map)` +
+`CallableStatement.getRef(int parameterIndex)` +
+`CallableStatement.getRef(String parameterName)` +
+`CallableStatement.getURL(int parameterIndex)` +
+`CallableStatement.getURL(String parameterName)` +
+`CallableStatement.executeBatch()` | The particular `CallableStatement` method is not supported.
+| `Connection.releaseSavepoint(Savepoint savepoint)` +
+`Connection.rollback(Savepoint savepoint)` +
+`Connection.setSavepoint()` +
+`Connection.setSavepoint(String name)` | The particular `Connection` methods are not supported.
+| `PreparedStatement.setArray(int parameterIndex, Array x)` +
+`PreparedStatement.setRef(int parameterIndex, Ref x)` +
+`PreparedStatement.setURL(int parameterIndex, URL x)` | The particular `PreparedStatement` methods are not supported.
+| `ResultSet.getArray(int columnIndex)` +
+`ResultSet.getArray(String columnName)` +
+`ResultSet.getObject(int columnIndex, Map map)` +
+`ResultSet.getObject(String columnName, Map map)` +
+`ResultSet.getRef(int columnIndex)ResultSet.getRef(String columnName)` +
+`ResultSet.getURL(int columnIndex)` +
+`ResultSet.getURL(String columnName)` +
+`ResultSet.updateArray(int columnIndex)` +
+`ResultSet.updateArray(String columnName)` +
+`ResultSet.updateRef(int columnIndex)` +
+`ResultSet.updateRef(String columnName) | The particular `ResultSet` methods are not supported.
+| `Statement.getQueryTimeout()` +
+`Statement.setQueryTimeout()` | The particular `Statement` methods are not supported.
+|===
+
+The following methods in the java.sql package throw an SQLException with
+the message `Auto generated keys not supported`:
+
+[cols="65%,35%", options="header" ]
+|===
+| Method | Comments
+| `Connection.prepareStatement(String sql, int autoGeneratedKeys)` +
+`Connection.prepareStatement(String sql, int[] columnIndexes)` +
+`Connection.prepareStatement(String sql, String[] columnNames)` | Automatically generated keys are not supported.
+| `Statement.executeUpdate(String sql, int autoGeneratedKeys)` +
+`Statement.executeUpdate(String sql, int[] columnIndexes)` +
+`Statement.executeUpdate(String sql, String[] columnNames)` +
+`Statement.getGeneratedKeys()` | Automatically generated keys are not supported.
+|===
+
+The following methods in the java.sql package throw an SQLException with
+the message `Data type not supported`:
+
+[cols="65%,35%", options="header" ]
+|===
+| Method | Comments
+| `CallableStatement.getBytes(int parameterIndex)` +
+`CallableStatement.setBytes(String parameterIndex, bytes[] x)` | The particular data type is not supported.
+|===
+
+The following interfaces in the `java.sql` package are not implemented in
+the Type 4 driver:
+
+[cols="65%,35%", options="header" ]
+|===
+| Method | Comments
+| `java.sql.Array` +
+`java.sql.Ref` +
+`java.sql.Savepoint` +
+`java.sql.SQLData` +
+`java.sql.SQLInput` +
+`java.sql.SQLOutput` +
+`java.sql.Struct` | The underlying data types are not supported by {project-name}.
+|===
+
+<<<<
+The following interfaces in the `javax.sql` package are not implemented in the Type 4 driver:
+
+[cols="65%,35%", options="header" ]
+|===
+| Method | Comments
+| `javax.sql.XAConnection` +
+`javax.sql.XADataSource` | Distributed Transactions, as described in the JDBC 3.0 API specification, are not yet implemented.
+|===
+
+For additional information about deviations for some methods, see <<deviations, Deviations>>.
+
+[[deviations]]
+== Deviations
+
+The following table lists methods that differ in execution from the JDBC
+specification. When an argument in a method is ignored, the Type 4
+driver does not throw an SQLException,thus allowing the application to
+continue processing. The application might not obtain the expected
+results, however. Other methods listed do not necessarily throw an
+SQLException, unless otherwise stated, although they differ from the
+specification.
+
+NOTE: The `java.sql.DatabaseMetaData.getVersionColumns()` method mimics the
+`java.sql.DatabaseMetaData.getBestRowIdentifier()` method because
+{project-name} SQL does not support `SQL_ROWVER` (a columns function that
+returns the column or columns in the specified table, if any, that are
+automatically updated by the data source when any value in the row is
+updated by any transaction).
+
+[cols="50%,50%", options="header" ]
+|===
+| Method | Comments
+| `java.sql.DatabaseMetaData.getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern)` |
+The column is added to the column data, but its value is set to NULL because {project-name} SQL does not support the column type for these types: +
+ +
+`SCOPE_CATALOG,` +
+`SCOPE_SCHEMA,` +
+`SCOPE_TABLE,` +
+and `SOURCE_DATA_TYPE`
+| `java.sql.DatabaseMetaData.getTables(String catalog, String schemaPattern, String[] types)` |
+The column is added to the column data, but its value is set to NULL because {project-name} SQL does not support the column type for these types: +
+ +
+`TYPE_CAT,` +
+`TYPE_SCHEMA,` +
+`TYPE_NAME,` +
+`SELF_REFERENCING_COL_NAME,` +
+and `REF_GENERATION.`
+| `java.sql.DatabaseMetaData.getUDTs(String catalog, String schemaPattern, String tableNamePattern, int[] types)` |
+BASE_TYPE is added to the column data, but its value is set to NULL because {project-name} SQL does not support the base type.
+| `java.sql.DatabaseMetaData.getVersionColumns()` |
+Mimics the `DatabaseMetaData.getBestRowIdentifier()` method because {project-name} SQL does not support `SQL_ROWVER` (a columns function that returns the
+column or columns in the specified table, if any, that are automatically updated by the data source when any value in the row is updated by any transaction).
+| `java.sql.Connection.createStatement(. . .)` +
+`java.sql.Connection.prepareStatement(. . .)` |
+The Type 4 driver does not support the scroll-sensitive result set type, so an SQL Warning is issued if an application requests that type. The result set is changed to
+a scroll-insensitive type.
+| `java.sql.ResultSet.setFetchDirection(. . .)` | The fetch direction attribute is ignored.
+| `java.sql.Statement.cancel()` |
+In some instances, drops the connection to the server instead of just canceling the query. You must then reconnect to the server.
+Note that the connection is dropped if `cancel()` is issued for a statement that is being processed. Otherwise the connection is maintained.
+| `java.sql.Statement.setEscapeProcessing(. . .)` | Because {project-name} SQL parses the escape syntax, disabling escape processing has no effect.
+| `java.sql.Statement.setFetchDirection(. . .)` | The fetch direction attribute is ignored.
+|===
+
+<<<
+[[project-name-extensions]]
+== {project-name} Extensions
+
+The {project-name} extensions to the JDBC standard implemented in the Type 4 driver are as follows.
+
+[[internationalization-of-messages]]
+=== Internationalization of Messages
+
+The Type 4 driver is designed so that Java messages can be adopted for
+various languages. The error messages are stored outside the source code
+in a separate property file and retrieved dynamically based on the
+locale setting. The error messages in different languages are stored in
+separate property files based on the language and country. This
+extension does not apply to all messages that can occur when running
+JDBC applications.
+
+For details, see <<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>.
+
+[[additional-databasemetadata-apis]]
+=== Additional DatabaseMetaData APIs
+
+APIs added to the `HPT4DatabaseMetaData` class provide these capabilities:
+
+* Get a description of a table's synonyms.
++
+[source, java]
+----
+public java.sql.ResultSet getSynonymInfo(String catalog, String schema, String table) throws SQLException
+----
+
+////
+* Get a description of a table's materialized views.
++
+[source, java]
+----
+public java.sql.ResultSet getMaterializedViewInfo(String catalog, String schema, String table) throws SQLException
+----
+////
+
+[[additional-connection-apis]]
+=== Additional Connection APIs
+
+APIs added to the `HPT4Connection` class provide these capabilities:
+
+* Sets the current service name for this Connection object.
++
+[source, java]
+----
+public void setServiceName(String serviceName) throws SQLException
+----
+
+* Gets (retrieves) the current service name of this Connection object. Default return value: HP_DEFAULT_SERVICE.
++
+[source, java]
+----
+public String getServiceName() throws SQLException
+----
+
+[[conformance-of-databasemetadata-methods-handling-of-null-parameters]]
+== Conformance of DatabaseMetaData Methods' Handling of Null Parameters
+
+This topic describes how the Type 4 driver determines the value of null
+parameters passed as a parameter value on DatabaseMetaData methods.
+Since other vendors might implement the JDBC specification differently,
+this information explains the Type 4 driver results on the affected
+queries.
+
+This implementation applies to methods that take parameters that can
+represent a pattern. The names of these parameters have the format:
+
+```
+attributePattern
+```
+
+The many methods of the java.sql.DatabaseMetaData class are affected;
+for example, the `getColumns()` method.
+
+For another example, schema is the attribute in the parameter
+`schemaPattern`, which is a parameter to the `java.sql.ResultSet.getAttributes` method.
+
+[source, java]
+----
+public ResultSet getAttributes( String catalog
+ , String schemaPattern
+ , String typeNamePattern
+ , String attributeNamePattern
+ ) throws SQLException
+----
+
+If the application passes a null value, the null is treated as follows:
+
+* If a parameter name contains the suffix Pattern, the null is interpreted as a `%` wild card.
+* If the parameter name does not contain the suffix `Pattern`, nulls are interpreted as the default value for that parameter.
+
+Using this example, null parameters are interpreted as follows:
+
+|===
+| `catalog` | The default catalog name.
+| `schemaPattern` | A `%` wild card retrieves data for all schemas of the specified catalog
+|===
+
+<<<
+[[type-4-driver-conformance-to-sql-data-types]]
+== Type 4 Driver Conformance to SQL Data Types
+
+[[jdbc-data-types]]
+=== JDBC Data Types
+
+The following table shows the JDBC data types that are supported by Type
+4 driver and their corresponding {project-name} SQL data types:
+
+[cols="30%,40%,30%", options="header"]
+|===
+| JDBC Data Type | Support by JDBC Driver for {project-name} SQL | {project-name} SQL Data Type
+| `Types.Array` | No | Not applicable.
+| `Types.BIGINT` | Yes | `LARGEINT`
+| `Types.BINARY` | Data type is mapped by {project-name} SQL. Data type varies from that used for table creation. | `CHAR(n)`^1^
+| `Types.BIT` | Data type is mapped by {project-name} SQL. Data type varies from that used for table creation. | `CHAR(1)`
+| `Types.BLOB` | Yes | `LARGEINT`
+| `Types.CHAR` | Yes | `CHAR(n)`
+| `Types.CLOB` | Yes | `LARGEINT`
+| `Types.DATE` | Yes | `DATE`
+| `Types.DECIMAL` | Yes | `DECIMAL(p,s)`
+| `Types.DISTINCT` | No | Not applicable.
+| `Types.DOUBLE` | Yes | `DOUBLE PRECISION`
+| `Types.FLOAT` | Yes | `FLOAT(p)`
+| `Types.INTEGER` | Yes | `INTEGER`
+| `Types.JAVA_OBJECT` | No | Not applicable.
+| `Types.LONGVARBINARY` | Data type is mapped by {project-name} SQL. Data type varies from that used for table creation. | `VARCHAR(n)`^1^
+| `Types.LONGVARCHAR` | Yes. Maximum length is 4018. | `VARCHAR[(n)]`
+| `Types.NULL` | No | Not applicable.
+| `Types.NUMERIC` | Yes | `NUMERIC(p,s)`
+| `Types.REAL` | Yes | `FLOAT(p)`
+| `Types.REF` | No | Not applicable.
+| `Types.SMALLINT` | Yes | `SMALLINT`
+| `Types.STRUCT` | No | Not applicable.
+| `Types.TIME` | Yes | `TIME`
+| `Types.TIMESTAMP` | Yes | `TIMESTAMP`
+| `Types.TINYINT` | Data type is mapped by {project-name} SQL. Data type varies from that used for table creation. | `SMALLINT`
+| `Types.VARBINARY` | Data type is mapped by {project-name} SQL. Data type varies from that used for table creation. | `VARCHAR(n)`^1^
+| `Types.VARCHAR` | Yes | `VARCHAR(n)`
+| `Types.BOOLEAN` | Data type is mapped by {project-name} SQL. Data type varies from that used for table creation. | `CHAR(1)`
+| `Types.DATALINK` | No | Not applicable.
+|===
+
+^1^ Because of mapping provided by {project-name}, a `ResultSet.getObject()` method returns a string object instead of an array of bytes.
+
+The Type 4 driver maps the following data types to the JDBC data type `Types.OTHER`:
+
+```
+INTERVAL YEAR(p)
+INTERVAL YEAR(p) TO MONTH
+INTERVAL MONTH(p)
+INTERVAL DAY(p)
+INTERVAL DAY(p) TO HOUR
+INTERVAL DAY(p) TO MINUTE
+INTERVAL DAY(p) TO SECOND
+INTERVAL HOUR(p)
+INTERVAL HOUR(p) TO MINUTE
+INTERVAL HOUR(p) TO SECOND
+INTERVAL MINUTE(p)
+INTERVAL MINUTE(p) TO SECOND
+INTERVAL SECOND(p)
+```
+
+[[floating-point-support]]
+== Floating-Point Support
+
+The Type 4 driver supports only IEEE floating-point data to be passed between the application client and the Type 4 driver.
+
+[[sqlj-support]]
+== SQLJ Support
+
+The Type 4 driver supports non-customized SQLJ applications, but does not support customized SQLJ applications.
+
+<<<
+[[jdbc-3-0-features-not-supported-by-the-type-4-driver]]
+== JDBC 3.0 Features Not Supported by the Type 4 Driver
+
+These features are not required for JDBC 3.0 compliance, and they are not supported by the {project-name} JDBC Type 4 driver.
+
+* Multiple result sets returned by batch statements.
+* Database savepoint support. (Not provided in {project-name} SQL )
+* Retrieval of auto generated keys.
+* Transform group and type mapping.
+* Relationship between connector architecture and JDBC 3.0 SPI.
+* Secured socket communication or encryption for the interaction between the Type 4 driver and DCS.
+* Security context (user name and password) implicit propagation from AppServer to the Type 4 driver.
+* IPV6 protocol stack. (IPV6 addressing is emulated over IPV4 on the {project-name} platform - server side)
+* Distributed transactions.
+
+[[restrictions]]
+== Restrictions
+
+* The Type 4 driver supports only database features that are supported by {project-name} SQL and SPJ.
+Therefore, the Type 4 driver is not fully compliant with JDBC 3.0 specifications.
+
+* The Type 4 driver depends on the HP connectivity service for all server side manageability related features.
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/c2116c2b/docs/jdbct4ref_guide/src/asciidoc/_chapters/introduction.adoc
----------------------------------------------------------------------
diff --git a/docs/jdbct4ref_guide/src/asciidoc/_chapters/introduction.adoc b/docs/jdbct4ref_guide/src/asciidoc/_chapters/introduction.adoc
new file mode 100644
index 0000000..a0f8219
--- /dev/null
+++ b/docs/jdbct4ref_guide/src/asciidoc/_chapters/introduction.adoc
@@ -0,0 +1,53 @@
+////
+/**
+ *@@@ START COPYRIGHT @@@
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * @@@ END COPYRIGHT @@@
+ */
+////
+
+[[introduction]]
+= Introduction
+
+This document describes how to use the {project-name} JDBC Type 4
+Driver. This driver provides Java applications running on a foreign
+platform with JDBC access to {project-name} SQL databases on the
+{project-name}.
+
+*Supported Java Releases:* The Type 4 driver requires Java enabled
+platforms that support JDK 1.4.1 or higher.
+
+
+[[type-4-driver-api-package]]
+== Type 4 Driver API Package
+
+The Type 4 driver package, `org.trafodion.t4jdbc`, is shipped with the
+driver software. For class and method descriptions, see the
+_{project-name} JDBC Type 4 Driver API Reference_.
+
+The {project-name} JDBC Type 4 Driver (hereafter, Type 4 driver)
+implements JDBC technology that conforms to the standard JDBC 3.0 Data
+Access API.
+
+To obtain detailed information on the standard JDBC API, download the
+JDBC API documentation: http://docs.oracle.com/en/java/.
+
+[[installation]]
+== Installation
+
+Refer to the {docs-url}/client_install/index.html[Trafodion Client Installation Guide].
+