blob: 43dbf73559d5231ca8a57fc16e927b8f62c1f517 [file] [log] [blame]
////
/**
*@@@ 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 @@@
*
////
[[jdbct4]]
= Install JDBC Type-4 Driver
== Prerequisites
If you have not done so already, please ensure that you have <<java-setup, setup your Java environment>>
and <<download-software, unpackaged the {project-name} client software>>.
The examples in this chapter assumes that you have unpackaged the JDBC Type 4 driver installation files
to `c:\trafodion\jdbct4` (Windows) or `$HOME/trafodion/jdbct4` (Linux).
[[jdbct4-validate-install]]
== Validate Install Directory
The content of the `jdbct4` installation directory is as follows:
[cols="33%,30%,37%",options="header"]
|===
| Installation Folder | Files | Description
| `/lib` | `jdbcT4.jar` | Product JAR file.
| `/samples` | `t4jdbc.properties` | Properties file that you can configure for your application environment.
| | `README` | Readme file that explains how to use the common sample set.
| `/samples/common` | `sampleUtils.java` | Sample source code for creating, populating, and dropping sample tables.
| `/samples/DBMetaSample` | `DBMetaSample.java` | Sample source code for getting metadata about the sample tables.
| | `README` | Readme file that explains how to use this sample set.
| `/samples/PreparedStatementSample` | `PreparedStatementSample.java` | Sample code for simple or parameterized SELECT statements that are prepared.
| | `README` | Readme file that explains how to use this sample set.
| `/samples/ResultSetSample` | `README` | Readme file that explains how to use this sample set.
| | `ResultSetSample.java` | Sample source code for fetching rows from a result set.
| `/samples/StatementSample` | `README` | Readme file that explains how to use this sample set.
| | `StatementSample.java` | Sample source code for fetching rows from a simple SELECT statement.
|===
<<<
[[jdbct4-setup-env]]
== Set Up Client Environment
[[jdbct4-java-development]]
=== Java Development
If you plan to write and run Java applications that use the {project-name} JDBC Type 4 Driver to connect to a {project-name} database, then set these
environment variables on the client workstation, replacing `_jdk-directory_` with the location of your Java Development Kit and
replacing `_jdbc-installation-directory_` with the name of the directory where you downloaded the JDBC Type 4 driver:
[cols="20%,40%,40%",options="header"]
|===
| Environment Variable | On Windows | On Linux
| `JAVA_HOME` | `set JAVA_HOME="_jdk-directory_"`^1^ | `export JAVA_HOME=_jdk-directory_`
| `PATH` | `set PATH=%PATH%;%JAVA_HOME%\bin` | `export PATH=$PATH:$JAVA_HOME/bin`
| `CLASSPATH` | `set CLASSPATH=%CLASSPATH%;_jdbc-installation-directory_\lib\jdbcT4.jar;` | `export CLASSPATH=$CLASSPATH:_jdbc-installation-directory_/lib/jdbcT4.jar:`
|===
^1^ Enclose the _jdk-directory_ in quotes to ensure that Windows can find the directory correctly. You can use the `set <variable>` command to verify the setting.
<<<
=== Configure Applications
Edit the `t4jdbc.properties` file in the `samples` folder. Refer to the `README` file in the `samples` folder for instructions.
Set these values for your environment:
* `catalog`: Specify a catalog that exists in the database.
* `schema`: Specify a schema that exists in the database.
* `user`: Specify the name of a user who will be accessing the database.
* `password`: Specify the password of a user who will be accessing the database.
* `url`: Specify this string: `jdbc:t4jdbc://<host-name>:<port-number>/:`
`<host-name>` is the IP address or host name of the database platform.
`<port-number>` is the location where the
{project-name} Database Connectivity Service (DCS) is running. (Default: *23400*).
See the http://trafodion.incubator.apache.org/docs/dcs_reference/index.html[{project-name} Database Connectivity Services Reference Guide]
for information about how to configure the DCS port.
*Example*
In this example, {project-name} authentication has not been enabled. Therefore, you can use a dummy
user and password. If authentication is enabled, then use your user and password information.
```
catalog = TRAFODION
schema = SEABASE
user = usr
password = pwd
url = jdbc:t4jdbc://trafodion.host.com:23400/:
```
NOTE: The driver’s class name is `org.trafodion.jdbc.t4.T4Driver`.
<<<
[[jdbct4-test-programs]]
== Test Programs
NOTE: You must use JDK and set up the environmental variables as documented in
<<jdbct4-java-development, Java Development>> to build the test programs.
The `README` file in the `samples` folder provide information for how you build and run sample Java programs.
You can use these programs to verify the setup of the {project-name} JDBC Type-4 driver.
See the <<jdbct4-validate-install, Validate Install Directory>> section above for information on the different
sample programs that are included with the {project-name} JDBC Type-4 driver.
*Windows Example*
Build and run the StatementSample test program to verify the JDBC Type-4 driver installation.
```
C:\trafodion\jdbct4\samples> cd StatementSample
C:\trafodion\jdbct4\samples\StatementSample> %JAVA_HOME%\bin\javac -classpath ..\..\lib\jdbcT4.jar *.java ..\common\*.java
Note: ..\common\sampleUtils.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
C:\trafodion\jdbct4\samples\StatementSample> %JAVA_HOME%\bin\java -classpath ..\..\lib\jdbcT4.jar;..;. -Dt4jdbc.properties=..\t4jdbc.properties StatementSample
Mar 16, 2016 9:36:54 PM common.sampleUtils getPropertiesConnection
INFO: DriverManager.getConnection(url, props) passed
Inserting TimeStamp
Simple Select
Printing ResultSetMetaData ...
No. of Columns 12
Column 1 Data Type: CHAR Name: C1
Column 2 Data Type: SMALLINT Name: C2
Column 3 Data Type: INTEGER Name: C3
Column 4 Data Type: BIGINT Name: C4
Column 5 Data Type: VARCHAR Name: C5
Column 6 Data Type: NUMERIC Name: C6
Column 7 Data Type: DECIMAL Name: C7
Column 8 Data Type: DATE Name: C8
Column 9 Data Type: TIME Name: C9
Column 10 Data Type: TIMESTAMP Name: C10
Column 11 Data Type: REAL Name: C11
Column 12 Data Type: DOUBLE PRECISION Name: C12
Fetching rows...
Printing Row 1 using getString(), getObject()
Column 1 - Row1 ,Row1
Column 2 - 100,100
Column 3 - 12345678,12345678
Column 4 - 123456789012,123456789012
Column 5 - Selva,Selva
Column 6 - 100.12,100.12
Column 7 - 100.12,100.12
Column 8 - 2000-05-06,2000-05-06
Column 9 - 10:11:12,10:11:12
Column 10 - 2000-05-06 10:11:12.000000,2000-05-06 10:11:12.0
Column 11 - 100.12,100.12
Column 12 - 100.12,100.12
Printing Row 2 using getString(), getObject()
Column 1 - Row2 ,Row2
Column 2 - -100,-100
Column 3 - -12345678,-12345678
Column 4 - -123456789012,-123456789012
Column 5 - Selva,Selva
Column 6 - -100.12,-100.12
Column 7 - -100.12,-100.12
Column 8 - 2000-05-16,2000-05-16
Column 9 - 10:11:12,10:11:12
Column 10 - 2000-05-06 10:11:12.000000,2000-05-06 10:11:12.0
Column 11 - -100.12,-100.12
Column 12 - -100.12,-100.12
Printing Row 3 using getString(), getObject()
Column 1 - TimeStamp ,TimeStamp
Column 2 - -100,-100
Column 3 - -12345678,-12345678
Column 4 - -123456789012,-123456789012
Column 5 - Selva,Selva
Column 6 - -100.12,-100.12
Column 7 - -100.12,-100.12
Column 8 - 2016-03-16,2016-03-16
Column 9 - 21:37:03,21:37:03
Column 10 - 2016-03-16 21:37:03.053,2016-03-16 21:37:03.053
Column 11 - -100.12,-100.12
Column 12 - -100.12,-100.12
End of Data
C:\trafodion\jdbct4\samples\StatementSample>
```
<<<
*Linux Example*
Build and run the StatementSample test program to verify the JDBC Type-4 driver installation.
```
$ cd $HOME/trafodion/jdbct4/samples/StatementSample
$ $JAVA_HOME/bin/javac -classpath ../../lib/jdbcT4.jar *.java ../common/*.java
Note: ..\common\sampleUtils.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
$ $JAVA_HOME/bin/java -classpath ../../lib/jdbcT4.jar:..:. -Dt4jdbc.properties=../t4jdbc.properties StatementSample
Mar 16, 2016 9:36:54 PM common.sampleUtils getPropertiesConnection
INFO: DriverManager.getConnection(url, props) passed
Inserting TimeStamp
Simple Select
Printing ResultSetMetaData ...
No. of Columns 12
Column 1 Data Type: CHAR Name: C1
Column 2 Data Type: SMALLINT Name: C2
Column 3 Data Type: INTEGER Name: C3
Column 4 Data Type: BIGINT Name: C4
Column 5 Data Type: VARCHAR Name: C5
Column 6 Data Type: NUMERIC Name: C6
Column 7 Data Type: DECIMAL Name: C7
Column 8 Data Type: DATE Name: C8
Column 9 Data Type: TIME Name: C9
Column 10 Data Type: TIMESTAMP Name: C10
Column 11 Data Type: REAL Name: C11
Column 12 Data Type: DOUBLE PRECISION Name: C12
Fetching rows...
Printing Row 1 using getString(), getObject()
Column 1 - Row1 ,Row1
Column 2 - 100,100
Column 3 - 12345678,12345678
Column 4 - 123456789012,123456789012
Column 5 - Selva,Selva
Column 6 - 100.12,100.12
Column 7 - 100.12,100.12
Column 8 - 2000-05-06,2000-05-06
Column 9 - 10:11:12,10:11:12
Column 10 - 2000-05-06 10:11:12.000000,2000-05-06 10:11:12.0
Column 11 - 100.12,100.12
Column 12 - 100.12,100.12
Printing Row 2 using getString(), getObject()
Column 1 - Row2 ,Row2
Column 2 - -100,-100
Column 3 - -12345678,-12345678
Column 4 - -123456789012,-123456789012
Column 5 - Selva,Selva
Column 6 - -100.12,-100.12
Column 7 - -100.12,-100.12
Column 8 - 2000-05-16,2000-05-16
Column 9 - 10:11:12,10:11:12
Column 10 - 2000-05-06 10:11:12.000000,2000-05-06 10:11:12.0
Column 11 - -100.12,-100.12
Column 12 - -100.12,-100.12
Printing Row 3 using getString(), getObject()
Column 1 - TimeStamp ,TimeStamp
Column 2 - -100,-100
Column 3 - -12345678,-12345678
Column 4 - -123456789012,-123456789012
Column 5 - Selva,Selva
Column 6 - -100.12,-100.12
Column 7 - -100.12,-100.12
Column 8 - 2016-03-16,2016-03-16
Column 9 - 21:37:03,21:37:03
Column 10 - 2016-03-16 21:37:03.053,2016-03-16 21:37:03.053
Column 11 - -100.12,-100.12
Column 12 - -100.12,-100.12
End of Data
$
```
<<<
== Uninstall JDBC Type-4 Driver
Run one of these sets of commands to remove the {project-name} JDBC Type 4 Driver:
* On Windows:
+
```
rmdir /s /q <jdbc-installation-directory>
```
+
*Example*
+
```
rmdir /s /q c:\trafodion\jdbct4
```
* On Linux:
+
```
rm -rf <jdbc-installation-directory>
```
+
*Example*
+
```
rm -rf $HOME/trafodion/jdbct4
```
NOTE: Remember to update/remove environmental variables if you've created them in th
<<jdbct4-java-development, Java Development>>.