SQLGetDiagRec 함수

  • 아티클

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

요약
SQLGetDiagRec 는 오류, 경고 및 상태 정보를 포함하는 진단 레코드의 여러 필드의 현재 값을 반환합니다. 호출당 하나의 진단 필드를 반환하는 SQLGetDiagField와 달리 SQLGetDiagRec는 SQLSTATE, 네이티브 오류 코드 및 진단 메시지 텍스트를 포함하여 진단 레코드의 여러 일반적으로 사용되는 필드를 반환합니다.

구문

  
SQLRETURN SQLGetDiagRec(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLCHAR *       SQLState,  
     SQLINTEGER *    NativeErrorPtr,  
     SQLCHAR *       MessageText,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   TextLengthPtr);

인수

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 드라이버에서 연결 풀 인식 개발을 참조 하세요.

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

RecNumber
[입력] 애플리케이션에서 정보를 검색하는 상태 레코드를 나타냅니다. 상태 레코드는 1부터 번호가 매겨집니다.

SQLState
[출력] 진단 레코드 RecNumber에 대해 5자 SQLSTATE 코드(및 NULL 종료)를 반환할 버퍼에 대한 포인터입니다. 처음 두 문자는 클래스를 나타냅니다. 다음 세 가지는 하위 클래스를 나타냅니다. 이 정보는 SQL_DIAG_SQLSTATE 진단 필드에 포함되어 있습니다. 자세한 내용은 SQLSTATE를 참조 하세요.

NativeErrorPtr
[출력] 데이터 원본과 관련된 네이티브 오류 코드를 반환할 버퍼에 대한 포인터입니다. 이 정보는 SQL_DIAG_NATIVE 진단 필드에 포함되어 있습니다.

MessageText
[출력] 진단 메시지 텍스트 문자열을 반환할 버퍼에 대한 포인터입니다. 이 정보는 SQL_DIAG_MESSAGE_TEXT 진단 필드에 포함되어 있습니다. 문자열 형식은 진단 메시지를 참조 하세요.

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

BufferLength
[입력] *MessageText 버퍼의 문자 길이입니다. 진단 메시지 텍스트의 최대 길이는 없습니다.

TextLengthPtr
[출력] *MessageText에서 반환할 수 있는 총 문자 수(null 종료 문자에 필요한 문자 수 제외)를 반환할 버퍼에 대한 포인터입니다. 반환할 수 있는 문자 수가 BufferLength보다 크면 *MessageText의 진단 메시지 텍스트가 BufferLength에서 null 종료 문자의 길이를 뺀 값으로 잘립니다.

반품

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA 또는 SQL_INVALID_HANDLE.

진단

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

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

  • SQL_SUCCESS_WITH_INFO: *MessageText 버퍼가 너무 작아서 요청된 진단 메시지를 보관할 수 없습니다. 진단 레코드가 생성되지 않았습니다. 잘림이 발생했는지 확인하려면 애플리케이션이 BufferLength를 *TextLengthPtr에 기록된 사용 가능한 실제 바이트 수와 비교해야 합니다.

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

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

    • RecNumber가 음수 이거나 0입니다.

    • BufferLength 가 0보다 작습니다.

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

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

주석

애플리케이션은 일반적으로 ODBC 함수에 대한 이전 호출이 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환한 경우 SQLGetDiagRec를 호출합니다. 그러나 ODBC 함수는 호출할 때마다 0개 이상의 진단 레코드를 게시할 수 있으므로 애플리케이션은 ODBC 함수 호출 후 SQLGetDiagRec를 호출할 수 있습니다. 애플리케이션은 SQLGetDiagRec를 여러 번 호출하여 진단 데이터 구조의 일부 또는 모든 레코드를 반환할 수 있습니다. ODBC는 한 번에 저장할 수 있는 진단 레코드 수에 제한을 두지 않습니다.

SQLGetDiagRec 는 진단 데이터 구조의 헤더에서 필드를 반환하는 데 사용할 수 없습니다. (다음 항목RecNumber 인수는 0보다 커야 합니다.) 애플리케이션은 이 목적을 위해 SQLGetDiagField를 호출해야 합니다.

SQLGetDiagRec은 Handle 인수에 지정된 핸들과 가장 최근에 연결된 진단 정보만 검색합니다. 애플리케이션이 SQLGetDiagRec, SQLGetDiagField 또는 SQLError를 제외한 다른 ODBC 함수를 호출하는 경우 동일한 핸들에 대한 이전 호출의 진단 정보가 손실됩니다.

SQLGetDiagRec에서 SQL_SUCCESS 반환하는 한 애플리케이션은 RecNumber를 반복하고 증가시켜 모든 진단 레코드를 검색할 수 있습니다. SQLGetDiagRec에 대한 호출은 헤더 및 레코드 필드에 대한 구조적이지 않습니다. 애플리케이션은 SQLGetDiagRec, SQLGetDiagField 또는 SQLError를 제외한 다른 함수가 중간에 호출되지 않는 한 나중에 다시 SQLGetDiagRec를 호출하여 레코드에서 필드를 검색할 수 있습니다. 또한 애플리케이션은 SQLGetDiagField를 호출하여 SQL_DIAG_NUMBER 필드의 값을 검색한 다음 SQLGetDiagRec를 여러 번 호출하여 사용 가능한 총 진단 레코드 수를 검색할 수 있습니다.

진단 데이터 구조의 필드에 대한 설명은 SQLGetDiagField를 참조 하세요. 자세한 내용은 SQLGetDiagRec 및 SQLGetDiagField 사용 및 SQLGetDiagRec 및 SQLGetDiagField 구현을 참조하세요.

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

HandleType 인수

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

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

SqlGetDiagRec에 대한 호출은 HandleType이 공유 환경 핸들을 나타내는 SQL_HANDLE_SENV 경우 SQL_INVALID_HANDLE 반환합니다. 그러나 HandleType이 SQL_HANDLE_ENV 경우 핸들은 공유 또는 공유되지 않은 환경 핸들일 수 있습니다.

추가 정보 참조
진단 레코드의 필드 또는 진단 헤더의 필드 가져오기 SQLGetDiagField 함수

참고 항목

ODBC API 참조
ODBC 헤더 파일
샘플 ODBC 프로그램