http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/da748b4d/docs/client_install/src/asciidoc/_chapters/jdbct4.adoc ---------------------------------------------------------------------- diff --git a/docs/client_install/src/asciidoc/_chapters/jdbct4.adoc b/docs/client_install/src/asciidoc/_chapters/jdbct4.adoc index 3714472..43dbf73 100644 --- a/docs/client_install/src/asciidoc/_chapters/jdbct4.adoc +++ b/docs/client_install/src/asciidoc/_chapters/jdbct4.adoc @@ -1,413 +1,329 @@ -//// -/** - *@@@ 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 - -[[jdbct4-installation-requirements]] -== Installation Requirements - -The {project-name} JDBC Type 4 Driver requires a Java-enabled platform that supports the Java Development Kit (JDK) 1.7 or higher. - -[[jdbct4-java-environment]] -=== Java Environment - -The {project-name} JDBC Type 4 Driver requires that a compatible Java version be installed on the client workstation and that the Java path be set to -the correct location. The supported Java version is 1.7 or higher. - -NOTE: If you plan to do Java-based development, install the Java Development Kit (JDK) rather than the Java Runtime Environment (JRE). -These examples use JRE. - -[[jdbct4-verify-java-version]] -==== Verify Java Version - -To display the Java version of the client workstation on the screen, enter: - -``` -java -version -``` - -``` -C:\> java -version - -java version "1.7.0_45" # This is the version you need to check -Java(TM) SE Runtime Environment (build 1.7.0_45-b18) -Java HotSpot(TM) Client VM (build 24.45-b08, mixed mode, sharing) -C:\> -``` - -The Java version should be *1.7* or higher. If the returned version is not supported, please refer to -<<jdbct4-install-java, Installing a Supported Java Version>> below. - -<<< -If you see this message: - -``` -'java' is not recognized as an internal or external command, operable program or batch file.` -``` - -It indicates that the Java PATH is not set. Follow one of these sets of instructions, depending on the operating system of your client -workstation: - -* <<jdbct4-path-windows, Setting the PATH to a Supported Java Version on Windows>> -* <<jdbct4-path-linux, Setting the PATH to a Supported Java Version on Linux>> - -[[jdbct4-install-java]] -==== Install Supported Java Version - -The supported Java version is 1.7 or higher. To install one of the supported Java versions on the client workstation, -go to this link: http://www.java.com/en/download - -After installing the Java version, proceed with setting the Java path. Follow one of these sets of instructions, depending on the operating -system of your client workstation: - -* <<jdbct4-path-windows, Setting the PATH to a Supported Java Version on Windows>> -* <<jdbct4-path-linux, Setting the PATH to a Supported Java Version on Linux>> - -[[jdbct4-path-windows]] -==== Set Windows PATH Variable - -===== Windows 10 - -1. Right-click on the Windows icon on the menu bar. Select *System*. - -2. Click on *Advanced System Settings*. - -3. In the *System Properties* dialog box, click the *Advanced* tab. -4. Click the *Environment Variables* button. -5. Under *System* variables, select the variable named *Path*, and then click *Edit. . .*: -+ -image:{images}/win10_edit_path.jpg[Windows 10 Edit Path Variable] - -6. Click *Browse. . .*. Find the directory where you installed Java and select it. -+ -image:{images}/win10_select_java.jpg[image] - -7. Click *OK* to close the browse window. Click *OK* to close the edit window. -8. Verify that the updated *Path* appears under *System* variables, and click *OK*. -9. In the *System Properties* dialog box, click *OK* to accept the changes. - - -===== Windows 8 - -1. Open system Right-click the *Computer* icon on your desktop, and then select *Properties*. The *Control Panel > System and Security > System* window -appears. - -2. In the left navigation bar, click the *Advanced* system settings link. - -3. In the *System Properties* dialog box, click the *Environment Variables* button. - -4. Under *System* variables, select the variable named *Path*, and then click *Edit*: -+ -image:{images}/path2.jpg[image] - -5. Place the cursor at the start of the *Variable* value field and enter the path of the Java bin directory, ending with a semicolon (;): -+ -image:{images}/varval2.jpg[image] -+ -*Example* -+ -``` -"C:\Program Files (x86)\Java\jre7\bin"; -``` -+ -NOTE: Check that no space exists after the semicolon (;) in the path. If there are spaces in the directory name, delimit the entire directory -path in double quotes (") before the semicolon. - -6. Click *OK*. -7. Verify that the updated *Path* appears under *System* variables, and click *OK*. -8. In the *System Properties* dialog box, click *OK* to accept the changes. - -[[jdbct4-path_linux]] -==== Set Linux PATH Variable - -1. Open the user profile (`.profile` or `.bash_profile` for the Bash shell) in the `$HOME` directory. -+ -``` -cd $HOME -vi .profile -``` - -2. In the user profile, set the `PATH` environment variable to include the path of the Java bin -directory. -+ -``` -export PATH=/opt/java1.7/jre/bin:$PATH -``` -+ -NOTE: Place the path of the Java bin directory before `$PATH`, and check that no space exists after the colon (:) in the path. In the C shell, -use the setenv command instead of export. - -3. To activate the changes, either log out and log in again or execute the user profile. -+ -``` -. .profile -``` - -[[jdbct4-install-instructions]] -== Installation Instructions - -You download and extract the {project-name} client package using the instructions in <<introduction-download, Download Installation Package>> above. - -[[jdbct4-install-driver]] -=== Install JDBC Type-4 Driver - -1. Change the directory to the `clients` subdirectory. -2. Extract the contents of the `JDBCT4.zip` file by using the unzip command (or the extract function of your compression software): -+ -*Example* -+ -``` -unzip JDBCT4.zip -d $HOME/jdbc -``` - -The content of the target directory is as follows: - -[cols="33%l,30%l,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 - -=== 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%l,40%l,40%l",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, and _port-number_ is the location where the -{project-name} Database Connectivity Service (DCS) is running, which is *23400* by default. 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 - -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-install-driver, Install JDBC Type-4 Driver>> section above for information on the different -sample programs that are included with the {project-name} JDBC Type-4 driver. - -*Example* - -Build and run the StatementSample test program to verify the JDBC Type-4 driver installation. - -``` -C:\Development Tools\Trafodion JDBCT4\samples>cd StatementSample - -C:\Development Tools\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:\Development Tools\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:\Development Tools\Trafodion JDBCT4\samples\StatementSample> -``` - -<<< -== Uninstall JDBC Type-4 Driver -Run one of these sets of commands to remove the {project-name} JDBC Type 4 Driver: - -* On Linux: -+ -``` -rm -rf <jdbc-installation-directory> -``` -+ -*Example* -+ -``` -rm -rf ~/jdbc -``` - -* On Windows: -+ -``` -del <jdbc-installation-directory> -rmdir <jdbc-installation-directory> -``` -+ -<<< -+ -*Example* -+ -Windows uninstall -+ -``` -C:\>del /s JDBC -C:\JDBC\, Are you sure (Y/N)? Y -C:\JDBC\install\*, Are you sure (Y/N)? Y -Deleted file - C:\JDBC\install\t4jdbcSanityCheck.class -Deleted file - C:\JDBC\install\t4jdbcUninstall.class -Deleted file - C:\JDBC\install\product.contents -C:\JDBC\lib\*, Are you sure (Y/N)? Y -Deleted file - C:\JDBC\lib\jdbcT4.jar -C:\JDBC\samples\*, Are you sure (Y/N)? Y -Deleted file - C:\JDBC\samples\t4jdbc.properties -Deleted file - C:\JDBC\samples\README -C:\JDBC\samples\common\*, Are you sure (Y/N)? Y -Deleted file - C:\JDBC\samples\common\sampleUtils.java -C:\JDBC\samples\DBMetaSample\*, Are you sure (Y/N)? Y -Deleted file - C:\JDBC\samples\DBMetaSample\DBMetaSample.java -Deleted file - C:\JDBC\samples\DBMetaSample\README -C:\JDBC\samples\PreparedStatementSample\*, Are you sure (Y/N)? Y -Deleted file - C:\JDBC\samples\PreparedStatementSample\PreparedStatementSample.java -Deleted file - C:\JDBC\samples\PreparedStatementSample\README -C:\JDBC\samples\ResultSetSample\*, Are you sure (Y/N)? Y -Deleted file - C:\JDBC\samples\ResultSetSample\README -Deleted file - C:\JDBC\samples\ResultSetSample\ResultSetSample.java -C:\JDBC\samples\StatementSample\*, Are you sure (Y/N)? Y -Deleted file - C:\JDBC\samples\StatementSample\README -Deleted file - C:\JDBC\samples\StatementSample\StatementSample.java -C:\>rmdir /s JDBC -JDBC, Are you sure (Y/N)? Y -C:\> -``` - -<<< -== Reinstall JDBC Type-4 Driver - -1. Close all applications running on the workstation, except the Web browser. -2. Download and extract the {project-name} client package using the instructions in <<introduction-download, Download Installation Package>> above. -3. Install the new {project-name} JDBC Type-4 driver. See <<jdbct4-install-driver, Install JDBC Type-4 Driver>>. -4. Set up the client environment. Please refer to: <<jdbct4-setup-env, Set Up Client Environment>>. - +//// +/** + *@@@ 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>>. + +
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/da748b4d/docs/client_install/src/asciidoc/_chapters/odb.adoc ---------------------------------------------------------------------- diff --git a/docs/client_install/src/asciidoc/_chapters/odb.adoc b/docs/client_install/src/asciidoc/_chapters/odb.adoc index 512a0ea..c433513 100644 --- a/docs/client_install/src/asciidoc/_chapters/odb.adoc +++ b/docs/client_install/src/asciidoc/_chapters/odb.adoc @@ -1,66 +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 @@@ - */ -//// - -[[install-odb]] -= Install odb - -[[installation-requirements]] -== Installation Requirements - -The odb tool runs on 64-bit Linux. On a Linux workstation, odb requires `pthread` libraries, which are usually installed by default. It also -requires the unixODBC Driver Manager to be installed and configured on the client workstation. For more information, see the -{docs-url}/odb/index.html[_{project-name} odb User Guide_]. - -[[installation-instructions]] -== Installation Instructions - -NOTE: Before following these installation instructions, please make sure to install and configure unixODBC on the client workstation. For more -information, see the {docs-url}/odb/index.html[_{project-name} odb User Guide_]. - -You download and extract the {project-name} client package using the instructions in <<introduction-download, Download Installation Package>> above. - -[[odb-install]] -=== Install odb - -1. Change the directory to the `clients` subdirectory. -2. Unpack the contents of the `odb64_linux.tar.gz` file to a location on your client workstation: -+ -``` -mkdir $HOME/odb -tar -xzf odb64_linux.tar.gz -C $HOME/odb -``` -+ -The command extracts these files: -+ -* `README` -* `/bin/odb64luo` (the odb executable) - -3. You are now ready to run the odb executable. For more information, see the {docs-url}/odb/index.html[_{project-name} odb User Guide_]. - -[[odb-uninstall]] -== Uninstall odb - -To uninstall odb, delete the `README` and `/bin/odb64luo` files from their installed location. - -``` -rm -rf odb-installation-directory -``` +//// +/** + *@@@ 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 @@@ + */ +//// + +[[odb-install]] += Install odb + +If you have not done so already, please ensure that you have +<<download-software, unpackaged the {project-name} client software>> and +<<odbc-linux-install, setup the {project-name} Linux ODBC Driver>>. + +The examples in this chapter assumes that you have unpackaged the odb installation file +to `$HOME/trafodion/odb`. + +== odb Requirements + +odb requires: + +* pthread libraries (Generally installed by default) +* unixODBC. See installation instructions <<odb-install-unixodbc, below>>. + +[[odb-install-unixodbc]] +== Install and Configure unixODBC + +This section explains how to install and configure `unixODBC`. +Refer to the http://www.unixodbc.org/doc/[unixODBC documentation] for additional +configuration information. + +1. Obtain the source code tar ball from http://www.unixodbc.org/ Use version 2.3.*_x_* or later. +2. Unpack the tar ball: ++ +``` +$ tar -xzvf unixODBC-2.3.1.tar.gz +``` + +3. Configure unixODBC installation (root access required): ++ +``` +$ cd unixODBC-2.3.1 +$ sudo ./configure --disable-gui --enable-threads --disable-drivers +``` ++ +unixODBC is installed under `/usr/local`. ++ +If you don't have root privileges or you want to install unixODBC somewhere else +then `add --prefix=<installation_path>` to the `configure` command here above. ++ +*Example - Install unixODBC in Alternate Location* ++ +``` +$ ./configure --prefix=$HOME/trafodion/unixodbc --disable-gui --enable-threads --disable-drivers +``` ++ +<<< +4. Compile unixODBC sources: ++ +``` +$ make +``` + +5. Install unixODBC: + +``` +$ make install +``` + +=== Configure unixODBC + +1. Define environment variables. +2. Define data sources. + +Start with the environment variables (which you can add to your profile script): + +1. Set the `ODBCHOME` variable to the unixODBC installation directory (the one configured via `--prefix` here above). ++ +*Example* ++ +``` +$ export ODBCHOME=$HOME/trafodion/unixodbc +``` + +2. Configure the system data sources directory (the one containing `odbc.ini` and `odbcinst.ini`). +Normally, the `etc/` directory under `$ODBCHOME`: ++ +``` +$ export ODBCSYSINI=$ODBCHOME/etc +``` + +3. Configure the `ODBCINI` variable to the full path of the `odbc.ini` file: ++ +``` +$ export ODBCINI=$ODBCSYSINI/odbc.ini +``` + +4. Add the unixODBC lib directory to your `LD_LIBRARY_PATH` (Linux) or `LIBPATH` (IBM AIX) or `SHLIB_PATH` (HP/UX): ++ +``` +$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ODBCHOME/lib +``` + +<<< +=== Configure Data Sources + +==== `odbc.ini` + +``` +[ODBC] +AppUnicodeType=utf16 + +[<DATA_SOURCE_NAME>] +Description = DSN Description +Driver = <odbcinst.ini corresponding section> +... +Other (Driver specific) parameters +... +``` + +==== `odbcinst.ini` + +``` +[<Driver name in odbc.ini>] +Description = Driver description +Driver = <ODBC driver> +FileUsage = 1 +UsageCount = 1 +``` + +<<< +*{project-name} Example* + +``` +$ cat odbc.ini + +[ODBC] +AppUnicodeType=utf16 + +[traf] +Description = traf DSN +Driver = Trafodion +Catalog = TRAFODION +Schema = QA +DataLang = 0 +FetchBufferSize = SYSTEM_DEFAULT +Server = TCP:<server-name>:<port-no> +SQL_ATTR_CONNECTION_TIMEOUT = SYSTEM_DEFAULT +SQL_LOGIN_TIMEOUT = SYSTEM_DEFAULT +SQL_QUERY_TIMEOUT = NO_TIMEOUT +ServiceName = TRAFODION_DEFAULT_SERVICE + +$ cat odbcinst.ini + +[Trafodion] +Description = {project-name} ODBC Stand Alone Driver +Driver = /<dir-name>/conn/clients/odbc/libtrafodbc_drvr64.so +FileUsage = 1 +UsageCount = 1 + +[ODBC] +Threading = 1 +Trace = Off +Tracefile = uodbc.trc +$ +``` + +<<< +The `Threading` setting is defined as follows +(extracted from unixODBC sources `DriverManager/handles.c`): + +[source,cplusplus] +---- +/* +* ... +* If compiled with thread support the DM allows four different +* thread strategies +* + +* Level 0 - Only the DM internal structures are protected +* the driver is assumed to take care of it's self +* + +* Level 1 - The driver is protected down to the statement level +* each statement will be protected, and the same for the connect +* level for connect functions, note that descriptors are considered +* equal to statements when it comes to thread protection. +* + +* Level 2 - The driver is protected at the connection level. only +* one thread can be in a particular driver at one time +* + +* Level 3 - The driver is protected at the env level, only one thing +* at a time. +* + +* By default the driver open connections with a lock level of 0, +* drivers should be expected to be thread safe now. +* this can be changed by adding the line +* + +* Threading = N +* +* to the driver entry in odbcinst.ini, where N is the locking level +* +*/ +---- + +<<< +[[odb-verify-install]] +== Verify odb Installation + +`$HOME/trafodion/odb` should contain the following files. + +* `README` +* `/bin/odb64luo` (the odb executable) + +See the {docs-url}/odb/index.html[{project-name} odb User Guide] for information how to use odb. + +[[odb-uninstall]] +== Uninstall odb + +To uninstall odb, delete the `README` and `/bin/odb64luo` files from their installed location. + +*Example* + +``` +rm -rf $HOME/trafodion/odb +``` http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/da748b4d/docs/client_install/src/asciidoc/_chapters/odbc_linux.adoc ---------------------------------------------------------------------- diff --git a/docs/client_install/src/asciidoc/_chapters/odbc_linux.adoc b/docs/client_install/src/asciidoc/_chapters/odbc_linux.adoc index 6838df8..0321ace 100644 --- a/docs/client_install/src/asciidoc/_chapters/odbc_linux.adoc +++ b/docs/client_install/src/asciidoc/_chapters/odbc_linux.adoc @@ -1,302 +1,399 @@ -//// -/** - *@@@ 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 @@@ - */ -//// - -= Install Linux ODBC Driver - -== Installation Requirements - -The driver for Linux requires `libgcc 3.4.3` and `libstd++ 6.0`. - -If you are building ODBC applications, please use the preferred build platform, RedHat 6.x or CentOS 6.x. - -== Installation Instructions - -You download and extract the {project-name} client package using the instructions in <<introduction-download, Download Installation Package>> above. - -The package file contains the {project-name} ODBC distribution file, `TRAF_ODBC_Linux_Driver_64.tar.gz`, which is extracted to the `clients` subdirectory. -It contains the following files: - -``` -connect_test.cpp -install.sh -libicudataNv44.so.44 -libicuucNv44.so.44 -libtrafodbc_l64.so -libtrafodbc_l64_drvr.so -LICENSE -license.txt -MD5SUM -TRAFDSN -``` - -By default, a new version of the {project-name} ODBC driver is installed in the following directories unless you specify a different directory -during installation: - -* `/usr/lib64` -* `/etc/odbc` - -NOTE: The following header files are not packaged with the {project-name} ODBC driver: + - + -- `sql.h` + -- `sqlext.h` + -- `sqltypes.h` + -- `sqlucode.h` + - + -To install those header files, <<win_odbc_client_env, Setting Up the Client Environment>>.. - -=== Install/Reinstall Linux ODBC Driver - -NOTE: You must have root access to install the {project-name} ODBC Driver for Linux at the default system location. - -1. Change the directory to the clients subdirectory, and decompress the `.tar.gz` distribution file: -+ -``` -gunzip TRAF_ODBC_Linux_Driver_64.tar.gz -``` -2. Extract the contents of the `.tar` file. A directory called `PkgTmp` is created. -+ -``` -tar âxvf TRAF_ODBC_Linux_Driver_64.tar -``` - -3. Install the product by entering these commands: -+ -``` -cd PkgTmp -sudo ./install.sh -``` -+ -Except for the sample file, the `install.sh` script saves a copy (`.SAV`) of your previous installation files if they exist. -4. Accept the terms of the license agreement by entering *yes*. -5. Enter a directory for the library files, or press Enter to use the default directory (`/usr/lib64`). -6. Enter a directory for the data-source template file, or press *Enter* to use the default directory (`/etc/odbc`). -7. Enter a directory for the sample program, or press *Enter* to use the default directory (`/etc/odbc`). - -<<< -=== Set Up Client Environment - -If you selected default options during installation, ensure that: - -* The libraries are located in the `/usr/lib64` directory. -* A `TRAFDSN` file is in the `/etc/odbc` directory. - -If you select non-default locations during installation, ensure that the files are installed in the directories that you specified during -installation. - -The driver expects the `TRAFDSN` file to be present in either the default location (`/etc/odbc`) or the current working directory (`CWD`) of the -application. - -If you are building ODBC applications, you need to install these header files in your build environment: - -* `sql.h` -* `sqlext.h` -* `sqltypes.h` -* `sqlucode.h` - -To install those header files from the latest packages, run this `yum` command: - -``` -sudo yum -y install libiodbc libiodbc-devel -``` - -The `yum` command automatically installs the header files in the `/usr/include` and `/usr/include/libiodbc` directories. - -<<< -=== Enable Compression - -When compression is enabled in the ODBC driver, the ODBC driver can send and receive large volumes of data quickly and efficiently to and from -the {project-name} Database Connectivity Services (DCS) server over a TCP/IP network. By default, compression is disabled. - -To enable compression in the ODBC driver or to change the compression setting, follow these steps: - -* If you are using the {project-name} ODBC driver manager, add -+ -``` -Compression = compression-level -``` -+ -to the `DSN` section of `TRAFDSN` file. - -* If you are using a third-party driver manager, such as unixODBC, add -+ -``` -Compression = compression-level -``` -+ -to the `DSN` section of the `odbc.ini` file. - -The `_compression-level_` is one of these values: - -* `SYSTEM_DEFAULT`, which is the same as no compression -* `no compression` -* `best speed` -* `best compression` -* `balance` -* An integer from `0` to `9`, with `0` being `no compression` and `9` being the `maximum available compression` - -<<< -=== Use Third-Party Driver Manager - -NOTE: For better performance, we recommend that you use at least version `2.3._x_` of unixODBC. - -* If you are using an external driver manager, then you must point to `libtrafodbc_drvr64.so` and not to `libtrafodbc64.so`. -* The driver, `libtrafodbc_l64_drvr.so`, has been verified with iODBC and unixODBC driver managers. -* These driver managers, as well as documentation, can be found at these Web sites: -* http://www.iodbc.org/ -* http://www.unixodbc.org/ -* For information on the necessary data-source configuration options, you will need to add to the respective configuration files (for example, -to `odbc.ini`). - -<<< -=== Run Sample Program (`connect_test`) - -NOTE: The examples after each step assume that you have default installation directories. - -If you have a previous version of the {project-name} ODBC driver installed, you need to re-link your existing application to ensure that you pick up -the correct version of the driver. If you are unsure of the version, check the version of your application with this command: - -``` -ldd object-file -``` - -1. Move to the directory where you installed the sample program: -+ -``` -cd /etc/odbc -``` - -2. Set the environment variable `LD_LIBRARY_PATH`: -+ -``` -export LD_LIBRARY_PATH=<path-to-odbc-library-files or /usr/lib64> -``` -+ -*Example* -+ -``` -export LD_LIBRARY_PATH=/usr/lib64 -``` - -3. In the `/etc/odbc/TRAFDSN` file, add the correct IP address to the `Server` parameter for the `Default_DataSource`. -+ -*Example* -+ -``` -[Default_DataSource] -Description = Default Data Source -Catalog = TRAFODION -Schema = SEABASE -DataLang = 0 -FetchBufferSize = SYSTEM_DEFAULT -Server = TCP:1.2.3.4:23400 <- _Set IP Address_ -SQL_ATTR_CONNECTION_TIMEOUT = SYSTEM_DEFAULT -SQL_LOGIN_TIMEOUT = SYSTEM_DEFAULT -SQL_QUERY_TIMEOUT = NO_TIMEOUT -``` -+ -<<< - -4. Compile the sample program. -+ -``` -sudo g++ -g connect_test.cpp -L/usr/lib64 -I/usr/include/odbc -ltrafodbc64 -o connect_test -``` - -5. Run the sample program: -+ -``` -./connect_test -d Default_DataSource -u username -p password -``` - -If the sample program runs successfully, you should see output similar to the following: - -``` -Using Connect String: DSN=Default_DataSource;UID=username;PWD=****; -Connect Test Passed... -``` - -<<< -[[linux_odbc_run_basicsql]] -=== Run Sample Program (`basicsql`) - -NOTE: The Basic SQL sample program is not currently bundled with the ODBC Linux driver. To obtain the source code for this program, see -<<odbc_sample_program, `basicsql` (Sample ODBC Program)>>. - -If you have a previous version of the {project-name} ODBC driver installed, you need to re-link your existing application to ensure that you pick up -the correct version of the driver. If you are unsure of the version, check the version of your application with this command: - -``` -ldd object-file -``` - -1. Move to the directory where you put the `basicsql.cpp` file. - -2. Set the environment variable `LD_LIBRARY_PATH`: -+ -``` -export LD_LIBRARY_PATH=<path-to-odbc-driver-dlls> -``` - -3. In the `/etc/odbc/TRAFDSN` file, add the correct IP address to the `Server` parameter for the `Default_DataSource`. For example: -+ -*Example* -+ -``` -[Default_DataSource] -Description = Default Data Source -Catalog = TRAFODION -Schema = SEABASE -DataLang = 0 -FetchBufferSize = SYSTEM_DEFAULT -Server = TCP:1.2.3.4:23400 -SQL_ATTR_CONNECTION_TIMEOUT = SYSTEM_DEFAULT -SQL_LOGIN_TIMEOUT = SYSTEM_DEFAULT -SQL_QUERY_TIMEOUT = NO_TIMEOUT -``` -+ -<<< - -4. Compile the sample program. -+ -``` -g++ -g basicsql.cpp -L. -I. -ltrafodbc64 -o basicsql -``` - -5. Run the sample program: -+ -``` -basicsql Default_DataSource <username> <password> -``` - -If the sample program runs successfully, you should see output similar to the following: - -``` -Using Connect String: DSN=Default_DataSource;UID=user1;PWD=pwd1; -Successfully connected using SQLDriverConnect. -Drop sample table if it exists... Creating sample table TASKS... -Table TASKS created using SQLExecDirect. -Inserting data using SQLBindParameter, SQLPrepare, SQLExecute Data -Data inserted. -Fetching data using SQLExecDirect, SQLFetch, SQLGetData -Data selected: 1000 CREATE REPORTS 2014-3-22 -Basic SQL ODBC Test Passed! -``` +//// +/** + *@@@ 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 @@@ + */ +//// + +[[odbc-linux-install]] += Install Linux ODBC Driver + +== Installation Requirements + +If you have not done so already, please ensure that you have <<download-software, unpackaged the {project-name} +client software>>. + +In addition, the ODBC driver for Linux requires `libgcc 3.4.3` and `libstd++ 6.0`. + +If you are building ODBC applications, please use the preferred build platform, RedHat 6.x or CentOS 6.x. + +The examples in this chapter assumes that you have unpackaged the JDBC Type for installation files +to `$HOME/trafodion/odbc`. + +<<< +== Validate Install Directory + +`$HOME/trafodion/odbc/PkgTmp` should contain: + +``` +connect_test.cpp +install.sh +libicudataNv44.so.44 +libicuucNv44.so.44 +libtrafodbc_l64.so +libtrafodbc_l64_drvr.so +LICENSE +license.txt +MD5SUM +TRAFDSN +``` + +By default, a new version of the {project-name} ODBC driver is installed in the following directories +unless you specify a different directory during installation: + +* `/usr/lib64` +* `/etc/odbc` + +NOTE: The following header files are not packaged with the {project-name} ODBC driver: + + + +- `sql.h` + +- `sqlext.h` + +- `sqltypes.h` + +- `sqlucode.h` + + + +To install those header files, <<linux_odbc_client_env, Set Up Client Environment>> below. + +<<< +== Install/Reinstall Linux ODBC Driver + +NOTE: You must have root (`sudo`) access to install the {project-name} ODBC Driver for Linux at the default system location. +If you don't have such access, the install the ODBC driver to an alternate location; for example: `$HOME/trafodion/odbc`. + +. Install the product by entering these commands: ++ +*With `sudo` Access* ++ +``` +cd $HOME/trafodion/odbc/PkgTmp +sudo ./install.sh +``` ++ +*Without `sudo` Access* ++ +``` +cd $HOME/trafodion/odbc/PkgTmp +./install.sh +``` ++ +Except for the sample file, the `install.sh` script saves a copy (`.SAV`) of your previous installation files if they exist. +. Accept the terms of the license agreement by entering *yes*. ++ +NOTE: Don't use environmental variables when specifying alternative location. Instead, use +the full path. For example, specify `/opt/user/trafodion/odbc` instead of `$HOME/trafodion/odbc`. + +. Enter a directory for the library files, or press Enter to use the default directory (`/usr/lib64`). +. Enter a directory for the data-source template file, or press *Enter* to use the default directory (`/etc/odbc`). +. Enter a directory for the sample program, or press *Enter* to use the default directory (`/etc/odbc`). +. If you installed the library files, data-source template file, and the sample program in an + alternative location, then verify the directory content: + +<<< + +[[linux_odbc_client_env]] +=== Set Up Client Environment + +If you selected default options during installation, ensure that: + +* The libraries are located in the `/usr/lib64` directory. +* A `TRAFDSN` file is in the `/etc/odbc` directory. + +If you select non-default locations during installation, ensure that the files are installed +in the directories that you specified during installation: + +``` +$ cd $HOME/trafodion/odbc +$ ls +connect_test.cpp libicuuc.so libtrafodbc_drvr64.so libtrafodbc_l64.so PkgTmp +libicudata.so libicuuc.so.44 libtrafodbc_l64_drvr.so libtrafodbc_l64.so.1 TRAFDSN +libicudata.so.44 libtrafodbc64.so libtrafodbc_l64_drvr.so.1 MD5SUM + +$ +``` + +The driver expects the `TRAFDSN` file to be present in either the default location (`/etc/odbc`) +or the current working direct or (`CWD`) of the application. As a best practice, copy +the `TRAFDSN` file to the application directory. + +Edit the `TRAFDSN` file. Make changes to the `Default_DataSource` section. At a minimum, +change the value for `Server` to the address of the host you are connecting to. + +*Before* + +``` +[Default_DataSource] +Description = Default Data Source +Catalog = TRAFODION +Schema = SEABASE +DataLang = 0 +FetchBufferSize = SYSTEM_DEFAULT +Server = TCP:1.2.3.4:23400 +SQL_ATTR_CONNECTION_TIMEOUT = SYSTEM_DEFAULT +SQL_LOGIN_TIMEOUT = SYSTEM_DEFAULT +SQL_QUERY_TIMEOUT = NO_TIMEOUT +``` + +<<< +*After* + +``` +[Default_DataSource] +Description = Default Data Source +Catalog = TRAFODION +Schema = SEABASE +DataLang = 0 +FetchBufferSize = SYSTEM_DEFAULT +Server = TCP:node01.host.com:23400 +SQL_ATTR_CONNECTION_TIMEOUT = SYSTEM_DEFAULT +SQL_LOGIN_TIMEOUT = SYSTEM_DEFAULT +SQL_QUERY_TIMEOUT = NO_TIMEOUT +``` + +If you are building ODBC applications, you need to install these header files in your build environment: + +* `sql.h` +* `sqlext.h` +* `sqltypes.h` +* `sqlucode.h` + +To install those header files from the latest packages, run this `yum` command: + +``` +sudo yum -y install libiodbc libiodbc-devel +``` + +The `yum` command automatically installs the header files in the `/usr/include` and `/usr/include/libiodbc` directories. + +<<< +=== Enable Compression + +When compression is enabled in the ODBC driver, the ODBC driver can send and receive large volumes of data quickly and efficiently to and from +the {project-name} Database Connectivity Services (DCS) server over a TCP/IP network. By default, compression is disabled. + +To enable compression in the ODBC driver or to change the compression setting, follow these steps: + +* If you are using the {project-name} ODBC driver manager, add ++ +``` +Compression = compression-level +``` ++ +to the `DSN` section of `TRAFDSN` file. + +* If you are using a third-party driver manager, such as unixODBC, add ++ +``` +Compression = compression-level +``` ++ +to the `DSN` section of the `odbc.ini` file. + +The `_compression-level_` is one of these values: + +* `SYSTEM_DEFAULT`, which is the same as no compression +* `no compression` +* `best speed` +* `best compression` +* `balance` +* An integer from `0` to `9`, with `0` being `no compression` and `9` being the `maximum available compression` + +*Example* + +``` +[Default_DataSource] +Description = Default Data Source +Catalog = TRAFODION +Schema = SEABASE +DataLang = 0 +FetchBufferSize = SYSTEM_DEFAULT +Server = TCP:node01.host.com:23400 +SQL_ATTR_CONNECTION_TIMEOUT = SYSTEM_DEFAULT +SQL_LOGIN_TIMEOUT = SYSTEM_DEFAULT +SQL_QUERY_TIMEOUT = NO_TIMEOUT +Compression = Best Compression +``` + +<<< +== Use Third-Party Driver Manager + +NOTE: For better performance, we recommend that you use at least version `2.3._x_` of unixODBC. + +* If you are using an external driver manager, then you must point to `libtrafodbc_drvr64.so` and not to `libtrafodbc64.so`. +* The driver, `libtrafodbc_l64_drvr.so`, has been verified with iODBC and unixODBC driver managers. +* These driver managers, as well as documentation, can be found at these Web sites: +** http://www.iodbc.org/ +** http://www.unixodbc.org/ +* For information on the necessary data-source configuration options, you will need to add to the respective configuration files (for example, +to `odbc.ini`). + +<<< +== Run Sample Program (`connect_test`) + +NOTE: The examples after each step assume that you have default installation directories. + +If you have a previous version of the {project-name} ODBC driver installed, +you need to re-link your existing application to ensure that you pick up +the correct version of the driver. If you are unsure of the version, +check the version of your application with this command: + +``` +ldd object-file +``` + +. Move to the directory where you installed the sample program: ++ +``` +cd /etc/odbc +``` + +. Set the environment variable `LD_LIBRARY_PATH`: ++ +``` +export LD_LIBRARY_PATH=<path-to-odbc-library-files or /usr/lib64> +``` ++ +*Example* ++ +``` +export LD_LIBRARY_PATH=/usr/lib64 +``` + +. In the `/etc/odbc/TRAFDSN` file, add the correct IP address to the `Server` parameter for the `Default_DataSource`. ++ +*Example (connecting to `node01.host.com:23400`)* ++ +``` +[Default_DataSource] +Description = Default Data Source +Catalog = TRAFODION +Schema = SEABASE +DataLang = 0 +FetchBufferSize = SYSTEM_DEFAULT +Server = TCP:node01.host.com:23400 +SQL_ATTR_CONNECTION_TIMEOUT = SYSTEM_DEFAULT +SQL_LOGIN_TIMEOUT = SYSTEM_DEFAULT +SQL_QUERY_TIMEOUT = NO_TIMEOUT +Compression = Best Compression +``` ++ +<<< + +. Compile the sample program. ++ +*Default Installation* ++ +``` +g++ -g connect_test.cpp -L/usr/lib64 -I/usr/include/odbc -ltrafodbc64 -o connect_test +``` ++ +*Alterntiave Installation* ++ +``` +g++ -g connect_test.cpp -L$HOME/trafodion/odbc -I/usr/include/odbc -ltrafodbc64 -o connect_test +``` + +. Run the sample program: ++ +``` +./connect_test -d Default_DataSource -u username -p password +``` + +If the sample program runs successfully, you should see output similar to the following: + +``` +Using Connect String: DSN=Default_DataSource;UID=username;PWD=****; +Connect Test Passed... +``` + +<<< +[[linux_odbc_run_basicsql]] +== Run Sample Program (`basicsql`) + +NOTE: The Basic SQL sample program is not currently bundled with the ODBC Linux driver. To obtain the source code for this program, see +<<odbc_sample_program, `basicsql` (Sample ODBC Program)>>. + +If you have a previous version of the {project-name} ODBC driver installed, +you need to re-link your existing application to ensure that you pick up +the correct version of the driver. + +If you are unsure of the version, check the version of your application with this command: + +``` +ldd object-file +``` + +. Move to the directory where you put the `basicsql.cpp` file. + +. Set the environment variable `LD_LIBRARY_PATH`: ++ +``` +export LD_LIBRARY_PATH=<path-to-odbc-driver-dlls> +``` + +. In the `/etc/odbc/TRAFDSN` file, add the correct IP address to the `Server` parameter for the `Default_DataSource`. For example: ++ +*Example (connecting to `node01.host.com:23400`)* ++ +``` +[Default_DataSource] +Description = Default Data Source +Catalog = TRAFODION +Schema = SEABASE +DataLang = 0 +FetchBufferSize = SYSTEM_DEFAULT +Server = TCP:node01.host.com:23400 +SQL_ATTR_CONNECTION_TIMEOUT = SYSTEM_DEFAULT +SQL_LOGIN_TIMEOUT = SYSTEM_DEFAULT +SQL_QUERY_TIMEOUT = NO_TIMEOUT +Compression = Best Compression +``` ++ +<<< + +. Compile the sample program. ++ +*Default Installation* ++ +``` +g++ -g basicsql.cpp -L/usr/lib64 -I/usr/include/odbc -ltrafodbc64 -o basicsql +``` ++ +*Alterntiave Installation* ++ +``` +g++ -g basicsql.cpp -L$HOME/trafodion/odbc -I/usr/include/odbc -ltrafodbc64 -o basicsql +``` + +. Run the sample program: ++ +``` +./basicsql Default_DataSource <username> <password> +``` + +If the sample program runs successfully, you should see output similar to the following: + +``` +Using Connect String: DSN=Default_DataSource;UID=user1;PWD=pwd1; +Successfully connected using SQLDriverConnect. +Drop sample table if it exists... Creating sample table TASKS... +Table TASKS created using SQLExecDirect. +Inserting data using SQLBindParameter, SQLPrepare, SQLExecute Data +Data inserted. +Fetching data using SQLExecDirect, SQLFetch, SQLGetData +Data selected: 1000 CREATE REPORTS 2014-3-22 +Basic SQL ODBC Test Passed! +``` http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/da748b4d/docs/client_install/src/asciidoc/_chapters/odbc_windows.adoc ---------------------------------------------------------------------- diff --git a/docs/client_install/src/asciidoc/_chapters/odbc_windows.adoc b/docs/client_install/src/asciidoc/_chapters/odbc_windows.adoc index 48435ff..67e2d6d 100644 --- a/docs/client_install/src/asciidoc/_chapters/odbc_windows.adoc +++ b/docs/client_install/src/asciidoc/_chapters/odbc_windows.adoc @@ -1,244 +1,246 @@ -//// -/** - *@@@ 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 @@@ - */ -//// - -[[install-windows-odbc-driver]] -= Install Windows ODBC Driver - -WARNING: License issues prevent us from including the ODBC Driver for Windows in this release. Contact the -{project-name} user e-mail list ({project-support}) for help obtaining the driver. - -== Installation Requirements - -[cols="40%s,60%",options="header"] -|=== -| Item | Requirement -| Computer | Windows compatible PC workstation -| Memory | Recommended minimum 32 MB -| Disk Space | Minimum 30 MB additional free space -| Operating System | x64 Edition of Microsoft Windows 7, Windows 8, Windows 10, or Windows Server 2008 -| Network Software | TCP/IP -|=== - -== Installation Instructions -[[win_odbc_install]] - -=== Install Windows ODBC Driver - -NOTE: To install the driver on your PC, you must be logged on with a user ID that has administrator privileges. - -You download and extract the {project-name} client package using the instructions in <<introduction-download, Download Installation Package>> above. - -The ODBC client installation file, `TFODBC64-*.exe`, which installs or links to multiple client components: - -[cols="40%s,60%",options="header"] -|=== -| This client component… | Does this… -| Microsoft ODBC Driver Manager | Manages access to ODBC drivers for applications. The driver manager loads and unloads drivers and passes calls for ODBC functions to the -correct driver. -| Trafodion ODBC driver | Implements ODBC function calls to enable an ODBC client application to access the {project-name} database. -| Microsoft ODBC Administrator | Adds, configures, and removes ODBC data sources on client workstations. -|=== - -By default, a new version of the ODBC driver is installed in this directory and its folders unless you specify a different directory -during installation: - -[cols="40%l,60%",options="header"] -|=== -| Default Installation Directory | Client Operating System -| C:\Program Files\Trafodion\TRAF | ODBC _version_ Windows 64-bit -|=== - -=== Start the InstallShield wizard -The InstallShield wizard walks you through the steps to install the client components ({project-name} ODBC 1.0) on your workstation. You can -perform the installation in _interactive mode_, in which you provide input or accept defaults when prompted as ODBC is installed. -Please refer to <<win_odbc_interactive_mode,Interactive Mode Installation>> below. - -[[win_odbc_interactive_mode]] -==== Interactive Mode Installation - -1. Double-click the `TFODBC64-*.exe` distribution file to start the InstallShield wizard. -2. On the *Welcome* page, click *Next*. -3. Read and select the *I accept the agreement* radio button. Click *Next*. -4. On the *Destination Folder* page, click *Install* to select the default location: `C:\Program Files\Trafodion\TRAF ODBC _version_\` -+ -This location is the installation directory for ODBC header and help files. All other ODBC files are installed in `%SYSTEMROOT%\system32`. - -5. Read and accept the Microsoft C++ license agreement by checking the *I agree to the license terms and conditions*. Click *Install*. -6. Click *Close*. -7. Click *Finish* to exit the installation wizard. - -=== Add a client data source -1. Start the Microsoft ODBC Administrator: -* On Windows 7: *Start>All Programs>{project-name} ODBC _version_>MS ODBC Administrator* -* On Windows 8: Right-click the *{project-name} ODBC _version_* icon on the desktop and select MS ODBC Administrator. -* On Windows 10: Right-click the Windows icon in the menu bar. Select *Settings*. Search for *Set up ODBC data sources (64-bit)*. Click on the found item. - -2. In the *ODBC Data Source Administrator* dialog box, click *Add*. -3. Select *TRAF ODBC _version_*, and then click *Finish* to start the *Create a New {project-name} ODBC Data Source* wizard. -4. Enter the data source name (for example, `Default_DataSource_Schema1`) and an optional description, and click *Next*. -5. Enter the `IP address` or `host name` for the database platform. Enter the default port number as *23400*^1^. Leave the defaults as is, and click *Next*. -6. Enter the schema name. The default schema name is `SEABASE`. Click *Next*. -7. Enter the translate DLL name and its option, if you have one. If not, leave it blank. Leave the localization defaults as is. -+ -The Replacement Character replaces any character that is incompatible for translation when retrieving data. It is one character (one or two -bytes long). The Replacement Character is assumed to be in the character set specified in the Client/Server Character Set Interaction. If it is not specified, `?` is used as the default. -+ -Click *Finish*. - -8. The wizard gives you an opportunity to test the connection. Click *Test Connection* and click *OK*. -9. The server ID and schema are filled in for you. Enter a valid user name and password, and click *OK*. -+ -The wizard attempts to connect to the data source and displays a message stating whether it was successful or not. -10. Click *OK* to save the data source, or click *Cancel* _twice_ to quit the *Create Data Source* wizard. - -^1^ Your specific installation may use a different port number. Check with your {project-name} administrator. - -<<< -[[win_odbc_client_env]] -=== Set Up Client Environment -All client data sources connect to the pre-configured server data source on the database platform, which is `Default_DataSource`. - -You can configure one data source only, `Default_DataSource`, on the database platform, but you can create other data source -definitions on the workstation. - -For example, if you have more than one schema on the database platform and you want to connect -to each of those schemas on the database platform, you can create a client data source for each of those schemas. - -Instead of changing the schema definition in the data source definition on the workstation, you can create multiple data source -definitions with different schemas on the workstation. The client data source will use the specified schema but will connect to -`Default_DataSource` on the database platform. - -To create a data source on the client workstation, follow these steps: - -1. Launch the *MS ODBC Administrator*. -* On Windows 7: *Start>All Programs>{project-name} ODBC _version_>MS ODBC Administrator* -* On Windows 8: Right-click the *{project-name} ODBC _version_* icon on the desktop and select MS ODBC Administrator. -* On Windows 10: Right-click the Windows icon in the menu bar. Select *Settings*. Search for *Set up ODBC data sources (64-bit)*. Click on the found item. - -2. In the *ODBC Data Source Administrator* dialog box, select the *User DSN* tab, and click *Add*. -3. Select the *TRAF ODBC _version_* driver, and then click *Finish*. -+ -A new dialog box appears, prompting you to create a new data source. -4. Enter the name of the data source, `Default_DataSource`, and click *Next* to continue. -5. Enter the IP address and port number of the {project-name} system to which will be connecting. By default, the port number is *23400*^1^. -Click *Next* to continue. -6. Select the default schema. If you do not select a schema, the default is `SEABASE`. Click *Next* to continue. -+ -<<< -7. If desired, configure the *translate dll*, which translates data from one character set to another, and configure the localization. By -default, the client error message language is English, and the clientâs local character set is used. Click *Finish* to continue. -+ -The *Test {project-name} ODBC Connection* dialog box appears, allowing you to test the connection using the data source that you created. - -8. Click *Test Connection*. -9. When prompted, enter your user name and password, and, optionally, schema. Click *OK*. -+ -If the connection is successful, you will see `Connected Successfully` in the *Test {project-name} ODBC Connection* dialog box. -10. Click *OK* to save the data source, or click *Cancel* _twice_ to quit the *Create Data Source* wizard. - -^1^ Your specific installation may use a different port number. Check with your {project-name} administrator. - -=== Enable Compression -When compression is enabled in the ODBC driver, the ODBC driver can send and receive large volumes of data quickly and efficiently to and from -the {project-name} Database Connectivity Services (DCS) server over a TCP/IP network. By default, compression is disabled. - -To enable compression in the ODBC driver or to change the compression setting, follow these steps: - -1. Launch the MS ODBC Administrator. -* On Windows 7: *Start>All Programs>{project-name} ODBC _version_>MS ODBC Administrator* -* On Windows 8: Right-click the *{project-name} ODBC _version_* icon on the desktop and select MS ODBC Administrator. -* On Windows 10: Right-click the Windows icon in the menu bar. Select *Settings*. Search for *Set up ODBC data sources (64-bit)*. Click on the found item. - -2. In the *ODBC Data Source Administrator* dialog box, select the *User DSN* tab, select the name of your data source under -*User Data Sources*, and click *Configure*. If you did not create a data source, please refer to -<<win_odbc_client_env, Setting Up the Client Environment>>. -+ -A new dialog box appears, showing the configuration of your data source. -+ -<<< -3. Select the *Network* tab, and then select one of these values for *Compression*: -* `SYSTEM_DEFAULT`, which is the same as no compression -* `no compression` -* `best speed` -* `best compression` -* `balance` -* An integer from 0 to 9, with 0 being no compression and 9 being the -maximum available compression -4. Click *OK* to accept the change. -5. Click *OK* to exit the *ODBC Data Source Administrator* dialog box. - -<<< -[[win_odbc_run_basicsql]] -=== Run Sample Program (`basicsql`) -NOTE: The Basic SQL sample program is not currently bundled with the ODBC Windows driver. To obtain the source code and the build and run -files for this program, please refer to <<odbc_sample_program, ODBC Sample Program>>. - -To build and run the executable file, follow these steps: - -1. Open a Visual Studio x64 Win64 Command Prompt. Make sure to select the x64 version of the command prompt. For example, on Windows 7, select -*Start>All Programs>Microsoft Visual Studio 2010>Visual Studio Tools>Visual Studio x64 Win64 Command Prompt*. -2. At the command prompt, move to the directory where you put the `basicsql.cpp` and build files. -3. Run build at the command prompt. You will see `basicsql.exe` created in the same directory as the source file. -4. Before running the sample program, create a {project-name} data source named `Default_DataSource` on the client workstation using MS ODBC -Administrator. For instructions, please refer to <<win_odbc_client_env,Set Up Client Environment>>. -5. From the command prompt, run the sample program by entering either run or this command: -+ -``` -basicsql DefaultDataSource <username> <password> -``` -+ -If the sample program executes successfully, you should see this output: -+ -*Example* -+ -``` -Using Connect String: DSN=Default_DataSource;UID=user1;PWD=pwd1; -Successfully connected using SQLDriverConnect. -Drop sample table if it exists... -Creating sample table TASKS... -Table TASKS created using SQLExecDirect. -Inserting data using SQLBindParameter, SQLPrepare, SQLExecute -Data inserted. -Fetching data using SQLExecDirect, SQLFetch, SQLGetData -Data selected: 1000 CREATE REPORTS 2014-3-22 -Basic SQL ODBC Test Passed! -``` - -<<< -== Reinstall Windows ODBC Driver -To reinstall the driver, we recommend that you fully remove your ODBC driver and then install the new version. Please refer to -<<win_odbc_uninstall,Uninstalling the {project-name} ODBC Driver for Windows>> and then <<win_odbc_install, Installing the {project-name} ODBC Driver for Windows>>. - -[[win_odbc_uninstall]] -== Uninstalling Windows ODBC Driver -1. Start to remove the ODBC driver: -* On Windows 7: *Start>All Programs>{project-name} ODBC _version_>Remove TRAF ODBC _version_* -* On Windows 8: Right-click the *{project-name} ODBC _version_* icon on the desktop and select *Remove TRAF ODBC _version_*. -* On Windows 10: Right-click the Windows icon in the menu bar. Select *Control Panel*. Click on *Uninstall a program*. Locate *{project-name} ODBC64 _version_* and select it. Click on *Uninstall*. - -2. When the *Windows Installer* dialog box asks you if you want to uninstall this product, click *Yes*. -3. The *{project-name} ODBC _version_* dialog box displays the status and asks you to wait while `Windows configures {project-name} ODBC _version_` (that is, removes -the {project-name} ODBC Driver from your Windows workstation). -+ -After this dialog box disappears, {project-name} ODBC _version_ is no longer on your workstation. - -NOTE: Uninstalling the ODBC driver does not remove pre-existing data source definitions from the Windows registry. +//// +/** + *@@@ 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 @@@ + */ +//// + +[[install-windows-odbc-driver]] += Install Windows ODBC Driver + +WARNING: License issues prevent us from including the ODBC Driver for Windows in this release. Contact the +{project-name} user e-mail list ({project-support}) for help obtaining the driver. + +If you have not done so already, please ensure that you have unpackaged the +<<download-software, unpackaged the {project-name} client software>>. + +The examples in this chapter assumes that you have unpackaged the installation files +to `c:\trafodion\odbc`. + +== Installation Requirements + +[cols="40%s,60%",options="header"] +|=== +| Item | Requirement +| Computer | Windows compatible PC workstation +| Memory | Recommended minimum 32 MB +| Disk Space | Minimum 30 MB additional free space +| Operating System | x64 Edition of Microsoft Windows 7, Windows 8, Windows 10, or Windows Server 2008 +| Network Software | TCP/IP +|=== + +<<< +[[win_odbc_install]] +== Installation Instructions + +NOTE: To install the driver on your PC, you must be logged on with a user ID that has administrator privileges. + +The ODBC client installation file (`c:\trafodion\odbc\TFODBC64-*.exe`) installs or links to +multiple client components: + +[cols="40%s,60%",options="header"] +|=== +| This client component… | Does this… +| Microsoft ODBC Driver Manager | Manages access to ODBC drivers for applications. The driver manager loads and unloads drivers and passes calls for ODBC functions to the +correct driver. +| Trafodion ODBC driver | Implements ODBC function calls to enable an ODBC client application to access the {project-name} database. +| Microsoft ODBC Administrator | Adds, configures, and removes ODBC data sources on client workstations. +|=== + +By default, a new version of the ODBC driver is installed in this directory and its folders unless you specify a different directory +during installation: + +[cols="40%l,60%",options="header"] +|=== +| Default Installation Directory | Client Operating System +| C:\Program Files\Trafodion\TRAF | ODBC _version_ Windows 64-bit +|=== + +<<< +To install the {project-name} ODBC driver, do the following: + +1. Double-click the `TFODBC64-*.exe` distribution file to start the InstallShield wizard. +2. On the *Welcome* page, click *Next*. ++ +image:{images}/winodbc_welcome.jpg[Windows ODBC Installer Welcome Screen] ++ +<<< +3. Read and select the *I accept the agreement* radio button. Click *Next*. ++ +image:{images}/winodbc_license.jpg[Windows ODBC Installer License Screen] ++ +<<< +4. On the *Destination Folder* page, click *Install* to select the default location: `C:\Program Files\Trafodion\TRAF ODBC _version_\` ++ +image:{images}/winodbc_destination.jpg[Windows ODBC Installer Destination Screen] ++ +This location is the installation directory for ODBC header and help files. All other ODBC files are installed in `%SYSTEMROOT%\system32`. ++ +<<< +5. Validate the Destination and click *Install*. ++ +image:{images}/winodbc_ready_to_install.jpg[Windows ODBC Ready to Install Screen] ++ +<<< +6. The Windows ODBC driver is installed. Click *Finish* to exit the installation wizard. ++ +image:{images}/winodbc_install_finished.jpg[Windows ODBC Install Finished Screen] + +<<< +[[win_odbc_setup_data_source]] +== Set Up ODBC Data Source + +1. Start the Microsoft ODBC Administrator: +* On Windows 7: *Start>All Programs>{project-name} ODBC _version_>MS ODBC Administrator* +* On Windows 8: Right-click the *{project-name} ODBC _version_* icon on the desktop and select MS ODBC Administrator. +* On Windows 10: Click the Windows icon in the menu bar. Type *Set up ODBC data sources (64-bit)*. Click on the found item. ++ +image:{images}/winodbc_admin_intro.jpg[Windows ODBC Admin Intro Screen] ++ +<<< +2. In the *ODBC Data Source Administrator* dialog box, click *Add*. ++ +image:{images}/winodbc_admin_add.jpg[Windows ODBC Admin Create Data Source Screen] ++ +<<< +3. Select *TRAF ODBC _version_*, and then click *Finish* to start the *Create a New {project-name} ODBC Data Source* wizard. ++ +image:{images}/winodbc_admin_add_general.jpg[Windows ODBC Admin Create Data Source General Screen] ++ +<<< +4. Enter the data source name (for example, `Default_DataSource_Schema1`) and an optional description, and click *Next*. ++ +image:{images}/winodbc_admin_add_general_edited.jpg[Windows ODBC Admin Create Data Source Edited General Screen] ++ +<<< +5. Enter the `IP address` or `host name` for the database platform. Enter the default port number as *23400*^1^. Leave the defaults as is, and click *Next*. ++ +image:{images}/winodbc_admin_add_network.jpg[Windows ODBC Admin Create Data Source Network Screen] ++ +<<< +6. Enter the schema name. The default schema name is `SEABASE`. Click *Next*. ++ +image:{images}/winodbc_admin_add_schema.jpg[Windows ODBC Admin Create Data Source Schema Screen] ++ +<<< +7. Enter the translate DLL name and its option, if you have one. If not, leave it blank. Leave the localization defaults as is. ++ +image:{images}/winodbc_admin_add_translate_dll.jpg[Windows ODBC Admin Create Data Source Translate DLL Screen] ++ +The Replacement Character replaces any character that is incompatible for translation when retrieving data. It is one character (one or two +bytes long). The Replacement Character is assumed to be in the character set specified in the Client/Server Character Set Interaction. If it is not specified, `?` is used as the default. ++ +Click *Finish*. + +8. The wizard gives you an opportunity to test the connection. Click *Test Connection* and click *OK*. ++ +<<< +9. The server ID and schema are filled in for you. Enter a valid user name and password, and click *OK*. ++ +image:{images}/winodbc_admin_add_test_connection.jpg[Windows ODBC Admin Create Data Source Test Connection Screen] ++ +The wizard attempts to connect to the data source and displays a message stating whether it was successful or not. +10. Click *OK* to save the data source, or click *Cancel* _twice_ to quit the *Create Data Source* wizard. + +^1^ Your specific installation may use a different port number. Check with your {project-name} administrator. + +<<< +=== Enable Compression +When compression is enabled in the ODBC driver, the ODBC driver can send and receive large volumes of data quickly and efficiently to and from +the {project-name} Database Connectivity Services (DCS) server over a TCP/IP network. By default, compression is disabled. + +To enable compression in the ODBC driver or to change the compression setting, follow these steps: + +1. Launch the MS ODBC Administrator. +* On Windows 7: *Start>All Programs>{project-name} ODBC _version_>MS ODBC Administrator* +* On Windows 8: Right-click the *{project-name} ODBC _version_* icon on the desktop and select MS ODBC Administrator. +* On Windows 10: Right-click the Windows icon in the menu bar. Select *Settings*. Search for *Set up ODBC data sources (64-bit)*. Click on the found item. + +2. In the *ODBC Data Source Administrator* dialog box, select the *User DSN* tab, select the name of your data source under +*User Data Sources*, and click *Configure*. If you did not create a data source, please refer to +<<win_odbc_client_env, Setting Up the Client Environment>>. ++ +A new dialog box appears, showing the configuration of your data source. + +3. Select the *Network* tab, and then select one of these values for *Compression*: +* `SYSTEM_DEFAULT`, which is the same as no compression +* `no compression` +* `best speed` +* `best compression` +* `balance` +* An integer from 0 to 9, with 0 being no compression and 9 being the +maximum available compression +4. Click *OK* to accept the change. +5. Click *OK* to exit the *ODBC Data Source Administrator* dialog box. + +<<< +[[win_odbc_run_basicsql]] +== Run Sample Program (`basicsql`) +NOTE: The Basic SQL sample program is not currently bundled with the ODBC Windows driver. To obtain the source code and the build and run +files for this program, please refer to <<odbc_sample_program, ODBC Sample Program>>. + +To build and run the executable file, follow these steps: + +1. Open a Visual Studio x64 Win64 Command Prompt. Make sure to select the x64 version of the command prompt. For example, on Windows 7, select +*Start>All Programs>Microsoft Visual Studio 2010>Visual Studio Tools>Visual Studio x64 Win64 Command Prompt*. +2. At the command prompt, move to the directory where you put the `basicsql.cpp` and build files. +3. Run build at the command prompt. You will see `basicsql.exe` created in the same directory as the source file. +4. Before running the sample program, create a {project-name} data source named `Default_DataSource` on the client workstation using MS ODBC +Administrator. For instructions, please refer to <<win_odbc_client_env,Set Up Client Environment>>. +5. From the command prompt, run the sample program by entering either run or this command: ++ +``` +basicsql DefaultDataSource <username> <password> +``` ++ +If the sample program executes successfully, you should see this output: ++ +*Example* ++ +``` +Using Connect String: DSN=Default_DataSource;UID=user1;PWD=pwd1; +Successfully connected using SQLDriverConnect. +Drop sample table if it exists... +Creating sample table TASKS... +Table TASKS created using SQLExecDirect. +Inserting data using SQLBindParameter, SQLPrepare, SQLExecute +Data inserted. +Fetching data using SQLExecDirect, SQLFetch, SQLGetData +Data selected: 1000 CREATE REPORTS 2014-3-22 +Basic SQL ODBC Test Passed! +``` + +<<< +== Reinstall Windows ODBC Driver +To reinstall the driver, we recommend that you fully remove your ODBC driver and then install the new version. Please refer to +<<win_odbc_uninstall,Uninstalling the {project-name} ODBC Driver for Windows>> and then <<win_odbc_install, Installing the {project-name} ODBC Driver for Windows>>. + +[[win_odbc_uninstall]] +== Uninstalling Windows ODBC Driver +1. Start to remove the ODBC driver: +* On Windows 7: *Start>All Programs>{project-name} ODBC _version_>Remove TRAF ODBC _version_* +* On Windows 8: Right-click the *{project-name} ODBC _version_* icon on the desktop and select *Remove TRAF ODBC _version_*. +* On Windows 10: Right-click the Windows icon in the menu bar. Select *Control Panel*. Click on *Uninstall a program*. Locate *{project-name} ODBC64 _version_* and select it. Click on *Uninstall*. + +2. When the *Windows Installer* dialog box asks you if you want to uninstall this product, click *Yes*. +3. The *{project-name} ODBC _version_* dialog box displays the status and asks you to wait while `Windows configures {project-name} ODBC _version_` (that is, removes +the {project-name} ODBC Driver from your Windows workstation). ++ +After this dialog box disappears, {project-name} ODBC _version_ is no longer on your workstation. + +NOTE: Uninstalling the ODBC driver does not remove pre-existing data source definitions from the Windows registry.
