Copyright (c) 1994-2025, Teradata Corporation.
ALL RIGHTS RESERVED


                              Teradata ODBC Driver
                                      for
                                    Windows


Product: ODBC Driver For Teradata
Version: 20.00.00.38

Contents
    1.0 Introduction
    2.0 Release Content
    3.0 Requirements
    4.0 ODBC Software Installation/Uninstallation
    5.0 Configuration
    6.0 Sample ODBC Applications
    7.0 Restrictions
    8.0 Limitations/Issues
    9.0 Documentation
    10.0 Support
    Appendix A - ODBC Coexistence (32-bit and 64-bit)
    Appendix B - ODBC Integrated Directories
    Appendix C - Client Usage Note on SLOB transfer from Server to Client


1.0 Introduction

    This release of the ODBC driver for Teradata will support Teradata 20.00
    features in both Teradata mode and ANSI mode, and is backwards
    compatible with previous releases of Teradata as noted in section 3.2.

    The TTU has introduced a new TTU directory tree structure which
    has unified all the TTU products under a common TTU release directory.
    The ODBC installation package has taken steps to make this new tree
    structure transparent to the existing ODBC users.  Please refer Appendix
    A and B for recommended usage of ODBC paths and odbc.ini file.


2.0 Release Content

    2.1 Enhancements & New Features

        The following new features are introduced in Teradata ODBC Driver 20.00.00.38.
        
        * [SENTDO-3103] OIDC_REFRESH
 
          OIDC_REFRESH=True (the default) 
          specifies that the driver should use an available refresh token to 
          obtain a new token when the current token expires.
   
          OIDC_REFRESH=False 
          specifies that the driver should ignore an available refresh token.
 
          OIDC_REFRESH_PERCENT
 
          Specifies the OpenID Connect (OIDC) token minimum remaining lifetime 
          percentage for the driver to reuse a token. The driver will replace 
          a token when its remaining lifetime falls below this percentage.
     
          The default percentage of 15 specifies that the driver should reuse a 
          token for the first 85% of its lifetime, and replace it when its remaining
          lifetime falls below 15%.
   
          Specify 0 to turn off preemptive replacement and use the entire token lifetime.
          Specify 100 to never reuse a token and always obtain a new token.
          
    2.2 Resolved Issues

        The following issues were resolved in Teradata ODBC Driver 20.00.00.38.
          
        * [ODBC-19951][CS2994349] Additional fix: SQLColAttribute(..., SQL_COLUMN_CHARACTER_SET, ...) 
          does not return correct charset code.
   
        * [SENTDO-3085][CS2871415] When using a proxy server, the driver did not 
          properly track successful socket connections, resulting in repeated connection
          attempts. This issue was introduced in version 20.00.00.026 and fixed in 
          version 20.00.00.038.
 
        * [ODBC-20012][CS3163518] ClientTdHostName column in dbc.logonoffv shows IP 
          address rather than hostname when the hostname is tied to multiple IP addresses.
 
        * [SENTDO-3115][CS3199625] DSN trace log does not print the correct row count
          (which is a 64-bit integer) for SQLRowCount. It only shows the value of the 
          lower order 4 bytes instead of the full 8 bytes.

    2.3 Teradata issues that no longer occur

        * ODBC Driver reports incorrect ODBC version

        * ODBC driver v 14.10.0.6 and higher having high RAM utilization
          impacting MS Access 2010

        * SQL Assistant 16.10 Problem with ODBC driver and LOBs

        * ODBC Light Weight Parser fails to compile Stored Procedure when
          Stored Procedure has comments in body

        * ODBC Driver throws [Error 22003] [Numeric value out of range] using
          SQLBindParameter when the whole portion contains leading zeros and
          whole portion > (Precision - Scale) is inserted into DECIMAL column

    2.4 Known Issues

    The following are known issues that you may encounter due to limitations in
    the data source, the driver, or an application.

        * [SF 00392810] StatementInfo Parcel returns errors for TIME parameters.

           When using StatementInfo Parcel and stored procedures with a TIME
           parameter are called, the driver returns an error.

        * Some custom fields not supported for SQLGetDescField

          When calling SQLGetDescField, the driver does not support the
          SQL_DESC_TD_ACTIVITY_TYPE and SQL_DESC_TD_COST_ESTIMATE custom header
          description fields.

        * Catalog functions always return ODBC 3.x column names.

          For catalog functions, the driver returns the ODBC 3.x column names rather
          than ODBC 2.x column names, even in an ODBC 2.x environment.

        * The SQL_ATTR_ROWS_FETCHED_PTR statement attribute cannot be set properly.

          You can set a value by calling SQLSetStmtAttr(SQL_ATTR_ROWS_FETCHED_PTR),
          but the value is reset after you close the cursor. The value that you set
          does not persist.

        * In specific cases, during INSERT operations that require the data to be
          truncated, there is no message indicating that truncation has occurred.

          This behavior occurs when:
          - The Session Mode option (the SessionMode property) is set to Teradata,
          - The driver inserts data that is too large for the target column.

          The database truncates the data to fit, but the message indicating that
          truncation has occurred is not returned. The driver expects the database
          to report the truncation. However, when Session Mode is set to Teradata,
          the database does not return the truncation message.

    2.5 Version History

        2.5.1
            Version 20.00.00.35 Resolved Issues

            * [ODBC-19785] The DSN option useLocalCatalog option controls whether the 
              driver includes catalog information in query results and metadata.
          
              When set to Y, the driver includes the catalog name (for example, TD_LOCAL) 
              in results returned to client applications.
          
              When set to N, catalog information is not included.
          
              This option allows users to choose whether their applications display 
              catalog details when connecting through ODBC.
          
            * [ODBC-19929] File descriptors were not all closed which can result in 
              running out of file descriptors and being unable to open new files causing
              the driver to crash.
          
            * [ODBC-19951] The first of multiple result sets generated by array parameter
              binding returns correct data while subsequent result sets contain extra 
              trailing spaces in character columns, even when the table columns are 
              defined with fixed CHAR lengths.
              
            * [ODBC-19955] Resolved an issue where the driver did not route connections
              through the proxy when HTTPS_PROXY was provided.
              
            * [ODBC-19957] The ODBC driver cannot connect to the database when Gateway 
              mode is Require and SSLMode is Allow and DBCName is an URL with two cops.
          
            * [CS3113045] TD ODBC driver crashes when DBCName is a FQDN (Fully Qualified 
              Domain Name) and password is provided through TDWallet.
          
            Version 20.00.00.30 Resolved Issues

            * [ODBC-19860] TPT and ODBC co-existing in the same process may result 
              in program crash in unix platforms.
   
            * [ODBC-19922] Column LogonSource of dbc.logonoffv table should include 
              the driver name ("ODBC") and driver version number.
   
            * [ODBC-19927] Data retrieval (SELECT queries) from database is 10 times 
              slower when connected to TLS (443) port.
   
            * [ODBC-19928] The driver fails to connect when using SSLMode Verify-CA 
              and Verify-Full.
              
            Version 20.00.00.28 Resolved Issues

            * [ODBC-19864] When the user selects ClientTdHostName on logonoffv, the
              driver returns only the IP address, without the port number.
          
            * [ODBC-19867] The driver fails to display Chinese characters in Teradata
              SQL Assistant.
          
            * [ODBC-19901] When SSL Mode is set to 'Require', SQL Assistant and other
              GUI-based login applications experience login failures.
   
            * [ODBC-19923] When user name or password is incorrect, the driver does not 
              generate error immediately, it waits until connection timed out.
              
            Version 20.00.00.26 Resolved Issues

            * [ODBC-19861][CS2739363] Long connection latency.

            * [ODBC-19796] LibCurl does not support Secure Transport on TLS 1.3.

            * [ODBC-19866][CS2755465][CS2813893] Username, or UID not allowed when using TD2 mechanism  
              in multiple thread.
         
            Version 20.00.00.24 Resolved Issues

            * [ODBC-19714] OIDC_LOGIN_HINT, OIDC_SCOPE and TOKEN_UID_CLAIM added in Token memory cache.
              The driver now added keys OIDC_LOGIN_HINT, OIDC_SCOPE and TOKEN_UID_CLAIM 
              in the token memory cache. For more information, see the Installation and Configuration Guide.

            * [ODBC-19796] The driver supports connecting to Vantage with TLS 1.3.
              The "SSL Protocol" setting that allows the user to select the SSL Protocol version they use to connect 
              to the database now supports TLS 1.3 in addition to the already existing TLS 1.2.

            * [ODBC-19862] Driver crashes when logging hex dump of received socket data.
              The driver will crash if
                a. Connection is using TLS; and
                b. Socket recv() failed; and
                c. Logging is set at TRACE (6) level.

            Version 20.00.00.22 Resolved Issues

            * [ODBC-19714] Multiple Identities support

             The driver now supports multiple identities OIDC_LOGIN_HINT,
             OIDC_PROMPT, and OIDC_TOKEN_CACHE in the token memory cache. For more
             information, see the Installation and Configuration Guide.

            * [ODBC-19826] When TLS sockets fail, the driver does not catch the
             SIGPIPE signal to prevent the application from crashing.

             This issue is resolved by the driver; however, if the application
             prefers to handle this signal, it can set the TD_NO_SIGPIPE_CATCH
             environment variable.

            Version 20.00.00.21 Resolved Issues

            * [ODBC-19810] Enhanced proxy server Windows support
             On Windows, the driver can now read from HTTP_PROXY, HTTPS_PROXY, and
             ALL_PROXY settings based on URI protocol. If URI protocol is:http://,
             HTTP_PROXY is used, if URI protocol is https://, HTTPS_PROXY is used, if
             both are unavailable, ALL_PROXY is used.

            * [ODBC-19809] When SSLMode is set to Allow and both TDMST and HTTPS ports
             are available, the driver uses the HTTPS port instead of returning an
             error message.

            Version 20.00.00.19 Resolved Issues
            * [ODBC-19714] OIDC Token Memory Cache support
            The driver can now reuse credentials and log in multiple times for
            short-lived connections without refreshing tokens. To do this, set the
            Disable Token Cache checkbox to Yes. For more information, see the
            Installation and Configuration Guide.

            * [CS2267639] Enhanced data encryption support
            You can now update the data encryption value from the connection string key
            UseDataEncryption to ClientAttributeEx in the database. For more
            information, see the Installation and Configuration Guide.

            * [CS2228944] In some cases, when using the EXTERNALBROWSER mechanism, the
            driver does not connect because a socket operation is blocking it.

            * [CS2377493] If the SSO Browser window is cancelled or closed before
            connecting to the database, the driver hangs.

            * [ODBC-19782] When SSLCRC is set to Require and either the OCSP certificate
            or the OCSP URI is unknown, the connection does not return to CRL.

            Version 20.00.00.18 Resolved Issues
            * [ODBC-19735] The PERIOD(TIME(n)) does not get inserted when the
            DecimalDigits of SQLBindParameter is incorrect.

            * [ODBC-19756] When using OCSP/CRL feature and SSLMode is Verify-Full, running
            "SELECT ClientAttributesEx FROM DBC.SessionInfoV" query does not return the
            correct certificate status (CERTSTATUS).

            * [ODBC-19758] When running a SELECT query with parameters, if the database
            does not figure out the type of an integral column (like INT or BIGINT),
            the driver wrongly assumes it is unsigned, causing a 'numeric value out
            of range' error.

            * [CS2429031] When the revocation server is unreachable and SSLCRC=Allow,
            driver returns "TD CURL failed to fetch URL" error.

            * [CS2398641] When the OCSP URI is missing in the database certificate, the
            driver continues to make OCSP requests.

            * [ODBC-19771] When the username and password fields in the ODBC
            Administrator's DSN are empty, SQLA terminates unexpectedly.

            * [ODBC-19713] Extended ASCII characters (0x80 and above) stored in a CHAR(1)
            column were not converted to UTF8 in 17.20.00.015, 20.00.00.001 and newer
            drivers when client program has "#define UNICODE" defined and environment
            variable LC_ALL is set to "C".

            Version 20.00.00.15 Resolved Issues
            * [ODBC-19754] When OCSP stapling status is unknown and SSLCRC setting is Require,
            the driver continues to verify the intermediate CA certificates instead of
            generating an error and the connection fails.

            * [ODBC-19755] When using OCSP feature with SSLCRC set to Require,
            OCSP verification fails and the driver disconnects.

            Version 20.00.00.14 Resolved Issues
            * [ODBC-19659] Driver add MD5 function calls which is non-FIPS-compliant
              to verify FIPS module works driver start up.

            * [SF 04902668] Authentication window does not close automatically after
              logging on with Ping SSO.

            Version 20.00.00.12 Resolved Issues
            * [SF 04774884] The 'abort' button in SQL Assistant does not work.

            * [SF 04836488] When converting time that is stored as a float in the database,
              the driver converts hour, minute, second, but not fractional seconds.

            Version 20.00.00.10 Resolved Issues
            * [TTUGEN-774] TtuFips: install.sh fails during upgrade

            Version 20.00.00.09 Resolved Issues
            * [SF 04622691] Federal Information Processing Standard (FIPS) support
              The driver uses the OpenSSL FIPS Provider module to make connections if
              the environment TTU_FIPS_ENABLE is set to the value "1".

            * Security Updates

            * [SF 04749726] Expired password issue with SQLA
              The driver does not properly update the password in the OutConnectionString
              return value of a SQLDriverConnect() call when the password has expired in the
              database, or an administrator has forced a password change.

            * [SF 04794798] Partially hidden button on Windows UI
              In the DSN Setup in ODBC Data Source Administrator of Windows, the Mechanism
              Options button is partially obscured if the pointer hovers over
              "Use Integrated Security".

            Version 20.00.00.08 Resolved Issues
            * [SF 04622702] Client Credentials authentication

              You can now authenticate your connection with Client Credentials, also
              known as Bearer Flow. To do this, from the Mechanism drop-down list select
              BEARER (set the MechanismName property to BEARER).

            * [SF 04622695] OIDC Device Authorization Grant authentication

              You can now authenticate your connection with OIDC Device Authorization
              Grant, also known as OIDC Device Flow. To do this, from the Mechanism
              drop-down list select CODE (set the MechanismName property to CODE).

            * [SF 4760041] When the client ID or scope value contains a space and it is
              not URL encoded, the driver truncates the value.

            * [SF 04648364] In some cases, when connecting to the Teradata database using
              SSLMode Prefer or Allow, the driver connects to an incorrect port.

            * [SF 04704277] When retrieving BIG5 characters (two bytes each) from a
              character set LATIN table's VARCHAR column that has odd number of bytes
              (e.g. VARCHAR(25)), the first character of the next row is corrupted.

            Version 20.00.00.06 Resolved Issues
            * [SF 04454094] When a table contains a CLOB column size greater than
              2,097,088,000 bytes, .NET System.Data.Odbc.OdbcDataReader.GetSchemaTable()
              returns arithmetic overflow exception.


            Version 20.00.00.05 Resolved Issues
             * [SF 04454094] When a table contains a CLOB column size greater than
               2,097,088,000 bytes, .NET System.Data.Odbc.OdbcDataReader.GetSchemaTable()
               returns arithmetic overflow exception.

            Version 20.00.00.04 Resolved Issues
             * [SF 00392841] Updated macOS help support

               The driver now uses the following Teradata web-based help system to
               display help requested from macOS ODBC Administrator: docs.teradata.com.

             * [SF 03621304] Updated proxy server Windows support

               On Windows, the UI has been updated with support for the Proxy Server
               feature. For more information, see the Installation and Configuration
               Guide.

             * [SF 03589774] When a table is created with multiple primary index columns,
               SQLSpecialColumns() returns only one instead of all primary indexed
               columns.

             * [SF 03603504] In some cases, the driver attempts to conduct TLS
               handshake while connected to TDMST (Legacy) port.

             * [SF 03623883] On macOS 10.14 and 10.15, the driver does not load.

             * [SF 03625371] The driver does not log the Linux ARM architecture
               correctly in the driver log.

             * [SF 03625393] The driver does not log the macOS ARM architecture
               correctly in the driver log.

             * [SF 03630566] On macOS, tdxodbc does not run if iodbc libraries are not
               installed.

            Version 20.00.00.03 Resolved Issues
            * [SF 00392841] Updated help support

              The driver now uses the following Teradata web-based help system to
              display help requested from Windows ODBC Administrator: docs.teradata.com.

            * [SF 03554602] Linux ARM support

              On Linux, the driver now supports ARM architecture.

            * [SF 00426147] Updated HTTP proxy server support

              You can now connect to a database through the HTTP proxy server. For more
              information, see the "ODBC User Guide".

            * [SF 03559421] Updated default login timeout

              The new default login timeout is 60 seconds. Previously, it was 20 seconds.

            * [SF 03467396] In some cases, on slow network environments, the driver
              does not establish an SSL connection.

            * [SF 03559421] Updated default login timeout

              The new default login timeout is 60 seconds. Previously, it was 20 seconds.

            Version 20.00.00.02 Resolved Issues
            * [SF 03500448] On macOS, the advanced options was hidden incorrectly.

            Version 20.00.00.01 Resolved Issues
            * [SF 02833533] The driver now prints the TeraSSO & TeraGSS version
              information in the driver trace log.

            * [SF 02659180] The driver now supports the Diffie-Hellman Bypass feature
              if the driver uses TLS connection and the Teradata database has this feature
              enabled. This feature improves login time performance when TLS connection is used.

            * [SF 02838903] In some cases, the driver can get stuck when using
              Federate authentication during connection to the Teradata database.

            * [SF 03061946] When using Federate authentication, the driver reads the
              custom scope parameter from the GTW parcel but only parses out the first
              entry in that parameter.

            * [SF 03310872] When inserting a parameterized array of DATE type and the
              first record is null, the database returns the following error message:
              "[Simba][ODBC Teradata Driver][Teradata Database](-2673)The source parcel
              length does not match data that was defined.".

            * [SF 03319679] In some cases, after a transaction finishes, the driver
              returns a "Response limit exceeded" error message.

            * [SF 03319679] The driver cannot locate the appropriate error message file
              and generates an incorrect error message.

            Version 20.00.00.00 Resolved Issues

            * [SF 02801276] Updated macOS support

            On macOS, the driver is now a Universal driver that natively supports
            Apple Silicon and is compatible with macOS versions 10.14 and later. macOS
            versions earlier than 10.14 are not supported by the driver due to
            library incompatibilities and Apple's deprecated support for older macOS
            versions. For security best practices, it is suggested to keep both the
            driver and OS updated.

            * [SF 00423130] When retrieving multiple SLOB columns with redrive turned on,
            the driver returns an error.

            * [SF 00426364] When inserting a parameterized array of DECIMAL type
            containing null values, the database returns a "Invalid data length for
            VarChar, VarByte, VARGRAPHIC or NUMBER" error message.

            * [SF 02801214] In some cases, the driver fails to connect to the server.

            This issue has been resolved. The driver now attempts to connect
            multiple times until a successful connection is found or login timeout is
            reached.

            * [SF 02801071] When the Teradata Gateway TLS setting is set to enable and
            PCLGTWCONFIGPORTS returns 1 for both TLS and Legacy ports, the driver
            connects to the fallback port.

            This issue has been resolved. The driver now returns an error message
            indicating that the preferred port is enabled, but the driver fails to
            connect to it.


