SQLGetDiagField 함수

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

요약
SQLGetDiagField 오류, 경고 및 상태 정보가 포함된 진단 데이터 구조(지정된 핸들과 연결된) 레코드 필드의 현재 값을 반환합니다.

통사론

SQLRETURN SQLGetDiagField(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     DiagIdentifier,  
     SQLPOINTER      DiagInfoPtr,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLengthPtr);  

인수

HandleType
[입력] 진단이 필요한 핸들의 형식을 설명하는 핸들 형식 식별자입니다. 다음 중 하나여야 합니다.

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN 핸들은 드라이버 관리자 및 드라이버에서만 사용됩니다. 애플리케이션은 이 핸들 형식을 사용하면 안 됩니다. SQL_HANDLE_DBC_INFO_TOKEN 대한 자세한 내용은 ODBC 드라이버Connection-Pool 인식 개발을 참조하세요.

핸들
[입력] HandleType표시된 형식의 진단 데이터 구조에 대한 핸들입니다. HandleType SQL_HANDLE_ENV 경우 핸들 공유 또는 공유되지 않은 환경 핸들일 수 있습니다.

RecNumber
[입력] 애플리케이션에서 정보를 검색하는 상태 레코드를 나타냅니다. 상태 레코드는 1부터 번호가 매겨집니다. DiagIdentifier 인수가 진단 헤더의 필드를 나타내는 경우 RecNumber 무시됩니다. 그렇지 않은 경우 0을 초과해야 합니다.

DiagIdentifier
[입력] 값을 반환할 진단 필드를 나타냅니다. 자세한 내용은 "Comments"의 "DiagIdentifier Argument" 섹션을 참조하세요.

DiagInfoPtr
[출력] 진단 정보를 반환할 버퍼에 대한 포인터입니다. 데이터 형식은 DiagIdentifier값에 따라 달라집니다. DiagInfoPtr 정수 형식인 경우 일부 드라이버는 버퍼의 하위 32비트 또는 16비트만 쓰고 상위 비트는 변경되지 않고 그대로 둘 수 있으므로 애플리케이션은 SQLULEN 버퍼를 사용하고 이 함수를 호출하기 전에 값을 0으로 초기화해야 합니다.

DiagInfoPtr NULL인 경우 StringLengthPtrDiagInfoPtr가리키는 버퍼에서 반환할 수 있는 총 바이트 수(문자 데이터의 null 종료 문자 제외)를 반환합니다.

BufferLength
[입력] DiagIdentifier ODBC 정의 진단이고 DiagInfoPtr이 문자열 또는 이진 버퍼를 가리키는 경우 이 인수는 *DiagInfoPtr길이여야 합니다. DiagIdentifier ODBC 정의 필드이고 *DiagInfoPtr 정수인 경우 BufferLength 무시됩니다. *DiagInfoPtr 값이 유니코드 문자열인 경우(SQLGetDiagFieldW호출할 때), BufferLength 인수는 짝수여야 합니다.

DiagIdentifier 드라이버 정의 필드인 경우 애플리케이션은 BufferLength 인수를 설정하여 드라이버 관리자에 대한 필드의 특성을 나타냅니다. BufferLength 다음 값을 가질 수 있습니다.

• DiagInfoPtr 문자열에 대한 포인터인 경우 BufferLength 문자열 또는 SQL_NTS 길이입니다.

• DiagInfoPtr 이진 버퍼에 대한 포인터인 경우 애플리케이션은 SQL_LEN_BINARY_ATTR(길이) 매크로의 결과를 BufferLength배치합니다. 그러면 BufferLength음수 값이 배치됩니다.

• DiagInfoPtr 문자열이나 이진 문자열이 아닌 값에 대한 포인터인 경우 BufferLength 값이 SQL_IS_POINTER.

• *DiagInfoPtr 고정 길이 데이터 형식이 포함된 경우 BufferLength 적절하게 SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT 또는 SQL_IS_USMALLINT.

