JetRetrieveColumns 함수
적용 대상: Windows | Windows Server
JetRetrieveColumns 함수
JetRetrieveColumns 함수는 단일 작업에서 현재 레코드에서 여러 열 값을 검색합니다. JET_RETRIEVECOLUMN 구조체의 배열은 검색할 열 값 집합을 설명하고 검색할 각 열 값에 대한 출력 버퍼를 설명하는 데 사용됩니다.
JET_ERR JET_API JetRetrieveColumns(
__in JET_SESID sesid,
__in JET_TABLEID tableid,
__in_out_opt JET_RETRIEVECOLUMN* pretrievecolumn,
__in unsigned long cretrievecolumn
);
매개 변수
sesid
이 호출에 사용할 세션입니다.
tableid
이 호출에 사용할 커서입니다.
pretrievecolumn
하나 이상의 JET_RETRIEVECOLUMN 구조체 배열에 대한 포인터입니다. 각 구조체에는 검색할 열 값과 반환된 데이터를 저장할 위치에 대한 설명이 포함됩니다.
cretrievecolumn
pretrievecolumn에서 지정된 배열의 JET_RETRIEVECOLUMN 구조체 수입니다.
반환 값
이 함수는 다음 반환 코드 중 하나를 사용하여 JET_ERR 데이터 형식을 반환합니다. 가능한 ESE 오류에 대한 자세한 내용은 확장 가능한 스토리지 엔진 오류 및 오류 처리 매개 변수를 참조하세요.
반환 코드 |
설명 |
|---|---|
JET_errSuccess |
작업이 성공적으로 완료되었습니다. |
JET_errBadItagSequence |
pretinfo-itagSequence>에서 잘못된 다중값 열 시퀀스 번호 값이 전달되었습니다. 다중값 열 값 시퀀스 번호의 유효한 값은 1 이상입니다. 값 0은 이 함수에 유효하지만 JetRetrieveColumn에는 유효하지 않습니다. |
JET_errBadColumnId |
지정된 열 ID가 열 ID의 법적 한도를 벗어났습니다. |
JET_errClientRequestToStopJetService |
JetStopService 호출로 인해 세션과 연결된 instance 모든 작업이 중단되었으므로 작업을 완료할 수 없습니다. |
JET_errColumnNotFound |
지정된 columnid 에서 설명하는 열이 테이블에 없습니다. |
JET_errIndexTuplesCannotRetrieveFromIndex |
부분 문자열로 인덱싱된 열은 일반적으로 각 인덱스 항목에 열의 작은 부분만 있기 때문에 인덱스에서 검색할 수 없습니다. |
JET_errInvalidBufferSize |
경우에 따라 열 값의 양을 반환하기 위해 검색 열에 지정된 버퍼의 크기를 충분히 조정해야 합니다. 예를 들어 에스크로 업데이트 가능한 열은 호출 세션의 트랜잭션 컨텍스트에 맞게 일관되도록 조정되며, 이 조정을 수행하려면 호출자가 제공하는 버퍼가 필요합니다. 버퍼 공간이 부족한 경우 JET_errInvalidBufferSize 반환되고 열 데이터가 반환되지 않습니다. |
JET_errInvalidgrbit |
제공된 옵션은 알 수 없거나 알려진 비트 설정의 잘못된 조합입니다. |
JET_errInvalidParameter |
지정된 매개 변수 중 하나 이상이 잘못되었습니다. 이는 retinfo.cbStruct가 JET_RETINFO 크기가 작은 경우에 발생할 수 있습니다. |
JET_errInstanceUnavailable |
세션과 연결된 instance 해당 데이터의 무결성을 보호하기 위해 모든 데이터에 대한 액세스를 해지해야 하는 심각한 오류가 발생하여 작업을 완료할 수 없습니다. Windows XP: 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다. |
JET_errNoCurrentRecord |
커서가 레코드에 배치되지 않습니다. 오류는 다양한 이유로 발생할 수 있습니다. 예를 들어 커서가 현재 인덱스의 마지막 레코드 뒤에 현재 위치하는 경우 이 문제가 발생합니다. |
JET_errNotInitialized |
세션과 연결된 instance 아직 초기화되지 않았기 때문에 작업을 완료할 수 없습니다. |
JET_errRestoreInProgress |
세션과 연결된 instance 복원 작업이 진행 중이므로 작업을 완료할 수 없습니다. |
JET_errSessionSharingViolation |
동시에 둘 이상의 스레드에 동일한 세션을 사용할 수 없습니다. Windows XP: 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다. |
JET_errTermInProgress |
세션과 연결된 instance 종료 중이므로 작업을 완료할 수 없습니다. |
JET_wrnBufferTruncated |
지정된 버퍼가 열 크기보다 작기 때문에 전체 열 값을 검색할 수 없습니다. |
성공하면 열 데이터와 열 크기는 JET_RETRIEVECOLUMN 구조의 배열에 설명된 제공된 버퍼에 반환됩니다. 열 데이터 대신 다중값 필드의 인스턴스 수가 필요했음을 나타내기 위해 itagSequence 를 0으로 설정한 경우 다중값 열의 인스턴스 수가 itagSequence 필드 자체에 반환됩니다. 각 JET_RETRIEVECOLUMN 구조에는 검색된 열에 대한 경고가 포함된 오류 필드가 있습니다. 열 값이 NULL 이면 오류 코드가 JET_wrnColumnNull 설정됩니다.
오류가 발생한 경우 커서 위치는 변경되지 않고 제공된 버퍼에 데이터가 복사되지 않습니다.
설명
JetRetrieveColumns 는 JetRetrieveColumn 이 지원하지 않는 하나의 기능을 지원합니다. 다중값 열의 인스턴스 수를 검색하는 기능입니다. 이 기능의 목적은 애플리케이션이 열의 모든 값을 검색할 수 있도록 하는 것입니다. 이 작업은 먼저 열에 있는 값의 수를 결정하여 수행할 수 있습니다. 다음으로, 각 값에 할당된 하나의 JET_RETRIEVECOLUMN 구조로 JetRetrieveColumns를 다시 호출하여 열 데이터의 길이를 확인하여 길이를 확인할 수 있습니다. 이 작업은 cbMax가 0인 NULLpvData 포인터를 전달하고 cbActual에서 열 길이를 검색하여 수행할 수 있습니다. 세 번째 및 마지막 호출은 열 값 데이터에 할당된 메모리를 사용하여 수행할 수 있습니다.
길이 버퍼가 부족하여 검색된 열이 잘리면 API는 JET_wrnBufferTruncated 반환합니다. 그러나 JET_wrnColumnNull 다른 오류는 JET_RETRIEVECOLUMN 오류 필드에만 반환됩니다. 그 이유는 애플리케이션이 종종 모든 데이터가 검색되었는지 확인하고 JetRetrieveColumns 에서 이 오류를 반환하면 이러한 이해를 용이하게 하기 때문입니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
클라이언트 |
Windows Vista, Windows XP 또는 Windows 2000 Professional이 필요합니다. |
서버 |
Windows Server 2008, Windows Server 2003 또는 Windows 2000 Server가 필요합니다. |
머리글 |
Esent.h에 선언되었습니다. |
라이브러리 |
ESENT.lib를 사용합니다. |
DLL |
ESENT.dll 필요합니다. |
참고 항목
JET_ERR
JET_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns