JetEnumerateColumns 함수
적용 대상: Windows | Windows Server
JetEnumerateColumns 함수
JetEnumerateColumns 함수는 커서의 현재 레코드 또는 해당 커서의 복사 버퍼에서 열 집합과 해당 값을 효율적으로 검색합니다. 검색된 열 및 값은 열 ID 목록, itagSequence 숫자 및 기타 특성으로 제한될 수 있습니다. 이 열 검색 API는 사용자가 제공한 realloc 호환 콜백을 사용하여 가져온 동적으로 할당된 메모리에 정보를 반환한다는 측면에서 고유합니다. 이 새로운 유연성을 통해 호출자에게 알려지지 않은 특정 특성(예: 크기 및 곱하기)을 사용하여 열 데이터를 효율적으로 검색할 수 있습니다. 이렇게 하면 원하는 데이터를 성공적으로 검색할 JetRetrieveColumn 에 대한 최종 호출을 설정하기 위해 JetRetrieveColumn 의 검색 모드를 사용하여 이러한 특성을 확인할 필요가 없습니다.
Windows XP: JetEnumerateColumns 가 Windows XP에 도입되었습니다.
JET_ERR JET_API JetEnumerateColumns(
__in JET_SESID sesid,
__in JET_TABLEID tableid,
__in unsigned long cEnumColumnId,
__in_opt JET_ENUMCOLUMNID* rgEnumColumnId,
__out unsigned long* pcEnumColumn,
__out JET_ENUMCOLUMN** prgEnumColumn,
__in JET_PFNREALLOC pfnRealloc,
__in void* pvReallocContext,
__in unsigned long cbDataMost,
__in JET_GRBIT grbit
);
매개 변수
sesid
이 호출에 사용할 세션입니다.
tableid
이 호출에 사용할 커서입니다.
cEnumColumnId
열거할 itagSequence 숫자의 선택적 배열이 있는 열 ID의 배열입니다.
cEnumColumnId가 0이면 rgEnumColumnId가 무시되고 모든 열 값이 열거되고 호출자에게 반환됩니다. 열 ID 배열의 요소가 0의 열 ID를 참조하는 경우 해당 열의 열 열거를 건너뛰고 출력의 해당 슬롯은 JET_wrnColumnSkipped 열 상태 함께 생성됩니다.
ctagSequence가 열 ID 배열의 지정된 요소에 대해 0이면 rgtagSequence가 무시되고 해당 열 ID의 모든 열 값이 열거되어 호출자에게 반환됩니다. itagSequence 숫자 배열의 요소가 itagSequence 번호 0(0)을 참조하는 경우 해당 itagSequence 번호의 열거를 건너뛰고 출력의 해당 슬롯이 JET_wrnColumnSkipped 열 값 상태 생성됩니다.
rgEnumColumnId
cEnumColumnId를 참조하세요.
pcEnumColumn
제공된 itagSequence 호환 콜백을 통해 할당된 열 및 해당 값의 열거형 배열을 반환합니다.
입력에 열 ID 배열이 요청되면 출력 배열의 순서와 크기에 입력 배열의 순서와 크기가 반영됩니다. 마찬가지로 입력 시 특정 열 ID에 대해 itagSequence 숫자 배열이 요청되는 경우 해당 열에 대한 열 값의 출력 배열의 순서와 크기는 입력 배열의 순서와 크기를 반영합니다.
출력 매개 변수는 JET_errBadColumnId 및 JET_errColumnNotFound 제외한 모든 오류에서 0(0) 및 NULL 로 설정됩니다. 이러한 오류가 반환되면 출력 데이터가 유효하고 영향을 받는 열 ID를 제외한 모든 항목에 대해 완료됩니다. 영향을 받는 각 열 ID에 대한 상태 코드는 호출자가 잘못된 열 ID를 결정하고 잠재적으로 수정 작업을 수행할 수 있도록 이러한 오류 중 하나로 설정됩니다.
prgEnumColumn
pcEnumColumn을 참조하세요.
pfnRealloc
열 및 해당 값의 출력 배열에 대한 메모리를 할당하는 데 사용되는 재 할당 호환 콜백 및 선택적 컨텍스트 포인터를 식별합니다.
pvReallocContext
pfnRealloc를 참조하세요.
cbDataMost
긴 텍스트 또는 긴 이진 열에서 반환할 데이터 양에 대한 상한을 설정합니다.
이 매개 변수는 매우 큰 열 값의 열거를 방지하는 데 사용할 수 있습니다. 일반적으로 이러한 열거형은 JET_errOutOfMemory 사용하여 API 호출에 실패할 수 있습니다. 이러한 방식으로 큰 열 값이 잘리면 열 값의 상태 JET_wrnColumnTruncated.
grbit
다음 옵션 중 0개 이상을 지정하는 비트 그룹입니다.
값 |
의미 |
|---|---|
JET_bitEnumerateCompressOutput |
열 값을 열거할 때 모든 값을 검색하고 NULL이 아닌 열 값이 하나만 있는 모든 열이 압축된 형식으로 반환될 수 있습니다. 이러한 열에 대한 상태 JET_wrnColumnSingleValue 설정되고 열 값의 크기와 열 값이 포함된 메모리가 JET_ENUMCOLUMN 구조에서 직접 반환됩니다. 모든 적격 열이 이러한 방식으로 압축되는 것은 아닙니다. 자세한 내용은 JET_ENUMCOLUMN 참조하세요. |
JET_bitEnumerateCopy |
이 옵션은 레코드의 수정된 열 값이 원래 열 값이 아니라 열거되어야 했음을 나타냅니다. 열 값이 수정되지 않은 경우 원래 열 값이 열거됩니다. 이러한 방식으로 레코드를 삽입하거나 업데이트할 때 아직 삽입되거나 업데이트되지 않은 열 값이 열거될 수 있습니다. 이 옵션은 JetRetrieveColumn 또는 JetRetrieveColumns와 함께 사용할 때 JET_bitRetrieveCopy 동일합니다. |
JET_bitEnumerateIgnoreDefault |
지정된 열이 레코드에 없으면 열 값이 반환되지 않습니다. 일반적으로 열의 기본값(있는 경우)이 이 경우 반환됩니다. 열이 기본값과 다른 값으로 설정된 경우 다른 값이 반환됩니다(즉, 기본값이 있는 열이 명시적으로 NULL 로 설정된 경우 NULL 이 해당 열의 값으로 반환됨). 이 옵션이 요청되더라도 기본값과 같은 열 값이 계속 표시될 수 있습니다. 기본값과 일치하는 열 값을 제거하려고 노력하지 않습니다. 이 옵션은 JET_bitEnumeratePresenceOnly 또는 JET_bitEnumerateTaggedOnly 사용할 때 JetEnumerateColumns 의 출력에 영향을 줍니다. |
JET_bitEnumerateIgnoreUserDefinedDefault |
지정된 열이 레코드에 없고 사용자가 정의한 기본값이 있는 경우 열 값이 반환되지 않습니다. 이 옵션을 사용하면 해당 열의 값을 열거할 때 열에 대해 사용자가 정의한 기본값을 계산하는 콜백이 호출되지 않습니다. Windows Server 2003 이하: Windows Server 2003 및 이전 릴리스의 경우 JET_errCallbackFailed 함께 작업이 실패합니다. Windows Server 2003 SP1: 이 가능한 값은 Windows Server 2003 SP1 이상 운영 체제에서만 사용할 수 있습니다. 이 가능한 값을 지정하고 테이블에 사용자가 정의한 기본값이 있는 열이 포함된 경우 작업이 실패하고 JET_errCallbackFailed. |
JET_bitEnumeratePresenceOnly |
요청된 열 또는 열 값에 대해 NULL이 아닌 값이 있는 경우 연결된 데이터가 반환되지 않습니다. 대신 해당 열 또는 열 값에 대한 연결된 상태 JET_wrnColumnPresent 설정됩니다. 열 또는 열 값이 NULL 이면 JET_wrnColumnNull 평소와 같이 반환됩니다. |
JET_bitEnumerateTaggedOnly |
레코드의 모든 열 값을 열거하는 경우(예: cEnumColumnId 가 0인 경우) 태그가 지정된 열 값만 반환됩니다. 열 ID의 특정 배열을 열거할 때는 이 옵션을 사용할 수 없습니다. |
JET_bitEnumerateInRecordOnly |
Windows 7: JET_bitEnumerateInRecordOnly Windows 7에 도입되었습니다. |
반환 값
이 함수는 다음 반환 코드 중 하나를 사용하여 JET_ERR 데이터 형식을 반환합니다. 가능한 ESE 오류에 대한 자세한 내용은 확장 가능한 스토리지 엔진 오류 및 오류 처리 매개 변수를 참조하세요.
반환 코드 |
설명 |
|---|---|
JET_errSuccess |
작업이 성공적으로 완료되었습니다. |
JET_errBadColumnId |
지정된 열 ID가 열 ID의 법적 제한을 벗어집니다. 이 오류는 특정 열 ID가 요청되고, 해당 열 ID 중 하나가 잘못되었으며, 열 상태 코드에 대한 이 오류로 인해 첫 번째 잘못된 열 ID가 실패한 경우 JetEnumerateColumns에서 반환됩니다. |
JET_errClientRequestToStopJetService |
JetStopService 호출로 인해 세션과 연결된 instance 모든 작업이 중단되었으므로 작업을 완료할 수 없습니다. |
JET_errColumnNotFound |
지정된 열 ID로 설명된 열이 테이블에 없습니다. 이 오류는 특정 열 ID가 요청되고, 해당 열 ID 중 하나가 잘못되었으며, 열 상태 코드에 대한 이 오류로 인해 첫 번째 잘못된 열 ID가 실패한 경우 JetEnumerateColumns에서 반환됩니다. |
JET_errInstanceUnavailable |
세션과 연결된 instance 해당 데이터의 무결성을 보호하기 위해 모든 데이터에 대한 액세스를 해지해야 하는 심각한 오류가 발생하여 작업을 완료할 수 없습니다. Windows XP: 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다. |
JET_errInvalidgrbit |
요청된 옵션 중 하나가 잘못되었거나 구현되지 않았습니다. 이 오류는 다음과 같은 경우 JetEnumerateColumns에서 반환됩니다.
|
JET_errInvalidParameter |
제공된 매개 변수 중 하나에 예기치 않은 값이 포함되어 있거나 다른 매개 변수의 값과 결합할 때 의미가 없는 값이 포함되어 있습니다. 이 오류는 다음과 같은 경우 JetEnumerateColumns에서 반환됩니다.
|
JET_errNoCurrentRecord |
커서가 레코드에 배치되지 않습니다. 오류는 다양한 이유로 발생할 수 있습니다. 예를 들어 커서가 현재 인덱스의 마지막 레코드 뒤에 현재 위치하는 경우 이 문제가 발생합니다. |
JET_errNotInitialized |
세션과 연결된 instance 아직 초기화되지 않았기 때문에 작업을 완료할 수 없습니다. |
JET_errRecordDeleted |
커서는 삭제된 레코드에 배치됩니다. 오류는 다양한 이유로 발생할 수 있습니다. 가장 일반적인 이유는 세션이 트랜잭션에 있지 않고, 커서가 레코드에 배치되고, 해당 레코드가 삭제된 다음 커서가 해당 레코드를 참조하려고 했기 때문입니다. |
JET_errRestoreInProgress |
세션과 연결된 instance 복원 작업이 진행 중이므로 작업을 완료할 수 없습니다. |
JET_errSessionSharingViolation |
동시에 둘 이상의 스레드에 동일한 세션을 사용할 수 없습니다. Windows XP: 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다. |
JET_errTermInProgress |
세션과 연결된 instance 종료 중이므로 작업을 완료할 수 없습니다. |
성공하면 요청된 데이터가 출력 버퍼에 반환됩니다. 이 콜백에 의해 할당되고 출력 버퍼에 반환된 모든 메모리를 해제하는 것은 호출자의 책임입니다. 해당 메모리는 제공된 재할당 호환 콜백을 통해 해제되어야 합니다. 데이터베이스 상태는 변경되지 않습니다.
실패 시 요청된 데이터는 반환되지 않습니다. 호출 중에 할당된 모든 메모리는 제공된 재할당 호환 콜백을 사용하여 자동으로 해제됩니다. 데이터베이스 상태는 변경되지 않습니다.
설명
레코드의 모든 열 값을 열거하고 JET_bitEnumerateIgnoreDefaults 지정하지 않은 경우 상태 코드가 JET_wrnColumnNull 열 또는 열 값이 표시되지 않는다고 가정할 수 없습니다. 열에 기본값이 있고 명시적으로 NULL로 설정된 경우 또는 열이 스파스가 아닌 열(예: 고정 열 또는 변수 열)인 경우 이 상태 코드를 볼 수 있습니다.
cbDataMost 매개 변수는 모든 열 값에 적용되지 않습니다. 이 매개 변수는 레코드와 별도로 저장될 정도로 큰 긴 텍스트 및 긴 이진 열 값만 자립니다.
JetEnumerateColumns가 출력 매개 변수의 데이터를 반환하는 경우 호출자는 배열의 메모리와 해당 배열에 포함된 포인터로 참조되는 모든 메모리를 해제해야 합니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
클라이언트 |
Windows Vista 또는 Windows XP가 필요합니다. |
서버 |
Windows Server 2008 또는 Windows Server 2003이 필요합니다. |
머리글 |
Esent.h에 선언되었습니다. |
라이브러리 |
ESENT.lib를 사용합니다. |
DLL |
ESENT.dll 필요합니다. |
참고 항목
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns