Specifying Data Source Names to Identify TimesTen Databases

When you connect from an application, you use a Data Source Name (DSN) to uniquely identify the particular TimesTen database to which you want to connect.

Specifically, a DSN is a character-string name that identifies a TimesTen database and a collection of connection attributes that are to be used when connecting to the database. On Windows, the DSN also specifies the ODBC driver to be used to access the database.

In TimesTen Classic, you can also define a default DSN that can be used when a user or an application either does not specify a DSN or specifies a DSN that is not defined in the odbc.ini file at connect time. See Setting Up a Default DSN in TimesTen Classic.

Note:

If a user tries to use a DSN that has connection attributes for which they do not have privileges, such as first connection attributes, they receive an error. For more information on first connection attribute privileges, see Connection Attributes in the Oracle TimesTen In-Memory Database Reference.

Even though the DSN uniquely identifies a TimesTen database, a database can be referenced by multiple DSNs. The difference between each of these unique DSNs is in the specification of the connection attributes to the database. This provides convenient names to different connection configurations for a single database.

Note:

According to the ODBC standard, when an attribute occurs multiple times in a connection string, the first value specified is used, not the last value.

A DSN has the following characteristics:

• Its maximum length is 32 characters.

• It is case insensitive.

• It is composed of ASCII characters except for the following: ( ) [ ] { } , ; ? * = ! @ \ /

• TimesTen does not recommend the use of spaces as part of the DSN. If a DSN contains a space, some TimesTen utilities truncate the DSN at the point where they encounter the space. In addition, a DSN cannot start or end with a space, or consist solely of spaces.

The following sections describe how to configure and manage your DSNs:

• Overview of User and System DSNs

• Defining DSNs for Direct or Client/Server Connections

• Connection Attributes for Data Manager DSNs or Server DSNs

Overview of User and System DSNs

DSNs are resolved using a two-tiered naming system, where TimesTen first tries to resolve the DSN within the defined user DSNs and secondly within the defined system DSNs.

• A user DSN can be used only by the user who created the DSN.

  • On Windows, user DSNs are defined from the User DSN tab of the ODBC Data Source Administrator.

  • For TimesTen Classic on Linux and UNIX, define user DSNs in the user odbc.ini file. TimesTen locates this file by first finding if a file is specified by the ODBCINI environment variable. If not, TimesTen locates the $HOME/.odbc.ini file.

    TimesTen Classic supports data sources for both TimesTen Data Manager driver and the TimesTen Client driver in the .odbc.ini file.

  • For TimesTen Scaleout, define user DSNs within the appropriate database definitions and connectables. See Managing a Database in the Oracle TimesTen In-Memory Database Scaleout User's Guide.

  Although a user DSN is private to the user who created it, it is only the DSN, consisting of the character-string name and its attributes, that is private. The underlying database can be referenced by other users' user DSNs or by system DSNs.

• A system DSN can be used by any user on the system on which the system DSN is defined to connect to the TimesTen database.

  • On Windows, system DSNs are defined from the System DSN tab of the ODBC Data Source Administrator.

  • For TimesTen Classic on Linux and UNIX, system DSNs are defined in the sys.odbc.ini file, which is referred to as the system odbc.ini file.

    TimesTen locates the system DSN file in the following order:

    • The file is located if it is specified by the SYSODBCINI environment variable.

    • In an installation, the file is located in timesten_home/conf/sys.odbc.ini.

    • If not found in any of these locations, TimesTen looks on the system for the /etc/odbc.ini file.

  • For TimesTen Scaleout, create system DSNs within the appropriate database definitions and connectables. See Managing a Database in the Oracle TimesTen In-Memory Database Scaleout User's Guide.

Defining DSNs for Direct or Client/Server Connections

DSNs are created to uniquely identify a database, whether local or remote.

The following explains the type of DSN to use for either a direct or client/server connection:

• Data Manager DSN: A DSN that specifies a local database on a Linux or UNIX host. You can use either the production version or debug version of the TimesTen Data Manager driver.

  A Data Manager DSN refers to a database using a path name and a file name prefix. The database path name specifies the directory location of the database and the prefix for the database, such as /disk1/databases/AdminDS.

  Note:

  This path name and prefix does not define a file name, but the name of the directory where the database is located and the prefix for all database files. The actual files used by the database append file suffixes, such as /disk1/databases/AdminDS.ds0.

  A Data Manager DSN that refers to a given TimesTen database must be defined on the same system on which the database resides. If multiple Data Manager DSNs refer to the same database, they must all use exactly the same database path name, even if some other path name identifies the same location. For example, you cannot use a symbolic link to refer to the database in one DSN and the actual path name in another DSN.

