Connecting to a Data Source Using a Connection String

If you want to use a connection string for connecting to a database, or if your application requires it, you must specify either a DSN (data source name), a File DSN, or a DSN-less connection in the string. The difference is whether you use the DSN=, FILEDSN=, or the DRIVER= keyword in the connection string, as described in the ODBC specification. A DSN or FILEDSN connection string tells the driver where to find the default connection information. Optionally, you may specify attribute=value pairs in the connection string to override the default values stored in the data source.

The DSN connection string has the form:

DSN=data_source_name[;attribute=value[;attribute=value]...] 

The FILEDSN connection string has the form:

FILEDSN=filename.dsn[;attribute=value[;attribute=value]...] 

The DSN-less connection string specifies a driver instead of a data source. All connection information must be entered in the connection string because there is no data source storing the information.

The DSN-less connection string has the form:

DRIVER=[{]driver_name[}][;attribute=value[;attribute=value]
...] 

Table 10-1 gives the long and short names for each attribute, as well as a description. You can specify either long or short names in the connection string. Connection string attribute names are the same as the option names on the driver Setup dialog box tabs unless otherwise noted. The connection string attribute name does not have spaces between the words. For example, the connection string attribute name UseIntegratedSecurity is equivalent to the option name Use Integrated Security.

The defaults listed in the table are initial defaults that apply when no value is specified in either the data source definition or in the connection string. If you specified a value for the attribute when configuring the data source, that value is the default.

An example of a DSN connection string with overriding attribute values for Teradata is:

DSN=Teradata Tables;AS=User2;EnableDataEncryption=Yes 

A FILEDSN connection string is similar except for the initial keyword:

FILEDSN=Teradata.dsn;AS=User2;EnableDataEncryption=Yes 

A DSN-less connection string must provide all necessary connection information:

DRIVER=DataDirect 5.3 Teradata; 
DBCSN=123.456.78.90;UIS=YES 
 



  
 

Table 10-1.  Teradata Connection String Attributes 


  
    
 

Attribute


    
 

Description



  
    
 

AccountString (AS)


    
 

Allows you to use an optional account string. For a complete description of account strings, refer to the Teradata Database Administration Guide.



  
    
 

CharacterSet (CS)


    
 

Specifies a character set name that overrides the Teradata character set. The initial default is ASCII.

 

The following character set names are defined by Teradata:


 
ASCII
 
UTF16 (valid only for V2R6.0 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 Setup dialog box option is Session Character Set.



  
    
 

AuthenticationDomain (AD)


    
 

This attribute allows you to specify the domain appropriate to the selected authentication mechanism.

 

The equivalent Setup dialog box option is Realm.



  
    
 

AuthenticationPassword (AP)


    
 

Specifies the password for the Kerberos, LDAP, NTLM, and TD authentication mechanisms.



  
    
 

AuthenticationUserId (AUI)


    
 

Specifies the user ID for the Kerberos, LDAP, NTLM, and TD authentication mechanisms.



  
    
 

DataSourceName (DSN)


    
 

A string that identifies a Teradata data source configuration. Examples include Accounting or Teradata-Serv1.



  
    
 

DBCName (DBCN)


    
 

Provides the IP address or alias name of the Teradata server. Use either one or the other; do not use 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 for the DBCName. Use only the alias name itself.



  
    
 

Database (DB)


    
 

Provides the name of the default database associated with this data source. This entry is optional and may be overridden when specifying a new connection.



  
    
 

EnableDataEncryption (EDE)


    
 

EnableDataEncryption={Yes | No}. Determines whether data is encrypted.

 

When set to Yes, the driver encrypts data and communicates with the Teradata gateway in an encrypted manner.

 

When set to No (the initial default), the driver does not encrypt data except for logon information.

 

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



  
    
 

EnableExtendedStmtInfo (EESI)


    
 

EnableExtendedStmtInfo={Yes | No}. Determines whether the driver uses extended statement information.

 

When set to Yes, 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 attribute must be set to Yes to enable the ReturnGeneratedKeys attribute.

 

When set to No (the initial default), the driver does not attempt to expose auto-generated key retrieval or SQLDescribeParam.

 

The equivalent connection string attribute is Enable Extended Statement Information.



  
    
 

EnableLOBs (EL)


    
 

EnableLOBs={Yes | No}. Determines LOB data type mapping.

 

When set to Yes (the initial default), the driver enforces native LOB data type mapping. This mapping is the default 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 set to No, the driver retains backward compatibility. It is intended for use by 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.

 

Set this attribute to No 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 attribute and try to retrieve data from a LOB column.



  
    
 

EnableReconnect (ER)


    
 

EnableReconnect={Yes | No}. Determines whether the driver reconnects after a system crash or reset is detected.

 

When set to Yes, 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 set to No (the initial default), the driver does not attempt to reconnect the saved sessions.



  
    
 

IANAAppCodePage (IACP)

 




    
 

For a list of valid values for this attribute, refer to "Values for the Attribute IANAAppCodePage" in the DataDirect Connect64 for ODBC and Connect64 XE for ODBC Reference. You need to specify a value for this attribute 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 Connect64 for ODBC and Connect64 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).

 

 



  
    
 

