JetRetrieveKey 함수

아티클
06/13/2023

적용 대상: Windows | Windows Server

JetRetrieveKey 함수

JetRetrieveKey 함수는 커서의 현재 위치에서 인덱스 항목에 대한 키를 검색합니다. 이러한 키는 JetMakeKey를 호출하여 생성됩니다. 그런 다음 검색된 키를 사용하여 JetSeek을 호출하여 해당 커서를 동일한 인덱스 항목으로 효율적으로 반환할 수 있습니다.

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit
    );

매개 변수

sesid

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

tableid

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

pvData

키를 받을 출력 버퍼입니다.

cbMax

출력 버퍼의 최대 크기(바이트)입니다.

pcbActual

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

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

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

grbit

다음 중 0개 이상을 포함하는 이 호출에 사용할 옵션이 포함된 비트 그룹입니다.

값	의미
JET_bitRetrieveCopy	지정된 경우 엔진은 커서에 대한 검색 키를 반환합니다. 검색 키는 JetSeek을 사용하여 해당 키를 검색하거나 JetSetIndexRange를 사용하여 인덱스 범위를 설정하기 위해 JetMakeKey에 대한 하나 이상의 이전 호출을 사용하여 빌드됩니다.

반환 값

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

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

성공하면 커서의 현재 위치에 있는 인덱스 항목의 키가 출력 버퍼에 반환됩니다. JET_wrnBufferTruncated 반환되면 출력 버퍼는 제공된 공간에 맞는 만큼의 키를 포함하며 키의 실제 크기는 정확합니다. 데이터베이스 상태는 변경되지 않습니다.

실패 시 출력 버퍼의 상태와 키의 실제 크기는 정의되지 않습니다. 데이터베이스 상태는 변경되지 않습니다.

설명

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

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

일반적으로 ESENT 키의 위의 속성 외에도 검색 키가 인덱스 항목의 키와 다르다는 점에 유의해야 합니다. 특히 검색 키는 일반 키보다 길 수 있습니다. 이 추가 길이는 검색 키를 생성하는 동안 와일드카드 옵션을 사용할 때 발생합니다. 자세한 내용은 JetMakeKey 를 참조하세요.

이 API에는 모든 릴리스에 있는 중요한 버그가 있습니다. JET_bitRetrieveCopy 사용을 사용하여 검색 키를 요청하고 출력 버퍼가 너무 작아서 전체 키를 수신할 수 없는 경우 JET_wrnBufferTruncated 반환되지 않습니다. 대신 JET_errSuccess 반환됩니다. pcbActual을 사용하여 반환된 키의 실제 크기가 출력 버퍼의 크기보다 작거나 같은지 확인하는 것이 중요합니다. 실제 크기가 출력 버퍼의 크기보다 큰 경우 JetRetrieveKey 호출자는 대신 JET_wrnBufferTruncated 반환된 것처럼 반응해야 합니다.

요구 사항

요구 사항	값
클라이언트	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_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetSeek
JetSetIndexRange

JetRetrieveKey 함수