Aster Database Client Guide 0503

Aster Database Client Guide
Release Number 5.0.3
December 2012
The product or products described in this book are licensed products of Teradata Corporation or its affiliates.
Teradata, Active Enterprise Intelligence, Applications-Within, Aprimo, Aprimo Marketing Studio, Aster, BYNET, Claraview, DecisionCast, Gridscale,
MyCommerce, Raising Intelligence, Smarter. Faster. Wins., SQL-MapReduce, Teradata Decision Experts, "Teradata Labs" logo, "Teradata Raising
Intelligence" logo, Teradata ServiceConnect, Teradata Source Experts, "Teradata The Best Decision Possible" logo, The Best Decision Possible,
WebAnalyst, and Xkoto are trademarks or registered trademarks of Teradata Corporation or its affiliates in the United States and other countries.
Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc.
AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc.
Apache, Apache Hadoop, Hadoop, and the yellow elephant logo are either registered trademarks or trademarks of the Apache Software Foundation
in the United States and/or other countries.
Axeda is a registered trademark of Axeda Corporation. Axeda Agents, Axeda Applications, Axeda Policy Manager, Axeda Enterprise, Axeda Access,
Axeda Software Management, Axeda Service, Axeda ServiceLink, and Firewall-Friendly are trademarks and Maximum Results and Maximum
Support are servicemarks of Axeda Corporation.
Data Domain, EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation.
GoldenGate is a trademark of Oracle.
Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company.
Hortonworks, the Hortonworks logo and other Hortonworks trademarks are trademarks of Hortonworks Inc. in the United States and other
countries.
Intel, Pentium, and XEON are registered trademarks of Intel Corporation.
IBM, CICS, RACF, Tivoli, and z/OS are registered trademarks of International Business Machines Corporation.
Linux is a registered trademark of Linus Torvalds.
LSI is a registered trademark of LSI Corporation.
Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United States
and other countries.
NetVault is a trademark or registered trademark of Quest Software, Inc. in the United States and/or other countries.
Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries.
Oracle, Java, and Solaris are registered trademarks of Oracle and/or its affiliates.
QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation.
Red Hat is a trademark of Red Hat, Inc., registered in the U.S. and other countries. Used under license.
SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc.
SPARC is a registered trademark of SPARC International, Inc.
Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States and
other countries.
Unicode is a registered trademark of Unicode, Inc. in the United States and other countries.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other product and company names mentioned herein may be the trademarks of their respective owners.
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN "AS-IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION
MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
The information contained in this document may contain references or cross-references to features, functions, products, or services that are not
announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions,
products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or
services available in your country.
Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated
without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time
without notice.
To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document.
Please email: teradata-books@lists.teradata.com.
Any comments or materials (collectively referred to as "Feedback") sent to Teradata Corporation will be deemed non-confidential. Teradata
Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform,
create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata
Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including
developing, manufacturing, or marketing products or services incorporating Feedback.
Copyright 2000-2012 by Teradata Corporation. All Rights Reserved.

Aster Database Client Guide 3
Table of Contents
General Tips for Connecting Clients to Aster Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

ODBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Installing ODBC on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Optional ODBC Setting for bytea-Stored Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Installing ODBC on Linux, Solaris, and MacOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Setting up ODBC for Perl Connectivity on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Setting up ODBC for PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
ODBC Usage Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Aster Database JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Aster Database JDBC Driver 5.0.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Differences Between the 5.0.3 JDBC Driver and the Legacy JDBC Driver . . . . . . . . . . . . 19
Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Installing the Aster Database JDBC Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Using the Aster Database JDBC Driver in a Java Application . . . . . . . . . . . . . . . . . . . . . . 20
Parameters for Connecting to Aster Database through JDBC . . . . . . . . . . . . . . . . . . . . . . 21
Behavior and Performance Settings for JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Using Client-Side Cursors in JDBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Test JDBC Connect Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Tailoring the Behavior of Aster Database SQL to Your Needs . . . . . . . . . . . . . . . . . . . . . . . . . 28
SQL Behavior Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Setting the SQL Behavior Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Syntax for ODBC Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
SSL Security for Aster Database-Client Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
SSL-Related Files and Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
SSL Settings Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Common SSL Configuration Scenarios in Aster Database . . . . . . . . . . . . . . . . . . . . . . . . . 32
Encrypting Data Traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Adding AD-Based SSO Authentication to SSL-Secured Aster Database . . . . . . . . . . . . . . 34
How to Set Configuration Parameters on the Queen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
How to Set Configuration Parameters on the Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Creating Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Processing SQL Statements in JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Processing a Simple Query in JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
JDBC Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Connecting Reporting Tools to Aster Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Connecting Aqua Data Studio to Aster Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Connecting MicroStrategy to Aster Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5 Aster Database Client Guide

Connect Using Database Drivers
Aster Database provides Open Database Connectivity (ODBC) and Java Database
Connectivity (JDBC) drivers for connecting business intelligence (BI) tools. This section
explains how to connect BI tools using the Aster Database drivers.
General tips:
General Tips for Connecting Clients to Aster Database (page 6).
Setting up database drivers:

ODBC Driver (page 7).
Aster Database JDBC Driver (page 19).
ADO.NET driver (a.k.a. Aster Database DNProvider driver) for SSIS, SSRS, and .NET: See
Tools for .NET Environments (page 295).
OleDB Driver for SSAS: See Tools for .NET Environments (page 295).
Using database drivers:

Processing SQL Statements in JDBC (page 40)
JDBC Issues (page 42)
Security for database drivers:

SSL Security for Aster Database-Client Communications (page 30)
Connecting BI and query tools:

Connecting Reporting Tools to Aster Database (page 42)
General Tips for Connecting Clients to Aster

Database
Recommended Character Set Is UTF-8
For all tools that you use to connect to databases in Aster, you will typically want to set the
default character set to UTF-8. This is particularly important if you plan to use special
characters (for example, German letters and ) in a char, varchar, or text column, and it is
particularly important if you are connecting from a Windows-based machine.

ODBC Driver
For example, if you will use an SSH client (e.g., putty) to run ACT or ncluster_loader, make
sure you set the SSH clients default character set to UTF-8.
When Querying System Tables with ODBC, Set AUTOCOMMIT to

'OFF'
Cursors cannot be declared and used with Aster Database system tables. The default mode of
autocommit-on with the ODBC driver declares cursors. Therefore, the ODBC driver should
always query system tables by turning AUTOCOMMIT to 'off '.
ODBC Driver
Teradata Aster provides a standard ODBC driver for Aster Database that is compatible with
Microsoft Windows and Linux.
The Aster Database ODBC driver may change in any Aster Database release. For this reason, with each new edition of
Aster Database, you should reinstall the driver and recompile your applications that include the driver.
See the section below that applies to your platform:

Setting up ODBC for PHP (page 17) (page 7)
Installing ODBC on Linux, Solaris, and MacOS (page 11)
Setting up ODBC for Perl Connectivity on Linux (page 16)
Setting up ODBC for PHP (page 17)
Installing ODBC on Windows

Follow these steps to install the Aster Database ODBC driver on Windows:
Procedure
1 On the machine where you will install the driver, make sure you have installed the
Microsoft Visual C++ 2008 Redistributable Package (x86). If its not installed, download it
from Microsoft now (choose the version that fits your architecture: 32-bit or 64-bit), and
install it. (Note that Microsoft also offers newer versions of the package, such as the
Microsoft Visual C++ 2010 Redistributable Package (x86). Teradata Aster has not tested
compatibility with these later versions!)
2 Get the Aster Database ODBC driver package (nClusterODBCInstaller_i386.msi for
32-bit Windows or nClusterODBCInstaller_x64.msi for 64-bit Windows) in one of
these ways:
a Copy the package from your queen node. On the queen, you can find the installers in /
home/beehive/clients_all/win32 or in /home/beehive/clients_all/win64.
b Download the package from ftp.asterdata.com.

ODBC Driver
3 If you are upgrading, use the Windows Add/Remove Programs tool to uninstall the old
version.
4 Copy the ODBC driver to the client machine and run the executable (for 32-bit, use
nClusterODBCInstaller_i386.msi or, for 64-bit, use
nClusterODBCInstaller_x64.msi). A setup wizard will walk you through the
installation of Aster Database ODBC as one of the available data sources on your
computer.
5 From the Windows Control Panel, double-click Administrative Tools to open the
Administrative Tools window.
6 Double-click the Data Sources (ODBC) option to open the ODBC Data Source
Administrator dialog box.
7 Click the System DSN tab, and click Add to open the Create New Data Source dialog box.
8 Select the Aster Data ODBC Driver for nCluster data source from the list.
9 Click Finish. The Aster Database Login window appears.

ODBC Driver
10 In the Aster Database Login window, enter the following information:

Data Source: Use this field to give this database connection an easy-to-recognize name.
Server: the hostname or IP address of your Aster Database queen.
Port: The port on which your Aster Database queen listens for client connections. The
default is 2406.
Database: the name of the database in Aster Database you want to connect to. Default
system database is beehive.
Username: Database user name.
Password: Database users password.
Fetch Count: See Throttle Query Results in ACT and Aster Database on page 120.
SSL Settings: See SSL Security for Aster Database-Client Communications on
page 30.
SSO Settings: See Adding AD-Based SSO Authentication to SSL-Secured Aster
Database on page 34.
enable_quoted_identifiers: See Quoted-Identifier Handling on page 28.
enable_backslash_escapes: See Escape Character Handling on page 28.
Map NUMERIC/DECIMAL to DOUBLE: Teradata Aster recommends that you turn this
feature on.

ODBC Driver
Bytea As Varchar: The current login window does not provide a check box for specifying
that values in a column of datatype bytea should be retrieved in a character
representation (as opposed to the default binary representation) but you can set this
later in the Windows registry. See Optional ODBC Setting for bytea-Stored Data on
page 10.
11 Click OK to save the data source information.
12 Click Test Connection to test the connectivity to the database. If the connection is successful,
the Aster Database Login window closes automatically.
13 If this window does not close automatically, click OK.
Your ODBC setup is complete. Now, in your applications that will query Aster Database, you
may connect to Aster Database as an ODBC data source.
Optional ODBC Setting for bytea-Stored Data