IntegratedSecurity (IS)


    
 

IntegratedSecurity={Yes | No}. Determines whether the driver connects to the database through Single Sign On (SSO) using one of the authentication mechanisms that support SSO.

 

When set to Yes, the driver enables the user to connect to the database through SSO.

 

When set to No (the initial default), username and password are required.



  
    
 

LoginTimeout (LTO)


    
 

Defines a value for the number of seconds to wait for login when establishing a virtual circuit with Teradata for login. Enter an integer value greater than 0.

 

The initial default is 20.



  
    
 

MapCallEscapeToExec (MCETE)


    
 

MapCallEscapeToExec={Yes | No}. Determines whether the driver converts {CALL <name>(...)} statements to EXEC.

 

When set to No (the initial default), the driver does not convert {CALL <name>(...)} statements to EXEC, and considers the statements as CALL statements for Stored Procedure Execution.

 

When set to Yes, the driver considers the {CALL <name>(...)} statement as the SQL for MACRO execution, and converts the above statement to an EXEC <name>(...).



  
    
 

MaxRespSize (MRS)


    
 

Limits the Teradata response buffer size for SQL requests. This value may be adjusted dynamically if Teradata cannot send a result within the limited packet size defined.

 

The maximum integer value is 65477.

 

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 initial default is 8192.

 

The equivalent Setup dialog box option is Maximum Response Buffer Size.



  
    
 

Password (PWD)


    
 

Specifies the password that the application uses to connect to your Teradata database.



  
    
 

PortNumber (PORT)


    
 

Specifies the port number to use to access the Teradata database.

 

The initial default is 1025.



  
    
 

PrintOption (PO)


    
 

PrintOption={P | N}. Determines whether the driver specifies the print option when creating stored procedures.

 

When set to P, the print option is enabled when creating stored procedures.

 

When set to N (the initial default), the procedure is created with the no print option.

 

The equivalent Setup dialog box option is ProcedureWithPrintStmt.



  
    
 

ProcedureWithSplSource (PWSS)


    
 

ProcedureWithSplSource={Y | N}. Specifies the SPL option when creating stored procedures.

 

When set to Y (the initial default), the Procedure is created with SPL text.

 

When set to N, the Procedure is created without SPL text.



  
    
 

ReportCodePage
ConversionErrors (RCCE)


    
 

ReportCodePageConversionErrors={0 | 1 | 2}. Provides flexibility for the way in which the driver returns error or warning messages associated with code page conversion. 

 

When set to 0 (the initial 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.

 

Settings 1 and 2 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, if the driver encounters code page conversion errors, it returns an error instead of substituting 0x1A for unconverted characters.

 

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



  
    
 

SecurityMechanism (SECM)


    
 

SecurityMechanism={TD1 | TD2 | LDAP | KRB5 | KRB5C | NTLM | NTLMC}. Specifies the authentication mechanism used for connections to the data source.

 

Valid values are: 

 

TD1-the driver uses Teradata 1 as the authentication mechanism. 

 

TD2-the driver uses Teradata 2 as the authentication mechanism. 

 

LDAP-the driver uses LDAP as the authentication mechanism. 

 

KRB5-the driver uses Kerberos as the authentication mechanism on Windows clients working with Windows servers if the server is V2R6.0. KBR5C (Kerberos Compatibility) is used if the server is pre-V2R6.0.

 

Kerberos authentication is not available on UNIX or Linux with the initial release of 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.

 

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.



  
    
 

SecurityParameter (SP)


    
 

A string of characters that is to be regarded as a parameter to the authentication mechanism. The string is ignored by the 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.



  
    
 

ShowSelectableTables (SST)


    
 

ShowSelectableTables={Yes| No}. Determines whether SQLTables() and SQLProcedures() use dbc.tablesX and dbc.databasesX instead of dbc.tables and dbc.databases.

 

When set to Yes (the initial default), SQLTables() and SQLProcedures() 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 check to ensure they exist.

 

When set to No, SQLTables() and SQLProcedures() use dbc.tables and dbc.databases. Also, SQLColumns() and SQLProcedureColumns() use dbc.columns. SqlStatistics() uses dbc.tablesize.



  
    
 

TDRole (TDR)


    
 

Specifies the Teradata role for the LDAP authentication mechanism.

 

The equivalent Setup dialog box option is Default Role.



  
    
 

TDProfile (TDP)


    
 

Specifies the Teradata profile for the LDAP authentication mechanism.

 

The equivalent Setup dialog box option is Profile.



  
    
 

TDUserName (TDUN)


    
 

Specifies the Teradata user name for the LDAP authentication mechanism.



  
    
 

UserID (UID)


    
 

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 Username and Password.

 

The equivalent Setup dialog box option is User Name.