StringLengthPtr
[출력] 문자 데이터에 대해 *DiagInfoPtr반환하는 데 사용할 수 있는 총 바이트 수(null 종료 문자에 필요한 바이트 수 제외)를 반환하는 버퍼에 대한 포인터입니다. 반환할 수 있는 바이트 수가 BufferLength크거나 같으면 *DiagInfoPtr 텍스트가 BufferLength null 종료 문자의 길이를 뺀 값으로 잘립니다.

반환

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE 또는 SQL_NO_DATA.

진단

SQLGetDiagField 진단 레코드 자체를 게시하지 않습니다. 다음 반환 값을 사용하여 자체 실행 결과를 보고합니다.

• SQL_SUCCESS: 함수가 진단 정보를 반환했습니다.

• SQL_SUCCESS_WITH_INFO: *DiagInfoPtr 너무 작아서 요청된 진단 필드를 보유할 수 없습니다. 따라서 진단 필드의 데이터가 잘렸습니다. 잘림이 발생했는지 확인하려면 애플리케이션에서 BufferLength 사용 가능한 실제 바이트 수와 비교해야 합니다. 이 바이트는 *StringLengthPtr기록됩니다.

• SQL_INVALID_HANDLE: HandleType 및 Handle 표시된 핸들이 유효한 핸들이 아닙니다.

• SQL_ERROR: 다음 중 하나가 발생했습니다.

  • DiagIdentifier 인수가 유효한 값 중 하나가 아닙니다.

  • DiagIdentifier 인수는 SQL_DIAG_CURSOR_ROW_COUNT, SQL_DIAG_DYNAMIC_FUNCTION, SQL_DIAG_DYNAMIC_FUNCTION_CODE 또는 SQL_DIAG_ROW_COUNT 핸들 문 핸들이 아니었습니다. (드라이버 관리자는 이 진단을 반환합니다.)

  • RecNumber 인수가 음수이거나 DiagIdentifier 진단 레코드의 필드를 표시했을 때 0입니다. RecNumber 헤더 필드에 대해서는 무시됩니다.

  • 요청된 값은 문자열이고 BufferLength 0보다 작습니다.

  • 비동기 알림을 사용하는 경우 핸들의 비동기 작업이 완료되지 않았습니다.

• SQL_NO_DATA: RecNumberHandle에 지정된 핸들에 대해 존재했던 진단 레코드 수보다 큰 경우 함수는 Handle대한 진단 레코드가 없는 경우 긍정 RecNumber 대한 SQL_NO_DATA 반환합니다.

코멘트

애플리케이션은 일반적으로 SQLGetDiagField 호출하여 다음 세 가지 목표 중 하나를 수행합니다.

1. 함수 호출이 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO(또는 SQLBrowseConnect 함수에 대한 SQL_NEED_DATA)를 반환할 때 특정 오류 또는 경고 정보를 가져오려면.

2. 삽입 시 영향을 받은 데이터 원본의 행 수를 확인하려면 sqlExecute, SQLExecDirect, SQLBulkOperations또는 SQL_DIAG_ROW_COUNT 헤더 필드에서 SQLSetPos 호출하거나 현재 열려 있는 커서에 있는 행 수를 확인하여 삭제하거나 업데이트 작업을 수행했습니다. 드라이버가 SQL_DIAG_CURSOR_ROW_COUNT 헤더 필드에서 이 정보를 제공할 수 있으면 입니다.

3. SQLExecDirect 또는 SQL_DIAG_DYNAMIC_FUNCTION 및 SQL_DIAG_DYNAMIC_FUNCTION_CODE 헤더 필드에서 SQLExecute 호출하여 실행된 함수를 확인합니다.

모든 ODBC 함수는 호출할 때마다 0개 이상의 진단 레코드를 게시할 수 있으므로 애플리케이션은 ODBC 함수 호출 후 SQLGetDiagField 호출할 수 있습니다. 한 번에 저장할 수 있는 진단 레코드 수에는 제한이 없습니다. SQLGetDiagFieldHandle 인수에 지정된 진단 데이터 구조와 가장 최근에 연결된 진단 정보만 검색합니다. 애플리케이션이 SQLGetDiagField 또는 SQLGetDiagRec이외의 ODBC 함수를 호출하는 경우 동일한 핸들이 있는 이전 호출의 진단 정보가 손실됩니다.