3.0 Requirements

    3.1 System

            Microsoft Windows Server 2012(including R2)
            Microsoft Windows Server 2016
            Microsoft Windows Server 2019
            Microsoft Windows 8.x
            Microsoft Windows 10

    3.2 Supported Teradata Database versions

            Teradata Database 16.10
            Teradata Database 16.20
            Teradata Database 17.00
            Teradata Database 17.10
            Teradata Database 17.20
            Teradata Database 20.00

    3.3 ODBC Dependencies

    3.4 ODBC Application development

        When developing an ODBC C++ application, the developer is encouraged to
        use the recommended compiler Visual Studio 2019 VC++.

        The ODBC 20.00 release has deployed tdsql.h which contains definitions to
        Teradata specific attributes for the ODBC connection, statement and
        descriptor objects. These are extensions to the ODBC standard.  The
        tdsql.h file can be found in the install directory of the
        ODBC Driver for Teradata.  For example,

             C:\Program Files\Teradata\Client\20.00\ODBC Driver for Teradata


4.0 ODBC Software Installation/Uninstallation

    Please use TTU/ODBC install suite wizard to install/unintall.  When ODBC Driver is selected,
    the install suite automatically installs dependendent packages Teradata ICU.

    Installing individual MSI's outside of the Suite is not supported and the product will not work.


