Developer Reference : Data Access Methods : ODBC Guide : DSN Setup and Connection Strings
 
DSN Setup and Connection Strings
Using DSNs and ODBC Administrator with Zen
The following topics cover the administration of domain source names and connection strings in Zen:
ODBC Database Access
Zen DSN Setup
Zen Engine DSN Setup
Create Database Through DSN Setup
ODBC Connection Strings
ODBC Database Access
The ODBC standard specifies that applications using ODBC connect to databases through data source names (DSNs) defined in the operating system. With Zen, you can use DSN connections or DSN-less connection strings. Zen provides ODBC drivers for communication with the database engine. These drivers are associated with a DSN or specified in the connection string.
The following sections list the Zen ODBC drivers and briefly introduce DSN database access and DSN-less connection string access.
Zen ODBC Driver Names
Communication with the database engine is through a Zen ODBC driver. The setup will associate the appropriate driver during DSN creation. If you are using connection strings, you must specify the appropriate driver. The following table lists the ODBC drivers.
Table 10 Zen ODBC Drivers
Driver Name
Bitness
Remarks
Pervasive ODBC Unicode Interface
32-bit and 64-bit
Available only on Windows operating systems1
Connects to a local or remote named database
With the 32-bit ODBC Administrator, creates 32-bit DSNs for use by 32-bit applications that use wide character data
With the 64-bit ODBC Administrator, creates 64-bit DSNs for use by 64-bit applications that use wide character data
Pervasive ODBC Interface
64-bit
Setup creates 64-bit DSNs
Connects to a local or remote named database
For use by 64-bit applications
Pervasive ODBC Client Interface
32-bit
Setup creates 32-bit Client DSNs
Connects to a local or remote named database or an Engine DSN
Interface GUI lists both named databases and Engine DSNs
For use by 32-bit applications
Pervasive ODBC Engine Interface
32-bit
Setup creates 32-bit Engine DSNs2
Connects to a local named database
For use by 32-bit applications
Deprecated
1 On Linux and macOS, the system encoding is usually UTF-8, which allows SQL text to contain wide character data. SQL text using UTF‑8 is compatible with the existing Pervasive ODBC Client Interface driver, so an ODBC Unicode driver on Linux or macOS is not required.
2 New or revised 32-bit applications, local or remote, should connect to a named database or use a Client DSN instead of using Engine DSNs. Alternately, applications could use DSN-less connections by specifying “Pervasive ODBC Client Interface.” Avoiding the use of Engine DSNs positions your application for the future when Engine DSNs will no longer be supported in Zen.
DSN Connections
Zen does not support File DSNs. You must use User or System DSNs. System DSNs are generally preferred, because they are available to all users on a given computer.
If your ODBC application expects to use DSNs, then the DSN must identify the database.
A Zen Unicode DSN points to a local or remote named database and is for use with Windows 32-bit or 64-bit applications that use wide character data.
Zen also provides both 32- and 64-bit non-Unicode DSNs. These also point to a local or remote named database. The 32-bit DSN is referred to as a Client DSN. A DSN on a 64-bit operating system is simply referred to as a 64-bit DSN, without the Client designation and is for use by a 64-bit application.
For setting up and configuring a DSN with the ODBC Administrator, see Zen DSN Setup.
Note Zen also continues to provide an additional 32-bit Engine DSN. Engine DSNs are deprecated. New or revised 32-bit applications, local or remote, should connect to a named database rather than using Engine DSNs. Avoiding the use of Engine DSNs positions your application for the future when Engine DSNs will no longer be supported in Zen. An Engine DSN points only to a local named database. Client DSNs may also point to an Engine DSN.
DSN-less Connections
As an alternative to DSNs, applications can use DSN-less connections by specifying the Zen driver name directly (see ODBC Connection Strings).
DSNs are not required for applications that access Zen databases only through the Btrieve API or through other SQL access methods, such as ADO.NET. Those access methods use named databases for the connection, which is also an option for ODBC applications.
The Zen Java utilities do not require DSNs. For example, ZenCC uses JDBC with named databases, not ODBC.
Zen DSN Setup
This dialog is available via the ODBC Administrator and allows you to set up a DSN using any of the following Zen ODBC interfaces.
Pervasive ODBC Unicode Interface
With the 32-bit ODBC Administrator, creates 32-bit DSNs. With the 64-bit ODBC Administrator, creates 64-bit DSNs.
Pervasive ODBC Client Interface
For 32-bit DSNs
Pervasive ODBC Interface
For 64-bit DSNs
ODBC Administrator
Windows 64-bit operating systems contain two different executable files for ODBC Administrator, one for 32-bit DSNs and one for 64-bit DSNs. Each ODBC Administrator lists the system DSNs that only match its bitness. That is, the 64-bit ODBC Administrator lists 64-bit system DSNs, and vice versa. If you start ODBC Administrator from the Windows Control Panel, the 64-bit version is run.
Zen Control Center (ZenCC) contains separate options in the Tools menu to start the 32-bit or the 64-bit ODBC Administrator. Note that, if an ODBC Administrator is already open, Windows defaults to it. That is, if the 32-bit ODBC Administrator is open and you attempt to start the 64-bit one, Windows displays the 32-bit version (and vice versa). In other words, only one version of the ODBC Administrator runs at a time. This is a limitation of the Windows operating system rather than Zen.
Data Source Name
The ODBC client-server architecture calls for the naming of each specific data set so that it can be referred to by a well-known name.
Enter a name (called a data source name, or DSN) for the data source to which you wish to set up a connection. This DSN will help you identify the data source.
For additional information about using DSNs with the database engine, see ODBC Database Access.
Description
Enter a description of the DSN, if desired, to help identify the DSN, database, or application.
Server Name/IP
Specifies the machine on which the database engine is running. Enter a machine name or IP address of the server machine to which you want the client to connect.
Transport Hint
Specify the transport protocol to use, or which to try first. Default is TCP.
Database Name
Click Database Name, click Get List, then select in the list the database to which you wish to connect. The list returns the databases on the server specified for Server Name/IP.
Optionally you may create a new database by clicking Create.
Read-Only DSN
Selecting this check box causes the DSN connection string to include the setting OpenMode=1. This setting is available for the following configuratins:
Pervasive ODBC Unicode Interface (32- and 64-bit)
Pervasive ODBC Interface (64 bit)
Database Configuration Details
See Create Database Through DSN Setup for the following database configuration details:
Dictionary Location
Data File Location
Integrity Enforced
Bound
Engine DSN
This option appears only on the 32-bit Client DSN dialog. It is not present on any of the other Zen driver DSN dialogs.
Click Engine DSN, click Get List, then select in the list the Engine DSN to which you want the client to connect. The list returns the Engine DSNs on the server specified for Server Name/IP.
Optionally, you may create a new Engine DSN by clicking Create, or modify an existing Engine DSN by clicking Modify.
See also Zen Engine DSN Setup.
Note New or revised 32-bit applications, local or remote, should connect to a named database, not to an Engine DSN. Alternately, applications could use DSN-less connections (see DSN-less Connections). Avoiding the use of Engine DSNs positions your application for the future when Engine DSNs will no longer be supported in Zen.
Advanced Connection Attributes
The following connection attributes apply to 32-bit Client DSNs, 64-bit DSNs, and Unicode DSNs.
Enable Array Fetch
TCP/IP Port Number
Encoding Translation
(For connection attributes that apply to Engine DSNs, see Engine DSN Advanced Connection Attributes.)
Enable Array Fetch
An array fetch is a memory cache on the client machine for result sets. When array fetch is enabled, data from the latest result set is cached to the client machine’s local memory, thereby speeding performance on subsequent queries. We recommend you leave array fetch On if you will be doing multiple queries.
The default size of the buffer used to cache array fetches is 8KB. You can set it anywhere between 1 and 64 KB.
TCP/IP Port Number
You can use this setting to change the network port number on which Zen transmits ODBC communications. The network layer on the server engine has a similar setting. You must change both settings at the same time, and you must change them both to the same port number, or else your client and server cannot communicate.
Caution Do not change the client port number unless you also change the corresponding port number on the server. If the server and client are not using the same port number, they cannot communicate. See TCP/IP Port in Advanced Operations Guide.
Generally, the only reason you would need to change this port number is if you have another network service that is already using this port, and it is easier to change the port number for your Zen applications than for the other application.
For additional information about ports, see Changing the Default Communication Ports in Getting Started with Zen.
Encoding Translation
Encoding translation refers to the operation of converting the encoding of character data from that present in the database to the encoding present at the client and vice versa. This allows a client to read and write text from and to the database, under certain conditions, even if the database and client are using different encodings. Obviously, if the two encodings are the same, no translation is needed. The effectiveness of the translation is dependent on the amount of overlap between the character sets on the client and server, i.e., the greater number of characters they have in common. Characters that cannot be translated are replaced by question marks. For example, if the database uses OEM code page 850 and the client uses ANSI code page 1252, the letters will translate, but some graphics symbols will not.
The database connection string or DSN can be configured to automatically negotiate the translation, perform OEM/ANSI translation between different code page encodings, or disable any translation. Automatic translation is the default when using the Unicode driver; no translation is the default for all other Zen ODBC drivers. You can specify automatic translation in the DSN setup, or in the ODBC connection string with the PvTranslate attribute.
The following table summarizes the operation of text encoding translation for various combinations of client and driver encodings. Your application may be either ANSI or Unicode, indicated in column one. The Zen driver is either the Client driver (Client 32-bit or 64-bit driver) or the Unicode driver, column two. (The client and Unicode drivers are described in ODBC Database Access, above.) The Microsoft ODBC Driver Manager connects your application to the Zen ODBC driver and may perform text conversions, as indicated in column three. The three remaining columns describe the Zen driver text handling for a given encoding configuration (column four) for SQL text or CHAR user data (columns five and six, respectively). When data is retrieved from the database, the translation is reversed. Following the table are descriptions of these configuration options.
Table 11  
Application
Zen Driver
Microsoft Driver Manager
Text Handlling
Translation Configuration in DSN or Connection String
Zen Driver
SQL Text Handling
Zen Driver
CHAR Data Handling
ANSI
Client
no translation
none
no translation
no translation
ANSI
Client
no translation
OEM/ANSI
Client encoding to OEM
Client encoding to OEM
ANSI
Client
no translation
Auto
Client encoding to database encoding
Client encoding to database encoding
ANSI
Unicode
Client encoding to UCS-2 for SQL text
Auto
UCS-2 to UTF-8
Client encoding to database encoding
Unicode
Client
UCS-2 to client encoding
none
no translation
no translation
Unicode
Client
UCS-2 to client encoding
OEM/ANSI
Client encoding to OEM
Client encoding to OEM
Unicode
Client
UCS-2 to client encoding
Auto
Client encoding to database encoding
Client encoding to database encoding
Unicode
Unicode
no translation
Auto
UCS-2 to UTF-8
UCS-2 to database encoding
Note When using the Zen Client driver, Unicode SQL text is always converted to the client encoding by the Microsoft Driver Manager. This restricts NCHAR literals in a SQL query string to the character set of the client. To preserve NCHAR literals in SQL query text, use the Zen Unicode driver.
DSN Encoding Translation Options
The encoding translation options specify how character data is translated between the Zen database engine and a Zen client application that uses ODBC. This option is only available when configuring a Client 32-bit or 64-bit DSN. The Unicode DSN defaults to automatic.
Automatic
This setting instructs the Zen ODBC client to automatically translate character data encoding when the database encoding on the engine machine differs from the OS encoding on the client machine. Automatic is the default for the Unicode driver.
Character data translation, if required, occurs on the client. (No character data translation is required if the database encoding on the engine machine is the same as the OS encoding on the client machine.)
“Automatic” requires that the client and the server be version 10.1 or greater.
See also Database Code Page and Client Encoding in Advanced Operations Guide.
None
This setting means that no character data is translated between the client and server. (The assumption is that the client and server use the same operating system encoding.)
Note that, in versions prior to Zen v10.10, OEM/ANSI Conversion was a single choice and had two states: not selected or selected. The not selected state is now labeled None and is the default for Zen ODBC drivers other than the Unicode driver.
OEM/ANSI Conversion
This setting allows applications to store or retrieve character data in any OEM character set in the Zen engine, while allowing the data to be manipulated and displayed using the ANSI Windows character set in the application.
The Zen ODBC driver translation DLL can perform all necessary translations between the two character sets. This feature can be turned on or off for each DSN. Any character data that is passed to and from the database is correctly translated by the ODBC driver between the OEM and ANSI character sets.
If your application connects to the data source using SQLDriverConnect, you can also specify the translation DLL using the connection string option TRANSLATIONDLL=path_and_DLL_name. The translation DLL name for Zen is W32BTXLT.DLL.
Note The OEM-to-ANSI translation option is available only for Client and 64-bit DSNs.
(You can also use this translate option with a local Engine DSN. It is not available when setting up a remote Client connection to an Engine DSN. Keep in mind that Engine DSNs are deprecated and should not be used for new applications.)
Interaction Between Database Code Page and Encoding Translation
The following table explains the interaction between database code page and DSN encoding translation. See Create Database Through DSN Setup for a discussion of code page.
Table 12 Database Code Page and DSN Setting for Encoding Translation
If Database Code Page Is
And the Connection Encoding Translation Is
Then the Zen ODBC Driver
Server Default
None
(The equivalent default behavior in versions prior to PSQL v10.10.)
Performs no translation of data or metadata. The assumption is that the OS encoding on the server matches the OS encoding on the client.
For compatible data interpretation, the encoding used by the client machine must match the encoding of the data and metadata in the database.
A specific code page
None
(The equivalent default behavior in versions prior to PSQL v10.10.)
Performs no translation of data or metadata. The assumption is that the OS encoding on the server matches the OS encoding on the client.
For compatible data interpretation, the encoding used by the client machine must match the encoding of the data and metadata in the database.
Server Default
or
A specific code page
OEM/ANSI
Ignores database code page and translates data and metadata from the OEM encoding of the database to ANSI Windows encoding for the client application.
Server Default
Automatic
Translates data and metadata from the default OS encoding on the server to the OS encoding on the client.
A specific code page
Automatic
Translates data and metadata from the database code page to the OS encoding on the client.
Zen Engine DSN Setup
Note that Engine DSNs are 32-bit only.
Windows 64-bit operating systems contain two different executable files for ODBC Administrator, one for 32-bit DSNs and one for 64-bit DSNs. Each ODBC Administrator lists only the system DSNs that match its bitness. That is, the 64-bit ODBC Administrator lists 64-bit system DSNs, and vice versa. If you start ODBC Administrator from the Windows Control Panel, the 64-bit version is run. The 64-bit version does not list Engine DSNs because they are 32-bit only.
Zen Control Center (ZenCC) contains separate options in the Tools menu to start the 32-bit or the 64-bit ODBC Administrator. Note that, if an ODBC Administrator is already open, Windows defaults to it. That is, if the 32-bit ODBC Administrator is open and you attempt to start the 64-bit one, Windows displays the 32-bit version (and vice versa). In other words, only one version of the ODBC Administrator runs at a time. This is a limitation of the Windows operating system, not Zen.
Note New or revised 32-bit applications, local or remote, should connect to a named database, not to an Engine DSN. Alternately, applications could use DSN-less connections (see DSN-less Connections). Avoiding the use of Engine DSNs positions your application for the future when Engine DSNs will no longer be supported in Zen.
Data Source Name
The ODBC client-server architecture calls for the naming of each specific data set so that it can be referred to by a well-known name.
Enter a name (called a data source name, or DSN) for the data source to which you wish to set up a connection. This DSN will help you identify the data source.
For additional information about using DSNs with the database engine, see ODBC Database Access.
Description
Enter a description of the DSN, if desired, to help identify the DSN, database, or application.
Database Name
Select a database with which you want to associate the DSN. Optionally, you may create a new database by clicking Create.
Database Configuration Details
See Create Database Through DSN Setup for the following database configuration details:
Dictionary Location
Data File Location
Integrity Enforced
Bound
Engine DSN Advanced Connection Attributes
The connection attributes for Engine DSNs include the following:
DSN Open Mode
Encoding Translation
Note Engine DSNs are deprecated. New or updated applications should use Client DSNs in local or remote connection mode.
DSN Open Mode
The DSN Open Mode options for Engine DSNs allow you to specify one of several characteristics that go into effect when tables are opened through the specified DSN. These options are mutually exclusive—you are not permitted to select more than one.
These options correspond directly to the Btrieve open modes allowed in the Open (0) operation. By setting an Open Mode for a DSN, you are setting the default behavior for tables (corresponding to Btrieve files) opened through that DSN.
Table 13 DSN Open Modes and ODBC Connection Options
Open Mode
ODBC Connection String Generated
SQLSetConnectOption Call
Normal
OPENMODE=0
SQLSetConnectOption( pSubDbc, SQL_ACCESS_MODE, SQL_MODE_READ_WRITE);
Accelerated
OPENMODE=-1
SQLSetConnectOption is ignored
Read-only
OPENMODE=1
SQLSetConnectOption( pSubDbc, SQL_ACCESS_MODE, SQL_MODE_READ_ONLY);
Exclusive
OPENMODE=-4
SQLSetConnectOption is ignored
Normal
Normal mode is the default. Opening a table in Normal mode allows read/write access according to the permissions defined in the database.
If this mode is selected, the ODBC connection string includes OPENMODE=0, and the following ODBC function call is executed when you connect to the database:
SQLSetConnectOption(pSubDbc, SQL_ACCESS_MODE, SQL_MODE_READ_WRITE);
Accelerated
Opening a table in Accelerated mode provides increased insert/update performance by disabling database engine logging functions for the current user. The changes to logging in Accelerated mode do not affect other users accessing the same table.
Caution The database engine cannot guarantee transaction atomicity, transaction durability, or archival log safety for any client during use of Accelerated mode by any client. The reason for this restriction is that in the event a restore from log is needed, the log may not contain adequate information to complete the restore, because it is only a partial record of operations on a data file.

