Prayer

SQLAllocEnv — 分配环境句柄

用途

SQLAllocEnv() 分配环境句柄和相关联的资源。

应用程序必须在 SQLAllocConnect() 或任何其它 DB2 UDB CLI 函数之前调用此函数。在以后所有需要环境句柄作为输入的函数调用中，都传送 henv 值。

语法

SQLRETURN SQLAllocEnv (SQLHENV    *phenv);

函数自变量

表 8. SQLAllocEnv 自变量

数据类型	自变量	使用	描述
SQLHENV *	phenv	输出	指向环境句柄的指针

用法

对于每个应用程序，在任何一个时候都只能有一个活动环境。以后任何对 SQLAllocEnv() 的调用将返回现有的环境句柄。

缺省情况下，对 SQLFreeEnv() 所作的第一个成功调用将释放与该句柄相关联的资源。无论成功地调用了多少次 SQLAllocEnv()，都会发生这种情况。如果环境属性 SQL_ATTR_ENVHNDL_COUNTER 设置为 SQL_TRUE，则在释放与句柄相关联的资源之前，必须为每次成功的 SQLAllocEnv() 调用来调用 SQLFreeEnv()。

要确保所有的 DB2 UDB CLI 资源都保持活动状态，调用 SQLAllocEnv() 的程序不应终止或离开堆栈。否则，应用程序将丢失打开的游标、语句句柄和其它已分配的资源。

返回码

• SQL_SUCCESS
• SQL_ERROR

如果返回 SQL_ERROR，并且 phenv 等于 SQL_NULL_HENV，则由于没有句柄可以与附加的诊断信息相关联，所以不能调用 SQLError()。

如果返回码是 SQL_ERROR，并且指向环境句柄的指针不等于 SQL_NULL_HENV，则该句柄是受限句柄。这表示该句柄只能在 SQLError() 的调用中使用以获取更多的错误信息，或者用于 SQLFreeEnv() 的调用。

诊断

表 9. SQLAllocEnv SQLSTATE

SQLSTATE	描述	说明
58004	系统错误	不可恢复的系统错误。

示例

有关代码示例的信息，参见代码不保证声明信息。

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

参考

• SQLAllocConnect — 分配连接句柄
• SQLFreeEnv — 释放环境句柄
• SQLAllocStmt — 分配语句句柄