5.0 Configuration

    For first time users, one or more DSNs will need to be configured.  This is
    done through the ODBC Administrator. There is an icon for the ODBC
    Administrator in the ODBC driver's program folder.

    5.1 ODBC and ODBCINST INI Configuration

    5.2 DSN Configuration

        After starting the ODBC Administrator, click on the Add... button to
        configure a new data source.  This will bring up a dialog with the names
        of all installed ODBC drivers. Select Teradata and then continue.
        (You may use the Help button to get information on how the various fields
         are used.)

        Note: Your TCP/IP must be functional through Microsoft Windows(r) in
              order to fully configure data sources.


        5.2.1 ODBC Driver Setup for Teradata Database (Dialog Box)

        Fill in the information in the first ODBC Teradata Driver Setup dialog
        box.

        1. A data source name is mapped to a combination of a Teradata system
           running Teradata Database such as (but not limited to) a 34xx, 35xx,
           3600, 43xx, 44xx, 47xx, 51xx and so on, and a default database within
           that system.

        2. One can optionally configure multiple data source entries for the same
           Teradata system to associate different user logons, default databases,
           or options. Data Source

        3. Description is an optional comment field.

        4. Enter the alias name or IP address of the Teradata Server you will be
           using. If you are using the alias name of a server, you must either be
           using Domain Name Services, or a local hosts file to resolve the named
           alias. Setup will automatically add "COPn" (where n is a number) to
           the name in order to search for other host IP addresses with similar
           aliases, following the standard Teradata naming conventions. Multiple
           server names may be entered by putting entries on separate lines.

        5. The ODBC Driver Setup for Teradata Database dialog contains a new
           check box in the Teradata Server Info section. If this box is checked,
           the alias names entered will not be resolved to IP addresses at setup
           time. Instead the driver will resolve the names at connect time.
           Entering user information is optional.

        6. IMPORTANT: Note that although the password is encrypted, storing a
           password is never 100% secure.


        5.2.2 Teradata ODBC Driver Options (Dialog Box)

        The first optional dialog box which contains options that are most useful.


        5.2.3 Teradata ODBC Driver Advanced Options (Dialog Box)

        The second optional dialog box, Advanced, contains options that are very
        risky to change; if you do not understand the effects of changing these
        default settings, you should not make any changes.


