SQLAllocEnv - Allocate environment handle
SQLAllocEnv()
allocates an environment
handle and associated resources.
An application
must call this function before SQLAllocConnect()
or
any other Db2® for
i CLI
functions. The henv value is passed in all later function calls
that require an environment handle as input.
Syntax
SQLRETURN SQLAllocEnv (SQLHENV *phenv);
Function arguments
Data type | Argument | Use | Description |
---|---|---|---|
SQLHENV * | phenv | Output | Pointer to environment handle |
Usage
There can be only one active environment
at any one time per application. Any later call to SQLAllocEnv()
returns
the existing environment handle.
By default, the first successful
call to SQLFreeEnv()
releases the resources associated
with the handle. This occurs no matter how many times SQLAllocEnv()
is
successfully called. If the environment attribute SQL_ATTR_ENVHNDL_COUNTER
is set to SQL_TRUE, SQLFreeEnv() must be called once for each successful
SQLAllocEnv() call before the resources associated with the handle
are released.
To ensure that all Db2 for
i CLI resources are
kept active, the program that calls SQLAllocEnv()
should
not stop or leave the stack. Otherwise, the application loses open
cursors, statement handles, and other resources it has allocated.
Return codes
- SQL_SUCCESS
- SQL_ERROR
If SQL_ERROR is returned and phenv is equal to SQL_NULL_HENV,
then SQLError()
cannot be called because there is
no handle with which to associate additional diagnostic information.
If
the return code is SQL_ERROR and the pointer to the environment handle
is not equal to SQL_NULL_HENV, then the handle is a restricted
handle. This means the handle can only be used in a call to SQLError()
to
obtain more error information, or to SQLFreeEnv()
.
Diagnostics
SQLSTATE | Description | Explanation |
---|---|---|
58004 | System error | Unrecoverable system error |
Example
/*******************************************************
** file = basiccon.c
** - demonstrate basic connection to two datasources.
** - error handling ignored for simplicity
**
** Functions used:
**
** SQLAllocConnect SQLDisconnect
** SQLAllocEnv SQLFreeConnect
** SQLConnect SQLFreeEnv
**
**
********************************************************/
#include <stdio.h>
#include <stdlib.h>
#include "sqlcli.h"
int
connect(SQLHENV henv,
SQLHDBC * hdbc);
#define MAX_DSN_LENGTH 18
#define MAX_UID_LENGTH 10
#define MAX_PWD_LENGTH 10
#define MAX_CONNECTIONS 5
int
main()
{
SQLHENV henv;
SQLHDBC hdbc[MAX_CONNECTIONS];
/* allocate an environment handle */
SQLAllocEnv(&henv);
/* Connect to first data source */
connect(henv, &hdbc[0];);
/* Connect to second data source */
connect(henv, &hdbc[1];);
/********* Start Processing Step *************************/
/* allocate statement handle, execute statement, and so on */
/********* End Processing Step ***************************/
printf("\nDisconnecting .....\n");
SQLFreeConnect(hdbc[0]); /* free first connection handle */
SQLFreeConnect(hdbc[1]); /* free second connection handle */
SQLFreeEnv(henv); /* free environment handle */
return (SQL_SUCCESS);
}
/********************************************************************
** connect - Prompt for connect options and connect **
********************************************************************/
int
connect(SQLHENV henv,
SQLHDBC * hdbc)
{
SQLRETURN rc;
SQLCHAR server[MAX_DSN_LENGTH + 1], uid[MAX_UID_LENGTH + 1],
pwd[MAX_PWD_LENGTH
+ 1];
SQLCHAR buffer[255];
SQLSMALLINT outlen;
printf("Enter Server Name:\n");
gets((char *) server);
printf("Enter User Name:\n");
gets((char *) uid);
printf("Enter Password Name:\n");
gets((char *) pwd);
SQLAllocConnect(henv, hdbc);/* allocate a connection handle */
rc = SQLConnect(*hdbc, server, SQL_NTS, uid, SQL_NTS, pwd, SQL_NTS);
if (rc != SQL_SUCCESS) {
printf("Error while connecting to database\n");
return (SQL_ERROR);
} else {
printf("Successful Connect\n");
return (SQL_SUCCESS);
}
}