• Client DSN: A client DSN specifies a remote database and uses the TimesTen client. A client DSN refers to a TimesTen database indirectly by specifying a hostname, DSN pair, where the hostname represents the server system on which TimesTen server is running and the DSN refers to a server DSN that specifies the TimesTen database on the server host.

• Server DSN: A server DSN is always defined as a system DSN and is defined on the server system for each database on that server that can be accessed by client applications. The format and attributes of a server DSN are very similar to those of a Data Manager DSN.

On Linux and UNIX, all user DSNs including both client DSNs and Data Manager DSNs that are created by a specific user are defined in the same user odbc.ini file. Similarly, all system DSNs are defined in the same system odbc.ini file.

The following table indicates the types of DSN supported by TimesTen, whether to create a user or system DSN and the location of the DSN.

DSN type	User or System DSN?	Location of DSN
Data Manager DSN	Can be a user or system DSN	Located on the system where the database resides.
Client DSN	Can be a user or system DSN	Located on any local or remote system.
Server DSN	Must be a system DSN	Located on the system where the database resides.

See Working with the TimesTen Client and Server for more information about Client DSNs and Server DSNs.

Connection Attributes for Data Manager DSNs or Server DSNs

On Linux and UNIX, you specify connection attributes in the odbc.ini file. Connection attributes that do not appear in the odbc.ini file assume their default value.

Common types of connection attributes:

Note:

For a complete description of all attributes, see List of Connection Attributes in the Oracle TimesTen In-Memory Database Reference.

• Data Store attributes are associated with a database when it is created and cannot be modified by subsequent connections. They can only be changed by destroying and re-creating the database.

  The following are the most commonly used data store attributes:

  • DataStore: Directory name and file name prefix of the database.

  • LogDir: Directory name of the database transaction log files. Placing the transaction log files and checkpoint files on different file systems can improve system performance.

  • DatabaseCharacterSet: Required character set specification that defines the storage encoding.

• First connection attributes are used when the TimesTen database is loaded into memory. Only the instance administrator can load a database with first connection attribute settings. By default, TimesTen loads an idle database, which is a database with no connections, into memory when a first connection is made to it. These attributes persist for all subsequent connections until the last connection to the database is closed. First connection attributes can be modified only when the TimesTen database is unloaded and then the instance administrator reconnects with different values for the first connection attributes.

  The following are the most commonly used first connection attributes:

  • PermSize: Configures the allocated size of the database's permanent memory region. The permanent memory region contains persistent database objects. TimesTen only writes the permanent memory region to the file system during a checkpoint operation.

  • TempSize: Configures the allocated size of the database's temporary memory region. The temporary memory region contains transient data generated when running statements.

    Note:

    Your system must have sufficient main memory to accommodate the entire database. For more details on setting region sizes, see Specifying the Memory Region Sizes of a Database.

• General connection attributes are set by each connection and persist for the duration of the connection. Each concurrent connection can have different values.

  The following are the most commonly used general connection attributes:

  Note:

  If you provide connection attributes in the connection string, this overrides the connection attributes set in the DSN. See Connecting to a Database Using a Connection String.

  • UID: Specifies the user name to be used for the connection to the database, whether using a direct or client/server connection. To connect as the instance administrator or as an external user, you do not need to specify a user name. When you do not specify a user name, TimesTen assumes that the UID is the user name identified by the operating system.

  • PWD: Specifies the password that corresponds with the specified UID. For internal users, if you do not set the PWD attribute in the odbc.ini file for the specified DSN or in the connection string, TimesTen prompts for the password. For external users, you do not provide the password as it is verified by the operating system.

    When you initiate a client/server connection, the password sent for the connection is encrypted by the client/server protocol.

  • PWDCrypt: Specifies the encrypted password that corresponds with the specified UID.

  • PwdWallet: TimesTen enables you to store user names and associated passwords in an Oracle Wallet. This is the most secure and preferred method of providing credentials for connecting to a TimesTen database. The PwdWallet connection attribute is the path to the location of the wallet, from which TimesTen retrieves the password for the specified user name.

  • Note:

    For more information, see UID and PWD, PWDCrypt, and PwdWallet in the Oracle TimesTen In-Memory Database Reference. See Authentication in TimesTen in the Oracle TimesTen In-Memory Database Security Guide.

• Cache attributes enable you to enter the Oracle Service Identifier for the Oracle database instance from which data is loaded into TimesTen.

Note:

See Working with the TimesTen Client and Server for a description of the connection attributes that can be used with the TimesTen client ODBC driver.