用途
SQLAllocEnv() 分配環(huán)境句柄和相關(guān)聯(lián)的資源。
應(yīng)用程序必須在 SQLAllocConnect() 或任何其它 DB2 UDB CLI 函數(shù)之前調(diào)用此函數(shù)。在以后所有需要環(huán)境句柄作為輸入的函數(shù)調(diào)用中，都傳送 henv 值。
語法
SQLRETURN SQLAllocEnv (SQLHENV *phenv);
函數(shù)自變量
表 8. SQLAllocEnv 自變量
| 數(shù)據(jù)類型 |
自變量 |
使用 |
描述 |
| SQLHENV * |
phenv |
輸出 |
指向環(huán)境句柄的指針 |
用法
對(duì)于每個(gè)應(yīng)用程序，在任何一個(gè)時(shí)候都只能有一個(gè)活動(dòng)環(huán)境。以后任何對(duì) SQLAllocEnv() 的調(diào)用將返回現(xiàn)有的環(huán)境句柄。
缺省情況下，對(duì) SQLFreeEnv() 所作的第一個(gè)成功調(diào)用將釋放與該句柄相關(guān)聯(lián)的資源。無論成功地調(diào)用了多少次 SQLAllocEnv()，都會(huì)發(fā)生這種情況。如果環(huán)境屬性 SQL_ATTR_ENVHNDL_COUNTER 設(shè)置為 SQL_TRUE，則在釋放與句柄相關(guān)聯(lián)的資源之前，必須為每次成功的 SQLAllocEnv() 調(diào)用來調(diào)用 SQLFreeEnv()。
要確保所有的 DB2 UDB CLI 資源都保持活動(dòng)狀態(tài)，調(diào)用 SQLAllocEnv() 的程序不應(yīng)終止或離開堆棧。否則，應(yīng)用程序?qū)G失打開的游標(biāo)、語句句柄和其它已分配的資源。
返回碼
如果返回 SQL_ERROR，并且 phenv 等于 SQL_NULL_HENV，則由于沒有句柄可以與附加的診斷信息相關(guān)聯(lián)，所以不能調(diào)用 SQLError()。
如果返回碼是 SQL_ERROR，并且指向環(huán)境句柄的指針不等于 SQL_NULL_HENV，則該句柄是受限句柄。這表示該句柄只能在 SQLError() 的調(diào)用中使用以獲取更多的錯(cuò)誤信息，或者用于 SQLFreeEnv() 的調(diào)用。
診斷
表 9. SQLAllocEnv SQLSTATE
| SQLSTATE |
描述 |
說明 |
| 58004 |
系統(tǒng)錯(cuò)誤 |
不可恢復(fù)的系統(tǒng)錯(cuò)誤。 |
示例
有關(guān)代碼示例的信息，參見代碼不保證聲明信息。
/*******************************************************
** 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);
}
}
參考