Configuring Data Sources

After you install the driver, you need to configure a data source or use a connection string to connect to the database. If you want to use a data source, but need to change some of its values, you can either modify it or override its values through a connection string. See "Quick Start Connect" for an explanation of different types of data sources.

If you choose to use a connection string, you must use specific connection string attributes. See "Connecting to a Data Source Using a Connection String" and Table 16-1 for a complete description of driver connection string attributes and their values.

UNIX

On UNIX and Linux, you must set up the proper ODBC environment before configuring data sources. See "Environment Configuration" for basic setup information and "Environment Variables" for more detail about this procedure.

Data sources are stored in the system information file (by default, odbc.ini). If you have a Motif GUI environment on UNIX or Linux, you can configure and modify data sources through the DataDirect ODBC Data Source Administrator for UNIX/Linux (the UNIX ODBC Administrator) using a driver Setup dialog box, as described in the following procedure. (See "Configuration Through the UNIX ODBC Administrator" for a detailed explanation of the Administrator.)

If you do not have a GUI environment, you can configure and modify data sources directly by editing the system information file and storing default connection values there. See "Configuration Through the System Information File" for detailed information about the specific steps necessary to configure a data source.

Table 16-1 lists driver connection string attributes that must be used in the system information file. Note that only the long name of the attribute can be used in the file.

Windows

On Windows, data sources are stored in the Windows Registry. You can configure and modify data sources through the ODBC Administrator using a driver Setup dialog box, as described in the following section.

Configuration

Default connection values are specified through the options on the tabs of the Setup dialog box. Connection string attributes that override these options have the same names as the options unless noted otherwise. The connection string attribute name does not have spaces between the words. For example, the option name Application Using Threads is equivalent to the connection string attribute name ApplicationUsingThreads.

NOTE: This book shows dialog box images that are specific to Windows. If you are using the drivers in the UNIX/Linux environments, the dialog box that you see may differ slightly from the Windows version. Windows-only and UNIX-only connection options are specifically noted by icons in the Setup dialog box descriptions.

By default, edit boxes and drop-down lists on the Setup dialog box are empty unless a specific default is otherwise noted.

