JetGetSecondaryIndexBookmark 함수

아티클
06/13/2023

적용 대상: Windows | Windows Server

JetGetSecondaryIndexBookmark 함수

JetGetSecondaryIndexBookmark 함수는 커서의 현재 위치에서 보조 인덱스 항목에 대한 특수 책갈피를 검색합니다. 그런 다음 이 책갈피를 사용하여 JetGotoSecondaryIndexBookmark를 사용하여 해당 커서의 위치를 동일한 인덱스 항목으로 효율적으로 변경할 수 있습니다. 중복 키가 포함되거나 동일한 레코드에 대한 여러 인덱스 항목이 포함된 보조 인덱스의 위치를 변경할 때 가장 유용합니다.

Windows XP: JetGetSecondaryIndexBookmark 는 Windows XP에 도입되었습니다.

    JET_ERR JET_API JetGetSecondaryIndexBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvSecondaryKey,
      __in          unsigned long cbSecondaryKeyMax,
      __out_opt     unsigned long* pcbSecondaryKeyActual,
      __out_opt      void* pvPrimaryBookmark,
      __in          unsigned long cbPrimaryBookmarkMax,
      __out_opt     unsigned long* pcbPrimaryKeyActual,
      __in          const JET_GRBIT grbit
    );

매개 변수

sesid

이 호출에 사용할 세션입니다.

tableid

이 호출에 사용할 커서입니다.

pvSecondaryKey

보조 키를 받는 출력 버퍼입니다.

cbSecondaryKeyMax

보조 키에 대한 출력 버퍼의 최대 크기(바이트)입니다.

pcbSecondaryKeyActual

보조 키의 실제 크기(바이트)를 받습니다.

이 매개 변수가 NULL이면 보조 키의 실제 크기가 반환되지 않습니다.

출력 버퍼가 너무 작으면 보조 키의 실제 크기가 계속 반환됩니다. 즉, 이 숫자는 출력 버퍼의 크기보다 큽니다.

pvPrimaryBookmark

기본 키 책갈피를 받는 출력 버퍼입니다.

cbPrimaryBookmarkMax

기본 키 책갈피에 대한 출력 버퍼의 최대 크기(바이트)입니다.

pcbPrimaryKeyActual

기본 키 책갈피의 실제 크기(바이트)를 받습니다.

이 매개 변수가 NULL이면 기본 키 책갈피의 실제 크기가 반환되지 않습니다.

출력 버퍼가 너무 작으면 기본 키 책갈피의 실제 크기가 계속 반환됩니다. 즉, 이 숫자는 출력 버퍼의 크기보다 큽니다.

grbit

다음에 사용하도록 예약됩니다.

반환 값

이 함수는 다음 반환 코드 중 하나를 사용하여 JET_ERR 데이터 형식을 반환합니다. 가능한 ESE 오류에 대한 자세한 내용은 확장 가능한 스토리지 엔진 오류 및 오류 처리 매개 변수를 참조하세요.

반환 코드	설명
JET_errSuccess	작업이 성공적으로 완료되었습니다.
JET_errBufferTooSmall	작업이 성공적으로 완료되었지만 출력 버퍼 중 하나가 너무 작아서 요청된 데이터를 받을 수 없습니다. 출력 버퍼가 책갈피의 양만큼 채워졌습니다. 요청된 경우 책갈피의 실제 크기도 반환되었습니다.
JET_errClientRequestToStopJetService	JetStopService 호출로 인해 세션과 연결된 instance 모든 작업이 중단되었으므로 작업을 완료할 수 없습니다.
JET_errInstanceUnavailable	세션과 연결된 instance 해당 데이터의 무결성을 보호하기 위해 모든 데이터에 대한 액세스를 해지해야 하는 심각한 오류가 발생하여 작업을 완료할 수 없습니다. 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.
JET_errNoCurrentIndex	커서가 현재 보조 인덱스에 있지 않습니다. 커서가 현재 보조 인덱스를 사용하지 않는 경우 보조 인덱스 책갈피를 검색하는 것은 의미가 없습니다. 커서가 보조 인덱스에 없는 경우 JetGetBookmark를 사용해야 합니다.
JET_errNoCurrentRecord	커서가 레코드에 배치되지 않습니다. 오류는 다양한 이유로 발생할 수 있습니다. 예를 들어 커서가 현재 인덱스의 마지막 레코드 뒤에 현재 위치하는 경우 이 문제가 발생합니다.
JET_errNotInitialized	세션과 연결된 instance 아직 초기화되지 않았기 때문에 작업을 완료할 수 없습니다.
JET_errRestoreInProgress	세션과 연결된 instance 복원 작업이 진행 중이므로 작업을 완료할 수 없습니다.
JET_errSessionSharingViolation	동시에 둘 이상의 스레드에 동일한 세션을 사용할 수 없습니다. 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.
JET_errTermInProgress	세션과 연결된 instance 종료 중이므로 작업을 완료할 수 없습니다.

