2. Click Add Connection... The Add Connection window is displayed.
3. If the Progress DataDirect OpenAccess SDK for ADO.NET data provider is displayed in the Data source field, skip to Step 6. Otherwise, click the Change... button.
4. The Change Data Source window is displayed.
5. On the Change Data Source window, do the following steps:
a. In the Data source list box, select Progress DataDirect.
b. In the Data provider drop-down list, select Progress DataDirect OpenAccess SDK for ADO.NET.
c. If you want to use these selections for other connections, select the Always use this selection check box.
d. Click OK to return to the Add Connection window.
6. On the Add Connection window, do the following steps:
a. Enter the Host name.
b. Enter the User ID and password. These values are required for authentication.
c. (Optional) If you want to save the password for the lifetime of connection instance defined in Server Explorer, select the Save my password check box.
d. (Optional) In the Database entry field, enter the name of the database to which you want to connect.
7. Click the Advanced... button to specify additional provider-specific property values.
To change a value in the Advanced Properties dialog box, select or type the new value into the field and press ENTER. The value is added to the connection string that appears in the field below the description of the property. If you accept the default values, the connection string field remains unchanged. When you have made the necessary changes, click OK to return to the Add Connection window.
The following are the descriptions of the properties that appear in the Advanced Properties dialog box. The properties have the form:
property=value
Advanced
Application ID: Gets or sets an alphanumeric string passed by an OpenAccess SDK Client that identifies the client application to an OpenAccess SDK service that has been configured to accept connections only from specific application IDs.
Custom Properties: OpenAccess SDK for ADO.NET allows you to define the custom connection attributes and their default values in the oadm.ini, the configuration file of the OpenAccess SDK Server, using the DataSourceIPCustomProperties service attribute.
For example:
AttributeName=DataSourceIPCustomProperties
AttributeType=string
AttributeSize=16384
AttributeValidationType=none
AttributeValidationStringParam_=0
AttributeValidationIntegerParam_=0
AttributeValidationIntegerParam_0=0
AttributeValidationIntegerParam_1=11
The custom connection properties are key=value pairs separated by semicolons, and surrounded by quotes("") to distinguish them from the other connection properties. For example:
Database: Type the name of the database to which you want to connect.
DBPassword: Specifies the data store password, which may be required depending on the server configuration.
DBUser: Specifies the database user ID, which may be required depending on the server configuration.
Enable Trace: Specifies whether tracing is enabled.
Valid Values: 0 | 1 | 2
• If set to 0 (the initial default), tracing is not enabled.
• If set to 1, tracing is enabled. Results are appended to the file.
• If set to 2, tracing is enabled. The trace file is recreated.
Host Password: Specifies the host password, which may be required depending on the server configuration.
Host User: Specifies the host user name, which may be required depending on the server configuration.
New Password: Specifies the new host password to be used. If specified and applicable to the connection, the OpenAccess SDK password change mechanism is invoked. When the password has been changed successfully, the following warning is generated:
[DataDirect][ Open Access SDK for ADO.NET][OpenAccess Server] The user password was changed successfully
If unspecified and the OpenAccess SDK Server detects that the host password has expired, you are prompted for a new host password.
Parameter Mode: Select the behavior of native parameter markers and binding. This allows applications to reuse provider-specific SQL code and simplifies migration to the OpenAccess SDK for ADO.NET data provider.
• "If set to ANSI (the default), the ? character is processed as a parameter marker and bound as ordinal.
• "If set to BindByOrdinal, native parameter markers are used and are bound as ordinal.
• "If set to BindByName, native parameter markers are used and are bound by name.
Schema Collection Timeout: Specifies the number of seconds after which an attempted schema collection operation fails if it is not yet completed.
Trace File: Specifies the path and name of the trace file.
Connection Pooling
Connection Reset: Select whether a connection that is removed from the connection pool for reuse by an application will have its state reset to the initial configuration settings of the connection.
If set to False (the initial default), the data provider does not reset the state of the connection.
Connection Timeout: Type the number of seconds after which the attempted connection to the server will fail if not yet connected. If connection failover is enabled, this option applies to each connection attempt.
If set to 0, the data provider never times out on a connection attempt.
The initial default is 15 seconds.
Load Balance Timeout: Type the number of seconds to keep connections in a connection pool. The pool manager periodically checks all pools, and closes and removes any connection that exceeds this value. The Min Pool Size option can cause some connections to ignore the value specified for the Load Balance Timeout option.
The value can be any integer from 0 to 65535.
If set to 0 (the initial default), the connections have the maximum timeout.
Max Pool Size: Type the maximum number of connections within a single pool. When the maximum number is reached, no additional connections can be added to the connection pool.
The value can be any integer from 1 to 65535.
The initial default is 100.
Max Pool Size Behavior: Select whether the data provider can exceed the number of connections specified by the Max Pool Size option when all connections in the connection pool are in use.
If set to SoftCap, when all connections are in use and another connection is requested, a new connection is created, even when the connection pool exceeds the number set by the MaxPoolSize option. If a connection is returned and the pool is full of idle connections, the pooling mechanism selects a connection to be discarded so the connection pool never exceeds the Max Pool Size.
If set to HardCap, when the maximum number of connections allowed in the pool are in use, any new connection requests wait for an available connection until the Connection Timeout is reached.
Min Pool Size: Type the minimum number of connections that are opened and placed in a connection pool when it is created. The connection pool retains this number of connections, even when some connections exceed their Load Balance Timeout value.
The value can be any integer from 0 to 65535.
If set to 0 (the initial default), no additional connections are placed in the connection pool when it is created.
Pooling: Select True (the initial default) to enable connection pooling.
Failover
Alternate Servers: Type a list of alternate database servers to which the data provider will try to connect if the primary database server is unavailable. Specifying a value for this property enables connection failover for the data provider.
For example, the following Alternate Servers value defines two alternate servers for connection failover:
Connection Retry Count: Type the number of times the data provider tries to connect to the primary server, and, if specified, the alternate servers after the initial unsuccessful attempt.
The value can be any integer from 0 to 65535.
If set to 0 (the initial default), there is no limit to the number of attempts to reconnect.
Connection Retry Delay: Type the number of seconds the data provider waits after the initial unsuccessful connection attempt before retrying a connection to the primary server, and, if specified, the alternate servers.
The initial default is 3.
This property has no effect unless the Connection Retry Count property is set to an integer value greater than 0.
Load Balancing: Select True or False to determine whether the data provider uses client load balancing in its attempts to connect to primary and alternate database servers.
If set to False (the initial default), the data provider does not use client load balancing.
Security
Certificate Store Location: Specifies the location of the X.509 certificate store used for client authentication.
Valid Values: CurrentUser | LocalMachine
If set to CurrentUser (the initial default), the application uses the X.509 certificate store specified by the current user.
If set to LocalMachine, the application uses the X.509 certificate store assigned to the local machine.
Encryption Method: The method the driver uses to encrypt data sent between the driver and the database server. If the specified encryption method is not supported by the database server, the connection fails and the driver returns an error.
Host Name in Certificate: Specifies a host name for certificate validation. This attribute provides additional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the server that was requested. Consult your SSL administrator for the correct value.
Password: Specifies the host or data store password, which may be required depending on the server configuration.
Persist Security Info: Select whether to display secure information in clear text in the ConnectionString property.
If set to True, the value of the Password connection string option is displayed in clear text.
If set to False (the initial default), the data provider does not display secure information in clear text.
User ID: Type the default Open Access SDK for ADO.NET user name used to connect to your database.
Validate Server Certificate: Determines whether the driver validates the certificate that is sent by the database server when SSL encryption is enabled (Encryption Method=1). When using SSL server authentication, any certificate sent by the server must be issued by a trusted Certificate Authority (CA). Allowing the driver to trust any certificate returned from the server even if the issuer is not a trusted CA is useful in test environments because it eliminates the need to specify truststore information on each client in the test environment.
Standard Connection
Host: Type the name or the IP address of the Pervasive PSQL server to which you want to connect. For example, you can specify a server name such as accountingserver. Or, you can specify an IPv4 address such as 199.262.22.34 or an IPv6 address such as 2001:DB8:0000:0000:8:800:200C:417A.
Port: Type the TCP port number of the listener running on the Pervasive PSQL database.
The default port number is 1583.
Server Data Source: The name of the data source on the server, such as DEMODATA.
If you enter a value for this field, the Database Name field is not available.
8. Click Test Connection. At any point during the configuration process, you can click Test Connection to attempt to connect to the data source using the connection properties specified in the Add Connection window.
• If the data provider can connect, it releases the connection and displays a Connection Established message. Click OK.
• If the data provider cannot connect because of an incorrect environment or incorrect connection value, it displays an appropriate error message.
Click OK.
Note:If you are configuring alternate servers for use with the connection failover feature, be aware that the Test Connection button tests only the primary server, not the alternate servers.
9. Click OK or Cancel. If you click OK, the values you have specified become the defaults when you connect to the data source. You can change these defaults by using this procedure to reconfigure your data source. You can override these defaults by connecting to the data source using a connection string with alternate values.
