Icon Connection Strings

Connection strings are used when the SQLDriverConnect and SQLBrowseConnect ODBC API functions are called. They may specify as little as a data source name or as much as an entire data source configuration. The SQLDriverConnect function will interactively complete a connection string, if necessary, and, if the calling program indicates that it wants this behavior, by prompting the user for the missing information. On the other hand, the SQLBrowseConnect function will do so programmatically by iteratively interacting with the calling program. For more information on the SQLDriverConnect and SQLBrowseConnect API calls, please refer to the ODBC Programmers Reference from Microsoft. For more information on what function calls are used in your application program, please ask the vendor of the application program being used.

Pre-Configured Data Source Connection Strings
Connection strings that connect to a pre-configured data source, do so by specifying the DSN keyword in the connection string:

DSN=MyDataSource

Any other keywords that are specified in the connection string are overridden with the settings present in the data source configuration for the specified data source.

In addition, you can also use the FILEDSN keyword to load a data source configuration from a specific file instead of the registry:

FILEDSN=c:\windows\temp\mydatasource.dsn

That will load the configuration values from the mydatasource.dsn file. For more information on using the FILEDSN keyword, please refer to the ODBC Programmers Reference from Microsoft.

Direct Connection Strings
Direct connection strings bypass a pre-configured data source altogether and specify all of the keywords necessary to configure and access a given data source. The first keyword in a direct connection string must always be the special DRIVER keyword. For the ElevateDB ODBC Driver, it would look like this:

DRIVER={ElevateDB 2 ODBC Driver}

Notice the use of the required braces {} around the DRIVER keyword.

The keywords that can be used with direct connection strings and the ElevateDB ODBC Driver are listed below. Here is an example direct connection string that connects to a remote ElevateDB Server and a database called "Accounting" (case-insensitive):

DRIVER={ElevateDB 2 ODBC Driver};
CHARSET=UNICODE;
TYPE=REMOTE;
ADDRESS=192.168.0.28;
DATABASE=Accounting

Information The line breaks inserted above are only for readability and should not be used in an actual connection string.

Connection String Keywords
The following keywords are used with connection strings. All keywords marked with the (R) symbol next to their name are only applicable when the TYPE keyword is set to "REMOTE". Likewise, all keywords marked with the (L) symbol next to their name are only applicable when the TYPE keyword is set to "LOCAL".

NameDescription
CHARSETThis string value specifies which character set, "ANSI" or "UNICODE", to use for the connection. For remote connections to an ElevateDB Server, the value must match the character set being used by the ElevateDB Server. The default value is "UNICODE".
TYPEThis string value is set to either "LOCAL" if the connection is accessing the database directly, or "REMOTE" if the connection is accessing the database remotely via an ElevateDB Server.
NAMEThis string value specifies the name of the connection.
DESCRIPTIONThis string value specifies the description of the connection.
HOST (R)This string value specifies the host name of the ElevateDB Server machine that you are accessing. Either the HOST or ADDRESS values must be populated along with the SERVICE or PORT values in order to correctly access a database on an ElevateDB Server. The default value is "".
ADDRESS (R)This string value specifies the IP address of the ElevateDB Server machine that you are accessing. Either the HOST or ADDRESS values must be populated along with the SERVICE or PORT values in order to correctly access a database on an ElevateDB Server. The default value is "127.0.0.1".
SERVICE (R)This string value specifies the service name of the ElevateDB Server machine that you are accessing. Either the HOST or ADDRESS values must be populated along with the SERVICE or PORT values in order to correctly access a database on an ElevateDB Server. The default value is "".
PORT (R)This string value specifies the port number of the ElevateDB Server machine that you are accessing. Either the HOST or ADDRESS values must be populated along with the SERVICE or PORT values in order to correctly access a database on an ElevateDB Server. The default value is "12010".
CONNECTTIMEOUT (R)This string value specifies the maximum amount of time, in seconds, that ElevateDB will wait for a successful connection before aborting the connection attempt. The default value is "15" (seconds).
PING (R)This string value specifies whether pinging will be enabled for the connection to the ElevateDB Server. When pinging is enabled, the driver will send a keep-alive request to the ElevateDB Server in the interval specified by the PINGINTERVAL value. This prevents the ElevateDB Server from disconnecting and/or removing the connection, even if the connection has been idle for a very long period of time. Please see the Server Session Timeout configuration item in the Starting and Configuring the ElevateDB Server topic for more information on how idle connections are handled. Specify "TRUE" to enable pinging, or "FALSE" (the default) to disable pinging.
PINGINTERVAL (R)This string value specifies how often the connection will ping the ElevateDB Server when pinging is enabled via the PING value. The default value is "60" (seconds).
TIMEOUT (R)This string value specifies how long the connection will wait on a response from the ElevateDB Server before disconnecting and issuing an error. The default value is "180" (seconds).
ENCRYPTED (R)This string value specifies whether the connection to the ElevateDB Server should be encrypted or no. Specify "TRUE" to enable encryption for the connection, or "FALSE" (the default) to disable encryption for the connection.
ENCRYPTSRVPWD (R)This string value specifies the password to use for encrypted connections to the remote ElevateDB Server, as well as for encrypting logins to the remote ElevateDB Server. This password must match the configured encryption password for the remote ElevateDB Server, and you should only specify this value if you know exactly what you are doing and need to use a different encryption password than the default of "elevatesoft".
COMPRESSION (R)This string value specifies the amount of compression to use when communicating with the ElevateDB Server. The default value is "0", or no compression. A value of "1" to "10" specifies the amount of compression from fast, but not very thorough, to very thorough, but not as fast. A value of "6" specifies a balance between size and speed, and represents the ideal level for most applications.