성공하면 커서의 현재 위치에 있는 인덱스 항목에 대한 보조 인덱스 책갈피가 출력 버퍼에 반환됩니다. 데이터베이스 상태는 변경되지 않습니다.

실패 시 출력 버퍼의 상태와 보조 인덱스 책갈피의 실제 크기는 JET_errBufferTooSmall 반환되지 않는 한 정의되지 않습니다. JET_errBufferTooSmall 반환되는 경우 출력 버퍼에는 제공된 공간에 맞는 만큼의 보조 인덱스 책갈피가 포함되며 보조 인덱스 책갈피의 실제 크기는 정확합니다. 어떤 경우에도 데이터베이스 상태는 변경되지 않습니다.

설명

책갈피는 일반적으로 불투명한 데이터 청크로 처리되어야 합니다. 이 데이터의 내부 구조를 악용하려고 시도해서는 안 됩니다. 그러나 모든 ESENT 책갈피에 대해 다음 속성을 알 수 있습니다.

책갈피는 지정된 테이블의 레코드를 고유하게 식별합니다.
레코드의 책갈피는 해당 레코드의 수명 동안 변경되지 않습니다.
레코드의 책갈피는 해당 레코드가 포함된 테이블의 기본 인덱스에서 해당 레코드의 키와 동일합니다. 해당 테이블에 대해 기본 인덱스가 정의되지 않은 경우 데이터베이스 엔진은 레코드에 대한 자체 책갈피를 만듭니다.
책갈피는 memcmp 를 사용하여 원본 레코드의 테이블에 대한 기본 인덱스에서 상대적 순서를 설정하기 위해 서로 비교할 수 있습니다. 해당 테이블에 대해 기본 인덱스가 정의되지 않은 경우 해당 테이블에서 책갈피의 상대적 순서는 의미가 없습니다.
서로 다른 테이블의 레코드 책갈피를 서로 비교하는 것은 의미가 없습니다.
책갈피는 항상 Windows Vista 이전의 JET_cbBookmarkMost(256) 바이트보다 작거나 같습니다. Windows Vista 이상 릴리스에서는 책갈피가 더 클 수 있습니다. 책갈피의 최대 크기는 현재 값인 JET_paramKeyMost + 1과 같습니다.

키는 일반적으로 불투명한 데이터 청크로 처리되어야 합니다. 이 데이터의 내부 구조를 악용하려고 시도해서는 안 됩니다. 그러나 모든 ESENT 키에 대해 다음 속성을 알 수 있습니다.

memcmp를 사용하여 원본 인덱스 항목의 테이블에 대해 원래 인덱스에서 상대 순서를 설정하기 위해 키를 서로 비교할 수 있습니다.
서로 다른 인덱스의 인덱스 항목 키를 서로 비교하는 것은 의미가 없습니다.
키는 항상 Windows Vista 이전의 길이가 JET_cbKeyMost(255) 바이트보다 작거나 같습니다. Windows Vista 이상 릴리스에서는 키가 더 클 수 있습니다. 키의 최대 크기는 JET_paramKeyMost 현재 값과 같습니다.

요구 사항

요구 사항	값
클라이언트	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
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp

다음을 통해 공유

JetGetSecondaryIndexBookmark 함수