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