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 — 分配語句句柄