SQLAllocConnect - Allocate connection handle

 

SQLAllocConnect() allocates a connection handle and associated resources within the environment that is 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
SQLHENV henv Input Environment handle
SQLHDBC * phdbc Output Pointer to connection 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

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.

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);
 
}

 

References

 

Parent topic:

DB2 UDB CLI functions