For example, if a system failure occurs while the same file is being accessed by a client performing inserts using Accelerated mode and a client performing updates using Normal mode, it is possible for the transaction log to contain updates to records that do not yet exist in the data files, because the Accelerated insert operation in memory was never flushed to disk, while the transactional update operation was written to the transaction log.

An attempt to roll forward an archival log containing this combination of operations will fail.
When this mode is selected, the ODBC connection string includes OPENMODE=-1, and the SQLSetConnectOption call is ignored by the ODBC driver. You cannot use SQLSetConnectOption to specify this mode.
Read-Only
When a table is opened in read-only mode, operations that modify the database structure or the data in the database are not permitted.
If this mode is selected, the ODBC connection string includes OPENMODE=1, and the following ODBC function call is executed when you connect to the database:
SQLSetConnectOption(pSubDbc, SQL_ACCESS_MODE, SQL_MODE_READ_ONLY);
Exclusive
When a table is opened in exclusive mode, no other connections to the table are permitted. If other users are currently accessing the given table, it cannot be opened in Exclusive mode. You must try again later.
When this mode is selected, the ODBC connection string includes OPENMODE=-4, and the SQLSetConnectOption call is ignored by the ODBC driver. You cannot use SQLSetConnectOption to specify this mode.
Encoding Translation
The encoding translation options are the same as for Client and 64-bit DSNs. See Encoding Translation.
Create Database Through DSN Setup
The following table explains the controls on the Create Database dialog.
Element
Description
Database Name
The name for the database that you want to appear in the database listings. For example, the database name you see in Zen Control Center.
Note: The database name cannot be the same as an existing database name.
Integrity Enforced
Specifies whether integrity constraints (security, RI, and triggers) are enforced on the database. These constraints apply to Btrieve access to the data files as well as ODBC/SQL access.
For additional information, see Interactions Between Btrieve and Relational Constraints in Advanced Operations Guide.
Bound
Indicates whether or not the database is bound. Binding a database prevents the DDFs or data files from being used in another database and prevents a data file from having two or more different table definitions within the same database.
For more information about bound databases, refer to Bound Database versus Integrity Enforced in Advanced Operations Guide.
Long Metadata (V2 metadata)
Specifies whether you want the database to use version 1 (V1) or version 2 (V2) metadata.
The database engine supports two versions of metadata, referred to as version 1 (V1) and version 2 (V2). Metadata version is a property of the database, which means that it applies to all tables within that database and is recorded in the dbnames.cfg file. A database cannot use some tables with V1 metadata and others with V2 metadata. Metadata from the two versions cannot interact.
For additional information, see Zen Metadata in SQL Engine Reference.
Code Page
Specifies the code page that applies to the database data and metadata.This property is stored in DBNAMES.CFG.
The default code page is “server default,” meaning the operating system code page on the server where the database engine is running.
Note that database code page and client encoding are separate but interrelated. See Database Code Page and Client Encoding in Advanced Operations Guide.
Btrieve security policy
Specifies the security model to use for the transactional interface.See Security Models for the MicroKernel Engine in Advanced Operations Guide.
Dictionary Location
This location specifies where the dictionary files (DDFs) reside on physical storage. This location must be on the same server to which you are connected (and where the database engine is running). The location must be formatted as though you are working directly at the server machine.
Enter a path in the form drive:\path, where drive is a drive letter on the server.
Data File Location
This location specifies where the data files reside on physical storage. The Add button lets you add locations to the list. The Delete button lets you remove locations from the list. The locations must be on the same server where the database engine is running.
Specify the location in the same manner as for the dictionary locations.
ODBC Connection Strings
This section describes the ODBC connection strings supported by Zen. This information is provided for advanced users using a database access tool that allows connection strings to be specified and for developers writing ODBC or OLE DB applications to access Zen.
ODBC Driver Parameter
You must specify the Zen ODBC driver to use to connect to the Zen database engine. See Zen ODBC Driver Names for a description of the available drivers.
Use the ODBC Driver parameter to specify the appropriate driver. For example:
Driver={Pervasive ODBC Unicode Interface}
Driver={Pervasive ODBC Interface}
Driver={Pervasive ODBC Client Interface}
Driver={Pervasive ODBC Engine Interface}
Driver Parameters
The specific driver specified by the Driver parameter has additional attribute parameters for naming the server, port, database, etc. In addition to these common parameters, each driver has parameters specific to it. The tables below show, for the different drivers, the driver parameters that may be used. The attributes can be included with the ODBC function SQLDriverConnect or with SQLConnect.
Table 14 Unicode Driver Connection String Parameters
Connection String Parameters
Description
ServerName=server[.port]
Specify the machine name or IP address of the computer to which you wish to connect. Required. Port is provided from backwards compatibility and allows you to specify the port number to use if you are not using the default port. When using IPv6 addresses and appending a port number in ODBC connections, use an IPv6-literal.net name or UNC-safe name. See Drive-based Formats in Getting Started with Zen.
TransportHint=TCP
Specify the transport protocol to use, or which to try first. Default is TCP. Optional.
DBQ=[@]db_name
Specify the internal database name (not DSN) to which you wish to connect. Required.
The @ character is optional. It has no particular effect and is supported only for backward compatibility.
TCPPort=port
Specify the TCP/IP port on which to find the server. Optional. See also Changing the Default Communication Ports in Getting Started with Zen.
ArrayFetchOn=1 | 0
Specify whether to cache result sets on the client. Default is 1, “On.” Optional.
ArrayBufferSize=size
Specify the size of the client cache, in KB. Default is 8 KB. Optional.
PvTranslate=auto
Specify how to handle the data encoding when the client connects to the database engine. (See Encoding Translation for more information.)
PvTranslate defaults to “auto” for the Unicode driver. This allows you to use NCHAR columns and NCHAR literals with wide character data without having to explicitly set PvTranslate to “auto.”
With the attribute is set to “auto,” the client and server automatically establish compatible encoding. Data translation, if required, occurs on the client.
UID=user_name
If security is enabled for the given database, specify the user name. Optional, depending on security. See Zen Security in Advanced Operations Guide.
PWD=password
If security is enabled for the given database, specify the password. Optional, depending on security. See Zen Security in Advanced Operations Guide.
Example A
Connect to a database named SOMEDATA that contains wide character data on a remote server named ServerMain using TCP/IP port 1590:
Driver={Pervasive ODBC Unicode Interface}; ServerName=ServerMain.1590;DBQ=SOMEDATA; TransportHint=TCP;
Example B
Connect to a database named EuropeRegion4 that contains wide character data on a local server named with database security turned on:
Driver={Pervasive ODBC Unicode Interface}; DBQ=EuropeRegion4;UID=tonyawu7;PWD=HR19lb8w;
 