6.0 Sample ODBC Applications


7.0 Restrictions

    When calling SQLBindParameter with a data type that contains fractional seconds,
    you must set the DecimalDigit to 6 as that is what the driver will truncate to.
    Previous to 16.20, this could be any number between 0-6 with the same result
    as if you were to set it to 6, but this is incorrect and no longer supported.

    Additional restrictions are listed in the ODBC Driver for Teradata User Guide

    7.1 ODBC restrictions

    7.2 Binary Compatibilites


8.0 Limitations/Issues

    8.1 Japanese Online Help

        In place of the Japanese Online Help, the ODBC 14.0 GCA release will deploy the English version.
        When the Japanese Online Help becomes available, it will be included in a subsequent ODBC 14.0.0.x
        EFIX.



9.0 Documentation

    1) ODBC Driver for Teradata User Guide
    2) www.info.teradata.com


10.0 Support

    10.1 Contact Information

         Customers with support contracts may report problems with the ODBC Driver to
         Teradata Customer Services either by phone via the regional support center or
         on the web via Teradata@YourSevices
             www.teradata.com

         Contact your Teradata Customer Services Representative for details.


Appendix A - ODBC Driver Folder Tree Structure

    The ODBC driver folder tree structure is shown in the diagram below.

        C:\Program Files\Teradata\Client\20.00\ODBC Driver for Teradata\
                                                   Help
                                                   Samples
                                                   ErrorMessages
                                                   Readme.txt
                                                   tdodbcdsn.vbs
                                                   tdsql.h


