The following connection option descriptions are listed alphabetically by the GUI name that appears on the driver Setup dialog box. The connection string attribute name, along with its short name, is listed immediately underneath the GUI name.
In most cases, the GUI name and the attribute name are the same; however, some exceptions exist. If you need to look up an option by its connection string attribute name, please refer to the alphabetical table of connection string attribute names.
Also, a few connection string attributes, for example, Password, do not have equivalent options that appear on the GUI. They are in the list of descriptions alphabetically by their attribute names.
Table 22-1 lists the connection string attributes supported by the Sybase IQ Wire Protocol driver.
|
IANAAppCodePage (IACP)
UNIX ONLY |
|
A list of alternate database servers to which the driver tries to connect if the primary database server is unavailable. Specifying a value for this option enables connection failover for the driver. The value you specify must be in the form of a string that defines the physical location of each alternate server. All of the other required connection information for each alternate server is the same as what is defined for the primary server connection.
You must specify the network address of each alternate database server or the section in the Interfaces file that contains the network connection information for the Sybase IQ database server you want to access (InterfacesFileServerName).
NOTE: The Alternate Servers option and the HA Failover Server Connection Information option are mutually exclusive.
The following example Alternate Servers values define three alternate database servers for connection failover:
(InterfacesFileServerName=Accounting, NetworkAddress="255.125.1.11, 4200", NetworkAddress="SybaseIQ2, 4200")
In this example, the network address of the last two alternates contain commas. In this case, enclose the network address with double quotation marks as shown.
where string is a valid application name.
If set to 0 (Disabled), the driver does not work with multi-threaded applications. If using the driver with single-threaded applications, this value avoids additional processing required for ODBC thread-safety standards.
where charset is the name of a character set installed on the Sybase IQ server.
For the driver to return Unicode SQL types for connections to Sybase IQ 15.0 and higher, use a value of UTF-8. Refer to the Sybase IQ server documentation for a list of valid character sets.
If your client needs to receive data in iso-8859-1 from a non-Unicode Sybase IQ server, you would specify a value of iso_1.
where x is a positive integer representing the number of connections that the connection cache can hold.
To enable the connection cache, you must set the Select Method option to 1 (Direct). Increasing the connection cache may increase performance of some applications but requires additional database resources.
Determines whether the state of connections that are removed from the connection pool for reuse by the application is reset to the initial configuration of the connection.
If set to 1 (Enabled), the state of connections removed from the connection pool for reuse by an application is reset to the initial configuration of the connection. Resetting the state can negatively impact performance because additional commands must be sent over the network to the server to reset the state of the connection.
The number of times the driver retries connection attempts to the primary database server, and if specified, alternate servers until a successful connection is established.
This option and the Connection Retry Delay connection option, which specifies the wait interval between attempts, can be used in conjunction with failover.
0 | x
where x is a positive integer from 1 to 65535.
If set to x, the driver retries connection attempts the specified number of times. If a connection is not established during the retry attempts, the driver returns an error that is generated by the last server to which it tried to connect.
The number of seconds the driver waits between connection retry attempts when Connection Retry Count is set to a positive integer.
This option and the Connection Retry Count connection option can be used in conjunction with failover.
0 | x
where x is a positive integer from 1 to 65535.
If set to x, the driver waits the specified number of seconds between connection retry attempts.
Determines whether the driver returns raiserrors when the next statement is executed or handles them separately.
If set to 0 (Default), raiserrors are handled separately from surrounding statements. The error is returned when a raiserror is processed (for example, resulting from SQLExecute, SQLExecDirect, or SQLMoreResults). The result set is empty.
If set to 1 (Microsoft compatible), raiserrors are returned when the next statement is processed, and the cursor is positioned on the first row of the subsequent result set. This could result in multiple raiserrors being returned on a single execute.
where string is the name of a data source.
A list of database names that will appear in the drop-down list of the logon dialog box (see “Using a Logon Dialog Box” for a description).
where database_list is a comma-separated list of database names that will appear in the drop-down list of the logon dialog box.
where database_name is the name of a valid database. If you do not specify a value, the default is the database defined by the system administrator for each user.
An optional long description of a data source. This description is not used as a runtime connection attribute, but does appear in the ODBC.INI section of the Registry and in the odbc.ini file.
where string is a description of a data source.
The maximum length of data (in KB) the driver can fetch from long columns in a single round trip and the maximum length of data that the driver can send using the SQL_DATA_AT_EXEC parameter.
This option also applies to binding long parameters in chunks. The driver truncates any data passed in a Long/LOB SQL_DATA_AT_EXEC parameter to the size specified.
The value must be in multiples of 1024 (for example, 1024, 2048). You need to increase the default value if the total size of any Long data exceeds 1 MB. This value is multiplied by 1024 to determine the total maximum length of fetched data. For example, if you enter a value of 2048, the maximum length of data would be 1024 x 2048, or 2097152 (2 MB).
Determines whether the driver fails the entire failover process or continues with the process if errors occur while trying to reestablish a lost connection.
The Alternate Servers option specifies one or multiple alternate servers for failover and is required for all failover methods.
If set to 0 (Non-Atomic), the driver continues with the failover process and posts any errors on the statement on which they occur.
If set to 1 (Atomic) the driver fails the entire failover process if an error is generated as the result of anything other than executing and repositioning a Select statement. If an error is generated as a result of repositioning a result set to the last row position, the driver continues with the failover process, but generates a warning that the Select statement must be reissued.
If set to 2 (Atomic Including Repositioning), the driver fails the entire failover process if any error is generated as the result of restoring the state of the connection or the state of work in progress.
If set to 3 (Disable Integrity Check), the driver does not verify that the rows that were restored during the failover process match the original rows. This value applies only when Failover Mode is set to 2 (Select).
The Alternate Servers option specifies one or multiple alternate servers for failover and is required for all failover methods.
If set to 1 (Extended Connection), the driver provides failover protection for new and lost connections, but not any work in progress.
If set to 2 (Select), the driver provides failover protection for new and lost connections. In addition, it preserves the state of work performed by the last Select statement executed.
Specifies whether the driver tries to connect to the primary and an alternate server at the same time.
This attribute applies only when Failover Mode is set to 1 (Extended Connection) or 2 (Select) and at least one alternate server is specified.
The Alternate Servers option specifies one or multiple alternate servers for failover and is required for all failover methods.
If set to 0 (Disabled), the driver tries to connect to an alternate server only when failover is caused by an unsuccessful connection attempt or a lost connection. This value provides the best performance, but your application typically experiences a short wait while the failover connection is attempted.
If set to 1 (Enabled), the driver tries to connect to the primary and an alternate server at the same time. This can be useful if your application is time-sensitive and cannot absorb the wait for the failover connection to succeed.
The number of rows the driver retrieves from the server for a fetch. This is not the number of rows given to the user. You should use Fetch Array Size in conjunction with Select Method.
where x is a positive integer specifying the number of rows.
Determines whether the driver returns column values with the time data type as the ODBC data type SQL_TYPE_TIME or SQL_TYPE_TIMESTAMP.
If set to 1 (Enabled), the driver returns column values with the time data type as the ODBC data type SQL_TYPE_TIME. The fractional seconds portion of the value is truncated.
If set to 0 (Disabled), the driver returns column values with the time data type as the ODBC data type SQL_TYPE_TIMESTAMP. The fractional seconds portion of the value is preserved. Time columns are not searchable when they are described and fetched as timestamp
NOTE: When returning time with fractional seconds data as SQL_TYPE_TIMESTAMP, the Year, Month and Day parts of the timestamp must be set to zero.
The network address of the High Availability (HA) Failover server to be used in the event of a connection loss. The driver detects the dropped connection and automatically reconnects to the specified HA Failover server. This option is valid only for Sybase IQ servers that have the High Availability Failover feature enabled.
IP_ address is the IP address that uniquely identifies the HA Failover server.
port_number is the port number assigned to the listener process on the HA Failover server.
server_name is a name that uniquely identifies the HA Failover server. You can use this format if your environment supports named servers.
NOTE: The HA Failover Server Connection Information option and the Alternate Servers option are mutually exclusive.
IANAAppCodePageAn Internet Assigned Numbers Authority (IANA) value. You must specify a value for this option if your application is not Unicode‑enabled or if your database character set is not Unicode. Refer to Chapter 4 “Internationalization, Localization, and Unicode” in the DataDirect Connect Series for ODBC Reference for details.
If the driver does not find an IANAAppCodePage value, the driver uses the default value of 4 (ISO 8859-1 Latin-1).
where IANA_code_page is one of the valid values listed in Chapter 1 “Values for the Attribute IANAAppCodePage” in the DataDirect Connect Series for ODBC Reference. The value must match the database character encoding and the system locale.
A SQL command that is issued immediately after connecting to the database to manage session settings.
NOTE: If the statement fails to execute, the connection fails and the driver reports the error returned from the server.
where SQL_command is a valid SQL command that is supported by the database.
Interfaces Filewhere file_dir is the directory to the Interfaces file.
If unspecified and a value is specified for the Server Name option, the driver looks for the path name of the Interfaces file in the Registry under HKEY_LOCAL_MACHINE\SOFTWARE\DataDirect\InterfacesFile. If this Registry value is empty, the driver will try to open the SQL.INI file found in the same directory where the driver is located and use it as the Interfaces file.
where charset is the national character set installed on the Sybase IQ server.
The number of seconds to keep inactive connections open in a connection pool. An inactive connection is a database session that is not associated with an ODBC connection handle, that is, a connection in the pool that is not in use by an application.
0 | x
where x is a positive integer that specifies a number of seconds.
If set to x, inactive connections are closed after the specified number of seconds passes.
Determines whether the driver uses client load balancing in its attempts to connect to the database servers (primary and alternate). You can specify one or multiple alternate servers by setting the Alternate Servers option.
If set to 1 (Enabled), the driver uses client load balancing and attempts to connect to the database servers (primary and alternate servers) in random order.
If set to 0 (Disabled), the driver does not use client load balancing and connects to each server based on their sequential order (primary server first, then, alternate servers in the order they are specified).
NOTE: This option has no effect unless alternate servers are defined for the Alternate Servers connection option.
The number of seconds the driver waits for a connection to be established before returning control to the application and generating a timeout error. To override the value that is set by this connection option for an individual connection, set a different value in the SQL_ATTR_LOGIN_TIMEOUT connection attribute using the SQLSetConnectAttr() function.
-1 | 0 | x
where x is a positive integer that specifies a number of seconds.
If set to -1, the connection request does not time out. The driver silently ignores the SQL_ATTR_LOGIN_TIMEOUT attribute.
If set to 0, the connection request does not time out, but the driver responds to the SQL_ATTR_LOGIN_TIMEOUT attribute.
If set to x, the connection request times out after the specified number of seconds unless the application overrides this setting with the SQL_ATTR_LOGIN_TIMEOUT attribute.
The maximum number of connections allowed within a single connection pool. When the maximum number of connections is reached, no additional connections can be created in the connection pool.
The minimum number of connections that are opened and placed in a connection pool, in addition to the active connection, when the pool is created. The connection pool retains this number of connections, even when some connections exceed their Load Balance Timeout value.
0 | x
where x is an integer from 1 to 65535.
For example, if set to 5, the start-up number of connections in the pool is 5 in addition to the current existing connection.
server_name | IP_address
server_name is the Sybase IQ server name specified as: named_server, port_number. For example, you can enter SyIQserver, 2638.
IP_address is the Sybase IQ server address specified as: IP_address, port_number. For example, you can enter 199.226.224.34, 2638. The IP address can be specified in either IPv4 or IPv6 format, or a combination of the two. See “Using IP Addresses” for details about these formats.
Determines the number of bytes for each database protocol packet that is transferred from the database server to the client machine. Adjusting the packet size can improve performance. The optimal value depends on the typical size of data that is inserted, updated, or returned by the application and the environment in which it is running. Typically, larger packet sizes work better for large amounts of data. For example, if an application regularly returns character values that are 10,000 characters in length, using a value of 32 (16 KB) typically results in improved performance.
NOTE: The ODBC connection attribute SQL_ATTR_PACKET_SIZE provides the same functionality as the Packet Size option; however, SQL_ATTR_PACKET_SIZE and the Packet Size option are mutually exclusive. If Packet Size is specified, the driver returns the message Driver Not Capable if an application attempts to call SQLSetConnectAttr() for SQL_ATTR_PACKET_SIZE. If you do not set the Packet Size option, application calls to SQLSetConnectAttr() for SQL_ATTR_PACKET_SIZE are accepted by the driver.
-1 | 0 | x
If set to x, an integer from 1 to 127, the driver uses a packet size that is a multiple of 512 bytes. For example, PacketSize=8 means to set the packet size to 8 * 512 bytes (4096 bytes).
The password that the application uses to connect to your database. The Password option cannot be specified through the driver Setup dialog box and should not be stored in a data source. It is specified through the Logon dialog box or a connection string.
where pwd is a valid password.
The number of seconds for the default query timeout for all statements that are created by a connection. To override the value set by this connection option for an individual statement, set a different value in the SQL_ATTR_QUERY_TIMEOUT statement attribute on the SQLSetStmtAttr() function.
-1 | 0 | x
where x is a positive integer that specifies a number of seconds.
If set to -1, the query does not time out. The driver silently ignores the SQL_ATTR_QUERY_TIMEOUT attribute.
If set to 0, the query does not time out, but the driver responds to the SQL_ATTR_QUERY_TIMEOUT attribute.
If set to x, all queries time out after the specified number of seconds unless the application overrides this value by setting the SQL_ATTR_QUERY_TIMEOUT attribute.
Specifies how the driver handles code page conversion errors that occur when a character cannot be converted from one character set to another.
An error message or warning can occur if an ODBC call causes a conversion error, or if an error occurs during code page conversions to and from the database or to and from the application. The error or warning generated is Code page conversion error encountered. In the case of parameter data conversion errors, the driver adds the following sentence: Error in parameter x, where x is the parameter number. The standard rules for returning specific row and column errors for bulk operations apply.
If set to 0 (Ignore Errors), the driver substitutes 0x1A for each character that cannot be converted and does not return a warning or error.
If set to 1 (Return Error), the driver returns an error instead of substituting 0x1A for unconverted characters.
If set to 2 (Return Warning), the driver substitutes 0x1A for each character that cannot be converted and returns a warning.
If set to 0 (Cursor), database cursors are used. In some cases performance degradation can occur when performing large numbers of sequential Select statements because of the amount of overhead associated with creating database cursors.
If set to 1 (Direct), Select statements are run directly without using database cursors, and the data source is limited to one active statement.
The name of the section in the Interfaces file containing the network connection information for the Sybase IQ server. Typically, the section name is the host name of the Sybase IQ server.
where section_name is a section in the Interfaces file containing the network connection information for the Sybase IQ server.
Determines whether the driver sets fractional seconds to zero (0) when converting data from the TIME data type to TIMESTAMP, CHAR, or WCHAR data types.
If set to 1 (Enabled), the driver converts fractional seconds to zero when converting the TIME data type.
If set to 0 (Disabled), the driver does not set fractional seconds to zero when converting the TIME data type.
The default user ID that is used to connect to your database. Your ODBC application may override this value or you may override it in the logon dialog box or connection string.
where userid is a valid user ID with permissions to access the database.
where ID is workstation ID use by the client machine.