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