SQLDriverConnect

SQLDriverConnect

SQLDriverConnect() is alternative to SQLConnect(). This function supports the connection string that requires more information than three arguments (DSN, user ID, and password) of SQLConnect().

SQLDriverConnect() provides connection attributes as follows:

• host IP or host name

• One or more user IDs

• One or more passwords

• port number

• NLS_USE

• TIMEOUT setting

SQLDriverConnectW() as a Unicode string supports same execution as SQLDriverConnect().

Syntax

SQLRETURN  SQLDriverConnect (
    SQLHDBC         dbc,
    SQLPOINTER      windowHandle,
    SQLCHAR *       InConnectionString,
    SQLSMALLINT     length1,
    SQLCHAR *       OutConnectionString,
    SQLSMALLINT     bufferLength,
    SQLSMALLINT *   strLength2Ptr,
    SQLSMALLINT     DriverCompletion );

Arguments

Data Type	Argument	In/Ouput	Description
SQLHDBC	dbc	Input	Connection handler
SQLPOINTER	windowHandle	Input	Not used.
SQLCHAR*	InConnectionString	Input	A complete connection string A partial connection string Empty character string. For more information see the following description section.
SQLSMALLINT	length1	Input	The length, in bytes, of the contents of the InConnectionString argument
SQLCHAR *	OutConnectionString	Output	Not used
SQLSMALLINT	bufferLength	Input	Not used
SQLSMALLINT *	strLength2Ptr	Output	Not used
SQLSMALLINT	DriverCompletion	Input	Not used

Return Values

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA
SQL_INVALID_HANDLE
SQL_ERROR

Description

This connection string is used to transmit one or more values needed for completion of the connection. The contents of the connection string and DriverCompletion determine the connection method.

Each keyword has following attributes:

• DSN
  It can be a host name, an IPv4 address, or an IPv6 address. An IPv6 address must be enclosed by a left square bracket([) and a right square bracket(]). For example, in the case of localhost (meaning this computer), localhost can be specified as the host name, 127.0.0.1 as the IPv4 address, or [::1] as the IPv6 address. For more information about the IPv6 address notation, please refer to the Altibase Administrator's Manual.
• UID
  User Id
• PWD
  Password
• CONNTYPE
  Connection methods (1 : TCP/IP, 2 : UNIX DOMAIN, 3 : IPC)
• PRIVILEGE
  If this property is set to SYSDBA, the SYS account can connect to the Altibase server with the SYSDBA privilege. With the SYSDBA privilege, the user can connect to the server via any connection method(TCP/IP, UNIX DOMAIN, or IPC); when connected via IPC with the SYSDBA privilege, however, SHUTDOWN NORMAL and SHUTDOWN IMMEDIATE cannot be executed.
• PORT_NO
  Connection port number
• NLS_USE
  NLS language. such as US7ASCII for English, KO16KSC5601 for Korean
