SQLAllocEnv - Allocate environment handle

Purpose

SQLAllocEnv() allocates an environment handle and associated resources.

An application must call this function before SQLAllocConnect() or any other DB2^® UDB 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

Table 1. SQLAllocEnv 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 UDB 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

Table 2. SQLAllocEnv SQLSTATEs
SQLSTATE	Description	Explanation
58004	System error	Unrecoverable system error

Example

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

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