You are viewing a plain text version of this content. The canonical link for it is here.
Posted to codereview@trafodion.apache.org by gtapper <gi...@git.apache.org> on 2016/04/29 08:20:26 UTC
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
GitHub user gtapper opened a pull request:
https://github.com/apache/incubator-trafodion/pull/457
Trafodion 1949: New JDBC Type 4 Programmer's Reference Guide
For review. This guide isn't visible externally yet. Chapters/information related to blob/clob are commented out but part of the checkin.
Also changed the location of the Apache incubator logo from 300px to 200px right indent.
Added a missing source file for the SPJ Guide.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/gtapper/incubator-trafodion TRAFODION-1949
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-trafodion/pull/457.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #457
----
commit c2116c2b3dd857be5cd28160e0f18d2daca73140
Author: Gunnar Tapper <gt...@esgyn.local>
Date: 2016-04-29T06:13:43Z
JDBCT$ Programmer's Reference Guide
New guide. Added missing SPJ Guide file.
commit a3cc57d7f87c8f89148fe34f729e9c630e9e2091
Author: Gunnar Tapper <gt...@esgyn.local>
Date: 2016-04-29T06:16:17Z
Change logation of incubator logo.
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665288
--- Diff: 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
--- End diff --
package name and port num change
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61670067
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61669923
--- Diff: 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:
--- End diff --
Remove HP
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61670108
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
+== reserveDataLocators Property
+
+The `reserveDataLocators` property sets the number of data locators to be
+reserved for a process that stores data in a LOB table.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of data locators to be reserved
+
+Default: 100
+
+Range: 1 to 9,223,372,036,854,775,807 (2**63 -1)
+```
+
+Do not set a value much greater than the number of data locators
+actually needed. If the specified value is 0 (zero) or less, the default
+value (100) is used.
+
+Base the setting of the value of the `reserveDataLocators` property on the
+application profile being executed. If the application inserts a large
+number of LOB items, then a higher value of the `reserveDataLocators` property
+can prevent frequent updating of the `ZZ_DATA_LOCATOR` value in the LOB
+table. However, if the application inserts only a small number of LOB
+items, then a smaller value is better. If a large value is used, then holes
+(unused data-locator numbers) could occur in the LOB table. These holes
+represent unused space.
+
+Also, the administrator should avoid setting high values for the
+`reserveDataLocators` (for example, in the range of trillions or so).
+Setting high values prevents other Type 4 applications that use LOB
+table from reserving data locators.
+
+For additional information about data locator use, see
+<<reserving-data-locators, Reserving Data Locators>>.
+
+To change this value for a JDBC application, specify this property from
+the command line.
+
+*Example*
+
+The following command reserves 150 data
+locators for program class `myProgramClass`.
+
+```
+java -Dhpt4jdbc.reserveDataLocators=150 myProgramClass
+```
+
+<<<
+[[roundingmode]]
+== roundingMode Property
+
+The `roundingMode` property specifies the rounding behavior of the Type 4
+driver. For example, if the data is 1234.127 and column definition is
+`NUMERIC(6, 2)` and the application does `setDouble()` and `getDouble()`,
+then the value returned is 1234.12, which is truncated as specified by the
+default rounding mode, `ROUND_DOWN`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ROUND_DOWN
+```
+
+Values for roundingMode are:
+
+```
+ROUND_CEILING
+
+ROUND_DOWN
+
+ROUND_FLOOR
+
+ROUND_HALF_DOWN
+
+ROUND_HALF_EVEN
+
+ROUND_HALF_UP
+
+ROUND_UNNECESSARY
+
+ROUND_UP
+```
+
+* For the definition of rounding mode values, see the
+https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html[java.math.BigDecimal] documentation.
+
+* If the application sets erroneous values for the `roundingMode` property, no error is thrown by the Type 4 driver.
+The driver uses `ROUND_DOWN` value instead.
+
+* To have the application get the `DataTruncation` exception when data is
+truncated, set the `roundingMode` property to `ROUND_UNNECESSARY`.
+
+<<<
+[[schema]]
+== schema Property
+
+The `schema` property sets the database schema that accesses SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+schema=sales
+```
+
+<<<
+[[t4logfile]]
+== T4LogFile Property
+
+The `T4LogFile` property sets the name of the logging file for the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+```
+
+Default file name is defined by the following pattern:
+
+```
+%h/hpt4jdbc%u.log
+```
+
+where
+
+* `/` represents the local pathname separator.
+
+* `%h` represents the value of the user.home system property. _%u_
+represents a unique number to resolve conflicts.
+
+Any valid file name for your system is allowed.
+
+If you explicitly specify a log file, then that file is overwritten each time
+a `FileHandler` is established using that file name.
+
+To retain previously created log files, use the standard
+`java.util.logging `file syntax to append a unique number onto each log
+file.
+
+*Example*
+
+You can have the following property in a data source:
+
+```
+T4LogFile = C:/temp/MyLogFile%u.log
+```
+
+That name causes the Type 4 driver to create a new log file using a
+unique name for each connection made through that data source.
+
+<<<
+*Example*
+
+```
+C:/temp/MyLogFile43289.log
+
+C:/temp/MyLogFile87634.log
+
+C:/temp/MyLogFile27794.log
+```
+
+If you explicitly specify a log file that is not fully qualified, the
+Type 4 driver creates the file in the current working directory, for
+example, in the directory from which the JVM was invoked.
+
+For detailed information about java.util.logging, see the
+https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[logging summary] documentation.
+
+<<<
+[[t4loglevel]]
+== T4LogLevel Property
+
+The `T4LogLevel` property sets the logging levels that control logging
+output for the Type 4 driver. The Java package java.util.logging logs
+error messages and traces messages in the driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: OFF
+```
+
+*Logging Levels*
+[cols="20%,80%",options="header" ]
+|===
+| Level | Description
+| `OFF` | A special level that turns off logging; the default setting.
+| `SEVERE` | Indicates a serious failure; usually applies to SQL exceptions generated by the Type 4 driver.
+| `WARNING` | Indicates a potential problem, which usually applies to SQL warnings generated by the Type 4 driver.
+| `INFO` | Provides informational messages, typically about connection pooling, statement pooling, and resource usage. This information can
+help in tuning application performance.
+| `CONFIG` | Provides static configuration messages that can include property values and other Type 4 driver configuration information.
+| `FINE` | Provides tracing information from the Type 4 driver methods described in the Type 4 driver API. The level of tracing is equivalent
+to the level of tracing provided when calling the `setLogWriter()` method of the `DriverManager` class or the DataSource class.
+| `FINER` | Indicates a detailed tracing message for which internal Type 4 driver methods provide messages. These messages can be useful in debugging the Type 4 driver.
+| `FINEST` | Indicates a highly detailed tracing message. The driver provides detailed internal data messages that can be useful in debugging the Type 4 driver.
+| `ALL` |Logs all messages.
+|===
+
+*Example*
+
+To enable tracing, use the `hpt4jdbc.T4LogLevel` property specified in the command line:
+
+```
+-Dhpt4jdbc.T4LogLevel=FINE
+```
+
+<<<
+[[t4loglevel-considerations]]
+=== T4LogLevel Considerations
+
+* If a security manager is defined by your application using an AppServer,
+then `LoggingPermission` must be must be granted in the `java.policy` file as
+follows:
++
+```
+permission java.util.logging.LoggingPermission "control", "" ;
+```
+
+* The Type 4 driver is not designed to inherit the `java.util.logging.FileHandler.level` settings at program startup.
+
+<<<
+[[translationverification]]
+== translationVerification Property
+
+The `translationVerification` property defines the behavior of the driver
+if the driver cannot translate all or part of an SQL statement or SQL
+parameter.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The value can be TRUE or FALSE.
+
+```
+Data type: String
+
+Default: FALSE
+```
+
+
+[cols="10%,45%,45%", options="header"]
+|===
+| Value | Scenario | What Happens
+| `FALSE` | The driver is unable to 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.
+| `TRUE` | The driver cannot translation all or part of an SQL statement or parameter. | The driver throws an SQLException with this 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.
+|===
+
+NOTE: If the `translationVerification` property is set to TRUE, then the process can
+use significantly more system resources. For better performance, set this property to FALSE.
+
+For more information, see <<internationalization-support, Internationalization Support>>.
+
+<<<
+[[url]]
+== url Property
+
+The `url` property sets the URL value for the database.
+This property is used in the `DriverManager` object. The format
+to specify the URL is:
+
+```
+jdbc:hpt4jdbc//<primary IP addr or hostname of database>:37800/[:]
+[ property=value [ ; property2=value ] ... ]
+```
+
+where `<primary IP_addr or hostname of database>:37800>` specifies the location of the database.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+url=jdbc:hpt4jdbc://mynode.mycompanynetwork.net:37800/
--- End diff --
fix url string
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675346
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_overview.adoc ---
@@ -0,0 +1,245 @@
+////
+/**
+ *@@@ 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-properties]]
+= Type 4 Driver Properties
+
+[[summary-of-type-4-driver-properties]]
+== Summary of Type 4 Driver Properties
+
+Type 4 driver properties that effect client-side operations are
+summarized in the following tables. For the detailed description, click
+the link provided in the property name.
+
+NOTE: Unless otherwise noted in the brief description, the particular
+property applies to the `DataSource` object, `DriverManager` object, and
+`ConnectionPoolDataSource` object.
+
+[[client-side-properties]]
+=== Client-Side Properties
+
+*Connection-Control Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<dataSourceName, dataSourceName>>` | Specifies the registered DataSource or ConnectionPoolDataSource name. (Can be set only on the DriverManager object.) | None.
+| `<<loginTimeout, loginTimeout>>` | Sets the time limit that a connection can be attempted before the connection disconnects. | 60 (seconds)
+| `<<networkTimeout, networkTimeout>>` | Sets a time limit that the driver waits for a reply from the database server. | 0 (No network timeout is specified.
+|===
+
+*Pooling Management Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<initialPoolSize, initialPoolSize>>` | Sets the initial connection pool size when connection pooling is used with the Type 4 driver. (Ignored for
+connections made through the ConnectionPoolDataSource object.) | -1 (Do not create an initial connection pool.)
+| `<<maxIdleTime, maxIdleTime>>` | Sets the number of seconds that a physical connection can remain unused in the pool before the connection is closed. | 0 (Specifies no limit.)
+| `<<maxPoolSize, maxPoolSize>>` | Sets the maximum number of physical connections that the pool can contain. | -1 (Disables connection pooling.)
+| `<<maxStatements, maxStatements>>` | Sets the total number of PreparedStatement objects that the connection pool should cache. | 0 (Disables statement pooling.)
+| `<<minPoolSize, minPoolSize>>` | Limits the number of physical connections that can be in the free connection pool. | -1 (The minPoolSize value is ignored.)
+|===
+
+////
+*Operations on CLOB and BLOB Data*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<blobTableName, blobTableName>>` | Specifies the LOB table for using BLOB columns. | None.
+| `<<clobTableName, clobTableName>>` | Specifies the LOB table for using CLOB columns. | None.
+| `<<reserveDataLocators,reserveDataLocators>>` | Sets the number of data locators to be reserved for a process that stores data in a LOB table. | 100
+|===
+////
+
+<<<
+*Internationalization Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<ISO88591, ISO88591>>` | Sets character-set mapping that corresponds to the ISO88591 character set. | ISO88591_1
+| `<<KANJI, KANJI>>` | Sets character-set mapping that corresponds to the KANJI character set. | SJIS (which is shift-JIS, Japanese)
+| `<<KSC5601, KSC5601>>` | Sets character-set mapping that corresponds to the KSC5601 character set. | ECU_KR (which is KS C 5601, ECU encoding, Korean)
+| `<<language, language>>` | Sets the language used for error messages. | None.
+| `<<translationVerification, translationVerification>>` | Defines the behavior of the driver if the driver cannot translate all or part of an SQL statement or SQL parameter. | FALSE
+|===
+
+*Logging and Tracing Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<T4LogFile, T4LogFile>>` | Sets the name of the logging file for the Type 4 driver. | The name is defined by the following pattern: `%h/hpt4jdbc%u.log`
+| `<<T4LogLevel, T4LogLevel>>` | Sets the logging levels that control logging output for the Type 4 driver. | OFF
+|===
+
+*Miscellaneous Client-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<description, description>>` | Specifies the registered source name. | None.
+| `<<fetchBufferSize, fetchBufferSize>>` | Provides the benefits of bulk fetch when rows are fetched from a `ResultSet` object. | 4 kilobytes
+| `<<properties, properties>>` | Specifies the location of the properties file that contains keyword-value pairs
+that specify property values for configuring the Type 4 driver. | None.
+| `<<roundingMode, roundingMode>>` | Specifies the rounding behavior of the Type 4 driver. | ROUND_DOWN
+|===
+
+<<<
+[[server-side-properties]]
+=== Server-Side Properties
+
+The Type 4 driver properties that effect server-side operations are
+summarized in the following tables. Unless otherwise noted in the
+description, the particular property applies to the DataSource object,
+`DriverManager` object, and `ConnectionPoolDataSource` object.
+
+*Type 4 Driver Server-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<catalog, catalog>>` | Sets the default catalog used to access SQL objects referenced in SQL
+statements if the SQL objects are not fully qualified. | None. Must be "Seabase" in the current release.
+| `<<connectionTimeout, connectionTimeout>>` | Sets the number of seconds a connection can be idle before the connection is physically closed by DCS. |
+-1 (Use the ConnTimeout value set on the server data source.)
+| `<<password, password>>` | Sets the password value for passing to the database. Can also change the password. | Empty string.
+| `<<schema, schema>>` | Sets the database schema that accesses SQL objects referenced in SQL statements if the SQL objects are not fully qualified. | None.
+| `<<url, url>>` | Sets the URL value for the database. Can be set only on the `DriverManager` object. | None.
+| `<<user, user>>` | Sets the user value for the database. | None.
+|===
+
+[[how-to-specify-jdbc-type-4-properties]]
+== How to Specify JDBC Type 4 Properties
+
+The Type 4 JDBC driver properties configure the driver. These properties
+can be specified in a data source, a connection URL (the primary IP
+address or host name on the database), a properties file,
+or in the java command line.
+
+Java properties have the form:
+
+```
+key=value
+```
+
+At run time, the driver looks for a specific set of property keys and
+takes action based on their associated values.
+
+<<<
+[[where-to-set-properties]]
+=== Where to Set Properties
+
+* For connections made through a `DataSource` or a `ConnectionPoolDataSource`,
+set the property on the `DataSource` or the `ConnectionPoolDataSource` object.
+
+* For the `DriverManager` class, set properties in either of two ways:
++
+1. Using the option `-Dproperty_name=property_value` in the command line.
+2. Using the `java.util.Properties` parameter in the `getConnection()` method
+of the `DriverManager` class.
+
+[[creating-and-using-a-properties-file]]
+=== Creating and Using a Properties File
+
+JDBC applications can provide property values to configure a connection
+by using a file that contains properties for the JDBC driver. This
+property file is passed as a java command-line parameter. The format to
+enter the properties file in the command line is:
+
+```
+-Dhpt4jdbc.properties=<path of the properties file on disk>`
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665325
--- Diff: 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
--- End diff --
remove serverDataSource
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675332
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_overview.adoc ---
@@ -0,0 +1,245 @@
+////
+/**
+ *@@@ 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-properties]]
+= Type 4 Driver Properties
+
+[[summary-of-type-4-driver-properties]]
+== Summary of Type 4 Driver Properties
+
+Type 4 driver properties that effect client-side operations are
+summarized in the following tables. For the detailed description, click
+the link provided in the property name.
+
+NOTE: Unless otherwise noted in the brief description, the particular
+property applies to the `DataSource` object, `DriverManager` object, and
+`ConnectionPoolDataSource` object.
+
+[[client-side-properties]]
+=== Client-Side Properties
+
+*Connection-Control Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<dataSourceName, dataSourceName>>` | Specifies the registered DataSource or ConnectionPoolDataSource name. (Can be set only on the DriverManager object.) | None.
+| `<<loginTimeout, loginTimeout>>` | Sets the time limit that a connection can be attempted before the connection disconnects. | 60 (seconds)
+| `<<networkTimeout, networkTimeout>>` | Sets a time limit that the driver waits for a reply from the database server. | 0 (No network timeout is specified.
+|===
+
+*Pooling Management Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<initialPoolSize, initialPoolSize>>` | Sets the initial connection pool size when connection pooling is used with the Type 4 driver. (Ignored for
+connections made through the ConnectionPoolDataSource object.) | -1 (Do not create an initial connection pool.)
+| `<<maxIdleTime, maxIdleTime>>` | Sets the number of seconds that a physical connection can remain unused in the pool before the connection is closed. | 0 (Specifies no limit.)
+| `<<maxPoolSize, maxPoolSize>>` | Sets the maximum number of physical connections that the pool can contain. | -1 (Disables connection pooling.)
+| `<<maxStatements, maxStatements>>` | Sets the total number of PreparedStatement objects that the connection pool should cache. | 0 (Disables statement pooling.)
+| `<<minPoolSize, minPoolSize>>` | Limits the number of physical connections that can be in the free connection pool. | -1 (The minPoolSize value is ignored.)
+|===
+
+////
+*Operations on CLOB and BLOB Data*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<blobTableName, blobTableName>>` | Specifies the LOB table for using BLOB columns. | None.
+| `<<clobTableName, clobTableName>>` | Specifies the LOB table for using CLOB columns. | None.
+| `<<reserveDataLocators,reserveDataLocators>>` | Sets the number of data locators to be reserved for a process that stores data in a LOB table. | 100
+|===
+////
+
+<<<
+*Internationalization Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<ISO88591, ISO88591>>` | Sets character-set mapping that corresponds to the ISO88591 character set. | ISO88591_1
+| `<<KANJI, KANJI>>` | Sets character-set mapping that corresponds to the KANJI character set. | SJIS (which is shift-JIS, Japanese)
+| `<<KSC5601, KSC5601>>` | Sets character-set mapping that corresponds to the KSC5601 character set. | ECU_KR (which is KS C 5601, ECU encoding, Korean)
+| `<<language, language>>` | Sets the language used for error messages. | None.
+| `<<translationVerification, translationVerification>>` | Defines the behavior of the driver if the driver cannot translate all or part of an SQL statement or SQL parameter. | FALSE
+|===
+
+*Logging and Tracing Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<T4LogFile, T4LogFile>>` | Sets the name of the logging file for the Type 4 driver. | The name is defined by the following pattern: `%h/hpt4jdbc%u.log`
+| `<<T4LogLevel, T4LogLevel>>` | Sets the logging levels that control logging output for the Type 4 driver. | OFF
+|===
+
+*Miscellaneous Client-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<description, description>>` | Specifies the registered source name. | None.
+| `<<fetchBufferSize, fetchBufferSize>>` | Provides the benefits of bulk fetch when rows are fetched from a `ResultSet` object. | 4 kilobytes
+| `<<properties, properties>>` | Specifies the location of the properties file that contains keyword-value pairs
+that specify property values for configuring the Type 4 driver. | None.
+| `<<roundingMode, roundingMode>>` | Specifies the rounding behavior of the Type 4 driver. | ROUND_DOWN
+|===
+
+<<<
+[[server-side-properties]]
+=== Server-Side Properties
+
+The Type 4 driver properties that effect server-side operations are
+summarized in the following tables. Unless otherwise noted in the
+description, the particular property applies to the DataSource object,
+`DriverManager` object, and `ConnectionPoolDataSource` object.
+
+*Type 4 Driver Server-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<catalog, catalog>>` | Sets the default catalog used to access SQL objects referenced in SQL
+statements if the SQL objects are not fully qualified. | None. Must be "Seabase" in the current release.
--- End diff --
Change Seabase to TRAFODION
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675603
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/tracing_logging.adoc ---
@@ -0,0 +1,195 @@
+////
+/**
+ *@@@ 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 @@@
+ */
+////
+
+[[tracing-and-logging-facilities]]
+= Tracing and Logging Facilities
+
+The Type 4 driver provides two tracing and logging facilities:
+
+* Standard JDBC tracing and logging functionality as defined by the JDBC standard
+* Type 4 driver logging facility
+
+Server-side tracing (logging) is enabled by configuring DCS.
+
+[[standard-jdbc-tracing-and-logging-facility]]
+== Standard JDBC Tracing and Logging Facility
+
+The JDBC standard provides a logging and tracing facility, which allows
+tracing JDBC method calls by setting the log writer. To set the log
+writer, either call the `setLogWriter()` method on the `DriverManager` class
+or call the `setLogWriter()` method on the `DataSource` class
+(or `ConnectionPoolDataSource` class).
+
+* A `DriverManager` log writer is a character output stream to which all
+logging and tracing messages for all connections made through the
+`DriverManager` are printed. This stream includes messages printed by the
+methods of this connection, messages printed by methods of other objects
+manufactured by the connection, and so on. The `DriverManager` log writer
+is initially null, that is, the default is for logging to be disabled.
+
+For information about using the setLogWriter method, see the
+https://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html[DriverManager class API].
+
+* A `DataSource` log writer is a character output stream to which all
+logging and tracing messages for this data source are printed. This
+stream includes messages printed by the methods of this object, messages
+printed by methods of other objects manufactured by this object, and so
+on. Messages printed to a data-source-specific log writer are not
+printed to the log writer associated with the `java.sql.DriverManager`
+class. When a `DataSource` object is created, the log writer is initially
+null; that is, the default is for logging to be disabled.
+
+For information about using the setLogWriter method, see the
+https://docs.oracle.com/cd/E16338_01/appdev.112/e13995/oracle/jdbc/pool/OracleDataSource.html[DriverSource interface API].
+
+<<<
+[[the-type-4-driver-logging-facility]]
+== The Type 4 Driver Logging Facility
+
+
+The Type 4 driver Logging facility allows you to retrieve internal
+tracing information, which you can use in debugging the driver. It also
+allows you to capture error and warning messages.
+
+In addition to the standard JDBC tracing and logging facility, the Type
+4 driver provides an independent logging facility (Type 4 Driver
+Logging). The Type 4 Driver Logging provides the same level of logging
+and tracing as the standard JDBC tracing and logging facility with the
+following additional information:
+
+* More detail about the internals of the Type 4 driver and internal tracing information
+* Type 4 driver performance-tuning information
+* Finer control over the amount and type of logging information
+* Error and warning messages
+
+[[accessing-the-type-4-driver-logging-facility]]
+=== Accessing the Type 4 Driver Logging Facility
+
+The Type 4 Driver Logging facility is based on the `java.util.logging`
+package. The Type 4 driver instantiates a `java.util.logging.Logger` class
+and names the logger `org.trafodion.jdbc.t4.logger`.
+
+Your JDBC program can access the Type 4 driver logger directly by
+calling the `java.util.logging.Logger` static method `getLogger(String)`.
+
+*example*
+
+[source, java]
+----
+String t4Logger =
+ java.util.logging.Logger.getLogger( "org.trafodion.jdbc.t4.logger" ) ;
+----
+
+<<<
+[[controlling-type-4-driver-logging-output]]
+=== Controlling Type 4 Driver Logging Output
+
+The Type 4 driver provides two properties that you can use to control logging output.
+
+* `T4LogLevel`: Specifies the level of logging. For information about using this property, see <<t4loglevel-property, T4LogLevel Property>>.
+* `T4LogFile`: Specifies the file to which the driver is to write logging information. For information about using this property,
+see <<t4logfile-property, T4LogFile Property>>.
+
+If the application sets several property values, see
+<<precedence-of-property-specifications, Precedence of Property Specifications>> to determine which setting applies.
+
+*Example*
+
+These properties file entries set the logging level to SEVERE and specify a log file name:
+
+```
+T4LogLevel= SEVERE
+
+T4LogFile=c:/T4logfile1.log
+```
+<<<
+[[message-format]]
+=== Message Format
+
+The format of the trace output is
+
+```
+sequence-number ~ time-stamp ~ thread-id
+~ [connection-id] ~ [server-id] ~ [dialogue-id]
+~ [class].[method][(parameters)] ~ [text]
+```
+
+
+[cols="30%,70%",options="header" ]
+|===
+| Identifier | Provides
+| `sequence-number` | A unique sequence number in increasing order.
+| `time-stamp` | The time of the message, for example 10/17/2004 12:48:23.
+| `thread-id` | The thread identifier within the Java VM.
+| `connection-id` | If applicable, a unique ID for the connection associated with the message.
+| `server-id` | If applicable, information about the connectivity server associated with the message. The _server-id_ is of the form: +
+ +
+`TCP:node-name.server-name/port-number:HPODBC` +
+ +
+where +
+ +
+`node-name` is the name of the {project-name} database node. +
+`server-name` is the name of the {project-name} platform. +
+`port-number` is the port to which the server is connected. +
+ +
+*Example* +
+ +
+`TCP:\banshee-tcp.$Z0133/46003:HPODBC`
--- End diff --
Change HP
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675399
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_overview.adoc ---
@@ -0,0 +1,245 @@
+////
+/**
+ *@@@ 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-properties]]
+= Type 4 Driver Properties
+
+[[summary-of-type-4-driver-properties]]
+== Summary of Type 4 Driver Properties
+
+Type 4 driver properties that effect client-side operations are
+summarized in the following tables. For the detailed description, click
+the link provided in the property name.
+
+NOTE: Unless otherwise noted in the brief description, the particular
+property applies to the `DataSource` object, `DriverManager` object, and
+`ConnectionPoolDataSource` object.
+
+[[client-side-properties]]
+=== Client-Side Properties
+
+*Connection-Control Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<dataSourceName, dataSourceName>>` | Specifies the registered DataSource or ConnectionPoolDataSource name. (Can be set only on the DriverManager object.) | None.
+| `<<loginTimeout, loginTimeout>>` | Sets the time limit that a connection can be attempted before the connection disconnects. | 60 (seconds)
+| `<<networkTimeout, networkTimeout>>` | Sets a time limit that the driver waits for a reply from the database server. | 0 (No network timeout is specified.
+|===
+
+*Pooling Management Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<initialPoolSize, initialPoolSize>>` | Sets the initial connection pool size when connection pooling is used with the Type 4 driver. (Ignored for
+connections made through the ConnectionPoolDataSource object.) | -1 (Do not create an initial connection pool.)
+| `<<maxIdleTime, maxIdleTime>>` | Sets the number of seconds that a physical connection can remain unused in the pool before the connection is closed. | 0 (Specifies no limit.)
+| `<<maxPoolSize, maxPoolSize>>` | Sets the maximum number of physical connections that the pool can contain. | -1 (Disables connection pooling.)
+| `<<maxStatements, maxStatements>>` | Sets the total number of PreparedStatement objects that the connection pool should cache. | 0 (Disables statement pooling.)
+| `<<minPoolSize, minPoolSize>>` | Limits the number of physical connections that can be in the free connection pool. | -1 (The minPoolSize value is ignored.)
+|===
+
+////
+*Operations on CLOB and BLOB Data*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<blobTableName, blobTableName>>` | Specifies the LOB table for using BLOB columns. | None.
+| `<<clobTableName, clobTableName>>` | Specifies the LOB table for using CLOB columns. | None.
+| `<<reserveDataLocators,reserveDataLocators>>` | Sets the number of data locators to be reserved for a process that stores data in a LOB table. | 100
+|===
+////
+
+<<<
+*Internationalization Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<ISO88591, ISO88591>>` | Sets character-set mapping that corresponds to the ISO88591 character set. | ISO88591_1
+| `<<KANJI, KANJI>>` | Sets character-set mapping that corresponds to the KANJI character set. | SJIS (which is shift-JIS, Japanese)
+| `<<KSC5601, KSC5601>>` | Sets character-set mapping that corresponds to the KSC5601 character set. | ECU_KR (which is KS C 5601, ECU encoding, Korean)
+| `<<language, language>>` | Sets the language used for error messages. | None.
+| `<<translationVerification, translationVerification>>` | Defines the behavior of the driver if the driver cannot translate all or part of an SQL statement or SQL parameter. | FALSE
+|===
+
+*Logging and Tracing Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<T4LogFile, T4LogFile>>` | Sets the name of the logging file for the Type 4 driver. | The name is defined by the following pattern: `%h/hpt4jdbc%u.log`
+| `<<T4LogLevel, T4LogLevel>>` | Sets the logging levels that control logging output for the Type 4 driver. | OFF
+|===
+
+*Miscellaneous Client-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<description, description>>` | Specifies the registered source name. | None.
+| `<<fetchBufferSize, fetchBufferSize>>` | Provides the benefits of bulk fetch when rows are fetched from a `ResultSet` object. | 4 kilobytes
+| `<<properties, properties>>` | Specifies the location of the properties file that contains keyword-value pairs
+that specify property values for configuring the Type 4 driver. | None.
+| `<<roundingMode, roundingMode>>` | Specifies the rounding behavior of the Type 4 driver. | ROUND_DOWN
+|===
+
+<<<
+[[server-side-properties]]
+=== Server-Side Properties
+
+The Type 4 driver properties that effect server-side operations are
+summarized in the following tables. Unless otherwise noted in the
+description, the particular property applies to the DataSource object,
+`DriverManager` object, and `ConnectionPoolDataSource` object.
+
+*Type 4 Driver Server-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<catalog, catalog>>` | Sets the default catalog used to access SQL objects referenced in SQL
+statements if the SQL objects are not fully qualified. | None. Must be "Seabase" in the current release.
+| `<<connectionTimeout, connectionTimeout>>` | Sets the number of seconds a connection can be idle before the connection is physically closed by DCS. |
+-1 (Use the ConnTimeout value set on the server data source.)
+| `<<password, password>>` | Sets the password value for passing to the database. Can also change the password. | Empty string.
+| `<<schema, schema>>` | Sets the database schema that accesses SQL objects referenced in SQL statements if the SQL objects are not fully qualified. | None.
+| `<<url, url>>` | Sets the URL value for the database. Can be set only on the `DriverManager` object. | None.
+| `<<user, user>>` | Sets the user value for the database. | None.
+|===
+
+[[how-to-specify-jdbc-type-4-properties]]
+== How to Specify JDBC Type 4 Properties
+
+The Type 4 JDBC driver properties configure the driver. These properties
+can be specified in a data source, a connection URL (the primary IP
+address or host name on the database), a properties file,
+or in the java command line.
+
+Java properties have the form:
+
+```
+key=value
+```
+
+At run time, the driver looks for a specific set of property keys and
+takes action based on their associated values.
+
+<<<
+[[where-to-set-properties]]
+=== Where to Set Properties
+
+* For connections made through a `DataSource` or a `ConnectionPoolDataSource`,
+set the property on the `DataSource` or the `ConnectionPoolDataSource` object.
+
+* For the `DriverManager` class, set properties in either of two ways:
++
+1. Using the option `-Dproperty_name=property_value` in the command line.
+2. Using the `java.util.Properties` parameter in the `getConnection()` method
+of the `DriverManager` class.
+
+[[creating-and-using-a-properties-file]]
+=== Creating and Using a Properties File
+
+JDBC applications can provide property values to configure a connection
+by using a file that contains properties for the JDBC driver. This
+property file is passed as a java command-line parameter. The format to
+enter the properties file in the command line is:
+
+```
+-Dhpt4jdbc.properties=<path of the properties file on disk>`
+```
+
+*Example*
+
+```
+-Dhpt4jdbc.properties=C:\temp\t4props\myprops.properties
+```
+
+To create the file, use the editor of your choice on your workstation to
+type in the property values. The entries in properties file must have a
+`property_name=property_value` value-pair format:
+
+```
+property_name=property_value
+```
+
+*Example*
+
+```
+maxStatements=1024
+```
+
+To configure a `DataSource` connection, the properties file might contain
+property names and values as indicated in the following list:
+
+```
+url=jdbc:hpt4jdbc://<primary IP addr or host name of database>:37800/
+user=database_username
+password=mypassword
+description=<a string>
+catalog=Seabase
+schema=myschema
+maxPoolSize=20
+minPoolSize=5
+maxStatements=20
+loginTimeout=15
+initialPoolSize=10
+connectionTimeout=10
+serverDataSource=server_data_source
--- End diff --
remove serverDataSource
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665266
--- Diff: 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
--- End diff --
Fix all references of org.trafodion.t4jdbc to org.trafodion.jdbc.t4
Change HPT4Driver to T4Driver
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61660766
--- Diff: 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.)
--- End diff --
Yes, that's my understanding. No one has had time to do the larger change to change the class names.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665293
--- Diff: 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
--- End diff --
jdbc:t4jdbc
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61670015
--- Diff: 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/.
--- End diff --
might need to fix the link
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665296
--- Diff: 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>
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673132
--- Diff: 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
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61670061
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665441
--- Diff: 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`.
--- End diff --
jar file name change jdbcT4-<ver num>.jar Fix all places that applicable
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673378
--- Diff: 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/.
--- End diff --
This is the latest link I can find to Java documentation. Please suggest an alternative.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673153
--- Diff: 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
--- End diff --
changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665457
--- Diff: 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:
--- End diff --
Delete all of this till end of T7969...
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673006
--- Diff: 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/" );
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673086
--- Diff: 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" ) ;
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665243
--- Diff: 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
--- End diff --
This should be org.trafodion.jdbc.t4.T4Driver
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665392
--- Diff: 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
--- End diff --
jdbc.t4.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673157
--- Diff: 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
--- End diff --
Changed
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675683
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/tracing_logging.adoc ---
@@ -0,0 +1,195 @@
+////
+/**
+ *@@@ 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 @@@
+ */
+////
+
+[[tracing-and-logging-facilities]]
+= Tracing and Logging Facilities
+
+The Type 4 driver provides two tracing and logging facilities:
+
+* Standard JDBC tracing and logging functionality as defined by the JDBC standard
+* Type 4 driver logging facility
+
+Server-side tracing (logging) is enabled by configuring DCS.
+
+[[standard-jdbc-tracing-and-logging-facility]]
+== Standard JDBC Tracing and Logging Facility
+
+The JDBC standard provides a logging and tracing facility, which allows
+tracing JDBC method calls by setting the log writer. To set the log
+writer, either call the `setLogWriter()` method on the `DriverManager` class
+or call the `setLogWriter()` method on the `DataSource` class
+(or `ConnectionPoolDataSource` class).
+
+* A `DriverManager` log writer is a character output stream to which all
+logging and tracing messages for all connections made through the
+`DriverManager` are printed. This stream includes messages printed by the
+methods of this connection, messages printed by methods of other objects
+manufactured by the connection, and so on. The `DriverManager` log writer
+is initially null, that is, the default is for logging to be disabled.
+
+For information about using the setLogWriter method, see the
+https://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html[DriverManager class API].
+
+* A `DataSource` log writer is a character output stream to which all
+logging and tracing messages for this data source are printed. This
+stream includes messages printed by the methods of this object, messages
+printed by methods of other objects manufactured by this object, and so
+on. Messages printed to a data-source-specific log writer are not
+printed to the log writer associated with the `java.sql.DriverManager`
+class. When a `DataSource` object is created, the log writer is initially
+null; that is, the default is for logging to be disabled.
+
+For information about using the setLogWriter method, see the
+https://docs.oracle.com/cd/E16338_01/appdev.112/e13995/oracle/jdbc/pool/OracleDataSource.html[DriverSource interface API].
+
+<<<
+[[the-type-4-driver-logging-facility]]
+== The Type 4 Driver Logging Facility
+
+
+The Type 4 driver Logging facility allows you to retrieve internal
+tracing information, which you can use in debugging the driver. It also
+allows you to capture error and warning messages.
+
+In addition to the standard JDBC tracing and logging facility, the Type
+4 driver provides an independent logging facility (Type 4 Driver
+Logging). The Type 4 Driver Logging provides the same level of logging
+and tracing as the standard JDBC tracing and logging facility with the
+following additional information:
+
+* More detail about the internals of the Type 4 driver and internal tracing information
+* Type 4 driver performance-tuning information
+* Finer control over the amount and type of logging information
+* Error and warning messages
+
+[[accessing-the-type-4-driver-logging-facility]]
+=== Accessing the Type 4 Driver Logging Facility
--- End diff --
Remove this section "Accessing the Type4 Driver Logging Facility"
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665152
--- Diff: 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
--- End diff --
Change ID to password
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673045
--- Diff: 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
--- End diff --
Replaced everywhere.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673433
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
+== reserveDataLocators Property
+
+The `reserveDataLocators` property sets the number of data locators to be
+reserved for a process that stores data in a LOB table.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of data locators to be reserved
+
+Default: 100
+
+Range: 1 to 9,223,372,036,854,775,807 (2**63 -1)
+```
+
+Do not set a value much greater than the number of data locators
+actually needed. If the specified value is 0 (zero) or less, the default
+value (100) is used.
+
+Base the setting of the value of the `reserveDataLocators` property on the
+application profile being executed. If the application inserts a large
+number of LOB items, then a higher value of the `reserveDataLocators` property
+can prevent frequent updating of the `ZZ_DATA_LOCATOR` value in the LOB
+table. However, if the application inserts only a small number of LOB
+items, then a smaller value is better. If a large value is used, then holes
+(unused data-locator numbers) could occur in the LOB table. These holes
+represent unused space.
+
+Also, the administrator should avoid setting high values for the
+`reserveDataLocators` (for example, in the range of trillions or so).
+Setting high values prevents other Type 4 applications that use LOB
+table from reserving data locators.
+
+For additional information about data locator use, see
+<<reserving-data-locators, Reserving Data Locators>>.
+
+To change this value for a JDBC application, specify this property from
+the command line.
+
+*Example*
+
+The following command reserves 150 data
+locators for program class `myProgramClass`.
+
+```
+java -Dhpt4jdbc.reserveDataLocators=150 myProgramClass
+```
+
+<<<
+[[roundingmode]]
+== roundingMode Property
+
+The `roundingMode` property specifies the rounding behavior of the Type 4
+driver. For example, if the data is 1234.127 and column definition is
+`NUMERIC(6, 2)` and the application does `setDouble()` and `getDouble()`,
+then the value returned is 1234.12, which is truncated as specified by the
+default rounding mode, `ROUND_DOWN`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ROUND_DOWN
+```
+
+Values for roundingMode are:
+
+```
+ROUND_CEILING
+
+ROUND_DOWN
+
+ROUND_FLOOR
+
+ROUND_HALF_DOWN
+
+ROUND_HALF_EVEN
+
+ROUND_HALF_UP
+
+ROUND_UNNECESSARY
+
+ROUND_UP
+```
+
+* For the definition of rounding mode values, see the
+https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html[java.math.BigDecimal] documentation.
+
+* If the application sets erroneous values for the `roundingMode` property, no error is thrown by the Type 4 driver.
+The driver uses `ROUND_DOWN` value instead.
+
+* To have the application get the `DataTruncation` exception when data is
+truncated, set the `roundingMode` property to `ROUND_UNNECESSARY`.
+
+<<<
+[[schema]]
+== schema Property
+
+The `schema` property sets the database schema that accesses SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+schema=sales
+```
+
+<<<
+[[t4logfile]]
+== T4LogFile Property
+
+The `T4LogFile` property sets the name of the logging file for the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+```
+
+Default file name is defined by the following pattern:
+
+```
+%h/hpt4jdbc%u.log
+```
+
+where
+
+* `/` represents the local pathname separator.
+
+* `%h` represents the value of the user.home system property. _%u_
+represents a unique number to resolve conflicts.
+
+Any valid file name for your system is allowed.
+
+If you explicitly specify a log file, then that file is overwritten each time
+a `FileHandler` is established using that file name.
+
+To retain previously created log files, use the standard
+`java.util.logging `file syntax to append a unique number onto each log
+file.
+
+*Example*
+
+You can have the following property in a data source:
+
+```
+T4LogFile = C:/temp/MyLogFile%u.log
+```
+
+That name causes the Type 4 driver to create a new log file using a
+unique name for each connection made through that data source.
+
+<<<
+*Example*
+
+```
+C:/temp/MyLogFile43289.log
+
+C:/temp/MyLogFile87634.log
+
+C:/temp/MyLogFile27794.log
+```
+
+If you explicitly specify a log file that is not fully qualified, the
+Type 4 driver creates the file in the current working directory, for
+example, in the directory from which the JVM was invoked.
+
+For detailed information about java.util.logging, see the
+https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[logging summary] documentation.
+
+<<<
+[[t4loglevel]]
+== T4LogLevel Property
+
+The `T4LogLevel` property sets the logging levels that control logging
+output for the Type 4 driver. The Java package java.util.logging logs
+error messages and traces messages in the driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: OFF
+```
+
+*Logging Levels*
+[cols="20%,80%",options="header" ]
+|===
+| Level | Description
+| `OFF` | A special level that turns off logging; the default setting.
+| `SEVERE` | Indicates a serious failure; usually applies to SQL exceptions generated by the Type 4 driver.
+| `WARNING` | Indicates a potential problem, which usually applies to SQL warnings generated by the Type 4 driver.
+| `INFO` | Provides informational messages, typically about connection pooling, statement pooling, and resource usage. This information can
+help in tuning application performance.
+| `CONFIG` | Provides static configuration messages that can include property values and other Type 4 driver configuration information.
+| `FINE` | Provides tracing information from the Type 4 driver methods described in the Type 4 driver API. The level of tracing is equivalent
+to the level of tracing provided when calling the `setLogWriter()` method of the `DriverManager` class or the DataSource class.
+| `FINER` | Indicates a detailed tracing message for which internal Type 4 driver methods provide messages. These messages can be useful in debugging the Type 4 driver.
+| `FINEST` | Indicates a highly detailed tracing message. The driver provides detailed internal data messages that can be useful in debugging the Type 4 driver.
+| `ALL` |Logs all messages.
+|===
+
+*Example*
+
+To enable tracing, use the `hpt4jdbc.T4LogLevel` property specified in the command line:
+
+```
+-Dhpt4jdbc.T4LogLevel=FINE
+```
+
+<<<
+[[t4loglevel-considerations]]
+=== T4LogLevel Considerations
+
+* If a security manager is defined by your application using an AppServer,
+then `LoggingPermission` must be must be granted in the `java.policy` file as
+follows:
++
+```
+permission java.util.logging.LoggingPermission "control", "" ;
+```
+
+* The Type 4 driver is not designed to inherit the `java.util.logging.FileHandler.level` settings at program startup.
+
+<<<
+[[translationverification]]
+== translationVerification Property
+
+The `translationVerification` property defines the behavior of the driver
+if the driver cannot translate all or part of an SQL statement or SQL
+parameter.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The value can be TRUE or FALSE.
+
+```
+Data type: String
+
+Default: FALSE
+```
+
+
+[cols="10%,45%,45%", options="header"]
+|===
+| Value | Scenario | What Happens
+| `FALSE` | The driver is unable to 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.
+| `TRUE` | The driver cannot translation all or part of an SQL statement or parameter. | The driver throws an SQLException with this 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.
+|===
+
+NOTE: If the `translationVerification` property is set to TRUE, then the process can
+use significantly more system resources. For better performance, set this property to FALSE.
+
+For more information, see <<internationalization-support, Internationalization Support>>.
+
+<<<
+[[url]]
+== url Property
+
+The `url` property sets the URL value for the database.
+This property is used in the `DriverManager` object. The format
+to specify the URL is:
+
+```
+jdbc:hpt4jdbc//<primary IP addr or hostname of database>:37800/[:]
+[ property=value [ ; property2=value ] ... ]
+```
+
+where `<primary IP_addr or hostname of database>:37800>` specifies the location of the database.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+url=jdbc:hpt4jdbc://mynode.mycompanynetwork.net:37800/
+```
+
+[[url-property-considerations]]
+=== url Property Considerations
+
+* If the url parameter is not specified and `DriverManager.getConnection()` is called, then the Type 4 driver throws an SQLException.
+
+* If you use a literal IPV4 or IPV6 address in a URL, note these guidelines:
+
+** *For IPV6 only*: enclose the address in brackets (`[` and `]`).
+
+** The port number is optional according to both the IPV4 and IPV6 standard.
+
+** The default port number for the database is `37800`.
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673207
--- Diff: 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`.
--- End diff --
Changed to jdbcT4-*.jar everywhere.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673116
--- Diff: 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>
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673390
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by DaveBirdsall <gi...@git.apache.org>.
Github user DaveBirdsall commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61657384
--- Diff: 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>
--- End diff --
So, this is the 1.3.0 version? Is there also a 2.0,0 version?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665422
--- Diff: 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
--- End diff --
Remove HP
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675650
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/tracing_logging.adoc ---
@@ -0,0 +1,195 @@
+////
+/**
+ *@@@ 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 @@@
+ */
+////
+
+[[tracing-and-logging-facilities]]
+= Tracing and Logging Facilities
+
+The Type 4 driver provides two tracing and logging facilities:
+
+* Standard JDBC tracing and logging functionality as defined by the JDBC standard
+* Type 4 driver logging facility
+
+Server-side tracing (logging) is enabled by configuring DCS.
+
+[[standard-jdbc-tracing-and-logging-facility]]
+== Standard JDBC Tracing and Logging Facility
+
+The JDBC standard provides a logging and tracing facility, which allows
+tracing JDBC method calls by setting the log writer. To set the log
+writer, either call the `setLogWriter()` method on the `DriverManager` class
+or call the `setLogWriter()` method on the `DataSource` class
+(or `ConnectionPoolDataSource` class).
+
+* A `DriverManager` log writer is a character output stream to which all
+logging and tracing messages for all connections made through the
+`DriverManager` are printed. This stream includes messages printed by the
+methods of this connection, messages printed by methods of other objects
+manufactured by the connection, and so on. The `DriverManager` log writer
+is initially null, that is, the default is for logging to be disabled.
+
+For information about using the setLogWriter method, see the
+https://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html[DriverManager class API].
+
+* A `DataSource` log writer is a character output stream to which all
+logging and tracing messages for this data source are printed. This
+stream includes messages printed by the methods of this object, messages
+printed by methods of other objects manufactured by this object, and so
+on. Messages printed to a data-source-specific log writer are not
+printed to the log writer associated with the `java.sql.DriverManager`
+class. When a `DataSource` object is created, the log writer is initially
+null; that is, the default is for logging to be disabled.
+
+For information about using the setLogWriter method, see the
+https://docs.oracle.com/cd/E16338_01/appdev.112/e13995/oracle/jdbc/pool/OracleDataSource.html[DriverSource interface API].
+
+<<<
+[[the-type-4-driver-logging-facility]]
+== The Type 4 Driver Logging Facility
+
+
+The Type 4 driver Logging facility allows you to retrieve internal
+tracing information, which you can use in debugging the driver. It also
+allows you to capture error and warning messages.
+
+In addition to the standard JDBC tracing and logging facility, the Type
+4 driver provides an independent logging facility (Type 4 Driver
+Logging). The Type 4 Driver Logging provides the same level of logging
+and tracing as the standard JDBC tracing and logging facility with the
+following additional information:
+
+* More detail about the internals of the Type 4 driver and internal tracing information
+* Type 4 driver performance-tuning information
+* Finer control over the amount and type of logging information
+* Error and warning messages
+
+[[accessing-the-type-4-driver-logging-facility]]
+=== Accessing the Type 4 Driver Logging Facility
+
+The Type 4 Driver Logging facility is based on the `java.util.logging`
+package. The Type 4 driver instantiates a `java.util.logging.Logger` class
+and names the logger `org.trafodion.jdbc.t4.logger`.
+
+Your JDBC program can access the Type 4 driver logger directly by
+calling the `java.util.logging.Logger` static method `getLogger(String)`.
+
+*example*
+
+[source, java]
+----
+String t4Logger =
+ java.util.logging.Logger.getLogger( "org.trafodion.jdbc.t4.logger" ) ;
+----
+
+<<<
+[[controlling-type-4-driver-logging-output]]
+=== Controlling Type 4 Driver Logging Output
+
+The Type 4 driver provides two properties that you can use to control logging output.
+
+* `T4LogLevel`: Specifies the level of logging. For information about using this property, see <<t4loglevel-property, T4LogLevel Property>>.
+* `T4LogFile`: Specifies the file to which the driver is to write logging information. For information about using this property,
+see <<t4logfile-property, T4LogFile Property>>.
+
+If the application sets several property values, see
+<<precedence-of-property-specifications, Precedence of Property Specifications>> to determine which setting applies.
+
+*Example*
+
+These properties file entries set the logging level to SEVERE and specify a log file name:
+
+```
+T4LogLevel= SEVERE
+
+T4LogFile=c:/T4logfile1.log
+```
+<<<
+[[message-format]]
+=== Message Format
+
+The format of the trace output is
+
+```
+sequence-number ~ time-stamp ~ thread-id
+~ [connection-id] ~ [server-id] ~ [dialogue-id]
+~ [class].[method][(parameters)] ~ [text]
+```
+
+
+[cols="30%,70%",options="header" ]
+|===
+| Identifier | Provides
+| `sequence-number` | A unique sequence number in increasing order.
+| `time-stamp` | The time of the message, for example 10/17/2004 12:48:23.
+| `thread-id` | The thread identifier within the Java VM.
+| `connection-id` | If applicable, a unique ID for the connection associated with the message.
+| `server-id` | If applicable, information about the connectivity server associated with the message. The _server-id_ is of the form: +
+ +
+`TCP:node-name.server-name/port-number:HPODBC` +
+ +
+where +
+ +
+`node-name` is the name of the {project-name} database node. +
+`server-name` is the name of the {project-name} platform. +
+`port-number` is the port to which the server is connected. +
+ +
+*Example* +
+ +
+`TCP:\banshee-tcp.$Z0133/46003:HPODBC`
+| `dialogue-id` | If applicable, the `dialogue-id` used for the DCS connection.
+| `class` | If applicable, the name of the class that issued the logging request.
+| `method` | If applicable, the name of the method that issued the logging request.
+| `parameters` | An optional set of parameters associated with the method.
+| `text` | Optional textual information for the message.
+|===
+
+NOTE: The tilde (`~`) character separates message parts. This separator
+allows you to format the message using tools, such as Excel, Word, UNIX
+sort, and so forth. For example, you can format and sort messages based
+on sequence number or thread ID. You can edit the log file and change
+the separator (the tilde) to any character you want. When possible,
+numbers (such as `thread-id` and `sequence-number`) are prepended with
+zeros (0) to allow for readable formatting.
+
+<<<
+[[examples-of-logging-output]]
+=== Examples of Logging Output
+
+* Output where `T4LogLevel` is set to `SEVERE`:
++
+```
+00000036 ~ Dec 8, 2006 10:05:55 AM PST ~ 10 ~ 4508606 ~ null
+ ~ null ~ HPT4Messages.createSQLException("en_US",
--- End diff --
Remove HP
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675315
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_overview.adoc ---
@@ -0,0 +1,245 @@
+////
+/**
+ *@@@ 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-properties]]
+= Type 4 Driver Properties
+
+[[summary-of-type-4-driver-properties]]
+== Summary of Type 4 Driver Properties
+
+Type 4 driver properties that effect client-side operations are
+summarized in the following tables. For the detailed description, click
+the link provided in the property name.
+
+NOTE: Unless otherwise noted in the brief description, the particular
+property applies to the `DataSource` object, `DriverManager` object, and
+`ConnectionPoolDataSource` object.
+
+[[client-side-properties]]
+=== Client-Side Properties
+
+*Connection-Control Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<dataSourceName, dataSourceName>>` | Specifies the registered DataSource or ConnectionPoolDataSource name. (Can be set only on the DriverManager object.) | None.
+| `<<loginTimeout, loginTimeout>>` | Sets the time limit that a connection can be attempted before the connection disconnects. | 60 (seconds)
+| `<<networkTimeout, networkTimeout>>` | Sets a time limit that the driver waits for a reply from the database server. | 0 (No network timeout is specified.
+|===
+
+*Pooling Management Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<initialPoolSize, initialPoolSize>>` | Sets the initial connection pool size when connection pooling is used with the Type 4 driver. (Ignored for
+connections made through the ConnectionPoolDataSource object.) | -1 (Do not create an initial connection pool.)
+| `<<maxIdleTime, maxIdleTime>>` | Sets the number of seconds that a physical connection can remain unused in the pool before the connection is closed. | 0 (Specifies no limit.)
+| `<<maxPoolSize, maxPoolSize>>` | Sets the maximum number of physical connections that the pool can contain. | -1 (Disables connection pooling.)
+| `<<maxStatements, maxStatements>>` | Sets the total number of PreparedStatement objects that the connection pool should cache. | 0 (Disables statement pooling.)
+| `<<minPoolSize, minPoolSize>>` | Limits the number of physical connections that can be in the free connection pool. | -1 (The minPoolSize value is ignored.)
+|===
+
+////
+*Operations on CLOB and BLOB Data*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<blobTableName, blobTableName>>` | Specifies the LOB table for using BLOB columns. | None.
+| `<<clobTableName, clobTableName>>` | Specifies the LOB table for using CLOB columns. | None.
+| `<<reserveDataLocators,reserveDataLocators>>` | Sets the number of data locators to be reserved for a process that stores data in a LOB table. | 100
+|===
+////
+
+<<<
+*Internationalization Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<ISO88591, ISO88591>>` | Sets character-set mapping that corresponds to the ISO88591 character set. | ISO88591_1
+| `<<KANJI, KANJI>>` | Sets character-set mapping that corresponds to the KANJI character set. | SJIS (which is shift-JIS, Japanese)
+| `<<KSC5601, KSC5601>>` | Sets character-set mapping that corresponds to the KSC5601 character set. | ECU_KR (which is KS C 5601, ECU encoding, Korean)
+| `<<language, language>>` | Sets the language used for error messages. | None.
+| `<<translationVerification, translationVerification>>` | Defines the behavior of the driver if the driver cannot translate all or part of an SQL statement or SQL parameter. | FALSE
+|===
+
+*Logging and Tracing Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<T4LogFile, T4LogFile>>` | Sets the name of the logging file for the Type 4 driver. | The name is defined by the following pattern: `%h/hpt4jdbc%u.log`
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673429
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
+== reserveDataLocators Property
+
+The `reserveDataLocators` property sets the number of data locators to be
+reserved for a process that stores data in a LOB table.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of data locators to be reserved
+
+Default: 100
+
+Range: 1 to 9,223,372,036,854,775,807 (2**63 -1)
+```
+
+Do not set a value much greater than the number of data locators
+actually needed. If the specified value is 0 (zero) or less, the default
+value (100) is used.
+
+Base the setting of the value of the `reserveDataLocators` property on the
+application profile being executed. If the application inserts a large
+number of LOB items, then a higher value of the `reserveDataLocators` property
+can prevent frequent updating of the `ZZ_DATA_LOCATOR` value in the LOB
+table. However, if the application inserts only a small number of LOB
+items, then a smaller value is better. If a large value is used, then holes
+(unused data-locator numbers) could occur in the LOB table. These holes
+represent unused space.
+
+Also, the administrator should avoid setting high values for the
+`reserveDataLocators` (for example, in the range of trillions or so).
+Setting high values prevents other Type 4 applications that use LOB
+table from reserving data locators.
+
+For additional information about data locator use, see
+<<reserving-data-locators, Reserving Data Locators>>.
+
+To change this value for a JDBC application, specify this property from
+the command line.
+
+*Example*
+
+The following command reserves 150 data
+locators for program class `myProgramClass`.
+
+```
+java -Dhpt4jdbc.reserveDataLocators=150 myProgramClass
+```
+
+<<<
+[[roundingmode]]
+== roundingMode Property
+
+The `roundingMode` property specifies the rounding behavior of the Type 4
+driver. For example, if the data is 1234.127 and column definition is
+`NUMERIC(6, 2)` and the application does `setDouble()` and `getDouble()`,
+then the value returned is 1234.12, which is truncated as specified by the
+default rounding mode, `ROUND_DOWN`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ROUND_DOWN
+```
+
+Values for roundingMode are:
+
+```
+ROUND_CEILING
+
+ROUND_DOWN
+
+ROUND_FLOOR
+
+ROUND_HALF_DOWN
+
+ROUND_HALF_EVEN
+
+ROUND_HALF_UP
+
+ROUND_UNNECESSARY
+
+ROUND_UP
+```
+
+* For the definition of rounding mode values, see the
+https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html[java.math.BigDecimal] documentation.
+
+* If the application sets erroneous values for the `roundingMode` property, no error is thrown by the Type 4 driver.
+The driver uses `ROUND_DOWN` value instead.
+
+* To have the application get the `DataTruncation` exception when data is
+truncated, set the `roundingMode` property to `ROUND_UNNECESSARY`.
+
+<<<
+[[schema]]
+== schema Property
+
+The `schema` property sets the database schema that accesses SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+schema=sales
+```
+
+<<<
+[[t4logfile]]
+== T4LogFile Property
+
+The `T4LogFile` property sets the name of the logging file for the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+```
+
+Default file name is defined by the following pattern:
+
+```
+%h/hpt4jdbc%u.log
+```
+
+where
+
+* `/` represents the local pathname separator.
+
+* `%h` represents the value of the user.home system property. _%u_
+represents a unique number to resolve conflicts.
+
+Any valid file name for your system is allowed.
+
+If you explicitly specify a log file, then that file is overwritten each time
+a `FileHandler` is established using that file name.
+
+To retain previously created log files, use the standard
+`java.util.logging `file syntax to append a unique number onto each log
+file.
+
+*Example*
+
+You can have the following property in a data source:
+
+```
+T4LogFile = C:/temp/MyLogFile%u.log
+```
+
+That name causes the Type 4 driver to create a new log file using a
+unique name for each connection made through that data source.
+
+<<<
+*Example*
+
+```
+C:/temp/MyLogFile43289.log
+
+C:/temp/MyLogFile87634.log
+
+C:/temp/MyLogFile27794.log
+```
+
+If you explicitly specify a log file that is not fully qualified, the
+Type 4 driver creates the file in the current working directory, for
+example, in the directory from which the JVM was invoked.
+
+For detailed information about java.util.logging, see the
+https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[logging summary] documentation.
+
+<<<
+[[t4loglevel]]
+== T4LogLevel Property
+
+The `T4LogLevel` property sets the logging levels that control logging
+output for the Type 4 driver. The Java package java.util.logging logs
+error messages and traces messages in the driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: OFF
+```
+
+*Logging Levels*
+[cols="20%,80%",options="header" ]
+|===
+| Level | Description
+| `OFF` | A special level that turns off logging; the default setting.
+| `SEVERE` | Indicates a serious failure; usually applies to SQL exceptions generated by the Type 4 driver.
+| `WARNING` | Indicates a potential problem, which usually applies to SQL warnings generated by the Type 4 driver.
+| `INFO` | Provides informational messages, typically about connection pooling, statement pooling, and resource usage. This information can
+help in tuning application performance.
+| `CONFIG` | Provides static configuration messages that can include property values and other Type 4 driver configuration information.
+| `FINE` | Provides tracing information from the Type 4 driver methods described in the Type 4 driver API. The level of tracing is equivalent
+to the level of tracing provided when calling the `setLogWriter()` method of the `DriverManager` class or the DataSource class.
+| `FINER` | Indicates a detailed tracing message for which internal Type 4 driver methods provide messages. These messages can be useful in debugging the Type 4 driver.
+| `FINEST` | Indicates a highly detailed tracing message. The driver provides detailed internal data messages that can be useful in debugging the Type 4 driver.
+| `ALL` |Logs all messages.
+|===
+
+*Example*
+
+To enable tracing, use the `hpt4jdbc.T4LogLevel` property specified in the command line:
+
+```
+-Dhpt4jdbc.T4LogLevel=FINE
+```
+
+<<<
+[[t4loglevel-considerations]]
+=== T4LogLevel Considerations
+
+* If a security manager is defined by your application using an AppServer,
+then `LoggingPermission` must be must be granted in the `java.policy` file as
+follows:
++
+```
+permission java.util.logging.LoggingPermission "control", "" ;
+```
+
+* The Type 4 driver is not designed to inherit the `java.util.logging.FileHandler.level` settings at program startup.
+
+<<<
+[[translationverification]]
+== translationVerification Property
+
+The `translationVerification` property defines the behavior of the driver
+if the driver cannot translate all or part of an SQL statement or SQL
+parameter.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The value can be TRUE or FALSE.
+
+```
+Data type: String
+
+Default: FALSE
+```
+
+
+[cols="10%,45%,45%", options="header"]
+|===
+| Value | Scenario | What Happens
+| `FALSE` | The driver is unable to 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.
+| `TRUE` | The driver cannot translation all or part of an SQL statement or parameter. | The driver throws an SQLException with this 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.
+|===
+
+NOTE: If the `translationVerification` property is set to TRUE, then the process can
+use significantly more system resources. For better performance, set this property to FALSE.
+
+For more information, see <<internationalization-support, Internationalization Support>>.
+
+<<<
+[[url]]
+== url Property
+
+The `url` property sets the URL value for the database.
+This property is used in the `DriverManager` object. The format
+to specify the URL is:
+
+```
+jdbc:hpt4jdbc//<primary IP addr or hostname of database>:37800/[:]
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61669998
--- Diff: 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
--- End diff --
jdbc.t4
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61669973
--- Diff: 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`
--- End diff --
For all of BLOB and CLOB section will let Sandhya review
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673063
--- Diff: 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]...]
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61670047
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
--- End diff --
change seabase to TRAFODION
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675360
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_overview.adoc ---
@@ -0,0 +1,245 @@
+////
+/**
+ *@@@ 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-properties]]
+= Type 4 Driver Properties
+
+[[summary-of-type-4-driver-properties]]
+== Summary of Type 4 Driver Properties
+
+Type 4 driver properties that effect client-side operations are
+summarized in the following tables. For the detailed description, click
+the link provided in the property name.
+
+NOTE: Unless otherwise noted in the brief description, the particular
+property applies to the `DataSource` object, `DriverManager` object, and
+`ConnectionPoolDataSource` object.
+
+[[client-side-properties]]
+=== Client-Side Properties
+
+*Connection-Control Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<dataSourceName, dataSourceName>>` | Specifies the registered DataSource or ConnectionPoolDataSource name. (Can be set only on the DriverManager object.) | None.
+| `<<loginTimeout, loginTimeout>>` | Sets the time limit that a connection can be attempted before the connection disconnects. | 60 (seconds)
+| `<<networkTimeout, networkTimeout>>` | Sets a time limit that the driver waits for a reply from the database server. | 0 (No network timeout is specified.
+|===
+
+*Pooling Management Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<initialPoolSize, initialPoolSize>>` | Sets the initial connection pool size when connection pooling is used with the Type 4 driver. (Ignored for
+connections made through the ConnectionPoolDataSource object.) | -1 (Do not create an initial connection pool.)
+| `<<maxIdleTime, maxIdleTime>>` | Sets the number of seconds that a physical connection can remain unused in the pool before the connection is closed. | 0 (Specifies no limit.)
+| `<<maxPoolSize, maxPoolSize>>` | Sets the maximum number of physical connections that the pool can contain. | -1 (Disables connection pooling.)
+| `<<maxStatements, maxStatements>>` | Sets the total number of PreparedStatement objects that the connection pool should cache. | 0 (Disables statement pooling.)
+| `<<minPoolSize, minPoolSize>>` | Limits the number of physical connections that can be in the free connection pool. | -1 (The minPoolSize value is ignored.)
+|===
+
+////
+*Operations on CLOB and BLOB Data*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<blobTableName, blobTableName>>` | Specifies the LOB table for using BLOB columns. | None.
+| `<<clobTableName, clobTableName>>` | Specifies the LOB table for using CLOB columns. | None.
+| `<<reserveDataLocators,reserveDataLocators>>` | Sets the number of data locators to be reserved for a process that stores data in a LOB table. | 100
+|===
+////
+
+<<<
+*Internationalization Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<ISO88591, ISO88591>>` | Sets character-set mapping that corresponds to the ISO88591 character set. | ISO88591_1
+| `<<KANJI, KANJI>>` | Sets character-set mapping that corresponds to the KANJI character set. | SJIS (which is shift-JIS, Japanese)
+| `<<KSC5601, KSC5601>>` | Sets character-set mapping that corresponds to the KSC5601 character set. | ECU_KR (which is KS C 5601, ECU encoding, Korean)
+| `<<language, language>>` | Sets the language used for error messages. | None.
+| `<<translationVerification, translationVerification>>` | Defines the behavior of the driver if the driver cannot translate all or part of an SQL statement or SQL parameter. | FALSE
+|===
+
+*Logging and Tracing Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<T4LogFile, T4LogFile>>` | Sets the name of the logging file for the Type 4 driver. | The name is defined by the following pattern: `%h/hpt4jdbc%u.log`
+| `<<T4LogLevel, T4LogLevel>>` | Sets the logging levels that control logging output for the Type 4 driver. | OFF
+|===
+
+*Miscellaneous Client-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<description, description>>` | Specifies the registered source name. | None.
+| `<<fetchBufferSize, fetchBufferSize>>` | Provides the benefits of bulk fetch when rows are fetched from a `ResultSet` object. | 4 kilobytes
+| `<<properties, properties>>` | Specifies the location of the properties file that contains keyword-value pairs
+that specify property values for configuring the Type 4 driver. | None.
+| `<<roundingMode, roundingMode>>` | Specifies the rounding behavior of the Type 4 driver. | ROUND_DOWN
+|===
+
+<<<
+[[server-side-properties]]
+=== Server-Side Properties
+
+The Type 4 driver properties that effect server-side operations are
+summarized in the following tables. Unless otherwise noted in the
+description, the particular property applies to the DataSource object,
+`DriverManager` object, and `ConnectionPoolDataSource` object.
+
+*Type 4 Driver Server-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<catalog, catalog>>` | Sets the default catalog used to access SQL objects referenced in SQL
+statements if the SQL objects are not fully qualified. | None. Must be "Seabase" in the current release.
+| `<<connectionTimeout, connectionTimeout>>` | Sets the number of seconds a connection can be idle before the connection is physically closed by DCS. |
+-1 (Use the ConnTimeout value set on the server data source.)
+| `<<password, password>>` | Sets the password value for passing to the database. Can also change the password. | Empty string.
+| `<<schema, schema>>` | Sets the database schema that accesses SQL objects referenced in SQL statements if the SQL objects are not fully qualified. | None.
+| `<<url, url>>` | Sets the URL value for the database. Can be set only on the `DriverManager` object. | None.
+| `<<user, user>>` | Sets the user value for the database. | None.
+|===
+
+[[how-to-specify-jdbc-type-4-properties]]
+== How to Specify JDBC Type 4 Properties
+
+The Type 4 JDBC driver properties configure the driver. These properties
+can be specified in a data source, a connection URL (the primary IP
+address or host name on the database), a properties file,
+or in the java command line.
+
+Java properties have the form:
+
+```
+key=value
+```
+
+At run time, the driver looks for a specific set of property keys and
+takes action based on their associated values.
+
+<<<
+[[where-to-set-properties]]
+=== Where to Set Properties
+
+* For connections made through a `DataSource` or a `ConnectionPoolDataSource`,
+set the property on the `DataSource` or the `ConnectionPoolDataSource` object.
+
+* For the `DriverManager` class, set properties in either of two ways:
++
+1. Using the option `-Dproperty_name=property_value` in the command line.
+2. Using the `java.util.Properties` parameter in the `getConnection()` method
+of the `DriverManager` class.
+
+[[creating-and-using-a-properties-file]]
+=== Creating and Using a Properties File
+
+JDBC applications can provide property values to configure a connection
+by using a file that contains properties for the JDBC driver. This
+property file is passed as a java command-line parameter. The format to
+enter the properties file in the command line is:
+
+```
+-Dhpt4jdbc.properties=<path of the properties file on disk>`
+```
+
+*Example*
+
+```
+-Dhpt4jdbc.properties=C:\temp\t4props\myprops.properties
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61672979
--- Diff: 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
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61670102
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
+== reserveDataLocators Property
+
+The `reserveDataLocators` property sets the number of data locators to be
+reserved for a process that stores data in a LOB table.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of data locators to be reserved
+
+Default: 100
+
+Range: 1 to 9,223,372,036,854,775,807 (2**63 -1)
+```
+
+Do not set a value much greater than the number of data locators
+actually needed. If the specified value is 0 (zero) or less, the default
+value (100) is used.
+
+Base the setting of the value of the `reserveDataLocators` property on the
+application profile being executed. If the application inserts a large
+number of LOB items, then a higher value of the `reserveDataLocators` property
+can prevent frequent updating of the `ZZ_DATA_LOCATOR` value in the LOB
+table. However, if the application inserts only a small number of LOB
+items, then a smaller value is better. If a large value is used, then holes
+(unused data-locator numbers) could occur in the LOB table. These holes
+represent unused space.
+
+Also, the administrator should avoid setting high values for the
+`reserveDataLocators` (for example, in the range of trillions or so).
+Setting high values prevents other Type 4 applications that use LOB
+table from reserving data locators.
+
+For additional information about data locator use, see
+<<reserving-data-locators, Reserving Data Locators>>.
+
+To change this value for a JDBC application, specify this property from
+the command line.
+
+*Example*
+
+The following command reserves 150 data
+locators for program class `myProgramClass`.
+
+```
+java -Dhpt4jdbc.reserveDataLocators=150 myProgramClass
+```
+
+<<<
+[[roundingmode]]
+== roundingMode Property
+
+The `roundingMode` property specifies the rounding behavior of the Type 4
+driver. For example, if the data is 1234.127 and column definition is
+`NUMERIC(6, 2)` and the application does `setDouble()` and `getDouble()`,
+then the value returned is 1234.12, which is truncated as specified by the
+default rounding mode, `ROUND_DOWN`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ROUND_DOWN
+```
+
+Values for roundingMode are:
+
+```
+ROUND_CEILING
+
+ROUND_DOWN
+
+ROUND_FLOOR
+
+ROUND_HALF_DOWN
+
+ROUND_HALF_EVEN
+
+ROUND_HALF_UP
+
+ROUND_UNNECESSARY
+
+ROUND_UP
+```
+
+* For the definition of rounding mode values, see the
+https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html[java.math.BigDecimal] documentation.
+
+* If the application sets erroneous values for the `roundingMode` property, no error is thrown by the Type 4 driver.
+The driver uses `ROUND_DOWN` value instead.
+
+* To have the application get the `DataTruncation` exception when data is
+truncated, set the `roundingMode` property to `ROUND_UNNECESSARY`.
+
+<<<
+[[schema]]
+== schema Property
+
+The `schema` property sets the database schema that accesses SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+schema=sales
+```
+
+<<<
+[[t4logfile]]
+== T4LogFile Property
+
+The `T4LogFile` property sets the name of the logging file for the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+```
+
+Default file name is defined by the following pattern:
+
+```
+%h/hpt4jdbc%u.log
+```
+
+where
+
+* `/` represents the local pathname separator.
+
+* `%h` represents the value of the user.home system property. _%u_
+represents a unique number to resolve conflicts.
+
+Any valid file name for your system is allowed.
+
+If you explicitly specify a log file, then that file is overwritten each time
+a `FileHandler` is established using that file name.
+
+To retain previously created log files, use the standard
+`java.util.logging `file syntax to append a unique number onto each log
+file.
+
+*Example*
+
+You can have the following property in a data source:
+
+```
+T4LogFile = C:/temp/MyLogFile%u.log
+```
+
+That name causes the Type 4 driver to create a new log file using a
+unique name for each connection made through that data source.
+
+<<<
+*Example*
+
+```
+C:/temp/MyLogFile43289.log
+
+C:/temp/MyLogFile87634.log
+
+C:/temp/MyLogFile27794.log
+```
+
+If you explicitly specify a log file that is not fully qualified, the
+Type 4 driver creates the file in the current working directory, for
+example, in the directory from which the JVM was invoked.
+
+For detailed information about java.util.logging, see the
+https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[logging summary] documentation.
+
+<<<
+[[t4loglevel]]
+== T4LogLevel Property
+
+The `T4LogLevel` property sets the logging levels that control logging
+output for the Type 4 driver. The Java package java.util.logging logs
+error messages and traces messages in the driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: OFF
+```
+
+*Logging Levels*
+[cols="20%,80%",options="header" ]
+|===
+| Level | Description
+| `OFF` | A special level that turns off logging; the default setting.
+| `SEVERE` | Indicates a serious failure; usually applies to SQL exceptions generated by the Type 4 driver.
+| `WARNING` | Indicates a potential problem, which usually applies to SQL warnings generated by the Type 4 driver.
+| `INFO` | Provides informational messages, typically about connection pooling, statement pooling, and resource usage. This information can
+help in tuning application performance.
+| `CONFIG` | Provides static configuration messages that can include property values and other Type 4 driver configuration information.
+| `FINE` | Provides tracing information from the Type 4 driver methods described in the Type 4 driver API. The level of tracing is equivalent
+to the level of tracing provided when calling the `setLogWriter()` method of the `DriverManager` class or the DataSource class.
+| `FINER` | Indicates a detailed tracing message for which internal Type 4 driver methods provide messages. These messages can be useful in debugging the Type 4 driver.
+| `FINEST` | Indicates a highly detailed tracing message. The driver provides detailed internal data messages that can be useful in debugging the Type 4 driver.
+| `ALL` |Logs all messages.
+|===
+
+*Example*
+
+To enable tracing, use the `hpt4jdbc.T4LogLevel` property specified in the command line:
+
+```
+-Dhpt4jdbc.T4LogLevel=FINE
+```
+
+<<<
+[[t4loglevel-considerations]]
+=== T4LogLevel Considerations
+
+* If a security manager is defined by your application using an AppServer,
+then `LoggingPermission` must be must be granted in the `java.policy` file as
+follows:
++
+```
+permission java.util.logging.LoggingPermission "control", "" ;
+```
+
+* The Type 4 driver is not designed to inherit the `java.util.logging.FileHandler.level` settings at program startup.
+
+<<<
+[[translationverification]]
+== translationVerification Property
+
+The `translationVerification` property defines the behavior of the driver
+if the driver cannot translate all or part of an SQL statement or SQL
+parameter.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The value can be TRUE or FALSE.
+
+```
+Data type: String
+
+Default: FALSE
+```
+
+
+[cols="10%,45%,45%", options="header"]
+|===
+| Value | Scenario | What Happens
+| `FALSE` | The driver is unable to 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.
+| `TRUE` | The driver cannot translation all or part of an SQL statement or parameter. | The driver throws an SQLException with this 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.
+|===
+
+NOTE: If the `translationVerification` property is set to TRUE, then the process can
+use significantly more system resources. For better performance, set this property to FALSE.
+
+For more information, see <<internationalization-support, Internationalization Support>>.
+
+<<<
+[[url]]
+== url Property
+
+The `url` property sets the URL value for the database.
+This property is used in the `DriverManager` object. The format
+to specify the URL is:
+
+```
+jdbc:hpt4jdbc//<primary IP addr or hostname of database>:37800/[:]
--- End diff --
fix this url
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673374
--- Diff: 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
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61670098
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
+== reserveDataLocators Property
+
+The `reserveDataLocators` property sets the number of data locators to be
+reserved for a process that stores data in a LOB table.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of data locators to be reserved
+
+Default: 100
+
+Range: 1 to 9,223,372,036,854,775,807 (2**63 -1)
+```
+
+Do not set a value much greater than the number of data locators
+actually needed. If the specified value is 0 (zero) or less, the default
+value (100) is used.
+
+Base the setting of the value of the `reserveDataLocators` property on the
+application profile being executed. If the application inserts a large
+number of LOB items, then a higher value of the `reserveDataLocators` property
+can prevent frequent updating of the `ZZ_DATA_LOCATOR` value in the LOB
+table. However, if the application inserts only a small number of LOB
+items, then a smaller value is better. If a large value is used, then holes
+(unused data-locator numbers) could occur in the LOB table. These holes
+represent unused space.
+
+Also, the administrator should avoid setting high values for the
+`reserveDataLocators` (for example, in the range of trillions or so).
+Setting high values prevents other Type 4 applications that use LOB
+table from reserving data locators.
+
+For additional information about data locator use, see
+<<reserving-data-locators, Reserving Data Locators>>.
+
+To change this value for a JDBC application, specify this property from
+the command line.
+
+*Example*
+
+The following command reserves 150 data
+locators for program class `myProgramClass`.
+
+```
+java -Dhpt4jdbc.reserveDataLocators=150 myProgramClass
+```
+
+<<<
+[[roundingmode]]
+== roundingMode Property
+
+The `roundingMode` property specifies the rounding behavior of the Type 4
+driver. For example, if the data is 1234.127 and column definition is
+`NUMERIC(6, 2)` and the application does `setDouble()` and `getDouble()`,
+then the value returned is 1234.12, which is truncated as specified by the
+default rounding mode, `ROUND_DOWN`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ROUND_DOWN
+```
+
+Values for roundingMode are:
+
+```
+ROUND_CEILING
+
+ROUND_DOWN
+
+ROUND_FLOOR
+
+ROUND_HALF_DOWN
+
+ROUND_HALF_EVEN
+
+ROUND_HALF_UP
+
+ROUND_UNNECESSARY
+
+ROUND_UP
+```
+
+* For the definition of rounding mode values, see the
+https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html[java.math.BigDecimal] documentation.
+
+* If the application sets erroneous values for the `roundingMode` property, no error is thrown by the Type 4 driver.
+The driver uses `ROUND_DOWN` value instead.
+
+* To have the application get the `DataTruncation` exception when data is
+truncated, set the `roundingMode` property to `ROUND_UNNECESSARY`.
+
+<<<
+[[schema]]
+== schema Property
+
+The `schema` property sets the database schema that accesses SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+schema=sales
+```
+
+<<<
+[[t4logfile]]
+== T4LogFile Property
+
+The `T4LogFile` property sets the name of the logging file for the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+```
+
+Default file name is defined by the following pattern:
+
+```
+%h/hpt4jdbc%u.log
+```
+
+where
+
+* `/` represents the local pathname separator.
+
+* `%h` represents the value of the user.home system property. _%u_
+represents a unique number to resolve conflicts.
+
+Any valid file name for your system is allowed.
+
+If you explicitly specify a log file, then that file is overwritten each time
+a `FileHandler` is established using that file name.
+
+To retain previously created log files, use the standard
+`java.util.logging `file syntax to append a unique number onto each log
+file.
+
+*Example*
+
+You can have the following property in a data source:
+
+```
+T4LogFile = C:/temp/MyLogFile%u.log
+```
+
+That name causes the Type 4 driver to create a new log file using a
+unique name for each connection made through that data source.
+
+<<<
+*Example*
+
+```
+C:/temp/MyLogFile43289.log
+
+C:/temp/MyLogFile87634.log
+
+C:/temp/MyLogFile27794.log
+```
+
+If you explicitly specify a log file that is not fully qualified, the
+Type 4 driver creates the file in the current working directory, for
+example, in the directory from which the JVM was invoked.
+
+For detailed information about java.util.logging, see the
+https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[logging summary] documentation.
+
+<<<
+[[t4loglevel]]
+== T4LogLevel Property
+
+The `T4LogLevel` property sets the logging levels that control logging
+output for the Type 4 driver. The Java package java.util.logging logs
+error messages and traces messages in the driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: OFF
+```
+
+*Logging Levels*
+[cols="20%,80%",options="header" ]
+|===
+| Level | Description
+| `OFF` | A special level that turns off logging; the default setting.
+| `SEVERE` | Indicates a serious failure; usually applies to SQL exceptions generated by the Type 4 driver.
+| `WARNING` | Indicates a potential problem, which usually applies to SQL warnings generated by the Type 4 driver.
+| `INFO` | Provides informational messages, typically about connection pooling, statement pooling, and resource usage. This information can
+help in tuning application performance.
+| `CONFIG` | Provides static configuration messages that can include property values and other Type 4 driver configuration information.
+| `FINE` | Provides tracing information from the Type 4 driver methods described in the Type 4 driver API. The level of tracing is equivalent
+to the level of tracing provided when calling the `setLogWriter()` method of the `DriverManager` class or the DataSource class.
+| `FINER` | Indicates a detailed tracing message for which internal Type 4 driver methods provide messages. These messages can be useful in debugging the Type 4 driver.
+| `FINEST` | Indicates a highly detailed tracing message. The driver provides detailed internal data messages that can be useful in debugging the Type 4 driver.
+| `ALL` |Logs all messages.
+|===
+
+*Example*
+
+To enable tracing, use the `hpt4jdbc.T4LogLevel` property specified in the command line:
+
+```
+-Dhpt4jdbc.T4LogLevel=FINE
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675402
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_overview.adoc ---
@@ -0,0 +1,245 @@
+////
+/**
+ *@@@ 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-properties]]
+= Type 4 Driver Properties
+
+[[summary-of-type-4-driver-properties]]
+== Summary of Type 4 Driver Properties
+
+Type 4 driver properties that effect client-side operations are
+summarized in the following tables. For the detailed description, click
+the link provided in the property name.
+
+NOTE: Unless otherwise noted in the brief description, the particular
+property applies to the `DataSource` object, `DriverManager` object, and
+`ConnectionPoolDataSource` object.
+
+[[client-side-properties]]
+=== Client-Side Properties
+
+*Connection-Control Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<dataSourceName, dataSourceName>>` | Specifies the registered DataSource or ConnectionPoolDataSource name. (Can be set only on the DriverManager object.) | None.
+| `<<loginTimeout, loginTimeout>>` | Sets the time limit that a connection can be attempted before the connection disconnects. | 60 (seconds)
+| `<<networkTimeout, networkTimeout>>` | Sets a time limit that the driver waits for a reply from the database server. | 0 (No network timeout is specified.
+|===
+
+*Pooling Management Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<initialPoolSize, initialPoolSize>>` | Sets the initial connection pool size when connection pooling is used with the Type 4 driver. (Ignored for
+connections made through the ConnectionPoolDataSource object.) | -1 (Do not create an initial connection pool.)
+| `<<maxIdleTime, maxIdleTime>>` | Sets the number of seconds that a physical connection can remain unused in the pool before the connection is closed. | 0 (Specifies no limit.)
+| `<<maxPoolSize, maxPoolSize>>` | Sets the maximum number of physical connections that the pool can contain. | -1 (Disables connection pooling.)
+| `<<maxStatements, maxStatements>>` | Sets the total number of PreparedStatement objects that the connection pool should cache. | 0 (Disables statement pooling.)
+| `<<minPoolSize, minPoolSize>>` | Limits the number of physical connections that can be in the free connection pool. | -1 (The minPoolSize value is ignored.)
+|===
+
+////
+*Operations on CLOB and BLOB Data*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<blobTableName, blobTableName>>` | Specifies the LOB table for using BLOB columns. | None.
+| `<<clobTableName, clobTableName>>` | Specifies the LOB table for using CLOB columns. | None.
+| `<<reserveDataLocators,reserveDataLocators>>` | Sets the number of data locators to be reserved for a process that stores data in a LOB table. | 100
+|===
+////
+
+<<<
+*Internationalization Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<ISO88591, ISO88591>>` | Sets character-set mapping that corresponds to the ISO88591 character set. | ISO88591_1
+| `<<KANJI, KANJI>>` | Sets character-set mapping that corresponds to the KANJI character set. | SJIS (which is shift-JIS, Japanese)
+| `<<KSC5601, KSC5601>>` | Sets character-set mapping that corresponds to the KSC5601 character set. | ECU_KR (which is KS C 5601, ECU encoding, Korean)
+| `<<language, language>>` | Sets the language used for error messages. | None.
+| `<<translationVerification, translationVerification>>` | Defines the behavior of the driver if the driver cannot translate all or part of an SQL statement or SQL parameter. | FALSE
+|===
+
+*Logging and Tracing Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<T4LogFile, T4LogFile>>` | Sets the name of the logging file for the Type 4 driver. | The name is defined by the following pattern: `%h/hpt4jdbc%u.log`
+| `<<T4LogLevel, T4LogLevel>>` | Sets the logging levels that control logging output for the Type 4 driver. | OFF
+|===
+
+*Miscellaneous Client-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<description, description>>` | Specifies the registered source name. | None.
+| `<<fetchBufferSize, fetchBufferSize>>` | Provides the benefits of bulk fetch when rows are fetched from a `ResultSet` object. | 4 kilobytes
+| `<<properties, properties>>` | Specifies the location of the properties file that contains keyword-value pairs
+that specify property values for configuring the Type 4 driver. | None.
+| `<<roundingMode, roundingMode>>` | Specifies the rounding behavior of the Type 4 driver. | ROUND_DOWN
+|===
+
+<<<
+[[server-side-properties]]
+=== Server-Side Properties
+
+The Type 4 driver properties that effect server-side operations are
+summarized in the following tables. Unless otherwise noted in the
+description, the particular property applies to the DataSource object,
+`DriverManager` object, and `ConnectionPoolDataSource` object.
+
+*Type 4 Driver Server-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<catalog, catalog>>` | Sets the default catalog used to access SQL objects referenced in SQL
+statements if the SQL objects are not fully qualified. | None. Must be "Seabase" in the current release.
+| `<<connectionTimeout, connectionTimeout>>` | Sets the number of seconds a connection can be idle before the connection is physically closed by DCS. |
+-1 (Use the ConnTimeout value set on the server data source.)
+| `<<password, password>>` | Sets the password value for passing to the database. Can also change the password. | Empty string.
+| `<<schema, schema>>` | Sets the database schema that accesses SQL objects referenced in SQL statements if the SQL objects are not fully qualified. | None.
+| `<<url, url>>` | Sets the URL value for the database. Can be set only on the `DriverManager` object. | None.
+| `<<user, user>>` | Sets the user value for the database. | None.
+|===
+
+[[how-to-specify-jdbc-type-4-properties]]
+== How to Specify JDBC Type 4 Properties
+
+The Type 4 JDBC driver properties configure the driver. These properties
+can be specified in a data source, a connection URL (the primary IP
+address or host name on the database), a properties file,
+or in the java command line.
+
+Java properties have the form:
+
+```
+key=value
+```
+
+At run time, the driver looks for a specific set of property keys and
+takes action based on their associated values.
+
+<<<
+[[where-to-set-properties]]
+=== Where to Set Properties
+
+* For connections made through a `DataSource` or a `ConnectionPoolDataSource`,
+set the property on the `DataSource` or the `ConnectionPoolDataSource` object.
+
+* For the `DriverManager` class, set properties in either of two ways:
++
+1. Using the option `-Dproperty_name=property_value` in the command line.
+2. Using the `java.util.Properties` parameter in the `getConnection()` method
+of the `DriverManager` class.
+
+[[creating-and-using-a-properties-file]]
+=== Creating and Using a Properties File
+
+JDBC applications can provide property values to configure a connection
+by using a file that contains properties for the JDBC driver. This
+property file is passed as a java command-line parameter. The format to
+enter the properties file in the command line is:
+
+```
+-Dhpt4jdbc.properties=<path of the properties file on disk>`
+```
+
+*Example*
+
+```
+-Dhpt4jdbc.properties=C:\temp\t4props\myprops.properties
+```
+
+To create the file, use the editor of your choice on your workstation to
+type in the property values. The entries in properties file must have a
+`property_name=property_value` value-pair format:
+
+```
+property_name=property_value
+```
+
+*Example*
+
+```
+maxStatements=1024
+```
+
+To configure a `DataSource` connection, the properties file might contain
+property names and values as indicated in the following list:
+
+```
+url=jdbc:hpt4jdbc://<primary IP addr or host name of database>:37800/
+user=database_username
+password=mypassword
+description=<a string>
+catalog=Seabase
+schema=myschema
+maxPoolSize=20
+minPoolSize=5
+maxStatements=20
+loginTimeout=15
+initialPoolSize=10
+connectionTimeout=10
+serverDataSource=server_data_source
+T4LogLevel=OFF
+T4LogFile=/mylogdirectory/mylogfile
+```
+
+[[setting-properties-in-the-command-line]]
+=== Setting Properties in the Command Line
+
+When a Type 4 driver property is specified on the command line through
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675642
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/tracing_logging.adoc ---
@@ -0,0 +1,195 @@
+////
+/**
+ *@@@ 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 @@@
+ */
+////
+
+[[tracing-and-logging-facilities]]
+= Tracing and Logging Facilities
+
+The Type 4 driver provides two tracing and logging facilities:
+
+* Standard JDBC tracing and logging functionality as defined by the JDBC standard
+* Type 4 driver logging facility
+
+Server-side tracing (logging) is enabled by configuring DCS.
+
+[[standard-jdbc-tracing-and-logging-facility]]
+== Standard JDBC Tracing and Logging Facility
+
+The JDBC standard provides a logging and tracing facility, which allows
+tracing JDBC method calls by setting the log writer. To set the log
+writer, either call the `setLogWriter()` method on the `DriverManager` class
+or call the `setLogWriter()` method on the `DataSource` class
+(or `ConnectionPoolDataSource` class).
+
+* A `DriverManager` log writer is a character output stream to which all
+logging and tracing messages for all connections made through the
+`DriverManager` are printed. This stream includes messages printed by the
+methods of this connection, messages printed by methods of other objects
+manufactured by the connection, and so on. The `DriverManager` log writer
+is initially null, that is, the default is for logging to be disabled.
+
+For information about using the setLogWriter method, see the
+https://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html[DriverManager class API].
+
+* A `DataSource` log writer is a character output stream to which all
+logging and tracing messages for this data source are printed. This
+stream includes messages printed by the methods of this object, messages
+printed by methods of other objects manufactured by this object, and so
+on. Messages printed to a data-source-specific log writer are not
+printed to the log writer associated with the `java.sql.DriverManager`
+class. When a `DataSource` object is created, the log writer is initially
+null; that is, the default is for logging to be disabled.
+
+For information about using the setLogWriter method, see the
+https://docs.oracle.com/cd/E16338_01/appdev.112/e13995/oracle/jdbc/pool/OracleDataSource.html[DriverSource interface API].
+
+<<<
+[[the-type-4-driver-logging-facility]]
+== The Type 4 Driver Logging Facility
+
+
+The Type 4 driver Logging facility allows you to retrieve internal
+tracing information, which you can use in debugging the driver. It also
+allows you to capture error and warning messages.
+
+In addition to the standard JDBC tracing and logging facility, the Type
+4 driver provides an independent logging facility (Type 4 Driver
+Logging). The Type 4 Driver Logging provides the same level of logging
+and tracing as the standard JDBC tracing and logging facility with the
+following additional information:
+
+* More detail about the internals of the Type 4 driver and internal tracing information
+* Type 4 driver performance-tuning information
+* Finer control over the amount and type of logging information
+* Error and warning messages
+
+[[accessing-the-type-4-driver-logging-facility]]
+=== Accessing the Type 4 Driver Logging Facility
+
+The Type 4 Driver Logging facility is based on the `java.util.logging`
+package. The Type 4 driver instantiates a `java.util.logging.Logger` class
+and names the logger `org.trafodion.jdbc.t4.logger`.
+
+Your JDBC program can access the Type 4 driver logger directly by
+calling the `java.util.logging.Logger` static method `getLogger(String)`.
+
+*example*
+
+[source, java]
+----
+String t4Logger =
+ java.util.logging.Logger.getLogger( "org.trafodion.jdbc.t4.logger" ) ;
+----
+
+<<<
+[[controlling-type-4-driver-logging-output]]
+=== Controlling Type 4 Driver Logging Output
+
+The Type 4 driver provides two properties that you can use to control logging output.
+
+* `T4LogLevel`: Specifies the level of logging. For information about using this property, see <<t4loglevel-property, T4LogLevel Property>>.
+* `T4LogFile`: Specifies the file to which the driver is to write logging information. For information about using this property,
+see <<t4logfile-property, T4LogFile Property>>.
+
+If the application sets several property values, see
+<<precedence-of-property-specifications, Precedence of Property Specifications>> to determine which setting applies.
+
+*Example*
+
+These properties file entries set the logging level to SEVERE and specify a log file name:
+
+```
+T4LogLevel= SEVERE
+
+T4LogFile=c:/T4logfile1.log
+```
+<<<
+[[message-format]]
+=== Message Format
+
+The format of the trace output is
+
+```
+sequence-number ~ time-stamp ~ thread-id
+~ [connection-id] ~ [server-id] ~ [dialogue-id]
+~ [class].[method][(parameters)] ~ [text]
+```
+
+
+[cols="30%,70%",options="header" ]
+|===
+| Identifier | Provides
+| `sequence-number` | A unique sequence number in increasing order.
+| `time-stamp` | The time of the message, for example 10/17/2004 12:48:23.
+| `thread-id` | The thread identifier within the Java VM.
+| `connection-id` | If applicable, a unique ID for the connection associated with the message.
+| `server-id` | If applicable, information about the connectivity server associated with the message. The _server-id_ is of the form: +
+ +
+`TCP:node-name.server-name/port-number:HPODBC` +
--- End diff --
Remove HP
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61669988
--- Diff: 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.
--- End diff --
Change HP to Database Connectivity Service(DCS)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673106
--- Diff: 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
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by DaveBirdsall <gi...@git.apache.org>.
Github user DaveBirdsall commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61657710
--- Diff: 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.)
--- End diff --
We still use "HP" in the class name... hmmm...
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673073
--- Diff: 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.
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665164
--- Diff: 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.
--- End diff --
This sentence can be "The password is encrypted" and remove the remaining text...
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673096
--- Diff: 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
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61670095
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
+== reserveDataLocators Property
+
+The `reserveDataLocators` property sets the number of data locators to be
+reserved for a process that stores data in a LOB table.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of data locators to be reserved
+
+Default: 100
+
+Range: 1 to 9,223,372,036,854,775,807 (2**63 -1)
+```
+
+Do not set a value much greater than the number of data locators
+actually needed. If the specified value is 0 (zero) or less, the default
+value (100) is used.
+
+Base the setting of the value of the `reserveDataLocators` property on the
+application profile being executed. If the application inserts a large
+number of LOB items, then a higher value of the `reserveDataLocators` property
+can prevent frequent updating of the `ZZ_DATA_LOCATOR` value in the LOB
+table. However, if the application inserts only a small number of LOB
+items, then a smaller value is better. If a large value is used, then holes
+(unused data-locator numbers) could occur in the LOB table. These holes
+represent unused space.
+
+Also, the administrator should avoid setting high values for the
+`reserveDataLocators` (for example, in the range of trillions or so).
+Setting high values prevents other Type 4 applications that use LOB
+table from reserving data locators.
+
+For additional information about data locator use, see
+<<reserving-data-locators, Reserving Data Locators>>.
+
+To change this value for a JDBC application, specify this property from
+the command line.
+
+*Example*
+
+The following command reserves 150 data
+locators for program class `myProgramClass`.
+
+```
+java -Dhpt4jdbc.reserveDataLocators=150 myProgramClass
+```
+
+<<<
+[[roundingmode]]
+== roundingMode Property
+
+The `roundingMode` property specifies the rounding behavior of the Type 4
+driver. For example, if the data is 1234.127 and column definition is
+`NUMERIC(6, 2)` and the application does `setDouble()` and `getDouble()`,
+then the value returned is 1234.12, which is truncated as specified by the
+default rounding mode, `ROUND_DOWN`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ROUND_DOWN
+```
+
+Values for roundingMode are:
+
+```
+ROUND_CEILING
+
+ROUND_DOWN
+
+ROUND_FLOOR
+
+ROUND_HALF_DOWN
+
+ROUND_HALF_EVEN
+
+ROUND_HALF_UP
+
+ROUND_UNNECESSARY
+
+ROUND_UP
+```
+
+* For the definition of rounding mode values, see the
+https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html[java.math.BigDecimal] documentation.
+
+* If the application sets erroneous values for the `roundingMode` property, no error is thrown by the Type 4 driver.
+The driver uses `ROUND_DOWN` value instead.
+
+* To have the application get the `DataTruncation` exception when data is
+truncated, set the `roundingMode` property to `ROUND_UNNECESSARY`.
+
+<<<
+[[schema]]
+== schema Property
+
+The `schema` property sets the database schema that accesses SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+schema=sales
+```
+
+<<<
+[[t4logfile]]
+== T4LogFile Property
+
+The `T4LogFile` property sets the name of the logging file for the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+```
+
+Default file name is defined by the following pattern:
+
+```
+%h/hpt4jdbc%u.log
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61670127
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
+== reserveDataLocators Property
+
+The `reserveDataLocators` property sets the number of data locators to be
+reserved for a process that stores data in a LOB table.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of data locators to be reserved
+
+Default: 100
+
+Range: 1 to 9,223,372,036,854,775,807 (2**63 -1)
+```
+
+Do not set a value much greater than the number of data locators
+actually needed. If the specified value is 0 (zero) or less, the default
+value (100) is used.
+
+Base the setting of the value of the `reserveDataLocators` property on the
+application profile being executed. If the application inserts a large
+number of LOB items, then a higher value of the `reserveDataLocators` property
+can prevent frequent updating of the `ZZ_DATA_LOCATOR` value in the LOB
+table. However, if the application inserts only a small number of LOB
+items, then a smaller value is better. If a large value is used, then holes
+(unused data-locator numbers) could occur in the LOB table. These holes
+represent unused space.
+
+Also, the administrator should avoid setting high values for the
+`reserveDataLocators` (for example, in the range of trillions or so).
+Setting high values prevents other Type 4 applications that use LOB
+table from reserving data locators.
+
+For additional information about data locator use, see
+<<reserving-data-locators, Reserving Data Locators>>.
+
+To change this value for a JDBC application, specify this property from
+the command line.
+
+*Example*
+
+The following command reserves 150 data
+locators for program class `myProgramClass`.
+
+```
+java -Dhpt4jdbc.reserveDataLocators=150 myProgramClass
+```
+
+<<<
+[[roundingmode]]
+== roundingMode Property
+
+The `roundingMode` property specifies the rounding behavior of the Type 4
+driver. For example, if the data is 1234.127 and column definition is
+`NUMERIC(6, 2)` and the application does `setDouble()` and `getDouble()`,
+then the value returned is 1234.12, which is truncated as specified by the
+default rounding mode, `ROUND_DOWN`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ROUND_DOWN
+```
+
+Values for roundingMode are:
+
+```
+ROUND_CEILING
+
+ROUND_DOWN
+
+ROUND_FLOOR
+
+ROUND_HALF_DOWN
+
+ROUND_HALF_EVEN
+
+ROUND_HALF_UP
+
+ROUND_UNNECESSARY
+
+ROUND_UP
+```
+
+* For the definition of rounding mode values, see the
+https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html[java.math.BigDecimal] documentation.
+
+* If the application sets erroneous values for the `roundingMode` property, no error is thrown by the Type 4 driver.
+The driver uses `ROUND_DOWN` value instead.
+
+* To have the application get the `DataTruncation` exception when data is
+truncated, set the `roundingMode` property to `ROUND_UNNECESSARY`.
+
+<<<
+[[schema]]
+== schema Property
+
+The `schema` property sets the database schema that accesses SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+schema=sales
+```
+
+<<<
+[[t4logfile]]
+== T4LogFile Property
+
+The `T4LogFile` property sets the name of the logging file for the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+```
+
+Default file name is defined by the following pattern:
+
+```
+%h/hpt4jdbc%u.log
+```
+
+where
+
+* `/` represents the local pathname separator.
+
+* `%h` represents the value of the user.home system property. _%u_
+represents a unique number to resolve conflicts.
+
+Any valid file name for your system is allowed.
+
+If you explicitly specify a log file, then that file is overwritten each time
+a `FileHandler` is established using that file name.
+
+To retain previously created log files, use the standard
+`java.util.logging `file syntax to append a unique number onto each log
+file.
+
+*Example*
+
+You can have the following property in a data source:
+
+```
+T4LogFile = C:/temp/MyLogFile%u.log
+```
+
+That name causes the Type 4 driver to create a new log file using a
+unique name for each connection made through that data source.
+
+<<<
+*Example*
+
+```
+C:/temp/MyLogFile43289.log
+
+C:/temp/MyLogFile87634.log
+
+C:/temp/MyLogFile27794.log
+```
+
+If you explicitly specify a log file that is not fully qualified, the
+Type 4 driver creates the file in the current working directory, for
+example, in the directory from which the JVM was invoked.
+
+For detailed information about java.util.logging, see the
+https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[logging summary] documentation.
+
+<<<
+[[t4loglevel]]
+== T4LogLevel Property
+
+The `T4LogLevel` property sets the logging levels that control logging
+output for the Type 4 driver. The Java package java.util.logging logs
+error messages and traces messages in the driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: OFF
+```
+
+*Logging Levels*
+[cols="20%,80%",options="header" ]
+|===
+| Level | Description
+| `OFF` | A special level that turns off logging; the default setting.
+| `SEVERE` | Indicates a serious failure; usually applies to SQL exceptions generated by the Type 4 driver.
+| `WARNING` | Indicates a potential problem, which usually applies to SQL warnings generated by the Type 4 driver.
+| `INFO` | Provides informational messages, typically about connection pooling, statement pooling, and resource usage. This information can
+help in tuning application performance.
+| `CONFIG` | Provides static configuration messages that can include property values and other Type 4 driver configuration information.
+| `FINE` | Provides tracing information from the Type 4 driver methods described in the Type 4 driver API. The level of tracing is equivalent
+to the level of tracing provided when calling the `setLogWriter()` method of the `DriverManager` class or the DataSource class.
+| `FINER` | Indicates a detailed tracing message for which internal Type 4 driver methods provide messages. These messages can be useful in debugging the Type 4 driver.
+| `FINEST` | Indicates a highly detailed tracing message. The driver provides detailed internal data messages that can be useful in debugging the Type 4 driver.
+| `ALL` |Logs all messages.
+|===
+
+*Example*
+
+To enable tracing, use the `hpt4jdbc.T4LogLevel` property specified in the command line:
+
+```
+-Dhpt4jdbc.T4LogLevel=FINE
+```
+
+<<<
+[[t4loglevel-considerations]]
+=== T4LogLevel Considerations
+
+* If a security manager is defined by your application using an AppServer,
+then `LoggingPermission` must be must be granted in the `java.policy` file as
+follows:
++
+```
+permission java.util.logging.LoggingPermission "control", "" ;
+```
+
+* The Type 4 driver is not designed to inherit the `java.util.logging.FileHandler.level` settings at program startup.
+
+<<<
+[[translationverification]]
+== translationVerification Property
+
+The `translationVerification` property defines the behavior of the driver
+if the driver cannot translate all or part of an SQL statement or SQL
+parameter.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The value can be TRUE or FALSE.
+
+```
+Data type: String
+
+Default: FALSE
+```
+
+
+[cols="10%,45%,45%", options="header"]
+|===
+| Value | Scenario | What Happens
+| `FALSE` | The driver is unable to 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.
+| `TRUE` | The driver cannot translation all or part of an SQL statement or parameter. | The driver throws an SQLException with this 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.
+|===
+
+NOTE: If the `translationVerification` property is set to TRUE, then the process can
+use significantly more system resources. For better performance, set this property to FALSE.
+
+For more information, see <<internationalization-support, Internationalization Support>>.
+
+<<<
+[[url]]
+== url Property
+
+The `url` property sets the URL value for the database.
+This property is used in the `DriverManager` object. The format
+to specify the URL is:
+
+```
+jdbc:hpt4jdbc//<primary IP addr or hostname of database>:37800/[:]
+[ property=value [ ; property2=value ] ... ]
+```
+
+where `<primary IP_addr or hostname of database>:37800>` specifies the location of the database.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+url=jdbc:hpt4jdbc://mynode.mycompanynetwork.net:37800/
+```
+
+[[url-property-considerations]]
+=== url Property Considerations
+
+* If the url parameter is not specified and `DriverManager.getConnection()` is called, then the Type 4 driver throws an SQLException.
+
+* If you use a literal IPV4 or IPV6 address in a URL, note these guidelines:
+
+** *For IPV6 only*: enclose the address in brackets (`[` and `]`).
+
+** The port number is optional according to both the IPV4 and IPV6 standard.
+
+** The default port number for the database is `37800`.
--- End diff --
23400
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665223
--- Diff: 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/" );
--- End diff --
jdbc:t4jdbc instead of jdbc:hpt4jdbc
and the port number should be 23400
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673121
--- Diff: 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`
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673257
--- Diff: 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`
--- End diff --
Commented out the BLOB and CLOB entry.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673404
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
+== reserveDataLocators Property
+
+The `reserveDataLocators` property sets the number of data locators to be
+reserved for a process that stores data in a LOB table.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of data locators to be reserved
+
+Default: 100
+
+Range: 1 to 9,223,372,036,854,775,807 (2**63 -1)
+```
+
+Do not set a value much greater than the number of data locators
+actually needed. If the specified value is 0 (zero) or less, the default
+value (100) is used.
+
+Base the setting of the value of the `reserveDataLocators` property on the
+application profile being executed. If the application inserts a large
+number of LOB items, then a higher value of the `reserveDataLocators` property
+can prevent frequent updating of the `ZZ_DATA_LOCATOR` value in the LOB
+table. However, if the application inserts only a small number of LOB
+items, then a smaller value is better. If a large value is used, then holes
+(unused data-locator numbers) could occur in the LOB table. These holes
+represent unused space.
+
+Also, the administrator should avoid setting high values for the
+`reserveDataLocators` (for example, in the range of trillions or so).
+Setting high values prevents other Type 4 applications that use LOB
+table from reserving data locators.
+
+For additional information about data locator use, see
+<<reserving-data-locators, Reserving Data Locators>>.
+
+To change this value for a JDBC application, specify this property from
+the command line.
+
+*Example*
+
+The following command reserves 150 data
+locators for program class `myProgramClass`.
+
+```
+java -Dhpt4jdbc.reserveDataLocators=150 myProgramClass
+```
+
+<<<
+[[roundingmode]]
+== roundingMode Property
+
+The `roundingMode` property specifies the rounding behavior of the Type 4
+driver. For example, if the data is 1234.127 and column definition is
+`NUMERIC(6, 2)` and the application does `setDouble()` and `getDouble()`,
+then the value returned is 1234.12, which is truncated as specified by the
+default rounding mode, `ROUND_DOWN`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ROUND_DOWN
+```
+
+Values for roundingMode are:
+
+```
+ROUND_CEILING
+
+ROUND_DOWN
+
+ROUND_FLOOR
+
+ROUND_HALF_DOWN
+
+ROUND_HALF_EVEN
+
+ROUND_HALF_UP
+
+ROUND_UNNECESSARY
+
+ROUND_UP
+```
+
+* For the definition of rounding mode values, see the
+https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html[java.math.BigDecimal] documentation.
+
+* If the application sets erroneous values for the `roundingMode` property, no error is thrown by the Type 4 driver.
+The driver uses `ROUND_DOWN` value instead.
+
+* To have the application get the `DataTruncation` exception when data is
+truncated, set the `roundingMode` property to `ROUND_UNNECESSARY`.
+
+<<<
+[[schema]]
+== schema Property
+
+The `schema` property sets the database schema that accesses SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+schema=sales
+```
+
+<<<
+[[t4logfile]]
+== T4LogFile Property
+
+The `T4LogFile` property sets the name of the logging file for the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+```
+
+Default file name is defined by the following pattern:
+
+```
+%h/hpt4jdbc%u.log
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665310
--- Diff: 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`
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665306
--- Diff: 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`
--- End diff --
remove hp
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665276
--- Diff: 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]...]
--- End diff --
jdbc:t4jdbc and port change to 23400
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673018
--- Diff: 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" ) ;
--- End diff --
The catalog? It's my understanding that the only catalog for Trafodion is named Seabase?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673413
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
+== reserveDataLocators Property
+
+The `reserveDataLocators` property sets the number of data locators to be
+reserved for a process that stores data in a LOB table.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of data locators to be reserved
+
+Default: 100
+
+Range: 1 to 9,223,372,036,854,775,807 (2**63 -1)
+```
+
+Do not set a value much greater than the number of data locators
+actually needed. If the specified value is 0 (zero) or less, the default
+value (100) is used.
+
+Base the setting of the value of the `reserveDataLocators` property on the
+application profile being executed. If the application inserts a large
+number of LOB items, then a higher value of the `reserveDataLocators` property
+can prevent frequent updating of the `ZZ_DATA_LOCATOR` value in the LOB
+table. However, if the application inserts only a small number of LOB
+items, then a smaller value is better. If a large value is used, then holes
+(unused data-locator numbers) could occur in the LOB table. These holes
+represent unused space.
+
+Also, the administrator should avoid setting high values for the
+`reserveDataLocators` (for example, in the range of trillions or so).
+Setting high values prevents other Type 4 applications that use LOB
+table from reserving data locators.
+
+For additional information about data locator use, see
+<<reserving-data-locators, Reserving Data Locators>>.
+
+To change this value for a JDBC application, specify this property from
+the command line.
+
+*Example*
+
+The following command reserves 150 data
+locators for program class `myProgramClass`.
+
+```
+java -Dhpt4jdbc.reserveDataLocators=150 myProgramClass
+```
+
+<<<
+[[roundingmode]]
+== roundingMode Property
+
+The `roundingMode` property specifies the rounding behavior of the Type 4
+driver. For example, if the data is 1234.127 and column definition is
+`NUMERIC(6, 2)` and the application does `setDouble()` and `getDouble()`,
+then the value returned is 1234.12, which is truncated as specified by the
+default rounding mode, `ROUND_DOWN`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ROUND_DOWN
+```
+
+Values for roundingMode are:
+
+```
+ROUND_CEILING
+
+ROUND_DOWN
+
+ROUND_FLOOR
+
+ROUND_HALF_DOWN
+
+ROUND_HALF_EVEN
+
+ROUND_HALF_UP
+
+ROUND_UNNECESSARY
+
+ROUND_UP
+```
+
+* For the definition of rounding mode values, see the
+https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html[java.math.BigDecimal] documentation.
+
+* If the application sets erroneous values for the `roundingMode` property, no error is thrown by the Type 4 driver.
+The driver uses `ROUND_DOWN` value instead.
+
+* To have the application get the `DataTruncation` exception when data is
+truncated, set the `roundingMode` property to `ROUND_UNNECESSARY`.
+
+<<<
+[[schema]]
+== schema Property
+
+The `schema` property sets the database schema that accesses SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+schema=sales
+```
+
+<<<
+[[t4logfile]]
+== T4LogFile Property
+
+The `T4LogFile` property sets the name of the logging file for the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+```
+
+Default file name is defined by the following pattern:
+
+```
+%h/hpt4jdbc%u.log
+```
+
+where
+
+* `/` represents the local pathname separator.
+
+* `%h` represents the value of the user.home system property. _%u_
+represents a unique number to resolve conflicts.
+
+Any valid file name for your system is allowed.
+
+If you explicitly specify a log file, then that file is overwritten each time
+a `FileHandler` is established using that file name.
+
+To retain previously created log files, use the standard
+`java.util.logging `file syntax to append a unique number onto each log
+file.
+
+*Example*
+
+You can have the following property in a data source:
+
+```
+T4LogFile = C:/temp/MyLogFile%u.log
+```
+
+That name causes the Type 4 driver to create a new log file using a
+unique name for each connection made through that data source.
+
+<<<
+*Example*
+
+```
+C:/temp/MyLogFile43289.log
+
+C:/temp/MyLogFile87634.log
+
+C:/temp/MyLogFile27794.log
+```
+
+If you explicitly specify a log file that is not fully qualified, the
+Type 4 driver creates the file in the current working directory, for
+example, in the directory from which the JVM was invoked.
+
+For detailed information about java.util.logging, see the
+https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[logging summary] documentation.
+
+<<<
+[[t4loglevel]]
+== T4LogLevel Property
+
+The `T4LogLevel` property sets the logging levels that control logging
+output for the Type 4 driver. The Java package java.util.logging logs
+error messages and traces messages in the driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: OFF
+```
+
+*Logging Levels*
+[cols="20%,80%",options="header" ]
+|===
+| Level | Description
+| `OFF` | A special level that turns off logging; the default setting.
+| `SEVERE` | Indicates a serious failure; usually applies to SQL exceptions generated by the Type 4 driver.
+| `WARNING` | Indicates a potential problem, which usually applies to SQL warnings generated by the Type 4 driver.
+| `INFO` | Provides informational messages, typically about connection pooling, statement pooling, and resource usage. This information can
+help in tuning application performance.
+| `CONFIG` | Provides static configuration messages that can include property values and other Type 4 driver configuration information.
+| `FINE` | Provides tracing information from the Type 4 driver methods described in the Type 4 driver API. The level of tracing is equivalent
+to the level of tracing provided when calling the `setLogWriter()` method of the `DriverManager` class or the DataSource class.
+| `FINER` | Indicates a detailed tracing message for which internal Type 4 driver methods provide messages. These messages can be useful in debugging the Type 4 driver.
+| `FINEST` | Indicates a highly detailed tracing message. The driver provides detailed internal data messages that can be useful in debugging the Type 4 driver.
+| `ALL` |Logs all messages.
+|===
+
+*Example*
+
+To enable tracing, use the `hpt4jdbc.T4LogLevel` property specified in the command line:
+
+```
+-Dhpt4jdbc.T4LogLevel=FINE
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673233
--- Diff: 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:
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665226
--- Diff: 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" ) ;
--- End diff --
Change this to "TRAFODION"
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61675377
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_overview.adoc ---
@@ -0,0 +1,245 @@
+////
+/**
+ *@@@ 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-properties]]
+= Type 4 Driver Properties
+
+[[summary-of-type-4-driver-properties]]
+== Summary of Type 4 Driver Properties
+
+Type 4 driver properties that effect client-side operations are
+summarized in the following tables. For the detailed description, click
+the link provided in the property name.
+
+NOTE: Unless otherwise noted in the brief description, the particular
+property applies to the `DataSource` object, `DriverManager` object, and
+`ConnectionPoolDataSource` object.
+
+[[client-side-properties]]
+=== Client-Side Properties
+
+*Connection-Control Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<dataSourceName, dataSourceName>>` | Specifies the registered DataSource or ConnectionPoolDataSource name. (Can be set only on the DriverManager object.) | None.
+| `<<loginTimeout, loginTimeout>>` | Sets the time limit that a connection can be attempted before the connection disconnects. | 60 (seconds)
+| `<<networkTimeout, networkTimeout>>` | Sets a time limit that the driver waits for a reply from the database server. | 0 (No network timeout is specified.
+|===
+
+*Pooling Management Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<initialPoolSize, initialPoolSize>>` | Sets the initial connection pool size when connection pooling is used with the Type 4 driver. (Ignored for
+connections made through the ConnectionPoolDataSource object.) | -1 (Do not create an initial connection pool.)
+| `<<maxIdleTime, maxIdleTime>>` | Sets the number of seconds that a physical connection can remain unused in the pool before the connection is closed. | 0 (Specifies no limit.)
+| `<<maxPoolSize, maxPoolSize>>` | Sets the maximum number of physical connections that the pool can contain. | -1 (Disables connection pooling.)
+| `<<maxStatements, maxStatements>>` | Sets the total number of PreparedStatement objects that the connection pool should cache. | 0 (Disables statement pooling.)
+| `<<minPoolSize, minPoolSize>>` | Limits the number of physical connections that can be in the free connection pool. | -1 (The minPoolSize value is ignored.)
+|===
+
+////
+*Operations on CLOB and BLOB Data*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<blobTableName, blobTableName>>` | Specifies the LOB table for using BLOB columns. | None.
+| `<<clobTableName, clobTableName>>` | Specifies the LOB table for using CLOB columns. | None.
+| `<<reserveDataLocators,reserveDataLocators>>` | Sets the number of data locators to be reserved for a process that stores data in a LOB table. | 100
+|===
+////
+
+<<<
+*Internationalization Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<ISO88591, ISO88591>>` | Sets character-set mapping that corresponds to the ISO88591 character set. | ISO88591_1
+| `<<KANJI, KANJI>>` | Sets character-set mapping that corresponds to the KANJI character set. | SJIS (which is shift-JIS, Japanese)
+| `<<KSC5601, KSC5601>>` | Sets character-set mapping that corresponds to the KSC5601 character set. | ECU_KR (which is KS C 5601, ECU encoding, Korean)
+| `<<language, language>>` | Sets the language used for error messages. | None.
+| `<<translationVerification, translationVerification>>` | Defines the behavior of the driver if the driver cannot translate all or part of an SQL statement or SQL parameter. | FALSE
+|===
+
+*Logging and Tracing Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<T4LogFile, T4LogFile>>` | Sets the name of the logging file for the Type 4 driver. | The name is defined by the following pattern: `%h/hpt4jdbc%u.log`
+| `<<T4LogLevel, T4LogLevel>>` | Sets the logging levels that control logging output for the Type 4 driver. | OFF
+|===
+
+*Miscellaneous Client-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<description, description>>` | Specifies the registered source name. | None.
+| `<<fetchBufferSize, fetchBufferSize>>` | Provides the benefits of bulk fetch when rows are fetched from a `ResultSet` object. | 4 kilobytes
+| `<<properties, properties>>` | Specifies the location of the properties file that contains keyword-value pairs
+that specify property values for configuring the Type 4 driver. | None.
+| `<<roundingMode, roundingMode>>` | Specifies the rounding behavior of the Type 4 driver. | ROUND_DOWN
+|===
+
+<<<
+[[server-side-properties]]
+=== Server-Side Properties
+
+The Type 4 driver properties that effect server-side operations are
+summarized in the following tables. Unless otherwise noted in the
+description, the particular property applies to the DataSource object,
+`DriverManager` object, and `ConnectionPoolDataSource` object.
+
+*Type 4 Driver Server-Side Properties*
+[cols="25%,55%,30%",options="header" ]
+|===
+| Property Name | Description | Default Value
+| `<<catalog, catalog>>` | Sets the default catalog used to access SQL objects referenced in SQL
+statements if the SQL objects are not fully qualified. | None. Must be "Seabase" in the current release.
+| `<<connectionTimeout, connectionTimeout>>` | Sets the number of seconds a connection can be idle before the connection is physically closed by DCS. |
+-1 (Use the ConnTimeout value set on the server data source.)
+| `<<password, password>>` | Sets the password value for passing to the database. Can also change the password. | Empty string.
+| `<<schema, schema>>` | Sets the database schema that accesses SQL objects referenced in SQL statements if the SQL objects are not fully qualified. | None.
+| `<<url, url>>` | Sets the URL value for the database. Can be set only on the `DriverManager` object. | None.
+| `<<user, user>>` | Sets the user value for the database. | None.
+|===
+
+[[how-to-specify-jdbc-type-4-properties]]
+== How to Specify JDBC Type 4 Properties
+
+The Type 4 JDBC driver properties configure the driver. These properties
+can be specified in a data source, a connection URL (the primary IP
+address or host name on the database), a properties file,
+or in the java command line.
+
+Java properties have the form:
+
+```
+key=value
+```
+
+At run time, the driver looks for a specific set of property keys and
+takes action based on their associated values.
+
+<<<
+[[where-to-set-properties]]
+=== Where to Set Properties
+
+* For connections made through a `DataSource` or a `ConnectionPoolDataSource`,
+set the property on the `DataSource` or the `ConnectionPoolDataSource` object.
+
+* For the `DriverManager` class, set properties in either of two ways:
++
+1. Using the option `-Dproperty_name=property_value` in the command line.
+2. Using the `java.util.Properties` parameter in the `getConnection()` method
+of the `DriverManager` class.
+
+[[creating-and-using-a-properties-file]]
+=== Creating and Using a Properties File
+
+JDBC applications can provide property values to configure a connection
+by using a file that contains properties for the JDBC driver. This
+property file is passed as a java command-line parameter. The format to
+enter the properties file in the command line is:
+
+```
+-Dhpt4jdbc.properties=<path of the properties file on disk>`
+```
+
+*Example*
+
+```
+-Dhpt4jdbc.properties=C:\temp\t4props\myprops.properties
+```
+
+To create the file, use the editor of your choice on your workstation to
+type in the property values. The entries in properties file must have a
+`property_name=property_value` value-pair format:
+
+```
+property_name=property_value
+```
+
+*Example*
+
+```
+maxStatements=1024
+```
+
+To configure a `DataSource` connection, the properties file might contain
+property names and values as indicated in the following list:
+
+```
+url=jdbc:hpt4jdbc://<primary IP addr or host name of database>:37800/
--- End diff --
change url
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61672995
--- Diff: 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.
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673050
--- Diff: 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
--- End diff --
Done.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61669935
--- Diff: 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
--- End diff --
Remove this section Additional connection APIs
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673285
--- Diff: 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.
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665129
--- Diff: 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
--- End diff --
This sentence can be "application code and the database that establishes connection using Database Connectivity Services(DCS)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61670087
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
--- End diff --
not sure if this is still valid.. let sandhya review this
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673129
--- Diff: 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`
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673431
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[language]]
+== language Property
+
+The `language` property sets the language used for the error messages. For
+more information about using this property, see
+<<localizing-error-messages-and-status-messages, Localizing Error Messages and Status Messages>>
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+To set the language to shift-JIS, Japanese:
+
+```
+language=SJIS
+```
+
+////
+[[lob-table-name]]
+== LOB Table Name Properties
+
+LOB tables store data for BLOB columns and CLOB columns. The properties
+that specify the LOB table for using BLOB columns or CLOB columns are:
+
+* For the binary data for BLOB columns `blobTableName`.
+* For the character data for CLOB columns `clobTableName`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The property value is of the form:
+
+```
+catalog_name.schema_name.lob_table_name
+```
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+blobTableName=samdbcat.sales.lobvideo
+```
+////
+
+<<<
+[[logintimeout]]
+== loginTimeout Property
+
+The `loginTimeout` property sets the time limit that a connection can be
+attempted before the connection disconnects. When a connection is
+attempted for a period longer than the set value, in seconds, the
+connection disconnects.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 60
+
+Range: 0 to 2147483647
+```
+
+If set to 0 (zero), no login timeout is specified.
+
+<<<
+[[maxidletime]]
+== maxIdleTime Property
+
+The `maxIdleTime` property determines the number of seconds that a
+physical connection should remain unused in the pool before the
+connection is closed. 0 (zero) indicates no limit.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No timeout)
+
+Range: 0 through 2147483647
+```
+
+Any negative value is treated as 0, which indicates that no time limit
+applies.
+
+*Example*
+
+To set the maximum idle time to 5 minutes (300 seconds):
+
+```
+java -Dhpt4jdbc.maxIdleTime=300
+```
+
+<<<
+[[maxpoolsize]]
+== maxPoolSize Property
+
+The `maxPoolSize` property sets the maximum number of physical connections
+that the pool can contain. These connections include both free
+connections and connections in use. When the maximum number of physical
+connections is reached, the Type 4 driver throws an SQLException and
+sends the message, Maximum pool size is reached.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Disables connection pooling.)
+
+Range: -1, 0 through 2147483647, but greater than minPoolSize
+```
+
+The value determines connection-pool use as follows:
+
+* Any negative value is treated like -1.
+
+* 0 means no maximum pool size.
+
+* A value of -1 disables connection pooling.
+
+Any positive value less than `minPoolSize` is changed to the `minPoolSize` value.
+
+<<<
+[[maxstatements]]
+== maxStatements Property
+
+The `maxStatements` property sets the total number of `PreparedStatement`
+objects that the connection pool should cache. This total includes both
+free objects and objects in use.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of objects
+
+Default: 0 (Disables statement pooling.)
+
+Range: 0 through 2147483647
+```
+
+The value 0 disables statement pooling. Any negative value is treated
+like 0 (zero).
+
+TIP: To improve performance, we recommend that you enable statement pooling for
+your JDBC applications because this pooling can dramatically help the
+performance of many applications.
+
+NOTE: Statement pooling can be in effect only if connection pooling is
+enabled.
+
+*Example*
+
+To specify statement pooling, type:
+
+```
+maxStatements=10
+```
+
+<<<
+[[minpoolsize]]
+== minPoolSize Property
+
+The `minPoolSize` property limits the number of physical connections that
+can be in the free connection pool.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Default: -1 (The minPoolSize value is ignored.)
+
+Range: -1, 0 through n, but less than maxPoolSize
+```
+
+* Any negative value is treated like -1.
+
+* Any value greater than `maxPoolSize` is changed to the `maxPoolSize` value.
+
+* The value of `minPoolSize` is set to -1 when `maxPoolSize` is -1. The value determines
+connection pool use as follows:
+
+** When the number of physical connections in the free pool reaches the
+`minPoolSize` value, the Type 4 driver closes subsequent connections by
+physically closing them and not adding them to the free pool.
+
+** 0 (zero) means that the connections are not physically closed; the
+connections are always added to the free pool when the connection is
+closed.
+
+*Example*
+
+Use the following specification to set the `minPoolSize`
+value to 1, which ensures that one connection is always retained:
+
+```
+minPoolSize=1
+```
+
+<<<
+[[networktimeout]]
+== networkTimeout Property
+
+The `networkTimeout` property sets a time limit that the driver waits for
+a reply from the database server. When an operation is attempted for a
+period longer than the set value, in seconds, the driver stops waiting
+for a reply and returns an SQLException to the user application.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+CAUTION: Be careful when using this property. A network timeout causes
+the socket connection between the Type 4 driver and the connectivity
+server to timeout. If the server is engaged in a transaction or an SQL
+operation, then the server continues to perform that transaction or
+operation until the transaction or operation fails, the transaction
+manager times out, or the server realizes that the Type 4 driver client
+has gone away. A network timeout can result in an open transaction or
+operation that continues for a significant time before failing or
+rolling back. As a result of a network timeout, the connection becomes
+unavailable.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: 0 (No network timeout is specified.)
+
+0 through to 2147483647
+```
+
+<<<
+[[password]]
+== password Property
+
+The `password` property sets the password value for passing to the DCS
+server. By using this property, you can also change the password. The
+password is encrypted when it is passed to the server.
+
+The format for specifying the password is:
+
+```
+password=old [, new, new ]
+```
+
+* `old` is the current password
+
+* `new` is the new password. Passwords must be 6 to 8 characters long and
+cannot contain double quotes (").
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: empty string
+```
+
+*Example*
+
+```
+password=eye0weU$
+```
+
+[[properties]]
+== properties Property
+
+The `properties` property specifies the location of the properties file
+that contains keyword-value pairs that specify property values for
+configuring the Type 4 driver. For more information, see
+<<creating-and-using-a-properties-file, Creating and Using a Properties File>>.
+
+<<<
+[[reservedatalocators]]
+== reserveDataLocators Property
+
+The `reserveDataLocators` property sets the number of data locators to be
+reserved for a process that stores data in a LOB table.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: number of data locators to be reserved
+
+Default: 100
+
+Range: 1 to 9,223,372,036,854,775,807 (2**63 -1)
+```
+
+Do not set a value much greater than the number of data locators
+actually needed. If the specified value is 0 (zero) or less, the default
+value (100) is used.
+
+Base the setting of the value of the `reserveDataLocators` property on the
+application profile being executed. If the application inserts a large
+number of LOB items, then a higher value of the `reserveDataLocators` property
+can prevent frequent updating of the `ZZ_DATA_LOCATOR` value in the LOB
+table. However, if the application inserts only a small number of LOB
+items, then a smaller value is better. If a large value is used, then holes
+(unused data-locator numbers) could occur in the LOB table. These holes
+represent unused space.
+
+Also, the administrator should avoid setting high values for the
+`reserveDataLocators` (for example, in the range of trillions or so).
+Setting high values prevents other Type 4 applications that use LOB
+table from reserving data locators.
+
+For additional information about data locator use, see
+<<reserving-data-locators, Reserving Data Locators>>.
+
+To change this value for a JDBC application, specify this property from
+the command line.
+
+*Example*
+
+The following command reserves 150 data
+locators for program class `myProgramClass`.
+
+```
+java -Dhpt4jdbc.reserveDataLocators=150 myProgramClass
+```
+
+<<<
+[[roundingmode]]
+== roundingMode Property
+
+The `roundingMode` property specifies the rounding behavior of the Type 4
+driver. For example, if the data is 1234.127 and column definition is
+`NUMERIC(6, 2)` and the application does `setDouble()` and `getDouble()`,
+then the value returned is 1234.12, which is truncated as specified by the
+default rounding mode, `ROUND_DOWN`.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ROUND_DOWN
+```
+
+Values for roundingMode are:
+
+```
+ROUND_CEILING
+
+ROUND_DOWN
+
+ROUND_FLOOR
+
+ROUND_HALF_DOWN
+
+ROUND_HALF_EVEN
+
+ROUND_HALF_UP
+
+ROUND_UNNECESSARY
+
+ROUND_UP
+```
+
+* For the definition of rounding mode values, see the
+https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html[java.math.BigDecimal] documentation.
+
+* If the application sets erroneous values for the `roundingMode` property, no error is thrown by the Type 4 driver.
+The driver uses `ROUND_DOWN` value instead.
+
+* To have the application get the `DataTruncation` exception when data is
+truncated, set the `roundingMode` property to `ROUND_UNNECESSARY`.
+
+<<<
+[[schema]]
+== schema Property
+
+The `schema` property sets the database schema that accesses SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+schema=sales
+```
+
+<<<
+[[t4logfile]]
+== T4LogFile Property
+
+The `T4LogFile` property sets the name of the logging file for the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+```
+
+Default file name is defined by the following pattern:
+
+```
+%h/hpt4jdbc%u.log
+```
+
+where
+
+* `/` represents the local pathname separator.
+
+* `%h` represents the value of the user.home system property. _%u_
+represents a unique number to resolve conflicts.
+
+Any valid file name for your system is allowed.
+
+If you explicitly specify a log file, then that file is overwritten each time
+a `FileHandler` is established using that file name.
+
+To retain previously created log files, use the standard
+`java.util.logging `file syntax to append a unique number onto each log
+file.
+
+*Example*
+
+You can have the following property in a data source:
+
+```
+T4LogFile = C:/temp/MyLogFile%u.log
+```
+
+That name causes the Type 4 driver to create a new log file using a
+unique name for each connection made through that data source.
+
+<<<
+*Example*
+
+```
+C:/temp/MyLogFile43289.log
+
+C:/temp/MyLogFile87634.log
+
+C:/temp/MyLogFile27794.log
+```
+
+If you explicitly specify a log file that is not fully qualified, the
+Type 4 driver creates the file in the current working directory, for
+example, in the directory from which the JVM was invoked.
+
+For detailed information about java.util.logging, see the
+https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[logging summary] documentation.
+
+<<<
+[[t4loglevel]]
+== T4LogLevel Property
+
+The `T4LogLevel` property sets the logging levels that control logging
+output for the Type 4 driver. The Java package java.util.logging logs
+error messages and traces messages in the driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: OFF
+```
+
+*Logging Levels*
+[cols="20%,80%",options="header" ]
+|===
+| Level | Description
+| `OFF` | A special level that turns off logging; the default setting.
+| `SEVERE` | Indicates a serious failure; usually applies to SQL exceptions generated by the Type 4 driver.
+| `WARNING` | Indicates a potential problem, which usually applies to SQL warnings generated by the Type 4 driver.
+| `INFO` | Provides informational messages, typically about connection pooling, statement pooling, and resource usage. This information can
+help in tuning application performance.
+| `CONFIG` | Provides static configuration messages that can include property values and other Type 4 driver configuration information.
+| `FINE` | Provides tracing information from the Type 4 driver methods described in the Type 4 driver API. The level of tracing is equivalent
+to the level of tracing provided when calling the `setLogWriter()` method of the `DriverManager` class or the DataSource class.
+| `FINER` | Indicates a detailed tracing message for which internal Type 4 driver methods provide messages. These messages can be useful in debugging the Type 4 driver.
+| `FINEST` | Indicates a highly detailed tracing message. The driver provides detailed internal data messages that can be useful in debugging the Type 4 driver.
+| `ALL` |Logs all messages.
+|===
+
+*Example*
+
+To enable tracing, use the `hpt4jdbc.T4LogLevel` property specified in the command line:
+
+```
+-Dhpt4jdbc.T4LogLevel=FINE
+```
+
+<<<
+[[t4loglevel-considerations]]
+=== T4LogLevel Considerations
+
+* If a security manager is defined by your application using an AppServer,
+then `LoggingPermission` must be must be granted in the `java.policy` file as
+follows:
++
+```
+permission java.util.logging.LoggingPermission "control", "" ;
+```
+
+* The Type 4 driver is not designed to inherit the `java.util.logging.FileHandler.level` settings at program startup.
+
+<<<
+[[translationverification]]
+== translationVerification Property
+
+The `translationVerification` property defines the behavior of the driver
+if the driver cannot translate all or part of an SQL statement or SQL
+parameter.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The value can be TRUE or FALSE.
+
+```
+Data type: String
+
+Default: FALSE
+```
+
+
+[cols="10%,45%,45%", options="header"]
+|===
+| Value | Scenario | What Happens
+| `FALSE` | The driver is unable to 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.
+| `TRUE` | The driver cannot translation all or part of an SQL statement or parameter. | The driver throws an SQLException with this 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.
+|===
+
+NOTE: If the `translationVerification` property is set to TRUE, then the process can
+use significantly more system resources. For better performance, set this property to FALSE.
+
+For more information, see <<internationalization-support, Internationalization Support>>.
+
+<<<
+[[url]]
+== url Property
+
+The `url` property sets the URL value for the database.
+This property is used in the `DriverManager` object. The format
+to specify the URL is:
+
+```
+jdbc:hpt4jdbc//<primary IP addr or hostname of database>:37800/[:]
+[ property=value [ ; property2=value ] ... ]
+```
+
+where `<primary IP_addr or hostname of database>:37800>` specifies the location of the database.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+```
+url=jdbc:hpt4jdbc://mynode.mycompanynetwork.net:37800/
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673245
--- Diff: 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
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by DaveBirdsall <gi...@git.apache.org>.
Github user DaveBirdsall commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61657816
--- Diff: 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
--- End diff --
"an DCS" should be "a DCS". Have we defined DCS yet? If not we should spell it out.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673219
--- Diff: 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:
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61660717
--- Diff: 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>
--- End diff --
Document versions are driven from env.TRAFODION_VERSION. The value here is
required but doesn't have a meaning that I'm aware of.
On Fri, Apr 29, 2016 at 5:27 PM, DaveBirdsall <no...@github.com>
wrote:
> In docs/jdbct4ref_guide/pom.xml
> <https://github.com/apache/incubator-trafodion/pull/457#discussion_r61657384>
> :
>
> > +* @@@ 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>
>
> So, this is the 1.3.0 version? Is there also a 2.0,0 version?
>
> —
> You are receiving this because you authored the thread.
> Reply to this email directly or view it on GitHub
> <https://github.com/apache/incubator-trafodion/pull/457/files/a3cc57d7f87c8f89148fe34f729e9c630e9e2091#r61657384>
>
--
Thanks,
Gunnar
*If you think you can you can, if you think you can't you're right.*
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673384
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665283
--- Diff: 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.
--- End diff --
23400
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by hegdean <gi...@git.apache.org>.
Github user hegdean commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61665112
--- Diff: 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
--- End diff --
This should be org.trafodion.jdbc.t4 instead of org.trafodion.t4jdbc
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-trafodion pull request: Trafodion 1949: New JDBC Type 4 ...
Posted by gtapper <gi...@git.apache.org>.
Github user gtapper commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/457#discussion_r61673396
--- Diff: docs/jdbct4ref_guide/src/asciidoc/_chapters/properties_detail.adoc ---
@@ -0,0 +1,959 @@
+////
+/**
+ *@@@ 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-property-descriptions]]
+= Type 4 Driver Property Descriptions
+
+The properties are listed in alphabetic order with their descriptions.
+For the properties summarized in categories, see
+<<summary-of-type-4-driver-properties, Summary of Type 4 Driver Properties>>.
+
+////
+[[blobtablename]]
+== blobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+[[catalog]]
+== catalog Property
+
+The `catalog` property sets the default catalog used to access SQL objects
+referenced in SQL statements if the SQL objects are not fully qualified.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: none
+```
+
+*Example*
+
+Specifying the catalog Seabase:
+
+```
+catalog=Seabase
+```
+
+////
+[[clobtablename]]
+== clobTableName Property
+
+See <<lob-table-name, LOB Table Name Properties>>.
+////
+
+<<<
+[[connectiontimeout]]
+== connectionTimeout Property
+
+The `connectionTimeout` property sets the number of seconds a connection
+can be idle before the connection is physically closed by DCS.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: int
+
+Units: seconds
+
+Default: -1 (Use the ConnTimeout value set on the server-side data source.)
+
+Range: -1, 0 to 2147483647
+```
+
+* Zero (0) specifies infinity as the timeout value.
+* A non-zero positive value overrides the value set on the
+{project-name} data source, if allowed by the connectivity settings.
+* A negative value is treated as -1.
+
+*Example*
+
+Consider the following scenario.
+
+Even if a connection is not being used, it takes up resources. The application
+abandons connections; that is, the application does not physically close a
+connection after the application finishes using the connection.
+
+However, you can configure the connection to close itself after 300 seconds by setting
+the `connectionTimeout` property. Then, when a connection is not referenced for 300 seconds,
+the connection automatically closes itself.
+
+In this example, the specification to set the `connectionTimeout` property is:
+
+```
+connectionTimeout=300
+```
+
+<<<
+[[fetchbuffersize]]
+== fetchBufferSize Property
+
+The `fetchBufferSize` property provides the benefits of bulk fetch.
+
+This property sets the value in kilobytes (KB) of the size of the fetch
+buffer that is used when rows are fetched from a `ResultSet` object after
+a successful `executeQuery()` operation on a statement.
+
+Set this property on a `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: short
+
+Default size: 4
+
+Range: 4 through 32767
+```
+
+* Zero and negative values are treated as default values.
+* The Type 4 driver guarantees that the number of rows internally
+fetched will be no less than the minimum of the row size (set using
+the `setFetchSize` method) and the number of rows that will fit in the
+memory specified by the `setFetchSize` (set using the property).
+
+*Example*
+
+```
+fetchBufferSize=32
+```
+
+<<<
+[[initialpoolsize]]
+== initialPoolSize Property
+
+The `initialPoolSize` property sets the initial connection pool size when
+connection pooling is used with the Type 4 driver.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object. For information about how to set
+properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+The driver creates _n_ connections (where _n_ is `initialPoolSize`) for
+each connection pool when the first connection is requested. For
+example, if `initialPoolSize` is set to `5` for a data source, then the driver
+attempts to create and pool five connections the first time the
+application calls the data source's `getConnection()` method.
+
+```
+Data type: int
+
+Units: number of physical connections
+
+Default: -1 (Do not create an initial connection pool.)
+
+Range: -1 to maxPoolSize
+```
+
+* Any negative value is treated as -1.
+* Values can be less than `minPoolSize`, but must not exceed `maxPoolSize`.
+If the specified value is greater than `maxPoolSize`, the `maxPoolSize`
+property value is used.
+
+*Example*
+
+```
+initialPoolSize=10
+```
+
+<<<
+[[iso88591]]
+== ISO88591 Property
+
+The `ISO88591` character-set mapping property corresponds to the
+SQL ISO88591 character set, which is a single-byte
+8-bit character set for character data types. This property supports
+English and other Western European languages. For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+Set this property on a `DataSource` object or `DriverManager` object. This
+property is ignored for connections made through the
+`ConnectionPoolDataSource` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+```
+Data type: String
+
+Default: ISO88591_1
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[kanji]]
+== KANJI Property
+
+The `KANJI` character-set mapping property corresponds to the
+SQL KANJI character set, which is a double-byte character set widely used on Japanese mainframes.
+This property is a subset of Shift JIS: the double character portion. The encoding for
+this property is big endian.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: SJIS (which is shift-JIS, Japanese)
+```
+
+*Example*
+
+```
+java -Dhpt4jdbc.KANJI=SJIS
+```
+
+For more information, see
+<<internationalization-support, Internationalization Support>>.
+
+<<<
+[[ksc5601]]
+== KSC5601 Property
+
+The `KSC5601` character-set mapping property corresponds to the
+SQL KSC5601 character set, which is a double-byte
+character set.
+
+Set this property on a `DataSource` object, `ConnectionPoolDataSource`
+object, or `DriverManager` object.
+For information about how to set properties, see
+<<how-to-specify-jdbc-type-4-properties, How to Specify JDBC Type 4 Properties>>.
+
+```
+Data type: String
+
+Default: ECU_KR (which is KS C 5601, ECU encoding, Korean)
+```
+
+The value can be any valid Java Canonical Name as listed in the
+"Canonical Name for java.io and java.lang API" column of the
+http://docs.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html[Java documentation].
+
+*Example*
+
+```
+java -Dhpt4jdbc.KSC5601=ECU_KR
--- End diff --
Changed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---