• NLS_NCHAR_LITERAL_REPLACE
  This checks to use NCHAR with analyzing SQL statements. (0: doesn't analyze SQL statments, 1: analyzes SQL statements. This causes worse performance.)
• TIMEOUT
  Time waiting for server connection attemption. The default value is 3 seconds.
• CONNECTION_TIMEOUT
  Set timeout value to prevent blocking that may occur in select() or poll() in an unstable network.
• DATE_FORMAT
  Date Format. The default date format is YYYY/MM/DD HH:MI:SS.
• IpcFilePath
  Client can't connect to server through IPC in Unix because they have different socket paths if having different ALTIBASE_HOMEs each other. You can communicate with Unix domain by using ALTIBASE_HOME/trc/cm-ipc, and then you can get information of shared memory.
• APP_INFO
  This sets information of program you connect to, and you can check this with the following statement.select CLIENT_APP_INFO from v$session;
• AUTOCOMMIT
  This denotes to set AUTOCOMMIT mode (ON or OFF).
• LONGDATACOMPAT
  This enables BLOB and CLOB to be types for ODBC when you connect to ODBC with data whose type is BLOB or CLOB (YES or No).

• DEFER_PREPARES
  This property specifies whether or not communication to the server is to be deferred(ON, OFF) when SQLPrepare is called. If this property is set to ON, prepare requests are not sent to the server until the SQLExecute function is called, even if SQLPrepare is called. If this property is set to OFF, however, prepare requests are immediately sent to the server when SQLPrepare is called.
  On omission, the default value for this property is OFF.
  The deferred prepare feature enhances application performance by minimizing network flow.

  InConnectionString :
  DSN=192.168.1.11;UID=SYS;PWD=MANAGER;CONNTYPE=1;NLS_USE=KO16KSC5601;PORT_NO=20202;TIMEOUT=5; CONNECTION_TIMEOUT=10;DATE_FORMAT=DD-MON-YYYY;IPCFILEPATH="…/cm-ipc"
  

• SOCK_RCVBUF_BLOCK_RATIO
  Set the size of the socket receive buffer in 32K increments. For example, if this property value is set to 2, the socket receive buffer size is set to 64K. If the value of this attribute is not set, refer to the ALTIBASE_SOCK_RCVBUF_BLOCK_RATIO environment variable for the value. Set it. The default value is 0.
  If the maximum socket receive buffer size among the TCP kernel parameters is set to less than the socket receive buffer size set by this property value, this property may be ignored or an error may be generated depending on the OS. ('Linux.core.rmem_max' TCP kernel parameter).

Restrictions

• The user can access to database remotely with sysdba privilege, but can't start up database.

• When the user tries to contact local server with sysdba privilege through TCP/IP in the state of no remote access specified in REMOTE_SYSDBA_ENABLE and no loop back (127.0.0.1), local server can regard this trial as remote access and then can't allow it.

  $ isql -u sys -p manager -s 192.168.3.91 -port 11515 -sysdba ISQL_CONNECTION = TCP, SERVER = 192.168.3.91, PORT_NO = 11515
  [ERR-410C8 : remote access as SYSDBA not allowed]
  

• If the values of PORT_NO and NLS_USE aren't specified in connection string, you should set same value of environment variable below as the value specified in property file. However, if you want to set national-character figurative constant instead of environment variable, you should specify ALTIBASE_NLS_NCHAR_LITERAL_REPLACE as 1. This causes parsing additionally

  export ALTIBASE_PORT_NO=20300  
  export ALTIBASE_NLS_USE=US7ASCII  
  export ALTIBASE_NLS_NCHAR_LITERAL_REPLACE=0
  

Restriction for Deferred prepare

When the deferred prepare feature is activated(ON), calls to SQLPrepare() within an application always return SQL_SUCCESS; if prepare requests are running on the server, however, errors can be returned.

If SQLPrepare is called, and thereafter, a function which requires the result of the prepared execution is called, the Altibase CLI driver immediately sends a prepare request to the server and retrieves the result, instead of waiting for the SQLExecute function to be called - even if the DEFER_PREPARES property is set to ON. The following functions require the result of a prepared execution prior to its execution: SQLExecute, SQLColAttribute, SQLDescribeCol, SQLDescribeParam, SQLNumParams, SQLNumResultCols

Diagnosis

SQLSTATE	Description	Comments
08001	Unable to establish connection	The client is unable to connect to a server.
08002	The connection name is in use	The connection handle dbc is already connected to the database and still open.
08S01	Communication channel error	Communication line fails before function processing completes between Altibase CLI driver and DB
HY000	General error	Character set does not exist
HY001	Memory allocation error	Cannot allocate the requested memory for the Altibase CLI driver to execute the function and complete execution.

Related Functions

SQLAllocHandle
SQLConnect
SQLDisconnect
SQLFreeHandle
SQLSetConnectAttr

Example

< Refer to: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp >

sprintf(connStr,
        "DSN=127.0.0.1;UID=%s;PWD=%s;CONNTYPE=%d;NLS_USE=%s", /* ;PORT_NO=20300", */
        USERNAME, PASSWD, 1, NLS);

/* establish connection */
if (SQLDriverConnect( dbc, NULL, (SQLCHAR *)connStr, SQL_NTS,
                      NULL, 0, NULL,
                      SQL_DRIVER_NOPROMPT ) != SQL_SUCCESS)
{
    execute_err(dbc, SQL_NULL_HSTMT, "SQLDriverConnect");
    return SQL_ERROR;
}