Information The ElevateDB ODBC Driver will automatically adjust this value for situations where the existing compression level is not ideal, such as in cases where the amount of data being sent is so small that it is of no benefit to compress the data.
READAHEADROWS (R)This string value specifies how many rows will be read in a single request when the connection is requesting rows from the remote ElevateDB Server. The default value is "10".
CONFIGMEMORY (L)This string value specifies whether the configuration file used by the connection will be located in the process memory ("virtual") or on disk. Specify "TRUE" to use a virtual configuration file, or "FALSE" (the default) to use a disk-based configuration file in the location specified by the CONFIGPATH string value (see below). The configuration file in ElevateDB stores the contents of the system-defined Configuration Database. Please see the Architecture for more information on configuration files.
CONFIGPATH (L)This string value specifies the configuration path to use for the connection. The configuration file in ElevateDB stores the contents of the system-defined Configuration Database. Please see the Architecture for more information on the configuration path.
TEMPPATH (L)This string value specifies the temporary tables path to use for the connection. The temporary tables path is used to store any temporary tables generated during query execution. The default value is the operating system setting for the storing temporary files for the current user. Please see the Architecture for more information on the temporary tables path.
KEEPTABLESOPENThis string value specifies whether tables should be kept open for the duration of the connection once they have been opened at least once. Specify "TRUE" to keep tables open, or "FALSE" (the default) to have tables opened and closed on demand. Setting this value to "TRUE" can result in improved performance, especially with applications that execute many singleton SQL statements in a row.
CONFIGNAME (L)This string value specifies the root name (without extension) used by the connection for the configuration file. The default value is "EDBConfig". The extension used for the configuration file is determined by the CONFIGEXT value. The location of the configuration file is determined by the CONFIGPATH value.
CONFIGEXT (L)This string value specifies the extension used by the connection for the configuration file. The default value is ".EDBCfg". The root name (without extension) used for the configuration file is determined by the CONFIGNAME value. The location of the configuration file is determined by the CONFIGPATH value.
LOCKEXT (L)This string value specifies the extension used by the connection for both the configuration and database catalog lock files. The default value is ".EDBLck". The root name (without extension) used for the configuration lock file is determined by the CONFIGNAME value. The root name (without extension) used for a database catalog lock file is determined by the CATALOGNAME value. The location of the configuration lock file is determined by the CONFIGPATH value, and the configuration lock file is hidden, by default. The location of a database catalog lock file is determined by the path designated for the applicable database when the database was created, and a database catalog lock file is hidden, by default.
LOGEXT (L)This string value specifies the extension used by the connection for the configuration log file. The default value is ".EDBLog". The root name (without extension) used for the configuration log file is determined by the CONFIGNAME value. The location of the configuration log file is determined by the CONFIGPATH value.
MAXLOGSIZE (L)This string value specifies the maximum size of the log file (in bytes) that the log file can grow to. Log entries are added to the log in a circular fashion, meaning that once the maximum log file size ia reached, ElevateDB will start re-using the oldest log entries for new log entries. The default value is 1048576 bytes. Which types of logged events are recorded in the log can be controlled by the LOGCATS value. By default, all categories of events are logged (INFO, WARN, and ERROR).