SQLGetDiagField SQL_SUCCESS 반환하는 한 애플리케이션은 RecNumber증가시켜 모든 진단 레코드를 검색할 수 있습니다. 상태 레코드 수는 SQL_DIAG_NUMBER 헤더 필드에 표시됩니다. SQLGetDiagField 대한 호출은 헤더 및 레코드 필드에 대한 비동기적입니다. 진단 함수 이외의 함수가 중간에 호출되지 않았으므로 동일한 핸들에 레코드를 게시하는 경우 애플리케이션은 SQLGetDiagField 나중에 다시 호출하여 레코드에서 필드를 검색할 수 있습니다.

애플리케이션은 SQLGetDiagField 호출하여 SQL_DIAG_CURSOR_ROW_COUNT 또는 SQL_DIAG_ROW_COUNT 제외하고 언제든지 진단 필드를 반환할 수 있으며, Handle 문 핸들이 아닌 경우 SQL_ERROR 반환합니다. 다른 진단 필드가 정의되지 않은 경우 SQLGetDiagField 호출은 SQL_SUCCESS 반환하고(다른 진단이 발생하지 않는 경우) 필드에 대해 정의되지 않은 값이 반환됩니다.

자세한 내용은 SQLGetDiagRec 및 SQLGetDiagField 사용하고 SQLGetDiagRec 및 SQLGetDiagField구현하는 참조하세요.

비동기적으로 실행되는 API 이외의 API를 호출하면 HY010 "함수 시퀀스 오류"가 생성됩니다. 그러나 비동기 작업이 완료되기 전에는 오류 레코드를 검색할 수 없습니다.

HandleType 인수

각 핸들 형식에는 연결된 진단 정보가 있을 수 있습니다. HandleType 인수는 Handle핸들 형식을 나타냅니다.

환경, 연결, 문 및 설명자 핸들에는 일부 헤더 및 레코드 필드를 반환할 수 없습니다. 필드를 적용할 수 없는 핸들은 다음 "머리글 필드" 및 "레코드 필드" 섹션에 표시됩니다.

HandleType SQL_HANDLE_ENV 경우 핸들 공유 또는 공유되지 않은 환경 핸들일 수 있습니다.

드라이버별 헤더 진단 필드는 환경 핸들과 연결해서는 안 됩니다.

설명자 핸들에 대해 정의된 유일한 진단 헤더 필드는 SQL_DIAG_NUMBER SQL_DIAG_RETURNCODE.

DiagIdentifier 인수

이 인수는 진단 데이터 구조에서 필요한 필드의 식별자를 나타냅니다. RecNumber 1보다 크거나 같은 경우 필드의 데이터는 함수에서 반환된 진단 정보를 설명합니다. recNumber 경우 필드는 진단 데이터 구조의 헤더에 있으므로 특정 정보가 아니라 진단 정보를 반환한 함수 호출과 관련된 데이터를 포함합니다.

드라이버는 진단 데이터 구조에서 드라이버별 헤더 및 레코드 필드를 정의할 수 있습니다.

ODBC 2*.x* 드라이버로 작동하는 ODBC 3*.x* 애플리케이션은 SQL_DIAG_CLASS_ORIGIN, SQL_DIAG_CLASS_SUBCLASS_ORIGIN, SQL_DIAG_CONNECTION_NAME, SQL_DIAG_MESSAGE_TEXT, SQL_DIAG_NATIVE, SQL_DIAG_NUMBER, SQL_DIAG_RETURNCODE, SQL_DIAG_SERVER_NAME DiagIdentifier 인수로만 SQLGetDiagField 호출할 수 있습니다. 또는 SQL_DIAG_SQLSTATE. 다른 모든 진단 필드는 SQL_ERROR 반환합니다.

머리글 필드

다음 표에 나열된 헤더 필드는 DiagIdentifier 인수에 포함될 수 있습니다.

레코드 필드

다음 표에 나열된 레코드 필드는 DiagIdentifier 인수에 포함될 수 있습니다.

