Prayer

SQLAllocEnv — 分配環(huán)境句柄

用途

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)境句柄的指針

用法

對于每個(gè)應(yīng)用程序，在任何一個(gè)時(shí)候都只能有一個(gè)活動環(huán)境。以后任何對 SQLAllocEnv() 的調(diào)用將返回現(xiàn)有的環(huán)境句柄。

缺省情況下，對 SQLFreeEnv() 所作的第一個(gè)成功調(diào)用將釋放與該句柄相關(guān)聯(lián)的資源。無論成功地調(diào)用了多少次 SQLAllocEnv()，都會發(fā)生這種情況。如果環(huán)境屬性 SQL_ATTR_ENVHNDL_COUNTER 設(shè)置為 SQL_TRUE，則在釋放與句柄相關(guān)聯(lián)的資源之前，必須為每次成功的 SQLAllocEnv() 調(diào)用來調(diào)用 SQLFreeEnv()。

要確保所有的 DB2 UDB CLI 資源都保持活動狀態(tài)，調(diào)用 SQLAllocEnv() 的程序不應(yīng)終止或離開堆棧。否則，應(yīng)用程序?qū)G失打開的游標(biāo)、語句句柄和其它已分配的資源。

返回碼

• SQL_SUCCESS
• SQL_ERROR

如果返回 SQL_ERROR，并且 phenv 等于 SQL_NULL_HENV，則由于沒有句柄可以與附加的診斷信息相關(guān)聯(lián)，所以不能調(diào)用 SQLError()。

如果返回碼是 SQL_ERROR，并且指向環(huán)境句柄的指針不等于 SQL_NULL_HENV，則該句柄是受限句柄。這表示該句柄只能在 SQLError() 的調(diào)用中使用以獲取更多的錯誤信息，或者用于 SQLFreeEnv() 的調(diào)用。

診斷

表 9. SQLAllocEnv SQLSTATE

SQLSTATE	描述	說明
58004	系統(tǒng)錯誤	不可恢復(fù)的系統(tǒng)錯誤。

示例

有關(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);
}
}

參考

• SQLAllocConnect — 分配連接句柄
• SQLFreeEnv — 釋放環(huán)境句柄
• SQLAllocStmt — 分配語句句柄