If you retrieve bytea-stored data through the ODBC driver, you can specify whether values in a
column of datatype bytea will be retrieved in a character representation, or in the default
binary representation.
To set this up you must set the ByteaAsVarchar setting. Setting ByteaAsVarchar=1 instructs
the ODBC driver to retrieve values in character representation; leaving it unset preserves the
binary output representation.
To set this up on Linux, Solaris, or MacOS, see the discussion of the odbc.ini file in
Configure the ODBC Driver on Linux/Solaris/MacOS on page 13.
To set this up on Windows, see below.
For a 64-bit ODBC driver running on 64-bit Windows, and for 32-
bit driver on 32-bit Windows
Set the flag by adding it to the Windows registry entry for the DSN. Using a registry editor,
add this line to the registry, taking care to first replace <DSN-NAME> with your Data Source
name:
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\<DSN-NAME>]
"ByteaAsVarchar"="1"
For a 32-bit ODBC driver running on 32-bit Windows

name:
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\<DSN-NAME>]

ODBC Driver
For a 32-bit ODBC driver running on 64-bit Windows

name:
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBC.INI\<DSN-name>]
Installing ODBC on Linux, Solaris, and MacOS

To install the Aster Database ODBC driver on Linux, Solaris, or MacOS, follow the
instructions below.
Prerequisites
1 The Aster Database ODBC driver requires libgcc 3.4.6 or higher.
2 On UNIX/Linux systems, the Aster Database ODBC driver requires a driver manager.
Teradata Aster recommends that you use the unixODBC driver manager, version 2.2.12,
which is compatible with the Aster Database standard ODBC driver for UNIX,
libAsterDriver_unixODBC.so. Teradata Aster also supports the iODBC driver
manager, version 3.52.3, but if you use the iODBC manager, you must use a different
version of the Aster Database ODBC driver, called libAsterDriver.so. No other
combination of drivers and driver managers is supported!
Install the Driver Manager on Linux/Solaris/MacOS

Here, we explain how to install both the driver manager and the Aster Database ODBC driver.
If you already have the manager, proceed to Installing ODBC on Linux, Solaris, and MacOS
on page 11.
If your system does not have the unixODBC driver manager installed, install it now as shown
here:
1 Download the unixODBC driver manager v 2.2.12, from http://www.unixodbc.org/
unixODBC-2.2.12.tar.gz
2 Install unixODBC by running the following commands:

# CFLAGS="-DSIZEOF_LONG=8" ./configure --prefix=/usr \
--sysconfdir=/etc/unixodbc \
--enable-fdb \
--disable-gui &&
make
Wait while it builds and installs.

3 Working as root user, run this:
# make install &&
find doc -name "Makefile*" -exec rm {} \; &&