동적 함수 필드의 값

다음 표에서는 sqlExecute 또는 SQLExecDirect호출로 실행되는 각 SQL 문 유형에 적용되는 SQL_DIAG_DYNAMIC_FUNCTION 및 SQL_DIAG_DYNAMIC_FUNCTION_CODE 값을 설명합니다. 드라이버는 나열된 값에 드라이버 정의 값을 추가할 수 있습니다.

상태 레코드 시퀀스

상태 레코드는 행 번호 및 진단 유형에 따라 시퀀스에 배치됩니다. 드라이버 관리자는 생성되는 상태 레코드를 반환할 최종 순서를 결정합니다. 드라이버는 생성되는 상태 레코드를 반환할 최종 순서를 결정합니다.

드라이버 관리자와 드라이버 둘 다에서 진단 레코드를 게시하는 경우 드라이버 관리자는 해당 레코드의 순서를 지정합니다.

둘 이상의 상태 레코드가 있는 경우 레코드의 시퀀스는 먼저 행 번호에 따라 결정됩니다. 다음 규칙은 행별 진단 레코드 시퀀스를 결정하는 데 적용됩니다.

• 행에 해당하지 않는 레코드는 SQL_NO_ROW_NUMBER -1로 정의되기 때문에 특정 행에 해당하는 레코드 앞에 나타납니다.

• SQL_ROW_NUMBER_UNKNOWN -2로 정의되어 있으므로 행 번호를 알 수 없는 레코드가 다른 모든 레코드 앞에 나타납니다.

• 특정 행과 관련된 모든 레코드의 경우 레코드는 SQL_DIAG_ROW_NUMBER 필드의 값을 기준으로 정렬됩니다. 영향을 받는 첫 번째 행의 모든 오류 및 경고가 나열된 다음 영향을 받는 다음 행의 모든 오류 및 경고가 표시됩니다.

각 행 내에서 또는 행 번호에 해당하지 않거나 행 번호를 알 수 없는 모든 레코드 또는 행 번호가 SQL_NO_ROW_NUMBER 같은 모든 레코드에 대해 나열된 첫 번째 레코드는 정렬 규칙 집합을 사용하여 결정됩니다. 첫 번째 레코드 이후 행에 영향을 주는 다른 레코드의 순서는 정의되지 않습니다. 애플리케이션은 오류가 첫 번째 레코드 다음에 경고 앞에 있다고 가정할 수 없습니다. 애플리케이션은 전체 진단 데이터 구조를 검색하여 함수 호출 실패에 대한 전체 정보를 가져와야 합니다.

다음 규칙은 행 내의 첫 번째 레코드를 결정하는 데 사용됩니다. 순위가 가장 높은 레코드는 첫 번째 레코드입니다. 레코드의 원본(드라이버 관리자, 드라이버, 게이트웨이 등)은 레코드 순위 지정 시 고려되지 않습니다.

• 오류를 설명하는 오류 상태 레코드의 순위가 가장 높습니다. 정렬 오류에 다음 규칙이 적용됩니다.

  • 트랜잭션 실패 또는 가능한 트랜잭션 실패를 나타내는 레코드가 다른 모든 레코드를 능가합니다.

  • 두 개 이상의 레코드가 동일한 오류 조건을 설명하는 경우 Open Group CLI 사양(클래스 03~HZ)에 의해 정의된 SQLSTATE는 ODBC 및 드라이버 정의 SQLSTATE를 능가합니다.

• 구현에서 정의한 데이터 값 없음 드라이버 정의 No Data 값(클래스 02)을 설명하는 상태 레코드는 두 번째로 높은 순위를 갖습니다.

• 경고(클래스 01)를 설명하는 경고 상태 레코드의 순위가 가장 낮습니다. 두 개 이상의 레코드가 동일한 경고 조건을 설명하는 경우 Open Group CLI 사양으로 정의된 경고 SQLSTATE는 ODBC 정의 및 드라이버 정의 SQLSTATE보다 높습니다.

관련 함수

참고 항목

ODBC API 참조
ODBC 헤더 파일