DB2Connection.ConnectionString property
Gets or sets the string that is used to open a database connection.
- Namespace:
IBM.Data.
DB2
- Assembly:
IBM.Data.
(inDB2
IBM.Data.
)DB2
.dll
Syntax
[Visual Basic]
Public Property ConnectionString As String Implements _
IDbConnection.ConnectionString
[C#]
public string ConnectionString {get; set;}
[C++]
public: __property String* get_ConnectionString();
public: __property void set_ConnectionString(String*);
[JScript]
public function get ConnectionString() : String;
public function set ConnectionString(String);
- Implements:
- IDbConnection.ConnectionString
Property value
The connection string that includes settings, such as the database name, that are needed to establish an initial connection. The default value is an empty string (""). The maximum length is 1024 characters.
Remarks
You can use the ConnectionString property to connect to any supported data server. You can set the ConnectionString property only when the connection is closed.
The supported keywords are as follows.
Keyword | Default | Description |
---|---|---|
Database | Specifies the database alias. The maximum size of the value of the Database keyword is 255 bytes. | |
NewPWD | Specifies the new password for the user ID. | |
Password | PWD | Specifies the password. | |
Server | Specifies the server name with an optional port number for a direct connection. Use either the IPv4 notation (server_name|ip_address[:port]) or the IPv6 notation. | |
User ID | UID | Specifies the user ID. |
Keyword | Default | Description |
---|---|---|
allowDynamicSQL | True | Specifies whether an application can dynamically run any SQL statements that are not captured in a pureQueryXML file or that are captured but not bound. |
capturedOnly | False | Specifies whether to run only the SQL statements that are in the pureQueryXML file. |
captureMode | off | Specifies whether to capture information about SQL statements and the type of information to capture. An error is thrown if you set both the captureMode keyword to on and the executionMode keyword to static. |
enableDynamicSQLReplacement | False | Specifies whether to run alternative SQL statements that are in a pureQueryXML file when both the original statements and the alternative statements were not bound. |
executionMode | dynamic | Indicates whether previously captured statements are executed statically by using pureQuery technology. An error is thrown if you set both the captureMode keyword to on and the executionMode keyword to static. |
maxNonParmSQL | -1 | Specifies the maximum number of non-parameterized SQL statements to capture. This keyword applies only when the value of the captureMode keyword is ON. The maxNonParmSQL keyword value is ignored when the value of the captureMode keyword is OFF. |
propertiesGroupId | Specifies a runtime group ID in a repository that is created in a database. | |
pureQueryXML | Specifies the file name and path of the pureQuery capture file. | |
pureQueryXmlRepository | Specifies the repository that contains the pureQueryXML file data that is used with a .NET application that is enabled with pureQuery client optimization. | |
repositoryRequired | no | Specifies the pureQuery client optimization behavior if errors occur during retrieving or writing pureQuery data. |
sqlLiteralSubstitution | NOT_SET | Specifies whether to capture and consolidate SQL statements that share syntax and differ only in the literal values by having the pureQuery client substitute parameter markers for the literal values. |
traceFile | Specifies the name of the pureQuery log file. | |
traceLevel | OFF | Specifies the level of detail to write to the log file. |
Keyword | Default | Description |
---|---|---|
Authentication | Specifies the type of authentication. The following values are
acceptable:
Important: The DATA_ENCRYPT authentication type is
deprecated and might be removed in a future release. To encrypt data in-transit between clients and
Db2 databases, we recommend that you use the
Db2 database system support of Transport Layer Security (TLS). For more
information, see Encryption of data in transit
|
|
ClientAccountingString | Specifies the client accounting string that is sent to a database. | |
ClientApplicationName | Specifies the client application name that is sent to a database. | |
ClientEncAlg | Specifies whether advanced encryption standard (AES) encryption is used. The acceptable value is AES. | |
ClientUserID | Specifies the client user ID that is sent to a database. | |
ClientWorkStationName | Specifies the client workstation name that is sent to a database. | |
CodePage | 0 | Specifies the code page identifier. |
ConcurrentAccessResolution | Specifies the string values that represent the concurrent access
resolution. The following values are acceptable:
The database server defines the default behavior if the client does not provide a ConcurrentAccessResolution keyword value. For Db2 for IBM® i servers, the ConcurrentAccessResolution property is supported only by Db2 for IBM i V7R1 and later servers. |
|
ConnectNodeNumber | 0 - 999 | Specifies the database partition server to connect to. |
Connection Lifetime | 60 | Specifies the amount of time in seconds that a connection can remain idle in the connection pool. |
Connection Reset | false | Specifies whether a connection is put into the connection pool when the
connection is closed. The following values are acceptable:
|
Connection Timeout | Connect Timeout | Timeout | 0 | Specifies the time in seconds to wait for a database connection to be
established. A value of 0 indicates that there is no time limit for a database
connection to be established.
If client
reroute is enabled, the maximum waiting time is approximately double that of the specified
connection timeout because there is a second attempt to connect to the alternative
server. The connection timeout value is enforced for a connection regardless of a high availability solution being enabled. If a connection attempt fails within the time that is specified by the connection timeout value, control is returned to the application with an SQL30081N error. The error and control are returned whether all alternative servers are tried or not. |
CurrentFunctionPath | Specifies the list of schema names that can be used to resolve function references and data type references in dynamic SQL statements. | |
CurrentPackageSet | Issues the SET CURRENT PACKAGESET statement after every connection. | |
CurrentSchema | Specifies the schema name that is used to qualify all unqualified SQL objects that are used with the current connection. | |
CurrentSQLID | Specifies the SQLID that is used to qualify all unqualified SQL objects that are used with the current connection to Db2 for z/OS servers. On servers other than Db2 for z/OS, setting the CurrentSQLID keyword is equivalent to setting the CurrentSchema keyword. | |
DB2Explain | off | Determines whether the server generates Explain snapshot, Explain
table, or both types of information. The following values are acceptable:
|
DBName | Specifies the database name. This keyword is used only when connecting to Db2 for z/OS and OS/390® servers and only if the application requests base table catalog information. If many tables exist in the z/OS or OS/390 subsystem, you can specify the DBName keyword to reduce the time that it takes for the application to query table information and reduce the amount of table information in the result set. | |
DelimIdent | Specifies whether the connected Informix® database
server must support
delimited SQL identifiers. The DelimIdent keyword can be set to one of the
following values:
|
|
DisableCursorHold | false |
Indicates whether cursors that are opened on the server are left open after a
transaction is committed. The following values are acceptable:
|
Enlist | true | Indicates whether enlistment in the Distributed Transaction Coordinator
(DTC) is allowed. The following values are acceptable:
|
FetchBufferSize | 64K | Specifies the default query block size to optimize the data flow.
IBM Data Server Provider for
.NET
allows query block size only in multiples of 32K (that is 64K, 96K, 128K, 160K, 192K, 224K, and
256K). The FetchBufferSize value that is not in multiples of the 32K query block size is rounded up to the next nearest 32K boundary when they are within the range of 64K-256K. Values that are set outside the valid range (64K to 256K) are rounded to the next nearest 32K block size that is in the valid range. |
FitHighPrecisionType | ReturnException | Specifies how IBM Data Server Provider for
.NET converts the
high precision data to the .NET system types. The following values are acceptable:
|
HostVarParameter | false | Indicates whether host variable (:param) support is enabled. The
following values are acceptable:
|
Interrupt |
In Version 10.5 GA and Fix Pack 1: 1 In Version 10.5 Fix Pack 2 and later:
|
Specifies the interrupt processing mode. The following values are acceptable:
|
Isolation Level | IsolationLevel | Specifies the isolation level for the connection. The following values
are acceptable:
If you set the isolation level to Transaction, the isolation level is set to the value of Transaction.Current.IsolationLevel. . |
|
LibraryList | Specifies which libraries are to be loaded by the server for the connection. | |
Max Pool Size | No maximum | Specifies the maximum pool size. |
Min Pool Size | 0 | Specifies the minimum pool size. |
Persist Security Info | false | Indicates whether security-sensitive information is returned. The
following values are acceptable:
|
Pooling | true | Indicates whether connection pooling is disabled. The following values
are acceptable:
|
ProgramId | Specifies the program ID that is sent to a database. | |
ProgramName | Specifies the program name that is sent to a database. | |
QueryTimeout | Specifies the number of seconds to wait for an SQL statement or XQuery expression to complete. The QueryTimeout keyword indicates the default number of seconds to wait for execution of an SQL statement or XQuery expression to be completed before attempting to cancel the execution and return control to the application. This keyword overrides the default value of the DB2Command.CommandTimeout property, which is 30 seconds. | |
ResultArrayAsReturnValue | false | Indicates whether result sets from Informix user-defined routines (UDRs) are returned as parameters of type
ReturnValue. Values are as follows:
|
RetrieveXMLInBinaryFormat | false | Specifies whether XML data is returned in binary format. The following
values are acceptable:
|
RetryParameterBindingOnError | true | Indicates whether the provider re-executes failed statements. The
following values are acceptable:
|
SchemaList | Specifies a string value that contains list of schemas. The schema list is used to provide a more restrictive default, and therefore help improve performance, for those applications that list every table in the database. | |
Security | Indicates whether to use SSL as a secure transport. The SSL is the only value that can be specified for the Security keyword. | |
SessionTimeZone | Sets the value of the SESSION TIMEZONE special register on the z/OS server. | |
SkipSynonymProcessing | false |
Indicates whether IBM Data Server Provider for
.NET can send a
connection string to the DbPermission.Add method without passing the connection
string through the DB2ConnectionStringBuilder class. The following values are
acceptable:
|
SSLClientKeystash | Specifies the SSL stash file that is used for an SSL connection. | |
SSLClientKeystoredb | Specifies the SSL key database file that is used for an SSL connection. | |
SSLClientKeystoreDBPassword | Sets the keystore database password to use with CERTIFICATE authentication. | |
SSLClientLabel | Sets a unique label, which is mapped to a specific certificate to use with CERTIFICATE authentication. | |
SSLServerCertificate | Specifies the fully qualified name of a self-signed server certificate or a certificate authority (CA) certificate. | |
StatementConcentrator |
Indicates whether statement concentration is used. The following values are acceptable:
|
|
TargetPrincipal |
Specifies the fully qualified Kerberos principal name for the target server. The fully qualified Kerberos principal name of the Db2 instance owner in the form of name@REALM or instance@REALM.For Windows operating systems, the fully qualified Kerberos principal name is the logon account of the Db2 server service in the form of userid@DOMAIN, userid@xxx.xxx.xxx.com, or domain\userid. |
|
TLSVersion | Specifies the desired version of the Transport Layer Security (TLS) protocol to be used for a TLS connection. | |
TrustedContextSystemAccessToken |
TCSAT Note: This option is available starting from Db2
version 11.5.4.
|
Specifies the access token for the trusted context SYSTEM AUTHID to use with the connection. | |
TrustedContextSystemPassword | TCSPWD |
Specifies the password that corresponds to the trusted context SYSTEM AUTHID to use with the connection. |
|
TrustedContextSystemUserID | TCSUID |
Specifies the trusted context SYSTEM AUTHID to use with the connection. |
|
db2dumpSQLCodes |
Specifies whether diagnostic logs are gathered when specified SQLCODE's are encountered in a connection to the Db2 for z/OS server. Note: If db2dumpSQLCodes and
cfgRefreshInterval keywords are also mentioned in db2dsdriver.cfg, once the time specified in
cfgRefreshInterval is lapsed, the value of db2dumpSQLCodes specified in the db2dsdriver.cfg file
will take precedence.
|
|
Db2DumpSQLCodesInterval |
Specifies the time period in seconds during which the log information for the SQLCODE is not captured. |
|
TrustedContextUserRegistryName| TCURN | Sends the user registry name in the connection string while switching to a trusted connection.Should only be used when authenticating a user on a Db2 for z/OS server that is using an identity mapping service. |
Many of the settings that you can specify in the string have corresponding read-only properties. For example, the DATABASE keyword corresponds to the DB2Connection.Database property. When you set the connection string, all these read-only properties are updated except if an error is detected. In this case, none of the properties are updated. The DB2Connection properties, such as DB2Connection.Database return only default settings or those settings that you specified for the ConnectionString property.
Validation of the connection string occurs when you set it.
Resetting the ConnectionString property on a closed connection resets all connection string values and related properties, including the password.
Example
[Visual Basic, C#] The following examples create a DB2Connection object and set some of its properties in the connection string:
[Visual Basic]
Public Sub CreateDB2
Connection()
Dim myConnString As String = _
"DATABASE=SAMPLE;"
Dim myConnection As New DB2
Connection(myConnString)
myConnection.Open()
MessageBox.Show("ServerVersion: " + myConnection.ServerVersion _
+ ControlChars.Cr + "Database: " + myConnection.Database.ToString())
myConnection.Close()
End Sub
[C#]
public void CreateDB2
Connection()
{
string myConnString = "DATABASE=SAMPLE;";
DB2
Connection myConnection = new DB2
Connection(myConnString);
myConnection.Open();
MessageBox.Show("ServerVersion: " + myConnection.ServerVersion
+ "\nDatabase: " + myConnection.Database.ToString());
myConnection.Close();
}