chmod 644 doc/{lst,ProgrammerManual/Tutorial}/* &&
install -v -m755 -d /usr/share/doc/unixODBC-2.2.12 &&

cp -v -R doc/* /usr/share/doc/unixODBC-2.2.12

ODBC Driver
4 Check the installation by typing the following command. This prints version information
and lists the names and locations of the configuration files you will need to install or set
up.
# odbcinst -j
If your unixODBC installation is not working properly, check the instructions at http://
www.unixodbc.org/ for help.
Next Step: Proceed to the next section, Configure the ODBC Driver on Linux/Solaris/
MacOS.
Install the Aster Database ODBC Driver on Linux/Solaris/MacOS

Once an appropriate driver manager is installed, you can install the Aster Database ODBC
driver as shown below.
Warning! For MacOS, the Aster Database ODBC Driver supports only MacOS version 10.5 or earlier.
1 Download the Aster Database ODBC driver bundle for your platform. You can get this
from Teradata Asters website or from your queen node. Do one of the following:
Go to ftp.asterdata.com. Find the appropriate bundle for your release and operating
system (for example, clients-odbc-linux64.tar.gz for a 64-bit Linux machine)
and download it to your machine.
Connect to your queen node and copy the appropriate driver bundle from /home/
beehive/clients_all. The bundles are in the OS-specific directories, linux32/,
linux64/, mac/, solaris64 /, solaris-sparc/, solaris-x86/, win32/, and win64/.
2 Extract the bundle into the directory where you want to install drivers. In this example,
well assume you will install the driver in /usr/local/lib. Once extracted, you will see
the directory, stage/, that includes the driver.
3 Change to the Aster Database driver directory:
# cd stage/clients-odbc-linux64
4 Edit your LD_LIBRARY_PATH or DYLD_LIBRARY_PATH environment variable, adding the
Aster Database driver directory path to it. This folder has the path <install
location>/stage/clients-odbc-linux64/Libs. Edit the appropriate environment
settings file to do this (for example, edit the ~/.bashrc file if you want to set it for the
current user on a typical Linux environment). For this example, we will set it for the
current session only. To follow this example, type the export command shown below.
(Note that for MacOS only, the environment variable is called DYLD_LIBRARY_PATH, not
LD_LIBRARY_PATH.)
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/stage/clients-
odbc-linux64/Libs

ODBC Driver
5 Add or edit the ODBCSYSINI environment variable, setting it to the directory where your
ODBC connection settings files (odbc.ini and odbcinst.ini) will reside. To follow this
example, lets assume we are working as user mjones and will save the configuration files
to our home directory /home/mjones.
export ODBCSYSINI=/home/mjones
6 Check that the Aster Database ODBC driver library can find all its dependencies.
Assuming we have installed in /usr/local/lib, we would type (on Linux or Solaris):
# cd /usr/local/lib
# ldd stage/clients-odbc-linux64/ODBCDriver/ \
libAsterDriver_unixODBC.so
On MacOS, we would type:
# cd /usr/local/lib
# otool -L stage/clients-odbc-linux64/ODBCDriver/ \
libAsterDriver_unixODBC.dylib
If no not found messages appear, then all the required libraries have been linked. We
require libgcc 3.4.6 or higher.
Configure the ODBC Driver on Linux/Solaris/MacOS

Once the Aster Database ODBC driver is installed, you must configure it as shown below.
1 Get the templates for the ODBC connection settings files. Copy these files from the Aster
Database drivers Setup directory to the users home directory. The files you need are
aster.ini, odbc.ini and odbcinst.ini:
# cd /usr/local/lib/stage/clients-odbc-linux64/Setup
# cp odbc.ini ~
# cp odbcinst.ini ~
# cp aster.ini ~/.aster.ini
Note that we have also renamed the aster.ini file, adding a dot at the beginning of the
file name. You must do this.
2 Edit the .aster.ini file, setting the ErrorMessagesPath to point to the ErrorMessages
subdirectory in the Aster Database driver directory. For this example, we edit the last line
in the file to read:
ErrorMessagesPath=/usr/local/lib/stage/clients-odbc-linux64/ErrorMessages
Tip! At this point, you can run odbcinst -j to find out where the ODBC driver expects to find its configuration files.
3 ErrorMessagesPath=/usr/local/lib/stage/clients-odbc-linux64/ErrorMessages
4 In a text editor, edit the odbc.ini file, making the following changes:
a Set SERVER to the hostname or IP address of your Aster Database queen.
b Set PORT to 2406, the standard port on which your Aster Database queen listens for
client connections.
c Set DATABASE to the name of the database in Aster Database you want to connect to.

ODBC Driver
d Optionally, you may set UID and PWD to your Aster Database SQL username and
password, respectively.
e Finally, Teradata Aster recommends that you add the setting,
NumericAndDecimalAsDouble=1.
f If you retrieve bytea-stored data through the ODBC driver, you can specify whether
values in a column of datatype bytea will be retrieved in a character representation, or
in the default binary representation. To have the ODBC driver to retrieve values in
character representation, add the setting, ByteaAsVarchar=1 to your odbc.ini; if
you leave it unset, the driver preserves the binary output representation of bytea data.
g Optionally, you can set a number of other database connection behavior settings.
These include enable_quoted_identifiers (see Quoted-Identifier Handling on
page 28), enable_backslash_escapes: See Escape Character Handling on
page 28.
For this example, we set the contents of odbc.ini to read:
[ODBC Data Sources]

Aster Database ODBC for nCluster DSN=AsterDriver
[Aster Database ODBC for nCluster DSN]

Driver=AsterDriver
SERVER=10.50.52.100
PORT=2406
DATABASE=beehive
NumericAndDecimalAsDouble=1
# UID=<USERNAME>
# PWD=<PASSWORD>
Tip! You can have multiple data sources. The name Aster Database ODBC for nCluster DSN in the odbc.ini file
is just a default name that Teradata Aster has given to the sample data source. You can rename this source and add
more, as shown in this example:
[ODBC Data Sources]

my_1st_source=AsterDriver
my_2nd_source=AsterDriver
[my_1st_source]
Driver=AsterDriver
SERVER=10.50.52.100
...
[my_2nd_source]
Driver=AsterDriver
SERVER=10.42.43.100
...

ODBC Driver
5 In a text editor, edit the odbcinst.ini file, setting the Driver parameter to the Aster
Database driver directory path. For this example, we set the contents of odbcinst.ini to
read:
[AsterDriver]
Driver=/usr/local/lib/stage/clients-odbc-linux64/ODBCDriver/
IconvEncoding=UCS-4LE
On MacOS, it will look like:
[AsterDriver]
Driver=/usr/local/lib/stage/clients-odbc-linux64/ODBCDriver/
libAsterDriver_unixODBC.dylib
The installation and configuration are complete.
Test the installation

Once the driver is installed and configured, you should test it:
The unixODBC driver manager comes with a tool called isql that you can use to test the
driver. You can test your connection now by connecting to Aster Database using the isql tool.
1 Type the command as shown below. Here, we put the data source name in single quotes
because it contains spaces. The beehive and beehive are the default username and
password in a new Aster Database installation:
# isql -v 'Aster Database ODBC for nCluster DSN' beehive beehive
2 A Connected! message indicates that the driver is working correctly:
+---------------------------------------+
| Connected! |
| |
| sql-statement |
| help [tablename] |
| quit |
| |
+---------------------------------------+
SQL>
3 Set-up is complete.
Troubleshooting
If after installation you cannot connect:
1 Find the library libodbcinst.so and note its path.
2 Set the LD_LIBRARY_PATH environment variable so that it includes the directory that
contains libodbcinst.so. For example, if the library is in /usr/lib64, then you will
type:
export LD_LIBRARY_PATH=/usr/lib64:$LD_LIBRARY_PATH

ODBC Driver
Setting up ODBC for Perl Connectivity on Linux

To install the Aster Database ODBC driver and configure your environment to allow Perl
scripts to connect to the database through the driver, follow these steps. These instructions
assume you have installed Perl on your workstation, and that the Aster Database queen is
reachable on the network. Follow these steps to provide an Aster Database connection your
Perl scripts can use:
1 Set up your /etc/resolv.conf and /etc/nsswitch.conf for accessing the Aster
Database queen.
2 Make sure that an ODBC driver manager is installed and configured. Follow the
instructions in Install the Driver Manager on Linux/Solaris/MacOS on page 11.
3 Install and configure Aster Database ODBC. Follow the instructions in Configure the
ODBC Driver on Linux/Solaris/MacOS on page 13.
4 The server connection information is set in the odbc.ini file, as explained in the ODBC
installation sections of this document, Installing ODBC on Linux, Solaris, and MacOS
on page 11. On Windows, the server connection information is set using the ODBC Data
Source Administrator tool as explained in Setting up ODBC for PHP (page 17) on
page 7.
5 In /root type
$ perl -eshell -MCPAN
6 Get the latest packages and install them by entering:

$ install Bundle::CPAN
$ install DBI
7 Rebuild and install DBD::ODBC.
$ export LD_LIBRARY_PATH=/home/beehive/toolchain/x86_64-unknown-
linux-gnu/unixODBC-2.2.12/lib
$ export PATH=$PATH:/home/beehive/toolchain/x86_64-unknown-linux-
gnu/unixODBC-2.2.12/bin
$ which odbc_config
/home/beehive/toolchain/x86_64-unknown-linux-gnu/unixODBC-2.2.12/
bin/odbc_config
$ odbc_config --cflags -DHAVE_UNISTD_H -DHAVE_PWD_H
-DHAVE_SYS_TYPES_H -DHAVE_LONG_LONG -DSIZEOF_LONG=8
$ perl -eshell -MCPAN
cpan[1]> force install DBD::ODBC
8 Run odbcinst -j to see where the .ini files are being picked up:
$ odbcinst -j
9 Run the following Perl script to check your installation.

If everything is set correctly, it will run without an error. If you encounter problems, check
the data source name (DSN) in the connect statement. In the example below, the
username and password of the database are beehive and beehive:

ODBC Driver
#!/usr/bin/perl
use DBI;
use DBD::ODBC;
# Connect to ODBC DSN and turn off AutoCommit

my $dbh = DBI->connect('dbi:ODBC:nc',"beehive","beehive",
{AutoCommit => 0});
$dbh->do("BEGIN");
$dbh->do("set random_page_cost to '4'");
$dbh->do("set enable_seqscan to 'off'");
$dbh->disconnect;
Setting up ODBC for PHP

To set up PHP to work with ODBC, first follow all of the instructions to set up ODBC on
Linux: Installing ODBC on Linux, Solaris, and MacOS on page 11.
As described in the instructions, you should use unixODBC 2.2.12 and build it with the
CFLAG, SIZEOF_LONG=8. The same will apply to building PHP when compiled to be used
with unixODBC. Here are the supported versions:
PHP 5.2.16
Apache 2.2.3
PHP
To set up PHP:
1 Make sure Apache is installed and make note of the directory. For this example, we will
assume Apache is installed at /usr/local/apache
2 Ensure that unixODBC has been installed as described above.
3 Download the source for PHP 5.2.16 and extract it to the desired directory. The following
setup instructions should be used for PHP:
$ CFLAGS="-DSIZEOF_LONG=8" ./configure --with-apxs2=/usr/local/
apache/bin/apxs --with-zlib --with-unixODBC --with-pdo-odbc=unixODBC
$ make && make install
$ cp -p .libs/libphp5.so /usr/local/apache/modules
Apache and PHP

Apart from the typical PHP-Apache setup, there are two things to keep in mind:
1 Ensure that the Linux system is set up to find the libraries that the ODBC driver requires.
a Add the <INSTALL-DIR>/Libs and <INSTALL-DIR>/ODBCDriver paths to the /etc/
ld.so.conf file, where <INSTALL-DIR> is the location for the ODBC installation.
b The following commands should be executed to refresh the ld cache and restart the
Apache web server:
$/sbin/ldconfig
$/etc/init.d/apachectl restart

ODBC Driver
2 To make sure that the ODBCSYSINI environment variable is available when PHP calls are
made, use the following line in your PHP code:
#given ODBCSYSINI is to be set to /etc then:
putenv("ODBCSYSINI=/etc")
Tip! You should not set up your own PHP or use /etc/init.d/apachectl on the queen for your own web
pages.
ODBC Usage Notes
Avoid using bind_param with SQL_DECIMAL

When using the bind_param method call with decimal fields, you should not explicitly specify
SQL_DECIMAL as the parameter bind type. If you do this, and the parameter value has a
fractional digital part, the factional part changes to 0 after applying bind_param. The
DBD::ODBC bind_param implementation makes this conversion when specifying
SQL_DECIMAL/SQL_NUMERIC as the parameter bind type. Note that bind_param works
fine when SQL_DECIMAL is not explicitly specified, so you should avoid this when passing
decimal fields.
Bind columns without specifying a SQL datatype

Use the Perl API without specifying a SQL datatype the Aster datatypes, as in the example:
$rc = $sth->bind_col($column_number, \$var_to_bind);
Avoid specifying the SQL datatype to bind to the column, as in:
$rc = $sth->bind_col($column_number, \$var_to_bind, $bind_type);
This will work fine when binding boolean and character columns with DBI::SQL_CHAR, but
for the other datatypes, this will cause two issues:
1 If you specify a numeric SQL type in bind_col, corrupt data may be returned. Numeric
types include SQL_INTEGER, SQL_SMALLINT, SQL_DOUBLE, SQL_REAL,
SQL_NUMERIC/SQL_DECIMAL, SQL_BIT, SQL_TIME, SQL_TIMESTAMP,
SQL_DATE, and SQL_DATETIME.
2 If you specify a SQL_VARCHAR type in bind_col, an error may be returned. The error
looks like:
On Unix ODBC: DBD::ODBC::st fetch failed: [unixODBC][Driver Manager]Invalid
application buffer type (SQL-HY003)
On Windows ODBC: DBD::ODBC::st fetch failed: [Microsoft][ODBC Driver
Manager] Program type out of range (SQL-HY003)
This issue has been observed with the following software versions:
Perl 5.8.9
DBD-ODBC 1.3.1
DBI-1.616

Aster Database JDBC Driver

JDBC is an API for the Java programming language that provides methods for querying and
updating data in a relational database. The Aster Database JDBC driver enables your Java
applications and reporting tools to retrieve data directly from Aster Databases.
The Aster Database JDBC driver is a Type 4 JDBC driver that implements the JDBC 3
specification.
Aster Database JDBC Driver 5.0.3 (page 19)
Differences Between the 5.0.3 JDBC Driver and the Legacy JDBC Driver (page 19)
Before You Start (page 20)
Installing the Aster Database JDBC Driver (page 20)
Using the Aster Database JDBC Driver in a Java Application (page 20)
Parameters for Connecting to Aster Database through JDBC (page 21)
Behavior and Performance Settings for JDBC (page 22)
Using Client-Side Cursors in JDBC (page 23)
Test JDBC Connect Program (page 25)
Processing a Simple Query in JDBC (page 41)
Aster Database JDBC Driver 5.0.3

This version of the JDBC driver adds these capabilities to those that were already supported in
the legacy JDBC driver:
Ability to handle larger data sets than the legacy JDBC driver; doesnt try to load whole
result set onto the client in all cases
Support for multibyte characters in data and user metadata UTF-8 encoding
Support for Single Sign-On (SSO) authentication
Support for Secure Socket Layers (SSL) encrypted communications
Support customized connection parameters
Support configuring statement FetchSize to limit the data being returned
Support server side cursors
Support specifying maximum number of rows
Differences Between the 5.0.3 JDBC Driver and the Legacy JDBC Driver
These are important differences between the 5.0.3 JDBC driver and the legacy JDBC driver:
JDBC only supports scrollable forward cursors. Only the con.createStatement
(ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY) and
connection.createStatement() functions are supported. The Other parameter values like
ResultSet.TYPE_SCROLL_INSENSITIVE and ResultSet.CONCUR_UPDATABLE are not
supported.
The executeBatch() function throws a SQL exception (java.sql.SQLException).

The result set cannot be accessed after an explicit commit.

After running PreparedStatement.executenatch(), you must set all bind values or else the
driver throws an error.
The java.sql.PreparedStatement.setObject() function does not throw exceptions for invalid
java.sql.Types.TINYINT values. Instead, the function wraps the values around. This
behavior complies with the Java standard.
ResultSetMetaData cannot be accessed after a ResultSet reset.
The driver cannot establish a connection to the database when there are white space
characters to the left of the connection string.
If the JDBC connection is lost when using Aqua Data Studio, a new connection is not
initiated automatically. The next command issued will return an error. The user will need
to re-initiate a connection to the database.
The DatabaseMetaData.getBestRowIdentifier() function is not supported.
The ResultSet.getArray() function is not supported.
You can call com.asterdata.ncluster.Driver.ASTER_BUILD_VERSION() to get JDBC
version information. For detailed version information, check the MANIFEST.MF file.
Before You Start

The SSO support in the JDBC driver is based on Quest Authentication service. You must
acquire the SSO license from Quest in order to take advantage of SSO support in this client.
This support is for connecting to Aster Database only, and not for connecting through the
Teradata Connector or SQL-H.
Installing the Aster Database JDBC Driver

Follow these steps to install the Aster Database JDBC driver:
1 Obtain the ZIP package that contains the Aster Database JDBC driver (for example,
AsterJDBC_indep_indep.05.00.03.00.zip):
Obtain the file from the Aster ftp server or
Copy the package from your queen node. On the queen, you can find the installers in /
home/beehive/clients_all/<platform>.
2 Unzip the ZIP package.
The resulting folder contains multiple JAR file.
3 Copy the JAR files to a location in the classpath of the application that uses the driver.
Using the Aster Database JDBC Driver in a Java Application

Follow these steps to integrate the Aster Database JDBC driver into your Java application:
1 Set the CLASSPATH environment variable to include the paths of the JAR files extracted
from the Aster Database JDBC driver package.

Use the Java -classpath flag at the command line to add the paths to the CLASSPATH
environment variable. For example, if you place the JAR files in /usr/jars, then add the
path like this:
java -classpath /usr/my_program /usr/jars/
or
Add the paths to the driver to the CLASSPATH environment variable. For example:
export CLASSPATH=/usr/jars/:$CLASSPATH
2 In your application:
a Import the java.sql package like this:
import java.sql.*;
b Load the driver using the Class.forName() method:
Class.forName("com.asterdata.ncluster.Driver");
c Define the username, password, and url (including the host, port, and database)
parameters, which are needed to connect to the database. For example:
String username = "user";
String password = "password";
String url = "jdbc:ncluster://myhost:2406/database";
For more information about the URL format, see Required Parameters on page 21.
d Get a Connection instance from JDBC using the DriverManager.getConnection()
method:
try
{
Connection conn =
DriverManager.getConnection(url, username, password);
}
catch (SQLException ex)
{
// could not connect
}
NOTE: The getConnection method throws a No driver available SQLException
exception if CLASSPATH does not contain the path for the JDBC driver, or if the
parameters are incorrect.
Parameters for Connecting to Aster Database through JDBC
Required Parameters
To establish a connection to an Aster Database using the Aster Database JDBC driver, you
must provide the driver with the URL to use to connect to the database. The URL has this
format:
jdbc:ncluster://<Host:Port>/<Database>

The URL needs three parameters to connect to an Aster Database:

Table 1 - 1: Parameters in URL to connect to an Aster Database
Parameter Required? Description
Host Optional The name of the server where the database resides.
To specify an IPv6 address, enclose the this parameter in square
brackets. For example:
jdbc:ncluster://[::1]:2406/nCluster
Default is localhost.
Port Optional The port number that the database server is listening on.
Default is 2406.
Database Required The database name.
In addition, to the URL, you must also provide the username and password needed to access
the Aster Database, which you can get from your Aster Database administrator.
Optional Parameters
You can set the Autocommit and fetch_count settings for the connection in the URL by adding
the autocommit and fetch_count parameters. See Frequently Used JDBC Settings on
page 22. If your application will query large tables, you should set autocommit to false, and
you should declare a fetch_count for the connection. By doing this, you enable the
connection to use distributed cursors for improved performance.
Behavior and Performance Settings for JDBC

When using the Aster Database JDBC driver, you make most behavior and performance
settings in your SQL code using the SET command, as explained in SET on page 778.
You can also use a number of standard JDBC driver methods for setting behavior and
performance options, such as setAutoCommit() and setPrepareThreshold().
The scope of these variables are limited to the scope of the transaction. After the commit()
call, the transaction variables revert to their original values. In order to limit the transaction
variables to a particular query, the variables need to be saved prior to being set and once the
query is executed the variables must be set back to their original values.
Frequently Used JDBC Settings

autocommit: Boolean value that sets the autocommit behavior for the connection, true to
turn on autocommit (each statement, by default concluded with a semicolon, is run
immediately in the database) or false for off (you must COMMIT your transaction to run
it). You can set this in the connection URL with the autocommit parameter (for example,
jdbc:ncluster://10.80.50.100:2406/beehive?autocommit=false) or in the Java
code for your connection with Connection.setAutoCommit(). The default is true.

Unsupported JDBC Settings

Most JDBC option-setting methods in the Aster Database driver exhibit the standard JDBC
behavior, but there are exceptions. Please note:
setReadOnly(): Not supported; Aster Database does not allow changing connection type
to read-only.
setTransactionIsolation(): Not supported; Aster Database does not allow changing
transaction isolation levels.
Example Code Snippet That Sets Performance Tuning Variables

Assuming a Connection conn and a Query query, we can set some performance tuning
variables for a particular transaction like this:
// remember the current autocommit state
boolean autoCommit = conn.getAutoCommit();
// turn off auto commits

conn.setAutoCommit(false);
// create a statement with transaction variables set

// which will be used for this query
Statement stmt = conn.createStatement();
stmt.executeUpdate("SET enable_hashjoin = 'false'");
stmt.executeUpdate("SET enable_mergejoin = 'false'");
stmt.executeUpdate("SET enable_nestloop='true'");
stmt.executeUpdate("SET random_page_cost = '4.0'");
ResultSet resultSet = statement.executeQuery(query);

// commit the transaction (assumes the query has
// already been executed externally)
conn.commit();
// set the autocommit state back
conn.setAutoCommit(autoCommit);
// process the result set

while (resultSet.next()) {
// do something
}
stmt.close();
resultSet.close();
In the example above, the scope of the SET variables is limited to the commands between the
autoCommit(false) and commit() lines.
Using Client-Side Cursors in JDBC

To give you control over the latency of initial query results, the Aster Database JDBC driver
supports client-side cursors. Client-side cursors let you avoid retrieving all the result rows for
a query at once. Instead, you specify the number of rows that should be retrieved to the client
at a time. When that set is exhausted, the next page of rows is retrieved by repositioning the
cursor.

Observe the following guidelines when working with cursors:

1 Turn off autocommit mode for the Connection object. See Using Cursors in Your Code,
below.
2 The ResultSet object that receives the output of your Statement cannot be a scrollable
ResultSet. That is, it must have the type, ResultSet.TYPE_FORWARD_ONLY. This is the
default, so you need not rewrite your code.
3 If your application will query large tables, you should make sure your ResultSet can use
distributed cursors. To do this,
a make sure the ResultSet is not updatable (ResultSet.CONCUR_READ_ONLY)
b make sure its not scrollable (ResultSet.TYPE_FORWARD_ONLY)
c make sure it does not have HOLD enabled
(ResultSet.CLOSE_CURSORS_AT_COMMIT).
d Also, the application should connect with autocommit set to false and the connection
must have a specified fetch_count.
Tip! When working with ResultSets of type ResultSet.TYPE_FORWARD_ONLY, you cannot scroll back-
wards, nor can you jump to any location in the ResultSet other than the next row.
4 In the Statement object, you must pass a single query, not multiple queries strung together
with semicolons.
5 You must set the statements fetch_count using the Statement.setFetchSize(int
rows) command. This instructs the driver to fetch the specified number of rows at a time
from the database. If the fetch size is not set, the driver fetches the full set of rows that
match the query.
6 To help ensure a quick response when a page of rows is exhausted, the JDBC driver, by
default, pre-fetches and caches ten pages of results from the database. A page is one
fetch_count worth of rows. You can set the number of pages to be pre-fetched, or you can
disable pre-fetching if desired.
Using Cursors in Your Code

The driver fetches fetch_count number of rows (as set with Statement rows)) from Aster
Database and exposes them to the database application as a rows data structure. The default
fetch_count is zero, so you must set a fetch_count if you wish to use cursors.
With ResultSet.next(), your application iterates over the rows data structure. When all
rows in the rows data structure have been processed, the next call to next() will force the
fetching a new set of fetch_count number of rows, and so on.
To use cursors, set the fetch size of your SQL statement using the setFetchSize(int rows)
method. Later, setting the fetch_count back to 0 will cause all rows to be retrieved when the
query runs (the default behavior).

Tip! In the example below, we set the Autocommit setting and the FetchSize setting using the setAutoCom-
mit() and setFetchSize() methods, but you also have the option of setting these in the JDBC connection
parameters when you make the connection. See Frequently Used JDBC Settings on page 22.
Example That Uses Client-Side Cursors

Assuming a Connection conn, you can set the FetchSize like this:
// Remember the current autocommit state
boolean autoCommit = conn.getAutoCommit();
// Make sure autocommit is off

conn.setAutoCommit(false);
Statement st = conn.createStatement();
// Turn use of the cursor on by setting FetchSize, expressed in rows

st.setFetchSize(50);
ResultSet rs = st.executeQuery("SELECT * FROM mytable");
// Set the autocommit state back

conn.setAutoCommit(autoCommit);
while (rs.next()) {
System.out.print("a row was returned.");
}
rs.close();
// Close the statement.

st.close();
Disabling Cursors
Cursors are enabled by default. To turn them off, set the FetchSize to zero. Assuming a
statement st and a ResultSet rs, you would do this as shown here:
st.setFetchSize(0);
rs = st.executeQuery("SELECT * FROM mytable");
while (rs.next()) {
System.out.print("many rows were returned.");
}
Test JDBC Connect Program

This program can be used as a template for your JDBC connectivity:
// JDBC Test Program
import java.sql.Connection;
import java.sql.DatabaseMetaData;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;
import java.sql.ResultSet;
public class jdbctest {
static String userid="beehive", password = "beehive";
// Change the IP address to the node you want to connect to.

static String url = "jdbc:ncluster://10.60.3.100:2406/beehive"; //2.0

static Connection con = null;
public static void main(String[] args) throws Exception {
Connection con = getJDBCConnection();
if(con!= null){
try {
int count = 0;
System.out.println("Got Connection.");
DatabaseMetaData meta = con.getMetaData();
System.out.println("getDriverName: "+meta.getDriverName());
System.out.println("getDriverVersion: "+meta.getDriverVersion());
System.out.println("getDriverMajorVersion:
"+meta.getDriverMajorVersion());
System.out.println("getDriverMinorVersion:
"+meta.getDriverMinorVersion());
System.out.println("getDatabaseProductName:
"+meta.getDatabaseProductName());
System.out.println("getDatabaseProductVersion:
"+meta.getDatabaseProductVersion());
System.out.println("getIdentifierQuoteString:
"+meta.getIdentifierQuoteString());
System.out.println("\ngetSQLKeywords: "+meta.getSQLKeywords());
System.out.println("\ngetNumericFunctions: "+meta.getNumericFunctions());
System.out.println("\ngetStringFunctions :
"+meta.getStringFunctions());
System.out.println("getSystemFunctions : "+meta.getSystemFunctions());
System.out.println("getTimeDateFunctions :
"+meta.getTimeDateFunctions());
System.out.println("getSearchStringEscape :
"+meta.getSearchStringEscape());
System.out.println("getExtraNameCharacters :
"+meta.getExtraNameCharacters());
System.out.println("getCatalogTerm : "+meta.getCatalogTerm());
System.out.println("getCatalogSeparator :
"+meta.getCatalogSeparator());
System.out.println("getURL : "+meta.getURL());
System.out.println("getUserName : "+meta.getUserName());
System.out.println("getMaxCursorNameLength :
"+meta.getMaxCursorNameLength());
System.out.println("getMaxSchemaNameLength :
"+meta.getMaxSchemaNameLength());
System.out.println("getMaxProcedureNameLength :
"+meta.getMaxProcedureNameLength());
System.out.println("getMaxCatalogNameLength :
"+meta.getMaxCatalogNameLength());
System.out.println("getMaxColumnsInIndex :
"+meta.getMaxColumnsInIndex());
System.out.println("supportsSubqueriesInComparisons :
"+meta.supportsSubqueriesInComparisons());
System.out.println("getMaxConnections : "+meta.getMaxConnections());
System.out.println("getMaxColumnsInTable :
"+meta.getMaxColumnsInTable());
System.out.println("isReadOnly : "+meta.isReadOnly());
System.out.println("\ngetCatalogs:");
ResultSet res = meta.getCatalogs();
while (res.next()) {
System.out.println(res.getString(1));
}

System.out.println("\ngetTables:");
res.close();
res = meta.getTables(null,null,"%",null);
System.out.println(res.getString(1) +res.getString(2) +res.getString(3)
+res.getString(4));
}
System.out.println("");
res.close();
res = meta.getTableTypes();
System.out.println("\ngetTableTypes:");
System.out.println(res.getString(1));
}
res.close();
Statement stmt=con.createStatement();
ResultSet rs = stmt.executeQuery("select count(*) from page_views");
while (rs.next()) {
System.out.println(rs.getInt(1));
}
rs.close();
stmt.close();
con.close();
} catch(SQLException ex) {
System.err.println("SQLException: " + ex.getMessage());
}
}else{
System.out.println("Could not Get Connection");
}
}
public static Connection getJDBCConnection(){
try {
Class.forName("com.asterdata.ncluster.Driver");
} catch(java.lang.ClassNotFoundException e) {
System.err.print("ClassNotFoundException: ");
System.err.println(e.getMessage());
}
try {
con = DriverManager.getConnection(url,userid, password);
} catch(SQLException ex) {
System.err.println("SQLException: " + ex.getMessage());
}
return con;
}
}

Tailoring the Behavior of Aster Database SQL to Your Needs
Tailoring the Behavior of Aster Database SQL to

Your Needs
This section explains how to set parameters that customize the behavior of Aster Database
SQL.
SQL Behavior Parameters
Escape Character Handling

enable_backslash_escapes: Set to on (the default), Aster Database allows backslash
escape strings in your constants. The escape strings are C-like backslash escape sequences,
each introduced with a backslash character (\). Set to off , Aster Database does not recognize
backslash escape strings in your constants unless the constant is prefixed with a letter E before
its opening single quote. In any constant not prefixed with the letter E, a backslash is
interpreted simply as a backslash character.
Quoted-Identifier Handling
enable_quoted_identifiers: This setting affects the way Aster Database processes strings
enclosed in double-quote characters ("..."). With enable_quoted_identifiers='on' (the
default), Aster Database follows the standard behavior of interpreting each double-quoted
string as an identifier (a column, table, schema, or function name). With
enable_quoted_identifiers='off', each double-quoted string is interpreted as a literal
string constant. Any printable character may be represented in a double-quoted string. See
Quoted Identifiers on page 916.
Setting the SQL Behavior Parameters
At the SQL Prompt

You can set these parameters from the SQL prompt by executing SET commands in the form:
SET SESSION <parameter name> = {'<param setting>'};
For example:
SET SESSION enable_backslash_escapes = {'on'|'off'};
and
SET SESSION enable_quoted_identifiers = {'on'|'off'};
In the Aster Database ODBC Driver

The Aster Database ODBC-NG driver allows you to set Aster Database SQL behavior
parameters like, for example, enable_backslash_escapes. The connection parameters are:
enable_backslash_escapes={on|off}
enable_quoted_identifiers={on|off}

Tailoring the Behavior of Aster Database SQL to Your Needs
These can be set in the DSN configuration (i.e., the odbc.ini file or Windows registry).
Alternatively, a connecting application may set these options in the connection string when
connecting without a registered DSN.
Syntax for ODBC Commands

This section lists some ODBC commands for which the syntax differs from the native Aster
Database syntax. Note that comments and parameter markers are not allowed in these
commands. However, the prepare/execute model is supported.
COPY FROM/TO
Semantics and overall flow of execution for COPY is the same as for the Aster Database Loader
Tool. See Aster Database Loader Tool on page 375.
Syntax
COPY table [(column list)] FROM <quoted file name> ...COPY attributes
or
COPY table [(column list)] TO <quoted file name> ...COPY attributes
The COPY command accepts a quoted file name and streams the data into or out of Aster
Database using the Aster Database Loader Tool protocol for maximum throughput. For more
detailed syntax, see COPY (page 711).
INSTALL
The INSTALL command is similar to the ACT command \install <FILE> [[<SCHEMA>/
]<FILE_ALIAS>] on page 127, and supports SQL-MR security semantics. See SQL-
MapReduce Security on page 246.
Syntax
INSTALL FILE <quoted file name> [[<schema>/]<file alias>]
The schema name must be quoted if it contains spaces or mixed case.
The file alias must be quoted.
UNINSTALL
The UNINSTALL command supports SQL-MR security semantics. See SQL-MapReduce
Security on page 246.
Syntax
UNINSTALL FILE <quoted file name> [[<schema>/]<file alias>]
DOWNLOAD
The DOWNLOAD command is similar to the ACT command \download [[<SCHEMA>/
]<FILE_ALIAS>] <FILE> on page 127, and supports SQL-MR security semantics. See SQL-
MapReduce Security on page 246.

SSL Security for Aster Database-Client Communications
Syntax
DOWNLOAD FILE <quoted file name> [[<schema>/]<file alias>]
SSL Security for Aster Database-Client

Communications
Aster Database provides the option to use SSL to secure communications between second-
generation Aster Database ODBC clients (2nd-gen ODBC clients) and the Aster Database
queen. In Aster Database versions 4.5 and later, by default, a 2nd-gen ODBC client running on
Windows or Linux sends all of its communications to Aster Database over an SSL-encrypted
connection. By default, results and other data returned from Aster Database to the client are
NOT encrypted. This default configuration can be changed to suit your needs, as explained in
the sections that follow.
Important note for upgraders: Most pre-version-4.6 Aster Database drivers and the pre-4.6 ACT client do not
support SSL. During your upgrade to Aster Database 4.6, you must replace all Aster Database drivers and ACT cli-
ents that connect to your Aster Database installation.
Port Number
The Aster Database queen port number for SSL connections is the same as the regular client
connection port: 2406. Port 2406 is multiplexed to support both secure sockets layer (SSL)
connections and unencrypted connections.
Contents of This Section

This section contains:
SSL-Related Files and Settings (page 30)
SSL Settings Reference (page 31)
Common SSL Configuration Scenarios in Aster Database (page 32)
Encrypting Data Traffic (page 33)
Adding AD-Based SSO Authentication to SSL-Secured Aster Database (page 34)
How to Set Configuration Parameters on the Queen (page 35)
How to Set Configuration Parameters on the Client (page 35)
Creating Certificates (page 40)
SSL-Related Files and Settings

As shipped, the queen has the following files related to SSL communications and set-up:
Private key: Default one is /home/beehive/certs/server.key

Self-signed PEM certificate (that is, the base64-encoded ASCII representation of the
certificate only; this is the version of the certificate that starts with "-----BEGIN
CERTIFICATE-----" and ends with "-----END CERTIFICATE-----"). The default one is /
home/beehive/certs/server.cert
Another copy of the self-signed certificate, also in PEM format, but this time formatted in
X.509 structure. Note! This file may be missing from your Aster Database installation. To
work around this problem, you must create the default PEM file from the server.cert
file, saving it as /home/beehive/certs/server.pem. To create it, log in to the queen as
root, change directories to /home/beehive/certs, and type:
# openssl x509 -in server.cert -text >> server.pem
The queens SSL-related settings (see SSL Settings Reference on page 31) in the Aster
Database queen configuration file, /home/beehive/config/procmgmtConfigs/
coordinator.cfg
On the client side, the files related to SSL and its configuration are:
Copy of the queens public key in PEM format. This is a copy of the queens server.pem.
For example, you might save it as /home/mjones/certs/server.pem
The clients SSL-related settings (see Client-Side SSL Settings on page 32), stored:
for Linux, in the clients odbc.ini file; and
for Windows, in the ODBC parameter fields of the registry
SSL Settings Reference

This section provides a reference to the available SSL settings on the Aster Database queen.
Queen-Side SSL Parameters

Below, we list the configuration flags that can be used on the queen to tune SSL behavior. Most
queen-side flags have a corresponding client-side flag. When you change a flag on one side
(client or server), you will typically have to make appropriate changes to the other side.
disallowPeerWithoutCertificates: If this flag is set, the client cannot communicate
with its peer (server) without a valid certificate. This flag is defaulted to FALSE.
allowSelfSignedPeer: If this flag is set, Aster Database allows connections from clients
with self-signed certificates. Defaults to TRUE.
Set either trustedCAFileName or trustedCAPath, depending on whether you have one
or many CA certificates:
trustedCAFileName: The pathname of the single PEM-formatted CA certificate that
Aster Database trusts. (You also have the option of trusting multiple CA certificates;
see trustedCAPath, below.) Whenever the queen gets a certificate from the peer, the
queen traverses the certificate chain to verify that the certificate specified by
trustedCAFileName is part of the chain. If so, the peer is allowed to connect.
trustedCAPath: Directory containing PEM-formatted CA certificates that Aster
Database trusts. The files inside this directory are looked up based on the CA subject
name hash value.
sslCertificatePath: SSL certificate location.

sslPrivateKeyPath: SSL private key location.

sslFileType: The formatting type of the certificate. Set this to a string value of 1 for
PEM-encoded certs (called SSL_FILESYSTEM_PEM on the client side) or 2 for ASN1-
encoded certs (called SSL_FILETYPE_ASN1 on the client side). Default is 1.
secureMuleServer: If set, Aster Database will be configured to use a secure channel for
its communication. If secureMuleServer is enabled, the configuration flags
sslCertificatePath and sslPrivateKeyPath should be appropriately set.
Client-Side SSL Settings

Below, we list the configuration flags that can be used on the client side to tune SSL behavior.
These settings work only with the 2nd-generation Aster Database ODBC client. Most client-
side flags have a corresponding queen-side flag. When you change a flag on one side (client or
server), you will typically have to make appropriate changes to the other side.
EnableSSL: Enables/disables the use of SSL (string value of 0 for false, or 1 for true).
0 = Disable SSL (default)
1 = Enable SSL
SSLEncryptReads: Determines whether the client expects data returned from database to
be encrypted (string value of 0 for false, or 1 for true).
0 = query results are unencrypted (the default)
1 = query results are encrypted
SSLAllowSelfSignedPeer: Determines whether the client allows peers with self signed
certificates to communicate (string value of 0 for false, or 1 for true; default is 1).
SSLFileType: The certificate file type. A string value; one of:
SSL_FILETYPE_PEM (the default)
SSL_FILETYPE_ASN1
SSLPrivateKeyPath: Path to the private key to be used. Optional. (A string value.)
SSLCertificatePath: Path to the SSL certificate to be used. (A string value.)
Set either SSLTrustedCADir or SSLTrustedCAFilename, depending on whether you
have one or many CA certificates:
SSLTrustedCADir: Path to the directory containing CA certificates in PEM format.
(A string value.)
SSLTrustedCAFilename: Filename of CA certificate in PEM format. (A string value.)
Common SSL Configuration Scenarios in Aster Database

This section presents common SSL configuration scenarios and shows how to set up each one.
The scenarios are:
Scenario 1: Allowing connections from clients without certificates (page 33)
In all of the scenarios, we instruct you to set parameters on the queen and on the client. For
instructions, see:
For the queen: How to Set Configuration Parameters on the Queen on page 35; and

For clients: How to Set Configuration Parameters on the Client on page 35
Scenario 1: Allowing connections from clients without certificates

In this scenario, we edit the Aster Database SSL configuration to allow connections from
clients that have no certificate. In such a configuration, any 2nd-generation Aster Database
ODBC client can establish an SSL-secured connection, provided the user authenticates
successfully with Aster Database. Communications from the client to Aster Database (for
example, queries submitted to the database) are SSL encrypted, and query results travel in the
clear.
Queen-Side Settings
Make the following settings on the queen:
disallowPeerWithoutCertificates=false
allowSelfSignedPeer=true
trustedCAFileName=/home/beehive/certs/server.pem
sslCertificatePath=/home/beehive/certs/server.cert
sslPrivateKeyPath=/home/beehive/certs/server.key
sslFileType=1 (A value of 1 means SSL_FILETYPE_PEM.)
Ensure that secureWrites is set to false
Ensure that secureMuleServer is set to true
There is no need to set the trustedCAPath parameter.
Client-Side Settings
Make the following settings on each ODBC client:
EnableSSL=1
SSLEncryptReads=0
SSLAllowSelfSignedPeer=1
SSLFileType=SSL_FILETYPE_PEM
There is no need to set the other SSL settings such as SSLPrivateKeyPath.
Encrypting Data Traffic

By default, Aster Database encrypts only control-path communications, such as the login
credentials an ODBC user submits, and the queries he or she submits. For implementations
that demand greater security, Aster Database also gives you the option of SSL-encrypting the
data traffic as the queen returns it to the client.
Warning. All other things being equal, switching any network connection from unencrypted
to SSL-encrypted has the effect of reducing the maximum available rate of data transmission
on that connection.

To set this up:
Queen-Side Settings
secureWrites=true
Make the following settings on each ODBC client:
SSLEncryptReads=1
Adding AD-Based SSO Authentication to SSL-Secured Aster Database

If your Aster Database is configured to authenticate users against Active Directory (AD), you
can configure your 2nd-generation Aster Database ODBC clients to authenticate against AD,
too. With this configuration in place, each ODBC client will be required to authenticate
against AD when it tries to connect to Aster Database. If the ODBC client authenticates
successfully, an SSL channel is established automatically for communication between Aster
Database and the client. To set this up:
Queen-Side Settings
1 Set up Aster Database user authentication as explained in Set Up Active Directory
Authentication with Single Sign-On on page 336.
2 Configure the queen SSL configuration flags as described in one of the scenarios above
which you are planning on implementing. (For example, see Scenario 1: Allowing
connections from clients without certificates on page 33
Do the following:
1 Set the flags in the clients ODBC configuration file or registry as described in your chosen
scenario from above.
2 Set the EnableSSO flag in the clients ODBC configuration file:
EnableSSO=1
3 If EnableSSO is set to 1, you must also:
Ensure that ServerIP is set to the fully qualified domain name of the Aster Database
queen and not to an IP address.
For 64-bit Linux machines: The ODBC driver assumes that libvas-gssapi.so is
present at /opt/quest/lib64/. If /opt/quest/lib64/libvas-gssapi.so does
not exist, locate libvas-gssapi.so by referring to the VAS documentation and set
the GSSPath parameter to point to the installed location of libvas-gssapi.so. For
example, if libvas-gssapi.so is deployed at /usr/lib64, then the GSSPath
parameter needs to be set to /usr/lib64 in the ODBC.ini config file as shown below:
GSSPath=/usr/lib64

For 32-bit Linux machines: The ODBC driver assumes that libvas-gssapi.so is
present at /opt/quest/lib/. If /opt/quest/lib/libvas-gssapi.so does not
exist, locate libvas-gssapi.so by referring to the VAS documentation and set the
GSSPath parameter to point to the installed location of libvas-gssapi.so. For
example, if libvas-gssapi.so is deployed at /usr/lib, then the GSSPath parameter
needs to be set to /usr/lib in the ODBC.ini config file as shown below:
GSSPath=/usr/lib
How to Set Configuration Parameters on the Queen

Many procedures in this document ask you to set configuration parameters on the Aster
Database queen. Below, we explain how to do this.
Persistent Setting of Parameters

To edit a setting (and have your edit survive reboots), make the setting as shown below.
Settings you change in this manner will survive reboots and soft restarts but they will not
survive upgrades.
1 Login as root into queen and use a text editor to open the file, /home/beehive/config/
procmgmtConfigs/coordinator.cfg
2 Find the queenExec section which looks like:
"taskName": "queenExec",
"nodeIps": "REPLACE_NODE_IP",
"executableLocation": "/home/beehive/bin/exec/queenExec",
"maxTaskRestarts": -1
3 Add the executableArgs section to the above section as shown below:
"executableArgs": "<flags in CSV format>"
For example, executableArgs for Scenario 1 (described earlier in this chapter) will look
like:
"taskName": "queenExec",
"nodeIps": "REPLACE_NODE_IP",
"executableLocation": "/home/beehive/bin/exec/queenExec",
"maxTaskRestarts": -1,
"executableArgs": "--disallowPeerWithoutCertificates=false,
--allowSelfSignedPeer=true,--trustedCAFileName=/home/beehive/certs/
server.pem,--sslCertificatePath=/home/beehive/certs/server.cert,
--sslPrivateKeyPath=/home/beehive/certs/server.key,--sslFileType=1"
4 Soft restart and activate the cluster.
How to Set Configuration Parameters on the Client

This section explains how to set up the 2nd-generation Aster Database ODBC client for SSL
communications with Aster Database. Consult the section that applies to your operating
system:
Linux ODBC DSN Set-Up, below; or
Windows ODBC DSN Set-Up on page 36

Linux ODBC DSN Set-Up

On a UNIX-like systems, DSNs are added by setting parameters in the odbc.ini file
Sample ODBC.INI:
This sample assumes your queen machine is called cqueen.asterengqa.com and that you
are following Scenario 1 (outlined earlier in this chapter):
[ODBC Data Sources]
AsterTest=AsterDriverTest
[AsterTest]
Driver=AsterDriverTest
SERVER=cqueen.asterengqa.com
DATABASE=beehive
PORT=2406
UID=testuser13
PWD=testuser133
SQLSupportedConversions=3
NumericAndDecimalAsDouble=1
EnableSSO=0
GSSPath=
EnableSSL=1
SSLEncryptReads=0
SSLAllowSelfSignedPeer=1
SSLFileType=SSL_FILETYPE_PEM
SSLPrivateKeyPath=
SSLCertificatePath=
SSLTrustedCADir=
SSLTrustedCAFilename=
Sample ODBCINST.INI:
This sample assumes you have installed the driver in /Drivers/AsterDriver/ODBCDriver:
[AsterDriverTest]
Driver=/Drivers/AsterDriver/ODBCDriver/libAsterDriver_unixODBC.so
Sample aster.ini:
This sample assumes you want to log error messages in /Drivers/AsterDriver:
[driver]
DriverManagerEncoding=UTF-32
DSILogging=1
ErrorMessagesPath=/Drivers/AsterDriver/ErrorMessages
Windows ODBC DSN Set-Up

On Windows, DSNs are added by modifying the Windows Registry using regedit.exe or
using a .reg file. The standards surrounding key names (such as whether to use Server or
servername) used in a connection string for ODBC driver are loose, so please take care to
follow the examples we provide.

Details for setting the values in the registry are given below. Choose the section that fits your
needs and client type:
Adding a driver to a Windows 32-bit operating system, below.
Adding a 64-bit driver to a Windows 64-bit operating system on page 38
Adding a 32-bit driver to a Windows 64 bit operating system on page 39
Adding a driver to a Windows 32-bit operating system

Make the following registry settings:
Driver for 32-bit Windows

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC]
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI]
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\AsterDriver32]
"Driver"="C:\\AsterDriver-Win32\\ODBCDriver\\AsterDataODBCDSII.dll"
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\ODBC Drivers]
"AsterDriver32"="Installed"
[HKEY_LOCAL_MACHINE\SOFTWARE\Aster]
[HKEY_LOCAL_MACHINE\SOFTWARE\Aster\Driver]
"DSILogging"="0"
"ErrorMessagesPath"="C:\\AsterDriver-Win32\\ErrorMessages"
"DriverManagerEncoding"="UTF-16"
The values in the keys above can be modified depending on where the driver is located on the
local machine and what the name of the driver should be. The values above are based on the
assumption that the driver folder is at "C:\AsterDriver-Win32" and the name of the driver is
"AsterDriver32". For an example .reg file that makes these settings, contact Teradata support.
DSN for 32-bit Windows

To add a DSN for the above driver setup in the registry, make these entries in the registry:
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI]
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\AsterDSN32]
"driver"="AsterDriver32"
"SERVER"="10.51.12.100"
"DATABASE"="beehive"
"PORT"="2406"
"UID"="beehive"
"PWD"="beehive"
"SQLSupportedConversions"="3"
"NumericAndDecimalAsDouble"="1"
"EnableSSO"="0"
"SSLKeyFile"="\"\""
"GSSPath"=""
"EnableSSL"="1"
"SSLEncryptReads"="1"
"SSLAllowSelfSignedPeer"="0"
"SSLFileType"="SSL_FILETYPE_PEM"
"SSLPrivateKeyPath"="\"\""
"SSLCertificatePath"="\"\""
"SSLTrustedCADir"="\"\""
"SSLTrustedCAFilename"="\"\""

"EnableSSO"="0"
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\ODBC Data Sources]
"AsterDSN32"="AsterDriver32"
Adding a 64-bit driver to a Windows 64-bit operating system

Below we list the registry entries for setting up a 64-bit driver on Windows. Make the registry
settings shown below:
64-bit driver for 64-bit Windows
64-bit DSN for 64-bit Windows
64-bit driver for 64-bit Windows

[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI]
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\AsterDriver64]
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\ODBC Drivers]
[HKEY_LOCAL_MACHINE\SOFTWARE\Aster]
[HKEY_LOCAL_MACHINE\SOFTWARE\Aster\Driver]
"DSILogging"="0"
64-bit DSN for 64-bit Windows

[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI]
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\AsterDSN64]
"SERVER"="10.51.12.100"
"PORT"="2406"
"UID"="beehive"
"PWD"="beehive"
"EnableSSO"="0"
"SSLKeyFile"="\"\""
"GSSPath"=""
"EnableSSL"="1"
"EnableSSO"="0"
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\ODBC Data Sources]

Above, the name of the DSN for the 64-bit driver is AsterDSN64. The server being connected
to is 10.51.12.100.
Adding a 32-bit driver to a Windows 64 bit operating system

Some applications running on a Windows 64-bit machine require a 32-bit driver. The 32-bit
operations work on Windows 64 bit machines under a mechanism called Wow6432Node.
Below we list the registry entries for setting up 32-bit drivers on Windows. Make the registry
settings shown below:
32-bit driver on 64-bit Windows
32-bit DSN on 64-bit Windows
32-bit driver on 64-bit Windows

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC]
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBCINST.INI]
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBCINST.INI\AsterDriver32
]
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBCINST.INI\ODBC Drivers]
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Aster]
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Aster\Driver]
"DSILogging"="0"
The values in the keys above can be modified depending on where the driver is located on the
local machine and what the name of the driver should be. The values above are based on the
assumption that the driver folder is at "C:\AsterDriver-Win32" for 32 bit drivers and the name
of the driver is "AsterDriver32". For an example .reg file that makes these settings, contact
Teradata support.
32-bit DSN on 64-bit Windows

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC]
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBC.INI]
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBC.INI\AsterDSN32]
"SERVER"="10.51.12.100"
"PORT"="2406"
"UID"="beehive"
"PWD"="beehive"
"EnableSSO"="0"
"SSLKeyFile"="\"\""
"GSSPath"=""
"EnableSSL"="1"

Processing SQL Statements in JDBC
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBC.INI\ODBC Data
Sources]
Above, the name of the DSN for the 32-bit driver is AsterDSN32. The server being connected
to is 10.51.12.100.
Creating Certificates
Creating a Self-Signed Certificate

You may to create your own self-signed certificate. The high-level steps for doing this using
the OpenSSL tool are shown here, assuming you create a private key file called host.key:
openssl genrsa 1024 > host.key
chmod 400 host.key
openssl req \-new \-x509 \-nodes \-sha1 \-days 365 \-key host.key >
host.cert
Regenerating SSL Certificates/Private Key During Aster Database

Installation
You may manually regenerate the default private key and certificate using the following
command on the queen:
1 Working as root user, perform a soft shutdown on Aster Database:
# ncli system softshutdown
2 Wait for the system to shut down, and then run the resetCert command:
# /home/beehive/bin/lib/configure/ConfigureNCluster.py --resetCert
This will back up any existing server.key/server.cert files present in /home/beehive/certs
and generate a new private key and certificate file.

You can execute SQL statements by using a Statement or a PreparedStatement instance.
Sometimes it is more convenient to use a PreparedStatement object for sending SQL
statements to the database. This special type of statement is derived from the more general
class, Statement, that you already know.
If you want to execute a Statement object many times, it normally reduces execution time to
use a PreparedStatement object instead.
The main feature of a PreparedStatement object is that, unlike a Statement object, it is
given an SQL statement when it is created. The advantage to this is that in most cases, this SQL

statement is sent to the DBMS right away, where it is compiled. As a result,

the PreparedStatement object contains not just an SQL statement, but an SQL statement
that has been precompiled. This means that when the PreparedStatement is executed, the
DBMS can just run the PreparedStatement SQL statement without having to compile it
first.
Processing a Simple Query in JDBC

This example will issue a simple query and print out the first column of each row using
a Statement.
Statement st = conn.createStatement();
ResultSet rs = st.executeQuery("SELECT * FROM mytable WHERE columnf =
500");
while (rs.next()) {
System.out.print("Column 1 returned ");
System.out.println(rs.getString(1));
}
rs.close();
st.close();
This example issues the same query as before but uses a PreparedStatement and a bind
value in the query.
int fvalue = 500;
PreparedStatement st = conn.prepareStatement("SELECT * FROM mytable
WHERE columnf = ?");
st.setInt(1, fvalue);
ResultSet rs = st.executeQuery();
while (rs.next()) {
System.out.print("Column 1 returned ");
System.out.println(rs.getString(1));
}
rs.close();
st.close();
The instance returns a ResultSet containing the results. Aster Database does not support
cursor-based server-side caching of results which would save a small amount of time in
parsing.
To retrieve data from the ResultSet instance, call next(), which returns true if there are
results.
The ResultSet instance can be closed by calling close(), or if another query is issued using
the same Statement instance that was used to create this ResultSet.
Statement stmt=con.createStatement();
ResultSet rs = stmt.executeQuery("select count(*) from page_views");
while (rs.next()) {
System.out.println(rs.getInt(1));
}
rs.close();
stmt.close();
You can also run Update/Insert/Delete statements and Create/Drop Table statements using the
same method.

JDBC Issues
JDBC Issues
Infinity and Negative Infinity Timestamp Conversion
The JDBC driver converts 'infinity' and '-infinity' to specific TimeStamp values (a very large
and a very tiny TimeStamp) which can cause unexpected results on the client side.
Aqua Data Studio and other client tools, like SQL Assistant JAVA edition also have this issue.
These tools do not support 'infinity' and '-infinity' in the timestamp datatype. If they
encounter these values, they will display specific TimeStamp values (a very large and a very
tiny TimeStamp).
Connecting Reporting Tools to Aster Database

This section shows how to connect various reporting and query tools to Aster Database:
Connecting Aqua Data Studio to Aster Database (page 42)
Connecting MicroStrategy to Aster Database (page 43)
See also: Connect Using Database Drivers (page 6)
Connecting Aqua Data Studio to Aster Database
ADS support is being deprecated.
AquaFolds ADS lets you perform DDL operations and query data interactively, and it
provides tools that help you write and manage queries efficiently. ADS is a third-party tool
available for purchase from Aqua Fold directly.
Aster Database is compatible with ADS version 10.0.2 with patch ads-10.0.7_03-patch.zip.
Install ADS
This section explains how to install ADS on your client workstation and connect to an Aster
Database.
1 Download Aqua Data Studio version 10.0.2 or later from http://www.aquafold.com/
downloads.html
2 Install Aqua Data Studio on your client workstation as explained in your version of the
Aqua Data Studio documentation at http://docs.aquafold.com/
aquadatastudio_11_documentation.html
3 Start Aqua Data Studio.

4 Select the command Server: Register Server.
5 In the list, select the Aster nCluster Driver.
6 Fill in the tabs as required.

Apply the ADS Patch

1 Download the patch from AquaFold:
http://dd1.aquafold.com/download/v10.0.0/ads-10.0.7_03-patch.zip
2 Unzip the patch files.

3 Replace the files under C:\Program Files\Aqua Data Studio 10.0 - 64bit\lib with the files
from ads-10.0.7_03-patch.zip.
4 Restart ADS.
Connecting MicroStrategy to Aster Database

Observe the following guidelines when connecting MicroStrategy to Aster Database.
In this section: Versions | Platforms Supported | Limitations | Set-up Instructions | Best
Practices
Versions
MicroStrategy 9 or later is required, and Aster Database 3.0.1 or later is required.
Platforms Supported
Aster Database supports Intelligence Server clients running on Windows XP and Windows
Vista with the Aster Database ODBC driver for Windows.
Limitations
Aster Database is only certified as a warehouse with MicroStrategy. Aster Database cannot be
used as a repository.
Set-up Instructions
To connect MicroStrategy to Aster Database, follow the steps below.
Prerequisites
Make sure the following patches are applied to your MicroStrategy installation:
MicroStrategy 8: Contact MicroStrategy Customer support for
DATABASE.PDS file that's certified with Aster Database
DTMAPPING.PDS file that's certified with Aster Database
MicroStrategy 9: Contact MicroStrategy Customer support for
DTMAPPING.PDS file that works with Aster Database
MicroStrategy 9.0.1 and above: No changes required

Install Drivers
On the client machine where MicroStrategy runs, install the database drivers:
1 Install the Aster Database ODBC driver. This is available in the /home/beehive/clients
directory on your Aster Database queen. See ODBC Driver on page 7 for installation
instructions.
2 Install the MicroStrategy VLDB driver, version 9 or later.
Configure Drivers and Library Paths

1 Make sure the following are installed, and make sure that your Microstrategy installations
LD_LIBRARY_PATH includes them:
libstdc++.so.6
libgcc_s.so.1
2 Edit Microstrategys ODBC.sh file so that the Microstrategy installation can find the Aster
Database ODBC driver. To do this, modify {MSTR_HOME}/env/ODBC.sh and add or
modify the Aster section of the file. In this section, do two things:
a Include the Aster Database ODBC driver library in the LD_LIBRARY_PATH.
b Make sure there is an export ODBCSYSINI line in the section. This line points to the
odbc.ini that the Microstrategy application will use.
Below, we show an example setup from a sample {MSTR_HOME}/env/ODBC.sh file:
ASTER_PATH='/usr/local/lib/stage/<client_directory_for_OS>/
ODBCDriver: \
/usr/local/lib/stage/<client_directory_for_OS>/Libs'
if [ "${ASTER_PATH}" != '<ASTER_PATH>' ]; then
export ASTER_PATH
mstr_append_path LD_LIBRARY_PATH "${ASTER_PATH:?}"
export LD_LIBRARY_PATH
export ODBCSYSINI=/export/home/beehive/MicroStrategy
fi
3 Modify your ${ODBCSYSINI}/odbc.ini to include the new ODBC DSN
[ODBC Data Sources]
aster=AsterDriver
[aster]
Driver=/usr/local/lib/stage/<client_directory_for_OS>/ODBCDriver/
SERVER=<server_ip>
PORT=2406
DATABASE=<database>
UID=<uid>
PWD=<passwd>
4 Modify your ${ODBCSYSINI}/odbcinst.ini to include the Aster Database ODBC

settings as shown in the example below:
[AsterDriver]
Driver=/usr/local/lib/stage/<client_directory_for_OS>/ODBCDriver/

Connecting to an Aster Database

1 Open your MicroStrategy project and choose Intelligence Server as your connection option.
2 Use the Configuration Wizard to create a New Project Source.
3 Create a New Database Instance and give it a name.
4 In the Connection Type field, choose Aster Database nCluster.
5 Create a New Database Connection and give it a name.
6 Create a new ODBC System DSN and give it a name.
Once you have saved the System DSN, you can create reports in MicroStrategy that use the
data from your Aster Database. In your Logical Table definitions in MicroStrategy, you can
create queries that use special Aster Database tools such as nPath.
Best Practices
By following the guidelines below, you can avoid common errors in Aster Database-
MicroStrategy integration.
Schema changes
If your schema contains NUMERIC(X,0) type columns, you should replace these with
INT or BIGINT type columns for a higher probability of success with existing
MicroStrategy reports.
For your small- to medium-sized tables that have no BIGINT or INT columns, you should
create the tables in Aster Database as replicated dimension tables. This takes more space in
the cluster, but works better with MicroStrategy.
Operational items
When pointing an existing MicroStrategy report from another database to Aster Database, the
warehouse schema should be UPDATED the first time when pointed to an Aster Database
Instance. This updates the metadata inside MicroStrategy for correct MicroStrategy columns.
This is particularly important when a schema is ported from some other database to Aster
Database.
SQL query changes

To use Aster Databases nPath and other custom SQL-MapReduce functions:
Reports must be created as free-form SQL type reports in MicroStrategy.
Teradata Aster recommends that you embed the query in an MicroStrategy logical
table and build the reports on top of that.
If there are existing reports that need to run on Aster Database, some tweaking may be
needed in the VLDB Settings of MicroStrategy depending on the complexity of the
dynamically generated queries. For example, you may need to turn off TEMP table
creation, and so on. This is very rare, but editing VLDB settings can be useful in some
cases.
If the following error appears in queries: Unable to find function to convert from <x> to
<y>, and if x and y are datatypes like int, float, and so on, then you may need a
workaround to explicitly cast the column types. Contact Teradata Support for help on this.

Index
A ODBC 7
ODBC for Perl scripts 16
Active Directory authentication
distributed cursors 24
SSL connections and 34
drivers 6
Aster Database
JDBC 19
connecting, overview 6
ODBC 7
Aster Database configuration settings
ODBC for Perl scripts 16
SQL behavior 28
B E
backslash E prefix 28
allow backslash escapes 28 enable_quoted_identifiers 28
bytea encryption 30
handling bytea data in ODBC 10 of query results 33
SSL for ODBC 30
escape character
C allow backslash escapes 28
certificate 40 export
for ODBC connection 40 JDBC driver 19
character set, default 6 ODBC driver 7
characters, special 6
client J
recommended client settings 6
Java
client settings, recommended 6
JDBC statements 40
client-side cursors in JDBC 23
JDBC 19
configuration
connecting through JDBC 21
queen system parameters 35
cursors in 23
configuration settings
SQL behavior 28 driver 19
connect 6 how to write applications that use JDBC 40
JDBC driver 19 query example 41
MicroStrategy 43 sample test program 25
ODBC driver 7
connecting 6 L
overview 6 loading
through JDBC 21 JDBC driver 19
coordinator.cfg 35 ODBC driver 7
cursor
distributed 24
JDBC, cursors in 23
M
customizing SQL behavior 28 MicroStrategy, connections for 43
D O
data ODBC 7
encrypting data traffic 33 bytea handling 10
database drivers 6 driver 7
JDBC 19 ODBC driver

for MicroStrategy 43 T
installing for use with Perl scripts 16
tools
installing on Linux 11
MicroStrategy 43
installing on Windows 7
SSL settings 32
U
P umlauts 6
UTF-8
parameter recommended client settings 6
setting queen system parameters 35 utilities
Perl scripts, ODBC driver for 16 JDBC driver 19
preferences ODBC driver 7
SQL settings 28
PreparedStatement in JDBC 40
W
Q workaround
certificate, missing self-signed cert 31
queen
system parameters, setting 35
query
via Java JDBC calls 40
quoted identifier
enable in Aster Database 28
R
recommended client settings 6
reporting tools
MicroStrategy 43
S
security
SSL for ODBC 30
settings
enable_backslash_escapes 28
enable_quoted_identifiers 28
SQL settings 28
SSL connection settings 31
SQL
customizing SQL behavior 28
parameters that set SQL behavior 28
SSL 30
with Active Directory authentication 34
SSL for ODBC 30
certificates for 40
client settings 32
common configuration scenarios 32
encryption of query results 33
how to set up on client 35
how to set up on queen 35
queen settings 31
reference to Aster Database SSL settings 31
SSO for ODBC connections 34
Statement in JDBC 40

Aster Database Client Guide 0503

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Aster Database Client Guide 0503

Enviado por

Direitos autorais:

Formatos disponíveis

Aster Database Client Guide

Release Number 5.0.3

Copyright 2000-2012 by Teradata Corporation. All Rights Reserved.

General Tips for Connecting Clients to Aster Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Aster Database Client Guide 4

5 Aster Database Client Guide

Setting up database drivers:

Using database drivers:

Security for database drivers:

Connecting BI and query tools:

General Tips for Connecting Clients to Aster

Aster Database Client Guide 6

When Querying System Tables with ODBC, Set AUTOCOMMIT to

See the section below that applies to your platform:

Installing ODBC on Windows

b Download the package from ftp.asterdata.com.

7 Aster Database Client Guide

Aster Database Client Guide 8

10 In the Aster Database Login window, enter the following information:

9 Aster Database Client Guide

Optional ODBC Setting for bytea-Stored Data

For a 32-bit ODBC driver running on 32-bit Windows

Aster Database Client Guide 10

For a 32-bit ODBC driver running on 64-bit Windows

Installing ODBC on Linux, Solaris, and MacOS

Install the Driver Manager on Linux/Solaris/MacOS

2 Install unixODBC by running the following commands:

Wait while it builds and installs.

find doc -name "Makefile*" -exec rm {} \; &&

install -v -m755 -d /usr/share/doc/unixODBC-2.2.12 &&

11 Aster Database Client Guide

Install the Aster Database ODBC Driver on Linux/Solaris/MacOS

Aster Database Client Guide 12

Configure the ODBC Driver on Linux/Solaris/MacOS

13 Aster Database Client Guide

[ODBC Data Sources]

[Aster Database ODBC for nCluster DSN]

[ODBC Data Sources]

Aster Database Client Guide 14

On MacOS, it will look like:

The installation and configuration are complete.

Test the installation

15 Aster Database Client Guide

Setting up ODBC for Perl Connectivity on Linux

6 Get the latest packages and install them by entering:

9 Run the following Perl script to check your installation.

Aster Database Client Guide 16

# Connect to ODBC DSN and turn off AutoCommit

Setting up ODBC for PHP

Apache and PHP

17 Aster Database Client Guide

ODBC Usage Notes

Avoid using bind_param with SQL_DECIMAL

Bind columns without specifying a SQL datatype

Aster Database Client Guide 18

Aster Database JDBC Driver

Aster Database JDBC Driver 5.0.3

19 Aster Database Client Guide

The result set cannot be accessed after an explicit commit.

Before You Start

Installing the Aster Database JDBC Driver

Using the Aster Database JDBC Driver in a Java Application

Aster Database Client Guide 20

Parameters for Connecting to Aster Database through JDBC