SQLAllocConnect - Allocate connection handle

Purpose

SQLAllocConnect() allocates a connection handle and associated resources within the environment identified by the input environment handle. Call SQLGetInfo() with fInfoType set to SQL_ACTIVE_CONNECTIONS, to query the number of connections that can be allocated at any one time.

SQLAllocEnv() must be called before calling this function.

Syntax

SQLRETURN SQLAllocConnect (SQLHENV    henv,
                           SQLHDBC    *phdbc);

Function arguments

Table 1. SQLAllocConnect arguments
Data type	Argument	Use	Description
SQLHDBC *	phdbc	Output	Pointer to connection handle
SQLHENV	henv	Input	Environment handle

Usage

The output connection handle is used by DB2^® UDB CLI to reference all information related to the connection, including general status information, transaction state, and error information.

If the pointer to the connection handle (phdbc) points to a valid connection handle allocated by SQLAllocConnect(), the original value is overwritten as a result of this call. This is an application programming error and is not detected by DB2 UDB CLI

Return codes

SQL_SUCCESS
SQL_ERROR
SQL_INVALID_HANDLE

If SQL_ERROR is returned, the phdbc argument is set to SQL_NULL_HDBC. The application should call SQLError() with the environment handle (henv), with hdbc set to SQL_NULL_HDBC, and with hstmt set to SQL_NULL_HSTMT.

Diagnostics

Table 2. SQLAllocConnect SQLSTATEs
CLI SQLSTATE	Description	Explanation
HY001	Memory allocation failure	The driver is unable to allocate memory required to support the processing or completion of the function.
HY009	Argument value that is not valid	phdbc is a null pointer.

Example

The following example shows how to obtain diagnostic information for the connection and the environment. For more examples of using SQLError(), refer to Example: Interactive SQL and the equivalent DB2 UDB CLI function calls for a complete listing of typical.c.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

/*******************************************************************
** initialize
**  - allocate environment handle
**  - allocate connection handle
**  - prompt for server, user id, & password
**  - connect to server
*******************************************************************/
 
int initialize(SQLHENV *henv,
              SQLHDBC *hdbc)
{
SQLCHAR     server[SQL_MAX_DSN_LENGTH],
            uid[30],
            pwd[30];
SQLRETURN   rc;
 
    SQLAllocEnv (henv);         /* allocate an environment handle   */
    if (rc != SQL_SUCCESS )
        check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
 
    SQLAllocConnect (*henv, hdbc);  /* allocate a connection handle     */
    if (rc != SQL_SUCCESS )
        check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
 
    printf("Enter Server Name:\n");
    gets(server);
    printf("Enter User Name:\n");
    gets(uid);
    printf("Enter Password Name:\n");
    gets(pwd);
 
    if (uid[0] == '\0')
    {   rc = SQLConnect (*hdbc, server, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS);
        if (rc != SQL_SUCCESS )
            check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
    }
    else
    {   rc = SQLConnect (*hdbc, server, SQL_NTS, uid, SQL_NTS, pwd, SQL_NTS);
        if (rc != SQL_SUCCESS )
            check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
    }
}/* end initialize */
 
 
/*******************************************************************/
int check_error (SQLHENV    henv,
                 SQLHDBC    hdbc,
                 SQLHSTMT   hstmt,
                 SQLRETURN  frc)
{
SQLRETURN   rc;
 
    print_error(henv, hdbc, hstmt);
 
    switch (frc){
    case SQL_SUCCESS : break;
    case SQL_ERROR :
    case SQL_INVALID_HANDLE:
        printf("\n ** FATAL ERROR, Attempting to rollback transaction **\n");
        rc = SQLTransact(henv, hdbc, SQL_ROLLBACK);
        if (rc != SQL_SUCCESS)
            printf("Rollback Failed, Exiting application\n");
        else
            printf("Rollback Successful, Exiting application\n");
        terminate(henv, hdbc);
        exit(frc);
        break;
    case SQL_SUCCESS_WITH_INFO :
        printf("\n ** Warning Message, application continuing\n");
        break;
    case SQL_NO_DATA_FOUND :
        printf("\n ** No Data Found ** \n");
        break;
    default :
        printf("\n ** Invalid Return Code ** \n");
        printf(" ** Attempting to rollback transaction **\n");
        SQLTransact(henv, hdbc, SQL_ROLLBACK);
        terminate(henv, hdbc);
        exit(frc);
        break;
    }
    return(SQL_SUCCESS);
 
}