Table 15 64-bit Driver Connection String Parameters
Connection String Parameters
Description
ServerName=server[.port]
Specify the machine name or IP address of the computer to which you wish to connect. Required. Port is provided from backwards compatibility and allows you to specify the port number to use if you are not using the default port. When using IPv6 addresses and appending a port number in ODBC connections, use an IPv6-literal.net name or UNC-safe name. See Drive-based Formats in Getting Started with Zen.
TransportHint=TCP
Specify the transport protocol to use, or which to try first. Default is TCP. Optional.
DBQ=[@]db_name
Specify the internal database name (not DSN) to which you wish to connect. Required.
The @ character is optional. It has no particular effect and is supported only for backward compatibility.
TCPPort=port
Specify the TCP/IP port on which to find the server. Optional. See also Changing the Default Communication Ports in Getting Started with Zen.
ArrayFetchOn=1 | 0
Specify whether to cache result sets on the client. Default is 1, “On.” Optional.
ArrayBufferSize=size
Specify the size of the client cache, in KB. Default is 8 KB. Optional.
PvTranslate=auto
Specify how to handle the data encoding when the client connects to the database engine. The attribute can either be absent, or have a value set to “auto” to indicate automatic translation. (See Encoding Translation for more information.)
With the attribute is set to “auto,” the client and server automatically establish compatible encoding. Data translation, if required, occurs on the client. Note that “auto” overrides the “OEM/ANSI” setting for a DSN.
If the attribute is absent, ODBC does not translate any character data. This is the default behavior. The “OEM/ANSI” setting may still apply. See OEM/ANSI Conversion.
UID=user_name
If security is enabled for the given database, specify the user name. Optional, depending on security. See Zen Security in Advanced Operations Guide.
PWD=password
If security is enabled for the given database, specify the password. Optional, depending on security. See Zen Security in Advanced Operations Guide.
Example
Connect to a local named database acctdomestic with a 64-bit application:
Driver={Pervasive ODBC Interface};DBQ=acctdomestic;
Table 16 32-bit Client Driver Connection String Parameters
Connection String
Description
ServerName=server[.port]
Specify the machine name or IP address of the computer to which you wish to connect. Required. Port is provided from backwards compatibility and allows you to specify the port number to use if you are not using the default port. When using IPv6 addresses and appending a port number in ODBC connections, use an IPv6-literal.net name or UNC-safe name. See Drive-based Formats in Getting Started with Zen.
ServerDSN=dsn_name
Specify the Engine DSN to which you wish to connect. Required, unless DBQ is specified.
TransportHint=TCP
Specify the transport protocol to use, or which to try first. Default is TCP. Optional.
DBQ=[@]db_name
Specify the internal database name (not DSN) to which you wish to connect. Required.
The @ character is optional. It has no particular effect and is supported only for backward compatibility.
TCPPort=port
Specify the TCP/IP port on which to find the server. Optional. See also Changing the Default Communication Ports in Getting Started with Zen.
ArrayFetchOn=1 | 0
Specify whether to cache result sets on the client. Default is 1, “On.” Optional.
ArrayBufferSize=size
Specify the size of the client cache, in KB. Default is 8 KB. Optional.
PvTranslate=auto
Specify how to handle the data encoding when the client connects to the database engine. The attribute can either be absent, or have a value set to “auto” to indicate automatic translation. (See Encoding Translation for more information.)
With the attribute is set to “auto,” the client and server automatically establish compatible encoding. Data translation, if required, occurs on the client. Note that “auto” overrides the “OEM/ANSI” setting for a DSN.
If the attribute is absent, ODBC does not translate any character data. This is the default behavior. The “OEM/ANSI” setting may still apply. See OEM/ANSI Conversion.
UID=user_name
If security is enabled for the given database, specify the user name. Optional, depending on security. See Zen Security in Advanced Operations Guide.
PWD=password
If security is enabled for the given database, specify the password. Optional, depending on security. See Zen Security in Advanced Operations Guide.
Example A
Connect to a database named Atlantis on a remote server named AncientLore using TCP/IP port 1585:
Driver={Pervasive ODBC Client Interface}; ServerName=AncientLore.1585;DBQ=Atlantis;
Example B
Connect to a database named DomSales on a remote server named SalesSvr with database security turned on:
Driver={Pervasive ODBC Client Interface}; ServerName=SalesSvr;DBQ=DomSales;UID=alexjame;PWD=k7Jb9xRR;
Example C
Connect to an Engine DSN named mydata on a remote server named MyServer and establish automatic encoding support:
Driver={Pervasive ODBC Client Interface}; ServerName=MyServer;ServerDSN=mydata;PvTranslate=auto;
Table 17 32-bit Engine Driver Connection Strings
Connection String
Description
DBQ=[@]db_name
Specify the internal database name (not DSN) to which you wish to connect. Required.
The @ character is optional. It has no particular effect and is supported only for backward compatibility.
UID=user_name
If security is enabled for the given database, specify the user name. Optional, depending on security. See Zen Security in Advanced Operations Guide.
PWD=password
If security is enabled for the given database, specify the password. Optional, depending on security. See Zen Security in Advanced Operations Guide.
OPENMODE=-4 | -1 | 0 | 1
Specify the default file open mode for files opened with the current connection. Default is 0, “Normal.” Can be used only with local connections, not remote client connections. Optional.
For more information on file open modes, see DSN Open Mode.
TRANSLATIONDLL=path_and_DLL_name
Specify the full path name of the DLL to use for OEM/ANSI translation. For more information, see OEM/ANSI Conversion.
Example
Connect to a local database named DATA5:
Driver={Pervasive ODBC Engine Interface};DBQ=DATA5;
Note Engine DSNs are deprecated. New or updated applications should use Client DSNs in local or remote connection mode.