To configure a Teradata data source:

  1. Start the ODBC Administrator:


    • On Windows, start the ODBC Administrator by selecting the icon from the DataDirect program group.


    • On UNIX, change to the install_dir/tools directory and, at a command prompt, enter:

      • odbcadmin

      where install_dir is the path to the product installation directory.

  2. Select a tab:
    • User DSN: If you are configuring an existing user data source, select the data source name and click Configure to display the driver Setup dialog box.

      • If you are configuring a new user data source, click Add to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.



    • System DSN: If you are configuring an existing system data source, select the data source name and click Configure to display the driver Setup dialog box.

      • If you are configuring a new system data source, click Add to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.

    • File DSN: If you are configuring an existing file data source, select the data source file and click Configure to display the driver Setup dialog box.

      • If you are configuring a new file data source, click Add to display a list of installed drivers. Select the driver and click Advanced to specify attributes; otherwise, click Next to proceed. Specify a name for the data source and click Next. Verify the data source information; then, click Finish to display the driver Setup dialog box.

      The General tab of the Setup dialog box appears by default.


      The General tab of the ODBC Teradata Driver Setup dialog box

      NOTE: The General tab displays only fields that are required for creating a data source. The fields on all other tabs are optional, unless noted otherwise.

  3. On the General tab, provide the following information; then, click Apply.

    4. Name: Type a string that identifies this Teradata data source configuration. An example would be Accounting or Teradata-Serv1.

    The equivalent connection string attribute is DataSourceName.

    Description: Type an optional long description of a data source name. For example, My Accounting Database or Teradata files on Server number 1.

    DBCName or Alias: Type the IP address or the alias name of the Teradata Server. Use either one or the other; do not type both. Using an IP address reduces the time it takes to connect, but if that address is not available at connection time, the connection fails and the driver does not attempt to fail over to another address.

    Using an alias name increases the time it takes to connect because the driver must search a local hosts file to resolve the name to the IP address information, but it allows the driver to try and connect to alternate IP addresses if the first address fails.

    If you use an alias name, you must have or create a local hosts file that contains the alias names. The alias name itself cannot be more than eight characters long. In the hosts file, you must create the alias name and associate it with IP addresses in the order in which you want the driver to attempt the connections, for example:

    167.56.78.1 (NCR5100COP1)

    167.56.78.2 (NCR5100COP2)

    167.56.78.3 (NCR5100COP3)

    where NCR5100 is the alias name and COPn, where n = 1, 2, 3, ..., 128, is the suffix that indicates the order of failover connection attempts to the IP addresses until one is successful. COP stands for communications processor; the COP suffix is not part of the eight-character name limit. You are allowed 128 COP entries per host.

    NOTE: Although you must specify a COP suffix to the alias name in the hosts file, you must not specify the suffix when you enter that name in the DBCName or Alias field of the Setup dialog box. Use only the alias name itself.

    The equivalent connection string attribute is DBCName.

    DBCName List: Type the IP addresses or the alias names that are to appear in the drop-down list of the Logon dialog box (see "Connecting to a Data Source Using a Logon Dialog Box" for a description). Separate the names with commas. The same restrictions apply as described for the DBCName or Alias option.

    Integrated Security: Select this check box to enable the user to connect to the database through Single Sign On (SSO) using one of the authentication mechanisms that support SSO.

    When this check box is not selected (the default), username and password are required.

    Security Mechanism: Select a value from the drop-down list to specify the authentication mechanism used for connections to the data source. The default is no mechanism.

    Valid values are:

    • KRB5-the driver uses Kerberos as the authentication mechanism on Windows clients working with Windows servers if the server is V2R6.0.
    • KRB5C-the driver uses Kerberos Compatibility as the authentication mechanism on Windows clients working with Windows servers if the server is pre-V2R6.0.
    • LDAP-the driver uses LDAP as the authentication mechanism.
    • NTLM-the driver uses NTLM as the authentication mechanism on Windows clients working with Windows servers if the server is V2R6.0.
    • NTLMC-the driver uses NTLM Compatibility as the authentication mechanism on Windows clients working with Windows servers if the server is pre-V2R6.0.
    • TD1-the driver uses Teradata 1 as the authentication mechanism.
    • TD2 (default)-the driver uses Teradata 2 as the authentication mechanism.

    In addition, the following options are displayed, based on the mechanism selected:

    • No mechanism selected
    • User name: Type a user name for the default Teradata database. If TeraSSO allows fully qualified user names, then the user name may contain a domain or realm, for example, {judy@linedata}. Values containing a character like @ must be enclosed in braces.
    • KRB5 and KRB5C
    • Authentication UserID: Type the Kerberos user ID.
    • Realm: Type the Kerberos domain. (The equivalent connection string attribute is AuthenticationDomain.)
    • LDAP
    • Authentication UserID: Type the LDAP user ID.
    • Realm: Type the LDAP domain. (The equivalent connection string attribute is AuthenticationDomain.)
    • TD User name: Type the Teradata user name.
    • Profile: Type the Teradata Profile. (The equivalent connection string attribute is TDProfile.)
    • Default Role: Type the Teradata Role. (The equivalent connection string attribute is TDRole.)
    • NTLM and NTLMC
    • Authentication UserID: Type the NTLM user ID.
    • Realm: Type the NTLM domain. (The equivalent connection string attribute is AuthenticationDomain.)
    • TD1 and TD2
    • Authentication UserID: Type the TD1 or TD2 user ID.

    Other parameters for the authentication mechanism can be entered in the Security Parameter field.

    Security Parameter: Type a string of characters that is to be regarded as a parameter to the authentication mechanism. The string is ignored by the ODBC driver and is passed on to the TeraSSO function that is called to set the authentication mechanism. The characters [] {} () , ; ? * = ! @ must be enclosed in curly braces.

    UserID: Type a user name for the default Teradata database.

    The user name is interpreted in the context of the authentication mechanism. If, for example, the authentication mechanism is NTLM, then the user name is assumed to be a Windows user name.

    If TeraSSO allows fully qualified user names, then the user name may contain a domain or realm, for example, {judy@linedata}. Values containing a character like @ must be enclosed in curly braces.

    SSO is indicated by the absence of a UserID and Password.

    The equivalent connection string attribute is UserID.

    Default Database: Type an optional default Teradata database associated with this data source.

    The entry may be overridden when specifying a new connection.

    The equivalent connection string attribute is Database.

    Account String: Enter an optional account string. For a complete description of account strings, refer to the Teradata Database Administration Guide.

    Session Character Set: Select a value from the drop-down list or enter another value to override the Teradata character set. The initial default is ASCII.

    The following character set names defined by Teradata appear in the drop-down list:

    • ASCII
    • UTF16 (valid only for V2R6.x servers)
    • LATIN1252_0A
    • LATIN9_0A
    • LATIN1_0A
    • Shift-JIS
    • EUC
    • BIG5
    • GB
    • NetworkKorean

    NOTE: These character sets must be installed on the database.

    The equivalent connection string attribute is CharacterSet.

  4. Click the Options tab to specify additional configuration options.


    5. The Options tab of the ODBC Teradata Driver Setup dialog box

    On this tab, provide any of the following information; then, click Apply.

    Report Codepage Conversion Errors: Select the method by which the driver handles code page conversion errors.

    When set to 0 - Ignore Errors (the default), if the driver encounters code page conversion errors (a character cannot be converted from one character set to another), it makes a substitution for each character that cannot be converted and does not return a warning or error.

    Error and Warning apply both to all ODBC API calls that could cause a conversion error and to all code page conversions to and from the database and to and from the application. The error or warning returned is Code page conversion error encountered. In the case of parameter data conversion errors, the driver adds the following sentence: Error in parameter x, where x is the parameter number. The standard rules for returning specific row and column errors for bulk operations still apply.

    When set to 1 - Return Error, if the driver encounters code page conversion errors, it returns an error instead of substituting 0x1A for unconverted characters.

    When set to 2 - Return Warning, if the driver encounters code page conversion errors, it substitutes 0x1A for each character that cannot be converted and returns a warning.

    Show Selectable Tables: Select this check box (the default) to use X views. When selected, SQLTables() andSQLProcedures() use dbc.tablesX and dbc.databasesX instead of dbc.tables and dbc.databases.

    Also, SQLColumns() and SQLProcedureColumns() use dbc.columnsX instead of dbc.columns. SqlStatistics() uses dbc.tablesizex instead of dbc.tablesize.

    The X tables only contain information that the user has permission to access. These tables are optional for Teradata, so verify that they exist.

    When this check box is not selected, SQLTables() and SQLProcedures() use dbc.tables and dbc.databases. Also, SQLColumns() and SQLProcedureColumns() use dbc.columns. SqlStatistics() uses dbc.tablesize.

    Enable Reconnect: Select this check box to enable the driver to reconnect after a system crash or reset is detected. When selected, the driver attempts to reconnect to the saved sessions; however, sessions cannot be reconnected until the Teradata system is available. After a session has been reconnected, applications can expect to receive error messages describing why the ODBC function failed, as well as a status report describing the post-recovery state.

    When this check box is not selected (the default), the driver does not attempt to reconnect to the saved sessions.

    Map Call Escape to Exec: Select this check box for the driver to consider the {CALL <name>(...)} statement as the SQL for MACRO execution and convert it to EXEC <name>(...).

    When this check box is not selected (the default), the driver does not convert {CALL <name>(...)} statements to EXEC, and considers them as CALL statements for Stored Procedure Execution.

    Enable LOBs: Select this check box (the default) to enforce native LOB data type mapping. This mapping is the default mapping if the Teradata Database has LOB support.

    • ODBC data type SQL_LONGVARBINARY is mapped to the Teradata BLOB feature.
    • ODBC data type SQL_LONGVARCHAR is mapped to the Teradata CLOB feature.

    When this check box is not selected, the driver retains backward compatibility. It is intended for applications without LOB support that are using a version of Teradata Database prior to V2R5.1.

    • ODBC data type SQL_LONGVARBINARY is mapped to the Teradata VARBYTE(32000) feature.
    • ODBC data type SQL_LONGVARCHAR is mapped to the Teradata LONG VARCHAR feature.

    Disable this option for better performance if your application does not send data to, or retrieve it from, LOB columns. You may receive an error if you disable this option and try to retrieve data from a LOB column.

    Enable Data Encryption: Select this check box to enable data encryption.

    When the check box is selected, the driver encrypts data and communicates with the Teradata gateway in an encrypted manner.

    NOTE: When using this option, be sure that the server is encryption capable.

    When the check box is not selected (the default), the driver does not encrypt data except for logon information.

    Enable Extended Statement Information: Select this check box to enable extended statement information.

    When the check box is selected, the driver queries the server to see if it supports the Statement Information parcel. If the server does support the Statement Information parcel, the driver requests the Statement Information parcel and enables auto-generated key retrieval and SQLDescribeParam support. This check box must be selected to enable the Return Generated Keys option.

    When the check box is cleared (the default), the driver does not attempt to expose auto-generated key retrieval or SQLDescribeParam.

    The equivalent connection string attribute is EnableExtendedStmtInfo.

  5. Optionally, click the Advanced tab to specify additional data source settings.


    6. The Advanced tab of the ODBC Teradata Driver Setup dialog box

    On this tab, provide any of the following optional information; then, click Apply.

    Maximum Response Buffer Size: Type a maximum response buffer size or use the default value of 8192. The maximum integer value is 65477.

    This option is used to limit the Teradata response buffer size for SQL requests. This value may be adjusted dynamically if Teradata cannot send a result within the defined size.

    If you are using a slow TCP/IP interface, such as PPP or SLIP, enter a smaller value. If you are expecting large result sets in a LAN environment, set a larger value.

    The equivalent connection string attribute is MaxRespSize.

    Port Number: Type a value for the port number of the Teradata database or use the default value of 1025.

    Login Timeout: Type an integer value for the number of seconds to wait when establishing a virtual circuit with Teradata for login, or use the default value of 20.

    ProcedureWithPrintStmt: Select N (No) or P (Print) from the drop-down list to deactivate or activate the print option when creating stored procedures. The default is N.

    The equivalent connection string attribute is PrintOption.



    IANAAppCodePage: For a list of valid values for this option, refer to "Values for the Attribute IANAAppCodePage" in the DataDirect Connect for ODBC and Connect XE for ODBC Reference. You need to specify a value for this option if your application is not Unicode-enabled and/or if your database character set is not Unicode (refer to "Internationalization, Localization, and Unicode" in the DataDirect Connect for ODBC and Connect XE for ODBC Reference for details). The value you specify must match the database character encoding and the system locale.

    Both this driver and the Driver Manager check for the value of IANAAppCodePage in the following order:

    • In the connection string
    • In the Data Source section of the system information file (odbc.ini)
    • In the ODBC section of the system information file (odbc.ini)

    If no IANAAppCodePage value is found, the driver uses the default value of 4 (ISO 8859-1 Latin-1).

    ProcedureWithSPLSource: Select Y (Yes) or N (No) from the drop-down list to specify SPL text when creating stored procedures.



    Translate: Click Translate to display the Select Translator dialog box, which lists the translators specified in the ODBC Translators section of the Registry. DataDirect provides a translator named OEM to ANSI that translates your data from the IBM PC character set to the ANSI character set.

    Select a translator; then, click OK to close this dialog box and perform the translation.

  6. At any point during the configuration process, you can click Test Connect to attempt to connect to the data source using the connection options specified in the driver Setup dialog box. A logon dialog box appears (see "Connecting to a Data Source Using a Logon Dialog Box" for details). Note that the information you enter in the logon dialog box during a test connect is not saved.
    • If the driver can connect, it releases the connection and displays a Connection Established message. Click OK.
    • If the driver cannot connect because of an incorrect environment or connection value, it displays an appropriate error message.

      • Verify that all required client software is properly installed. If it is not, you will see the message:

      Specified driver could not be loaded due to system error [xxx].

      Click OK.

  7. Click OK or Cancel. If you click OK, the values you have specified become the defaults when you connect to the data source. You can change these defaults by using this procedure to reconfigure your data source. You can override these defaults by connecting to the data source using a connection string with alternate values.