Appendix B - DSN Migration

    For explicit DSN Migration , from a DOS window, the user will change directories
    to where the tdodbcdsn.vbs is located and use the below commandline to change all
    Teradata DSN's to the present installed version.

    For 32bit Package : cscript tdodbcdsn.vbs 32bit
    For 64bit Package : cscript tdodbcdsn.vbs 64bit

    For Backward DSN Migration, to restore the previous Teradata DSN driver
    values , change directories to where the tdodbcdsn.vbs is available and use
    the below command line .

    Note : The below command only restores the DSN values which are available
           at the time of installation.

    cscript tdodbcdsn.vbs %SYSTEMROOT%\temp\Teradata_DSN_Migration_[type]_[timestamp].txt



Appendix c - New Post TTU 16.20 GCA Features
             ==============================


Appendix D - Client Usage Note on SLOB transfer from Server to Client
             ========================================================

                    --- Teradata ODBC Driver 16.10 and later ---

    Terminology:

        LOB:    Large OBject

        CLOB:   Character LOB (a data type)

        BLOB:   Binary LOB (a data type)

        SLOB:   Smart LOB (a transport mechanism)

        DLOB:   Deferred LOB (a transport mechanism)

        Response Message:
                A message containing multiple data items returned from the
                database to the driver.

        Maximum Response Message Bytes (MaxRespSize):
                The maximum size of a response message; configurable by
                the client, up to a maximum of 16 MB.

        Maximum Single LOB Bytes (MaxSingleLOBBytes):
                The maximum size of any one SLOB (CLOB, BLOB) item. Configurable
                by the client. Default is 0.

        Total LOB Bytes Per Row (MaxTotalLOBBytesPerRow):
                The maximum size of all LOB bytes per row. Configurable by
                the client. Default is 0.

    In previous versions of Teradata ODBC Driver, non-LOB data are retrieved
    from the database to the driver in-line. Each LOB data item requires a
    round trip to the database for retrieval. This is not very efficient if
    the LOB data items are relatively small.

    Starting in TD ODBC Driver 16.10, LOB data can be retrieved from the
    database to the driver in-line, if certain size restrictions are met.

    This note describes how the client can configure the driver to return LOB
    data in-line.

    When the driver retrieves a LOB data item via an additional round trip,
    the mechanism is called deferred LOB (DLOB).

    When the database returns a LOB item in-line, the mechanism is called
    Smart LOB (SLOB).

    The client has no way of knowing the actual mechanism for any LOB item
    transfer. The client may experience better or worse performance.

    When either MaxSingleLOBBytes or MaxTotalLOBBytesPerRow is 0, the database
    will not send any SLOBs; all LOBs are sent as DLOB.

    Currently, MaxSingleLOBBytes defaults to 4000 and MaxTotalLOBBytesPerRow
    defaults to 65536.

    Users can configure their preferred MaxSingleLOBBytes and
    MaxTotalLOBBytesPerRow values using the following methods.

    1. In Windows,
        a. start up Microsoft ODBC Administrator,
        b. select the appropriate data source (in User DSN tab or System DSN tab),
        c. click [Configure…], click [Options>>], click [Advanced].
        d. Enter preferred values of MaxResponseBufferSize, MaxSingleLOBBytes
           and MaxTotalLOBBytesPerRow in the appropriate text boxes.

    2.   In UNIX, edit the odbc.ini file. Add or change the following values.

                [my_test_dsn]
                MaxRespSize            = 10000000
                MaxSingleLOBBytes      =  1000000
                MaxTotalLOBBytesPerRow = 10000000

    3.   Add to the connection string.

                MaxRespSize=10000000;MaxSingleLOBBytes=1000000;
                MaxTotalLOBBytesPerRow=10000000

    When both MaxSingleLOBBytes and MaxTotalLOBBytesPerRow are greater than 0,
    then the database will respond as follows:

       If ((the size of current LOB) < (MaxSingleLOBBytes)
            AND
           ((the current cumulative total size of SLOBs) < (MaxTotalLOBBytesPerRow))
          )
       then the current LOB will be sent as SLOB,
       otherwise the current LOB will be sent as DLOB.

    To maximize data transfer efficiency (from database to driver to client),
    the following should be noted:

    SLOB items are returned in order of column numbers and may span several
    response messages. The driver only keeps a maximum of two response
    messages at any one time. For example, when the driver is processing
    messages 2 and 3, the SLOB data that was originally in message 1 is
    destroyed and is no longer available.

    It is advisable (for efficiency reasons) to access SLOB data items
    sequentially (using SQLBindCol(), or SQLGetData(col i) where i is
    increasing. For example,

        SQLGetData(col 2) (SLOB is in response message 1)
        SQLGetData(col 8) (SLOB is in response message 3)
        SQLGetData(col 9) (SLOB is in response message 3)

    When retrieving LOB data randomly, the data may not be copied from SLOB
    data, but through the less efficient deferred LOB (DLOB) method. For
    example:

        SQLGetData(col 8) (SLOB is in response message 3)
        SQLGetData(col 9) (SLOB is in response message 3)
        SQLGetData(col 2) (SLOB was in response message 1, already deleted)

    If SLOBs from columns 8 and 9 resides in the same response message, they
    will be copied from the SLOBs to the client. If SLOB from col2 resides in
    a previous response message, the message is probably destroyed after
    accessing columns 8 and 9; hence the LOB from col 2 is retrieved as
    deferred LOB (DLOB) (even though it was already retrieved once before as
    SLOB and discarded).

    Note that LOB data items are always retrievable in any sequence; they are
    either retrieved as SLOB or DLOB. SLOB retrieval through sequential
    access is more efficient than DLOB retrieval through random access.

    A client has the ability to decide (to some degree) which LOB columns are
    to be retrieved as SLOB while others are to be retrieved on-demand as
    DLOB. There is no mechanism to advise the database to send LOB data of
    specific columns as SLOBs. The client configurable parameter
    MaxSingleLOBBytes is a surrogate method to achieve this. For example, if
    a database contains two columns: photo thumbnails of no more than 1 MB
    each, and high definition photos that are much greater 1 MB each. Let us
    say a (contrived) client application will only process the high definition
    photos if the thumbnail contains blue sky. The client should configure
    MaxSingleLOBBytes as 1 MB. So thumbnails are always retrieved as SLOB and
    high definition photos are retrieved as DLOB, and only if needed.

    Another example. If we know ahead of time that columns 1 to 3 are always
    1 MB or less and we want to send these as SLOB always; and columns 4 to 10
    are 10 MB each and we never want to send these as SLOB. Then we can
    configure the following:

        MaxRespSize            =  3100000
        MaxSingleLOBBytes      =  1000000  // each SLOB
        MaxTotalLOBBytesPerRow =  3000000  // sum of all SLOBs

    The MaxRespSize should be big enough to contain all SLOB data plus all
    non-LOB data (such as integer, varchar, deferred LOB locator information)
    of the row.

    The value of MaxRespSize can be tuned to meet application data processing
    efficiency. If the data columns are independent of each other and
    parallel processing is possible, then MaxRespSize can be set to be less
    than the sum of the sizes of all SLOB columns (so that SLOBs are sent back
    in several response messages). If all the data from all the columns are
    needed by the application before processing can begin, then we want all
    SLOBs to be sent in one response message; in this case we want to set
    MaxRespSize to be (at least) the sum of the sizes of all SLOB columns (up
    to 16 MB).

    If MaxTotalLOBBytesPerRow is less than or equal to the MaxRespSize, then
    the driver will always cache all SLOB columns and non-LOB columns; thus an
    application can randomly access the data even though the recommendation is
    to retrieve the data in sequential access mode.

