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
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® for i 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 for i 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
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 for i CLI function calls for a complete listing of typical.c.
/*******************************************************************
** 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);
}