Warning It is very important that all data sources and/or applications accessing the same configuration file use the same maximum log file size for the configuration log file. Using different values can result in log entries being prematurely overwritten or appearing "out-of-order" when viewing the log entries via the LogEvents Table.
LOGCATS (L)This string value specifies the types of events that should be logged in the configuration log file for the current connection, with each value separated by a comma (,). The default value is "INFO,WARN,ERROR", or all categories of events.
CATALOGNAME (L)This string value specifies the root name (without extension) used by the connection for all database catalog files. The default value is "EDBDatabase". The extension used for the catalog files is determined by the CATALOGEXT value. The location of the catalog file is determined by the path designated for the applicable database when the database was created.
CATALOGEXT (L)This string value specifies the extension used by the connection for database catalog files. The default value is ".EDBCat". The root name (without extension) used for all database catalog files is determined by the CATALOGNAME value. The location of the catalog file is determined by the path designated for the applicable database when the database was created.
BACKUPEXT (L)This string value specifies the extension used by the connection for database backup files. The default value is ".EDBBkp". The root name (without extension) used for a database backup file is determined by the name given when the BACKUP DATABASE statement is executed.
UPDATEEXT (L)This string value specifies the extension used by the connection for database update files. The default value is ".EDBUpd". The root name (without extension) used for a database update file is determined by the name given when the SAVE UPDATES statement is executed.
TABLEEXT (L)This string value specifies the extension used by the connection for database table files. The default value is ".EDBTbl". The root name (without extension) used for a table file is determined by the name given when the CREATE TABLE statement is executed. The location of the table files is determined by the path designated for the applicable database when the database was created.
INDEXEXT (L)This string value specifies the extension used by the connection for database table index files. The default value is ".EDBIdx". The root name (without extension) used for a table's index file is determined by the name given when the CREATE TABLE statement is executed. The location of the table index files is determined by the path designated for the applicable database when the database was created.
BLOBEXT (L)This string value specifies the extension used by the connection for database table BLOB files. The default value is ".EDBBlb". The root name (without extension) used for a table's BLOB file is determined by the name given when the CREATE TABLE statement is executed. The location of the table BLOB files is determined by the path designated for the applicable database when the database was created.
PUBLISHEXT (L)This string value specifies the extension used by the connection for database table publish files. The default value is ".EDBPbl". The root name (without extension) used for a table's publish file is determined by the name given when the CREATE TABLE statement is executed. The location of the table publish files is determined by the path designated for the applicable database when the database was created.
UIDThis string value specifies the user ID to use when connecting to the connection. If this value is left blank, the user will be prompted for the user ID, if possible. When executing in environments that don't support a user interface, such as web applications, it is not possible to display a login dialog and an error will be raised instead.
PWDThis string value specifies the password to use when connecting to the connection. If this value is left blank, the user will be prompted for the password, if possible. When executing in environments that don't support a user interface, such as web applications, it is not possible to display a login dialog and an error will be raised instead.
DATABASEThis string value specifies the name of the database being accessed with the connection. Please see the Architecture for more information on databases.
READONLYThis string value specifies whether the connection is read-only or read-write. Set this value to "TRUE" to make the connection read-only, and "FALSE" to make the connection read-write.
ROWLOCKPROTOCOLThis string value specifies which row locking protocol to use. Set this value to "PESSIMISTIC" to specify that all UPDATE row locks should be acquired when the rows are read during the process of the UPDATEs. Set this value to "OPTIMISTIC" to specify that all UPDATE row locks should only be acquired when the rows are actually being updated. Please see the Locking and Concurrency topic for more information.
ROWLOCKRETRIESThis string value specifies the number of row lock attempts that the driver should make before issuing an error. The default is "15".
ROWLOCKWAITThis string value specifies the amount of time (in milliseconds) to wait between each row lock attempt. The default is "100".
DETECTROWCHANGESThis string value specifies whether the driver should issue an error when a row is updated and the row has changed since it was last cached. Specify "TRUE" to enable row change detection, or "FALSE" (the default) to disable row change detection. Please see the Change Detection topic for more information.
CATALOGINFO (L)This string value specifies whether database catalog character set and version information should appear in the Databases system information table. The default value is "TRUE".

Information Setting the value to "FALSE" can significantly improve the performance of the loading of the Databases system information table when there are a lot of databases in a configuration. This is because ElevateDB has to open the database catalog for each database in order to read the character set and version number.
CACHEMODULES (L)This string value specifies whether module DLLs should be cached in memory for the duration of the connection. The default value is "FALSE".
STMTCACHESIZEThis string value specifies how many SQL statements can be cached in memory for the duration of the connection. Caching SQL statements improves the performance of ElevateDB by avoiding very expensive preparation/un-preparation cycles. The default value is "0", which means that SQL statements will not be cached for the connection.

Information The maximum number of open SQL statements per connection is 2048, so you should not set the statement cache size that high. Also, the SQL statement cache size is a per-open-database setting.
PROCCACHESIZEThis string value specifies how many functions/procedures can be cached in memory for the duration of the connection. Caching functions/procedures improves the performance of ElevateDB by avoiding very expensive preparation/un-preparation cycles. The default value is "0", which means that functions/procedures will not be cached for the connection.

Information The maximum number of open functions/procedures per connection is 2048, so you should not set the procedure cache size that high. Also, the function/procedure cache size is a per-open-database setting.
FLUSHWRITESThis string value controls whether the driver forces the operating system to flush any buffered writes to disk immediately after the data is written to the operating system. If the value is "FALSE" (the default), then ElevateDB will leave the flushing up to the operating system. If it is "TRUE", then ElevateDB will force a buffer flush after every write. Please see the Buffering and Caching topic for more information.
SIGNATURE This string value specifies the signature to use for the connection. A signature is used to "sign" all configuration and database files created by ElevateDB so that they are only accessible using that signature, as well as "signing" all communications with a remote ElevateDB Server. You should only specify this value if you know exactly what you are doing and need to use a different signature than the default of "edb_signature".
ENCRYPTPWD (L)This string value specifies the password to use for encrypting any local engine files. You should only specify this value if you know exactly what you are doing and need to use a different encryption password than the default of "elevatesoft".
Image