JetRetrieveColumn 함수
적용 대상: Windows | Windows Server
JetRetrieveColumn 함수
JetRetrieveColumn 함수는 현재 레코드에서 단일 열 값을 검색합니다. 레코드는 커서의 현재 위치에 있는 인덱스 항목과 연결된 레코드입니다. 또는 이 함수는 커서 복사 버퍼에 만들어지는 레코드에서 열을 검색할 수 있습니다. 이 함수는 현재 레코드를 참조하는 인덱스 항목에서 열 데이터를 검색할 수도 있습니다. JetRetrieveColumn은 실제 열 값을 검색하는 것 외에도 애플리케이션 버퍼의 크기를 적절하게 조정할 수 있도록 열 데이터 자체를 검색하기 전에 열 크기를 검색하는 데 사용할 수도 있습니다.
JET_ERR JET_API JetRetrieveColumn(
__in JET_SESID sesid,
__in JET_TABLEID tableid,
__in JET_COLUMNID columnid,
__out_opt void* pvData,
__in unsigned long cbData,
__out_opt unsigned long* pcbActual,
__in JET_GRBIT grbit,
__in_out_opt JET_RETINFO* pretinfo
);
매개 변수
sesid
이 호출에 사용할 세션입니다.
tableid
이 호출에 사용할 커서입니다.
columnid
검색할 열의 JET_COLUMNID .
열 id 값 0(0)을 지정할 수 있습니다. 이 값은 개별 열을 참조하지 않습니다. columnid 0(0)이 지정되면 태그가 지정된 모든 열, 스파스 및 다중값 열이 단일 열로 처리됩니다. 이렇게 하면 레코드에 있는 모든 스파스 열을 쉽게 검색할 수 있습니다.
pvData
열 값을 받는 출력 버퍼입니다.
cbData
출력 버퍼의 최대 크기(바이트)입니다.
pcbActual
열 값의 실제 크기(바이트)를 받습니다.
이 매개 변수가 NULL이면 열 값의 실제 크기가 반환되지 않습니다.
grbit
다음 중 0개 이상을 포함하는 이 호출에 사용할 옵션이 포함된 비트 그룹입니다.
값 |
의미 |
|---|---|
JET_bitRetrieveCopy |
이 플래그를 사용하면 검색 열이 원래 값 대신 수정된 값을 검색합니다. 값이 수정되지 않은 경우 원래 값이 검색됩니다. 이러한 방식으로 레코드를 삽입하거나 업데이트하는 작업 중에 아직 삽입되거나 업데이트되지 않은 값을 검색할 수 있습니다. |
JET_bitRetrieveFromIndex |
이 옵션은 가능한 경우 레코드에 액세스하지 않고 인덱스에서 열 값을 검색하는 데 사용됩니다. 이러한 방식으로 인덱스 항목 자체에서 필요한 데이터를 사용할 수 있는 경우 불필요한 레코드 로드를 방지할 수 있습니다. 되돌릴 수 없는 변환 또는 데이터 잘림으로 인해 인덱스에서 원래 열 값을 검색할 수 없는 경우 레코드에 액세스하고 데이터를 정상적으로 검색합니다. 이는 성능 옵션이며 열 값을 인덱스에서 검색할 수 있는 경우에만 지정해야 합니다. 클러스터형 또는 기본 인덱스에 대한 인덱스 항목이 레코드 자체이므로 현재 인덱스가 클러스터형 인덱스인 경우 이 옵션을 지정하면 안 됩니다. JET_bitRetrieveFromPrimaryBookmark 설정되면 이 비트를 설정할 수 없습니다. |
JET_bitRetrieveFromPrimaryBookmark |
이 옵션은 인덱스 책갈피에서 열 값을 검색하는 데 사용되며 기본 인덱스와 현재 인덱스에 열이 모두 표시되면 인덱스 값과 다를 수 있습니다. 현재 인덱스가 클러스터형 인덱스 또는 기본 인덱스인 경우 이 옵션을 지정해서는 안 됩니다. JET_bitRetrieveFromIndex 설정되면 이 비트를 설정할 수 없습니다. |
JET_bitRetrieveTag |
이 옵션은 pretinfo-itagSequence>에서 다중값 열 값의 시퀀스 번호를 검색하는 데 사용됩니다. itagSequence 필드는 일반적으로 레코드에서 다중값 열 값을 검색하기 위한 입력입니다. 그러나 인덱스에서 값을 검색할 때 인덱스 항목을 특정 시퀀스 번호와 연결하고 이 시퀀스 번호도 검색할 수 있습니다. 시퀀스 번호 검색은 비용이 많이 드는 작업일 수 있으며 필요한 경우에만 수행해야 합니다. |
JET_bitRetrieveNull |
이 옵션은 다중값 열 NULL 값을 검색하는 데 사용됩니다. 이 옵션을 지정하지 않으면 다중값 열 NULL 값이 자동으로 건너뜁니다. |
JET_bitRetrieveIgnoreDefault |
이 옵션은 다중값 열에만 영향을 줍니다. 요청된 시퀀스 번호가 1이고 레코드에 열에 설정된 값이 없을 때 NULL 값이 반환됩니다. |
JET_bitRetrieveLongId |
이 플래그는 내부 전용이며 애플리케이션에서 사용할 수 없습니다. |
JET_bitRetrieveLongValueRefCount |
이 플래그는 내부 전용이며 애플리케이션에서 사용할 수 없습니다. |
JET_bitRetrieveTuple |
이 플래그를 사용하면 인덱스의 튜플 세그먼트를 검색할 수 있습니다. 이 비트는 JET_bitRetrieveFromIndex 사용하여 지정해야 합니다. |
pretinfo
pretinfo가 NULL로 제공되면 함수는 itagSequence가 1이고 ibLongValue가 0인 것처럼 동작합니다. 이렇게 하면 열 검색이 다중값 열의 첫 번째 값을 검색하고 오프셋 0(0)에서 긴 데이터를 검색합니다.
이 매개 변수는 다음 중 하나 이상을 제공하는 데 사용됩니다.
값 |
의미 |
|---|---|
ibLongValue |
열 값의 일부를 검색할 때 긴 열 값으로 이진 오프셋을 제공합니다. |
itagSequence |
원하는 다중값 열 값의 시퀀스 번호를 제공합니다. 이 필드는 JET_bitRetrieveTag 지정된 경우에만 설정됩니다. 그렇지 않으면 수정되지 않습니다. |
columnidNextTagged |
0(0)의 전달 columnid 를 사용하여 태그가 지정된 모든 스파스 및 다중값 열을 검색할 때 반환된 열 값의 열 ID를 반환합니다. |
반환 값
이 함수는 다음 반환 코드 중 하나를 사용하여 JET_ERR 데이터 형식을 반환합니다. 가능한 ESE 오류에 대한 자세한 내용은 확장 가능한 스토리지 엔진 오류 및 오류 처리 매개 변수를 참조하세요.
반환 코드 |
설명 |
|---|---|
JET_errSuccess |
작업이 성공적으로 완료되었습니다. |
JET_errBadColumnId |
지정된 열 ID가 열 ID의 법적 제한을 벗어집니다. |
JET_errBadItagSequence |
pretinfo-itagSequence>에서 잘못된 다중값 열 시퀀스 번호 값이 전달되었습니다. 다중값 열 값 시퀀스 번호의 유효한 값은 1 이상입니다. 이 함수에 대해 값이 0(0)이 잘못되었습니다. |
JET_errClientRequestToStopJetService |
JetStopService 호출로 인해 세션과 연결된 instance 모든 작업이 중단되었으므로 작업을 완료할 수 없습니다. |
JET_errColumnNotFound |
지정된 columnid 에 의해 설명된 열이 테이블에 없습니다. |
JET_errIndexTuplesCannotRetrieveFromIndex |
하위 문자열로 인덱싱된 열은 일반적으로 각 인덱스 항목에 열의 작은 부분만 있기 때문에 인덱스에서 검색할 수 없습니다. |
JET_errInstanceUnavailable |
세션과 연결된 instance 해당 데이터의 무결성을 보호하기 위해 모든 데이터에 대한 액세스를 해지해야 하는 심각한 오류가 발생하여 작업을 완료할 수 없습니다. 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다. |
JET_errInvalidBufferSize |
경우에 따라 열 값의 양을 반환하기 위해 검색 열에 지정된 버퍼의 크기를 충분히 조정해야 합니다. 예를 들어 에스크로 업데이트 가능한 열은 호출 세션의 트랜잭션 컨텍스트에 맞게 일관되도록 조정되며, 이 조정을 수행하려면 호출자가 제공하는 버퍼가 필요합니다. 버퍼 공간이 부족한 경우 JET_errInvalidBufferSize 반환되고 열 데이터가 반환되지 않습니다. |
JET_errInvalidParameter |
지정된 매개 변수 중 하나 이상이 잘못되었습니다. 이는 retinfo.cbStruct가 JET_RETINFO 크기가 작은 경우에 발생할 수 있습니다. |
JET_errInvalidgrbit |
제공된 옵션은 알 수 없거나 알려진 비트 설정의 잘못된 조합입니다. |
JET_errNoCurrentRecord |
커서가 레코드에 배치되지 않습니다. 오류는 다양한 이유로 발생할 수 있습니다. 예를 들어 커서가 현재 인덱스의 마지막 레코드 뒤에 현재 위치하는 경우 이 문제가 발생합니다. |
JET_errNotInitialized |
세션과 연결된 instance 아직 초기화되지 않았기 때문에 작업을 완료할 수 없습니다. |
JET_errRestoreInProgress |
세션과 연결된 instance 복원 작업이 진행 중이므로 작업을 완료할 수 없습니다. |
JET_errSessionSharingViolation |
동시에 둘 이상의 스레드에 동일한 세션을 사용할 수 없습니다. Windows XP: 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다. |
JET_errTermInProgress |
세션과 연결된 instance 종료 중이므로 작업을 완료할 수 없습니다. |
JET_wrnBufferTruncated |
지정된 버퍼가 열 크기보다 작기 때문에 전체 열 값을 검색할 수 없습니다. |
JET_wrnColumnNull |
검색된 열 값이 NULL입니다. |
성공하면 지정된 열의 열 값이 지정된 버퍼에 복사됩니다. 모든 열 값보다 작으면 경고 JET_wrnBufferTruncated 반환됩니다. pcbActual이 지정된 경우 열 값의 실제 크기가 반환됩니다. NULL 값의 길이는 0이며 반환된 크기는 0으로 설정됩니다. 검색된 열이 다중값 열이고 pretinfo 가 지정되고 JET_bitReturnTag 옵션으로 설정된 경우 열 값의 시퀀스 번호가 pretinfo-itagSequence>로 반환됩니다.
오류가 발생한 경우 커서 위치는 변경되지 않고 제공된 버퍼에 데이터가 복사되지 않습니다.
설명
이 호출은 다중값이 아닌 열에 대해 고정 또는 알려진 크기의 데이터를 검색하는 데 한 번만 사용됩니다. 그러나 열 데이터가 알 수 없는 크기인 경우 이 호출은 일반적으로 두 번 사용됩니다. 필요한 스토리지 공간을 할당할 수 있도록 데이터의 크기를 확인하기 위해 먼저 호출됩니다. 그런 다음 열 데이터를 검색하기 위해 동일한 호출이 다시 이루어집니다. 열이 다중값이므로 실제 값 수를 알 수 없는 경우 호출은 일반적으로 세 번 사용됩니다. 먼저 값 수를 구한 다음 스토리지를 할당하고 실제 데이터를 검색하기 위해 두 번 더 가져옵니다.
pretinfo-itagSequence> 값이 1부터 시작되고 각 후속 호출에서 증가하여 다중 값 열에 대한 모든 값을 검색할 수 있습니다. 마지막 열 값은 함수에서 JET_wrnColumnNull 반환될 때 검색되는 것으로 알려져 있습니다. 이러한 값은 건너뛰기 때문에 다중 값 열에 값 시퀀스에 명시적 NULL 값이 설정된 경우 이 메서드를 수행할 수 없습니다. 애플리케이션이 명시적으로 NULL로 설정된 열 값을 포함하여 모든 다중 값 열 값을 검색하려는 경우 JetRetrieveColumn 대신 JetRetrieveColumns를 사용해야 합니다. 이 함수는 itagSequence 값이 0인 경우 다중값 함수의 값 수를 반환하지 않습니다. itagSequence 값이 0으로 전달되면 JetRetrieveColumns만 열 값의 값 수를 반환합니다.
예를 들어 이 함수가 트랜잭션 수준 0(0)에서 호출되는 경우 호출 세션 자체가 트랜잭션에 있지 않으면 함수 내에서 트랜잭션이 열리고 닫힙니다. 이 목적은 긴 값이 데이터베이스 페이지에 걸쳐 있는 경우 일관된 결과를 반환하는 것입니다. 세션이 트랜잭션에 없을 때 함수 호출과 이 함수에 대한 일련의 호출 간에 트랜잭션이 해제되면 이 함수에 대한 첫 번째 호출 후 업데이트된 데이터를 반환할 수 있습니다.
JET_bitRetrieveIgnoreDefault 옵션이 설정되지 않은 한 열이 다른 값으로 명시적으로 설정되지 않은 경우 기본 열 값이 검색됩니다.
삽입하기 전에 복사 버퍼에서 자동 증가 열 값을 검색하는 것은 정규화된 데이터를 여러 테이블에 삽입할 때 연결을 위해 레코드를 고유하게 식별하는 일반적인 수단입니다. 자동 증가 값은 삽입 작업이 시작될 때 할당되며 업데이트가 완료될 때까지 언제든지 복사 버퍼에서 검색할 수 있습니다.
columnid를 0으로 설정하여 태그가 지정된, 다중값 및 스파스 열을 모두 검색할 때 열은 가장 낮은 columnid에서 가장 높은 columnid로 columnid 순서로 검색됩니다. 열 값이 검색될 때마다 동일한 열 값 순서가 반환됩니다. 순서는 결정적입니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
클라이언트 |
Windows Vista, Windows XP 또는 Windows 2000 Professional이 필요합니다. |
서버 |
Windows Server 2008, Windows Server 2003 또는 Windows 2000 Server가 필요합니다. |
머리글 |
Esent.h에 선언되었습니다. |
라이브러리 |
ESENT.lib를 사용합니다. |
DLL |
ESENT.dll 필요합니다. |
참고 항목
JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_RETINFO
JetSetColumn
JetRetrieveColumns