SQLSetEnvAttr 함수

규칙
도입된 버전: ODBC 3.0 표준 준수: ISO 92

요약
SQLSetEnvAttr는 환경의 측면을 제어하는 특성을 설정합니다.

구문

  
SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);  

인수

EnvironmentHandle
[입력] 환경 핸들입니다.

특성
[입력] "Comments"에 나열된 설정할 특성입니다.

ValuePtr
[입력] 특성과 연결할 값에 대한 포인터입니다. 특성 값에 따라 ValuePtr은 32비트 정수 값이거나 null로 끝나는 문자열을 가리킵니다.

StringLength
[입력] ValuePtr이 문자열 또는 이진 버퍼를 가리키는 경우 이 인수는 *ValuePtr의 길이여야 합니다. 문자열 데이터의 경우 이 인수는 문자열의 바이트 수를 포함해야 합니다.

ValuePtr이 정수이면 StringLength는 무시됩니다.

반품

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR 또는 SQL_INVALID_HANDLE.

진단

SQLSetEnvAttr가 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_ENV HandleType 및 EnvironmentHandle 핸들을 사용하여 SQLGetDiagRec 를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 일반적으로 SQLSetEnvAttr에서 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각 값을 설명합니다. 표기법 "(DM)"은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR. 드라이버가 환경 특성을 지원하지 않는 경우 연결 시간 동안에만 오류를 반환할 수 있습니다.

SQLSTATE	Error	설명
01000	일반 경고	드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
01S02	옵션 값이 변경됨	드라이버는 ValuePtr에 지정된 값을 지원하지 않으며 비슷한 값을 대체했습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
HY000	일반 오류	특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다.
HY001	메모리 할당 오류	드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다.
HY009	null 포인터를 잘못 사용했습니다.	Attribute 인수는 문자열 값이 필요한 환경 특성을 식별했으며 ValuePtr 인수는 null 포인터였습니다.
HY010	함수 시퀀스 오류	(DM) EnvironmentHandle에 연결 핸들이 할당되었습니다. (DM) SQL_ATTR_ODBC_VERSION SQLSetEnvAttr로 설정되지 않았으며 특성이 SQL_ATTR_ODBC_VERSION 같지 않습니다. SQLAllocHandleStd를 사용하는 경우 SQL_ATTR_ODBC_VERSION 명시적으로 설정할 필요가 없습니다.
HY013	메모리 관리 오류	메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다.
HY024	잘못된 특성 값	지정된 특성 값이 지정된 경우 ValuePtr에 잘못된 값이 지정되었습니다.
HY090	잘못된 문자열 또는 버퍼 길이	StringLength 인수는 0보다 작지만 SQL_NTS 않았습니다.
HY092	잘못된 특성/옵션 식별자	(DM) 인수 특성 에 지정된 값이 드라이버에서 지원하는 ODBC 버전에 대해 유효하지 않습니다.
HY117	알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다.	(DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요.
HYC00	선택적 기능이 구현되지 않음	인수 특성 에 지정된 값은 드라이버에서 지원하는 ODBC 버전의 유효한 ODBC 환경 특성이지만 드라이버에서 지원되지 않았습니다. (DM) Attribute 인수가 SQL_ATTR_OUTPUT_NTS ValuePtr 이 SQL_FALSE.

주석

애플리케이션은 환경에 할당된 연결 핸들이 없는 경우에만 SQLSetEnvAttr를 호출할 수 있습니다. 환경에 대한 애플리케이션에서 설정한 모든 환경 특성은 환경에서 SQLFreeHandle이 호출될 때까지 유지됩니다. ODBC 3.x에서 둘 이상의 환경 핸들을 동시에 할당할 수 있습니다.

ValuePtr를 통해 설정된 정보 형식은 지정된 특성에 따라 달라집니다. SQLSetEnvAttr 는 null로 끝나는 문자 문자열 또는 32비트 정수 값의 두 가지 형식 중 하나로 특성 정보를 허용합니다. 각 형식은 특성의 설명에 나와 있습니다.

드라이버별 환경 특성이 없습니다.

SQLSetEnvAttr를 호출하여 연결 특성을 설정할 수 없습니다. 이렇게 하면 SQLSTATE HY092(잘못된 특성/옵션 식별자)가 반환됩니다.

특성	ValuePtr 콘텐츠
SQL_ATTR_CONNECTION_POOLING(ODBC 3.8)	환경 수준에서 연결 풀링을 사용하거나 사용하지 않도록 설정하는 32비트 SQLUINTEGER 값입니다. 다음 값이 사용됩니다. SQL_CP_OFF = 연결 풀링이 해제되었습니다. 기본값입니다. SQL_CP_ONE_PER_DRIVER = 각 드라이버에 대해 단일 연결 풀이 지원됩니다. 풀의 모든 연결은 하나의 드라이버와 연결됩니다. SQL_CP_ONE_PER_HENV = 각 환경에 대해 단일 연결 풀이 지원됩니다. 풀의 모든 연결은 하나의 환경과 연결됩니다. SQL_CP_DRIVER_AWARE = 사용 가능한 경우 드라이버의 연결 풀 인식 기능을 사용합니다. 드라이버가 연결 풀 인식을 지원하지 않는 경우 SQL_CP_DRIVER_AWARE 무시되고 SQL_CP_ONE_PER_HENV 사용됩니다. 자세한 내용은 드라이버 인식 연결 풀링을 참조 하세요. 일부 드라이버가 지원되고 일부 드라이버가 연결 풀 인식을 지원하지 않는 환경에서는 SQL_CP_DRIVER_AWARE 지원 드라이버에서 연결 풀 인식 기능을 사용하도록 설정할 수 있지만 연결 풀 인식 기능을 지원하지 않는 드라이버에서 SQL_CP_ONE_PER_HENV 설정하는 것과 같습니다. 연결 풀링을 사용하려면 SQLSetEnvAttr를 호출하여 SQL_ATTR_CONNECTION_POOLING 특성을 SQL_CP_ONE_PER_DRIVER 또는 SQL_CP_ONE_PER_HENV 설정합니다. 애플리케이션에서 연결 풀링을 사용하도록 설정할 공유 환경을 할당하기 전에 이 호출을 수행해야 합니다. SQLSetEnvAttr 호출의 환경 핸들은 null로 설정되므로 SQL_ATTR_CONNECTION_POOLING 프로세스 수준 특성이 됩니다. 연결 풀링을 사용하도록 설정한 후 애플리케이션은 inputHandle 인수를 SQL_HANDLE_ENV 설정하여 SQLAllocHandle 을 호출하여 암시적 공유 환경을 할당합니다. 연결 풀링을 사용하도록 설정하고 애플리케이션에 대해 공유 환경을 선택한 후에는 이 특성을 설정할 때 SQLSetEnvAttr가 null 환경 핸들로 호출되므로 해당 환경에 대해 SQL_ATTR_CONNECTION_POOLING 다시 설정할 수 없습니다. 연결 풀링이 공유 환경에서 이미 사용하도록 설정된 동안 이 특성이 설정된 경우 이 특성은 이후에 할당되는 공유 환경에만 영향을 줍니다. 환경에서 연결 풀링을 사용하도록 설정할 수도 있습니다. 환경 연결 풀링에 대해 다음 사항에 유의하세요. - NULL 핸들에서 연결 풀링을 사용하도록 설정하는 것은 프로세스 수준 특성입니다. 이후에 할당된 환경은 공유 환경이 되며 프로세스 수준 연결 풀링 설정을 상속합니다. - 환경이 할당된 후에도 애플리케이션은 연결 풀 설정을 변경할 수 있습니다. - 환경 연결 풀링을 사용하도록 설정하고 연결의 드라이버가 드라이버 풀링을 사용하는 경우 환경 풀링이 기본 설정됩니다. SQL_ATTR_CONNECTION_POOLING 드라이버 관리자 내에서 구현됩니다. 드라이버는 SQL_ATTR_CONNECTION_POOLING 구현할 필요가 없습니다. ODBC 2.0 및 3.0 애플리케이션은 이 환경 특성을 설정할 수 있습니다. 자세한 내용은 ODBC 연결 풀링을 참조 하세요.
SQL_ATTR_CP_MATCH(ODBC 3.0)	연결 풀에서 연결을 선택하는 방법을 결정하는 32비트 SQLUINTEGER 값입니다. SQLConnect 또는 SQLDriverConnect가 호출되면 드라이버 관리자가 풀에서 다시 사용할 연결을 결정합니다. 드라이버 관리자는 호출의 연결 옵션과 애플리케이션이 설정한 연결 특성을 풀에 있는 연결의 키워드 및 연결 특성과 일치시키려고 시도합니다. 이 특성의 값은 일치하는 조건의 전체 자릿수 수준을 결정합니다. 다음 값은 이 특성의 값을 설정하는 데 사용됩니다. SQL_CP_STRICT_MATCH = 호출의 연결 옵션과 정확히 일치하는 연결 및 애플리케이션에서 설정한 연결 특성만 다시 사용됩니다. 기본값입니다. SQL_CP_RELAXED_MATCH = 연결 문자열 키워드가 일치하는 연결을 사용할 수 있습니다. 키워드는 일치해야 하지만 모든 연결 특성이 일치해야 하는 것은 아닙니다. 드라이버 관리자가 풀링된 연결에 연결할 때 일치를 수행하는 방법에 대한 자세한 내용은 SQLConnect를 참조하세요. 연결 풀링에 대한 자세한 내용은 ODBC 연결 풀링을 참조 하세요.
SQL_ATTR_ODBC_VERSION(ODBC 3.0)	특정 기능이 ODBC 2.x 동작 또는 ODBC 3.x 동작을 나타내는지 여부를 결정하는 32비트 정수입니다. 다음 값은 이 특성의 값을 설정하는 데 사용됩니다. SQL_OV_ODBC3_80 = 드라이버 관리자와 드라이버는 다음과 같은 ODBC 3.8 동작을 표시합니다. - 드라이버는 날짜, 시간 및 타임스탬프에 대한 ODBC 3.x 코드를 반환하고 예상합니다. - 드라이버는 SQLError, SQLGetDiagField 또는 SQLGetDiagRec가 호출되면 ODBC 3.x SQLSTATE 코드를 반환합니다. - SQLTables 호출의 CatalogName 인수는 검색 패턴을 허용합니다. - 드라이버 관리자는 C 데이터 형식 확장성을 지원합니다. C 데이터 형식 확장성에 대한 자세한 내용은 ODBC의 C 데이터 형식을 참조하세요. 자세한 내용은 ODBC 3.8의 새로운 기능입니다. SQL_OV_ODBC3 = 드라이버 관리자와 드라이버는 다음과 같은 ODBC 3.x 동작을 표시합니다. - 드라이버는 날짜, 시간 및 타임스탬프에 대한 ODBC 3.x 코드를 반환하고 예상합니다. - 드라이버는 SQLError, SQLGetDiagField 또는 SQLGetDiagRec가 호출되면 ODBC 3.x SQLSTATE 코드를 반환합니다. - SQLTables 호출의 CatalogName 인수는 검색 패턴을 허용합니다. - 드라이버 관리자는 C 데이터 형식 확장성을 지원하지 않습니다. SQL_OV_ODBC2 = 드라이버 관리자와 드라이버는 다음과 같은 ODBC 2.x 동작을 표시합니다. 이는 ODBC 3.x 드라이버로 작업하는 ODBC 2.x 애플리케이션에 특히 유용합니다. - 드라이버는 날짜, 시간 및 타임스탬프에 대한 ODBC 2.x 코드를 반환하고 예상합니다. - SQLError, SQLGetDiagField 또는 SQLGetDiagRec가 호출되면 드라이버는 ODBC 2.x SQLSTATE 코드를 반환합니다. - SQLTables 호출의 CatalogName 인수는 검색 패턴을 허용하지 않습니다. - 드라이버 관리자는 C 데이터 형식 확장성을 지원하지 않습니다. 애플리케이션은 SQLHENV 인수가 있는 함수를 호출하기 전에 이 환경 특성을 설정해야 합니다. 그렇지 않으면 호출에서 SQLSTATE HY010(함수 시퀀스 오류)을 반환합니다. 이러한 환경 플래그에 대한 추가 동작이 존재하는지 여부는 드라이버별로 다릅니다. - 자세한 내용은 애플리케이션의 ODBC 버전 및 동작 변경 선언을 참조하세요.
SQL_ATTR_OUTPUT_NTS(ODBC 3.0)	드라이버가 문자열 데이터를 반환하는 방법을 결정하는 32비트 정수입니다. SQL_TRUE 경우 드라이버는 null로 종료된 문자열 데이터를 반환합니다. SQL_FALSE 경우 드라이버는 null로 종료된 문자열 데이터를 반환하지 않습니다. 이 특성은 기본적으로 SQL_TRUE. SQLSetEnvAttr를 SQL_TRUE 설정하기 위한 호출은 SQL_SUCCESS 반환합니다. SQLSetEnvAttr를 SQL_FALSE 설정하기 위한 호출은 SQL_ERROR 및 SQLSTATE HYC00(선택적 기능이 구현되지 않음)을 반환합니다.

관련 함수

추가 정보	참조
핸들 할당	SQLAllocHandle 함수
환경 특성의 설정 반환	SQLGetEnvAttr 함수

참고 항목

ODBC API 참조
ODBC 헤더 파일
ODBC 3.8의 새로운 기능