JetMakeKey 함수

  • 아티클

적용 대상: Windows | Windows Server

JetMakeKey 함수

JetMakeKey 함수는 키 열 값에 대한 몇 가지 간단한 검색 조건으로 인덱스에서 항목 집합을 찾는 데 사용할 수 있는 검색 키를 생성합니다. 검색 키는 커서의 내장 속성 중 하나이기도 하며 JetSeek 및 JetSetIndexRange 작업에서 해당 커서의 현재 인덱스에서 이러한 검색 조건과 일치하는 인덱스 항목을 찾는 데 사용됩니다. 전체 검색 키는 각 호출이 커서의 현재 인덱스의 다음 키 열에 대한 열 값을 로드하는 데 사용되는 일련의 JetMakeKey 호출에서 빌드됩니다. JetRetrieveKey를 사용하여 커서에서 검색된 이전에 생성된 검색 키를 로드할 수도 있습니다.

    JET_ERR JET_API JetMakeKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit
    );

매개 변수

sesid

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

tableid

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

pvData

검색 키가 생성되는 커서의 현재 인덱스 현재 키 열에 대한 열 데이터를 포함하는 입력 버퍼입니다.

입력 버퍼에 있는 열 데이터의 데이터 형식은 현재 키 열의 열 정의에 대한 데이터 형식 및 기타 속성과 정확히 일치해야 합니다. 열 데이터에 대해 형식 강제 변환이 수행되지 않습니다.

grbit 매개 변수에 JET_bitNormalizedKey 지정된 경우 입력 버퍼에는 이전에 생성된 검색 키가 포함되어야 합니다. 이러한 키는 JetRetrieveKey 호출을 사용하여 가져옵니다.

cbData

입력 버퍼에 제공된 열 데이터의 크기(바이트)입니다.

grbit 매개 변수에 JET_bitNormalizedKey 지정한 경우 입력 버퍼에 제공된 검색 키의 크기입니다.

열 데이터의 크기가 0이면 입력 버퍼의 내용이 무시됩니다. grbit 매개 변수에 JET_bitKeyDataZeroLength 지정되고 커서의 현재 인덱스 현재 키 열이 가변 길이 열인 경우 입력 열 데이터는 길이가 0인 것으로 간주됩니다. 그렇지 않으면 입력 열 데이터가 NULL 값으로 간주됩니다.

grbit

다음 옵션 중 0개 이상을 지정하는 비트 그룹입니다.

값

의미

JET_bitFullColumnEndLimit

검색 키는 현재 키 열 다음에 오는 모든 키 열이 와일드카드로 간주되는 방식으로 생성되어야 합니다. 즉, 생성된 검색 키를 사용하여 다음과 같은 인덱스 항목을 일치시킬 수 있습니다.

  • 이 키 열 및 모든 이전 키 열에 대해 제공된 정확한 열 값입니다.

  • 후속 키 열에 필요한 모든 열 값입니다.

이 옵션은 인덱스 끝에 가장 가까운 인덱스 항목을 찾는 데 사용할 와일드카드 검색 키를 빌드할 때 사용해야 합니다. 인덱스의 끝은 해당 인덱스의 마지막 레코드로 이동할 때 발견되는 인덱스 항목입니다. 인덱스의 끝은 인덱스에 있는 키 열의 정렬 순서에 따라 변경 될 수 있는 인덱스의 하이 엔드와 동일 하지 않습니다.

이 옵션은 Windows XP 이상 릴리스에서만 사용할 수 있습니다.

JETbitFullColumnStartLimit

현재 키 열 다음에 오는 모든 키 열을 와일드카드로 간주하도록 검색 키를 생성해야 합니다. 즉, 생성된 검색 키를 사용하여 다음과 같은 인덱스 항목을 일치시킬 수 있습니다.

  • 이 키 열 및 모든 이전 키 열에 대해 제공된 정확한 열 값입니다.

  • 후속 키 열에 필요한 모든 열 값입니다.

이 옵션은 인덱스의 시작 부분에 가장 가까운 인덱스 항목을 찾는 데 사용할 와일드카드 검색 키를 빌드할 때 사용해야 합니다. 인덱스의 시작은 해당 인덱스의 첫 번째 레코드로 이동할 때 발견되는 인덱스 항목입니다. 인덱스의 시작은 인덱스의 하위 끝과 동일하지 않으므로 인덱스에 있는 키 열의 정렬 순서에 따라 변경할 수 있습니다.

이 옵션은 Windows XP 이상 릴리스에서만 사용할 수 있습니다.

JET_bitKeyDataZeroLength

입력 버퍼의 크기가 0이고 현재 키 열이 가변 길이 열인 경우 이 옵션은 입력 버퍼에 길이 값이 0임을 나타냅니다. 그렇지 않으면 입력 버퍼 크기가 0이면 NULL 값이 표시됩니다.

JET_bitNewKey

새 검색 키를 생성해야 합니다. 기존 검색 키는 모두 삭제됩니다.

JET_bitNormalizedKey

이 옵션을 지정하면 다른 모든 옵션이 무시되고, 기존 검색 키가 삭제되고, 입력 버퍼의 내용이 새 검색 키로 로드됩니다.

JET_bitPartialColumnEndLimit

현재 키 열이 접두사 와일드카드로 간주되고 현재 키 열 다음에 오는 모든 키 열이 와일드카드로 간주되도록 검색 키를 생성해야 합니다. 즉, 생성된 검색 키를 사용하여 다음과 같은 인덱스 항목을 일치시킬 수 있습니다.

  • 이 키 열 및 모든 이전 키 열에 대해 제공된 정확한 열 값입니다.

  • 후속 키 열에 필요한 모든 열 값입니다.

이 옵션은 인덱스 끝에 가장 가까운 인덱스 항목을 찾는 데 사용할 와일드카드 검색 키를 빌드할 때 사용해야 합니다. 인덱스의 끝은 해당 인덱스의 마지막 레코드로 이동할 때 발견되는 인덱스 항목입니다. 인덱스의 끝은 인덱스에 있는 키 열의 정렬 순서에 따라 변경 될 수 있는 인덱스의 하이 엔드와 동일 하지 않습니다.

현재 키 열이 텍스트 열이나 가변 이진 열이 아닌 경우에는 이 옵션을 사용할 수 없습니다. 이 작업이 시도되면 JET_errInvalidgrbit 작업이 실패합니다.

이 옵션은 Windows XP 이상 릴리스에서만 사용할 수 있습니다.

JET_bitPartialColumnStartLimit

이 옵션은 현재 키 열이 접두사 와일드카드로 간주되고 현재 키 열 다음에 오는 모든 키 열이 와일드카드로 간주되도록 검색 키를 생성해야 했음을 나타냅니다. 즉, 생성된 검색 키를 사용하여 다음과 같은 인덱스 항목을 일치시킬 수 있습니다.

  • 이 키 열 및 모든 이전 키 열에 대해 제공된 정확한 열 값입니다.

  • 후속 키 열에 필요한 모든 열 값입니다.

이 옵션은 인덱스의 시작 부분에 가장 가까운 인덱스 항목을 찾는 데 사용할 와일드카드 검색 키를 빌드할 때 사용해야 합니다. 인덱스의 시작은 해당 인덱스의 첫 번째 레코드로 이동할 때 발견되는 인덱스 항목입니다. 인덱스의 시작은 인덱스의 하위 끝과 동일하지 않으므로 인덱스에 있는 키 열의 정렬 순서에 따라 변경할 수 있습니다.

현재 키 열이 텍스트 열이나 가변 이진 열이 아닌 경우에는 이 옵션을 사용할 수 없습니다. 이 작업이 시도되면 JET_errInvalidgrbit 작업이 실패합니다.

이 옵션은 Windows XP 이상 릴리스에서만 사용할 수 있습니다.

JET_bitStrLimit

이 옵션은 현재 키 열 다음에 오는 모든 키 열을 와일드카드로 간주하도록 검색 키를 생성해야 했음을 나타냅니다. 즉, 생성된 검색 키를 사용하여 다음과 같은 인덱스 항목을 일치시킬 수 있습니다.

  • 이 키 열 및 모든 이전 키 열에 대해 제공된 정확한 열 값입니다.

  • 후속 키 열에 필요한 모든 열 값입니다.

이 옵션은 인덱스 끝에 가장 가까운 인덱스 항목을 찾는 데 사용할 와일드카드 검색 키를 빌드할 때 사용해야 합니다. 인덱스의 끝은 해당 인덱스의 마지막 레코드로 이동할 때 발견되는 인덱스 항목입니다. 인덱스의 끝은 인덱스에 있는 키 열의 정렬 순서에 따라 변경 될 수 있는 인덱스의 하이 엔드와 동일 하지 않습니다.

이 옵션을 JET_bitSubStrLimit 함께 지정하고 현재 키 열이 텍스트 열인 경우 이 옵션은 무시됩니다. 이 동작은 검색 키를 빌드할 때 현재 키 열의 형식을 유추할 수 있도록 하기 위한 것입니다.

인덱스 시작에 대해 유사한 검색 키를 빌드하려는 경우 와일드카드가 아니지만 와일드카드 옵션이 지정되지 않은 마지막 키 열에 대해 JetMakeKey 를 비슷한 호출로 만들어야 합니다. 그런 다음 검색 키는 이러한 검색에 사용할 적절한 상태입니다. 이는 JET_bitFullColumnStartLimit 사용하는 것과 유사합니다. 단, 와일드카드 옵션을 사용한 후 검색 키가 제대로 완료되지 않았습니다.

이 옵션은 이 어색한 의미 체계를 해결하기 위해 Windows XP 및 이후 릴리스에서 더 이상 사용되지 않습니다. 가능한 경우 JET_bitFullColumnStartLimit 및 JET_bitFullColumnEndLimit 대신 사용해야 합니다.

JET_bitSubStrLimit

이 옵션은 현재 키 열이 접두사 와일드카드로 간주되고 현재 키 열 다음에 오는 모든 키 열이 와일드카드로 간주되도록 검색 키를 생성해야 했음을 나타냅니다. 즉, 생성된 검색 키를 사용하여 다음과 같은 인덱스 항목을 일치시킬 수 있습니다.

  • 모든 이전 키 열에 대해 제공된 정확한 열 값입니다.

  • 현재 키 열에 대한 열 값의 접두사로 지정된 열 데이터입니다.

  • 후속 키 열에 대한 모든 열 값입니다.

이 옵션은 인덱스 끝에 가장 가까운 인덱스 항목을 찾는 데 사용할 와일드카드 검색 키를 빌드할 때 사용해야 합니다. 인덱스의 끝은 해당 인덱스의 마지막 레코드로 이동할 때 발견되는 인덱스 항목입니다. 인덱스의 끝은 인덱스에 있는 키 열의 정렬 순서에 따라 변경 될 수 있는 인덱스의 하이 엔드와 동일 하지 않습니다.

이 옵션이 JET_bitStrLimit 함께 지정되고 현재 키 열이 텍스트 열인 경우 이 옵션이 우선적으로 적용됩니다. 현재 키 열이 텍스트 열이 아닌 경우 이 옵션은 무시됩니다. 이 동작은 검색 키를 빌드할 때 현재 키 열의 형식을 유추할 수 있도록 하기 위한 것입니다.

인덱스의 시작 부분에 유사한 검색 키를 빌드하려는 경우 접두사 와일드카드가 되지만 와일드카드 옵션이 지정되지 않은 키 열에 대해 JetMakeKey 를 비슷한 호출로 만들어야 합니다. 그런 다음 검색 키는 이러한 검색에 사용할 적절한 상태입니다. 이는 JET_bitPartialColumnStartLimit 사용하는 것과 유사합니다. 단, 와일드카드 옵션을 사용한 후 검색 키가 제대로 완료되지 않았습니다.

이 옵션은 이 어색한 의미 체계를 해결하기 위해 Windows XP 및 이후 릴리스에서 더 이상 사용되지 않습니다. 가능한 경우 JET_bitPartialColumnStartLimit 및 JET_bitPartialColumnEndLimit 대신 사용해야 합니다.

반환 값

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

반환 코드

설명

JET_errSuccess

작업이 성공적으로 완료되었습니다.

JET_errClientRequestToStopJetService

JetStopService 호출로 인해 세션과 연결된 instance 모든 작업이 중단되었으므로 작업을 완료할 수 없습니다.

JET_errIndexTuplesKeyTooSmall

제공된 열 데이터가 너무 작아서 해당 인덱스가 튜플 인덱스이고 최소 튜플 크기가 제공된 열 데이터보다 크기 때문에 현재 인덱스에 대한 유효한 키를 작성할 수 없습니다. 튜플 인덱스에 대한 자세한 내용은 JetCreateIndex 를 참조하세요. 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.

JET_errInstanceUnavailable

세션과 연결된 instance 해당 데이터의 무결성을 보호하기 위해 모든 데이터에 대한 액세스를 해지해야 하는 심각한 오류가 발생하여 작업을 완료할 수 없습니다. 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.

JET_errInvalidBufferSize

제공된 열 데이터가 열 정의에 필요한 크기와 일치하지 않습니다. 이 문제는 열의 데이터 형식이 본질적으로 특정 크기인 경우에 발생할 수 있습니다. 열의 데이터 형식이 본질적으로 특정 크기가 아니지만 열의 정의에서 고정 길이로 선언하는 경우에도 이 문제가 발생할 수 있습니다. 한 가지 예외는 누락된 데이터가 공백으로 자동으로 채워지므로 고정 길이 텍스트 열에 대해 너무 적은 데이터가 제공될 때 이 오류가 발생하지 않는다는 것입니다. 이에 대한 두 번째 예외는 누락된 데이터가 자동으로 0으로 채워지므로 고정 길이 이진 열에 대해 너무 적은 데이터가 제공될 때 이 오류가 발생하지 않는다는 것입니다.

JET_errInvalidgrbit

요청된 옵션 중 하나가 잘못되었거나, 잘못된 방식으로 사용되었거나, 구현되지 않았습니다. 이는 다음과 같은 경우 JetMakeKey 에 대해 발생할 수 있습니다.

  • JET_bitPartialColumnStartLimit 또는 JET_bitPartialColumnEndLimit 지정되고 해당 키 열은 텍스트 열이 아니며 가변 길이 이진 열이 아닙니다. 이 경우는 Windows XP 이상 릴리스에서만 발생합니다.

  • JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit 및 JET_bitFullColumnEndLimit 옵션 중 하나 이상을 함께 사용하려고 합니다. 이 경우는 Windows XP 이상 릴리스에서만 발생합니다.

  • JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit 및 JET_bitFullColumnEndLimit 옵션 중 하나를 사용하는 경우 JET_bitStrLimit 또는 JET_bitSubStrLimit 사용하려고 시도합니다. 이 경우는 Windows XP 이상 릴리스에서만 발생합니다.

JET_errInvalidParameter

제공된 매개 변수 중 하나에 예기치 않은 값이 포함되어 있거나 다른 매개 변수의 값과 결합할 때 의미가 없는 값이 포함되어 있습니다.

이 문제는 JET_bitNormalizedKey 지정되고 입력 버퍼에 제공된 값이 너무 커서 유효한 검색 키가 될 수 없을 때 JetMakeKey 에서 발생할 수 있습니다.

JET_errKeyIsMade

현재 인덱스의 모든 키 열에 대해 열 데이터가 이미 제공되었으므로 JetMakeKey 에 제공된 열 데이터가 거부되었습니다. 이 작업은 세 가지 방법으로 발생할 수 있습니다. 첫 번째 방법은 현재 인덱스의 각 키 열에 대해 열 데이터가 제공되는 경우입니다. 두 번째 방법은 하나 이상의 키 열에 대해 열 데이터가 제공되고 마지막 호출에 대해 와일드카드 옵션을 선택한 경우입니다. 세 번째 방법은 모든 키 열을 포함하는 JET_bitNormalizedKey 사용하여 이전에 생성된 검색 키를 제공한 경우입니다.

JET_errKeyNotMade

커서에 대한 현재 검색 키가 없습니다. 이는 JET_bitNewKey 지정되지 않았고 JetMakeKey 에 대한 이전 호출을 사용하여 이 커서에 대한 검색 키가 생성되지 않은 경우 JetMakeKey에 대해 발생합니다. 검색 키는 JetMove 이외의 커서에서 탐색 API에 대한 사전 호출에 의해 삭제됩니다.

JET_errNoCurrentIndex

커서에 대한 현재 인덱스가 없습니다. 커서가 테이블의 클러스터형 인덱스에 있고 기본 인덱스가 정의되지 않았으며 JET_bitNormalizedKey 지정되지 않은 경우 JetMakeKey 에 대해 발생합니다. 이전에 생성된 검색 키가 제공되지 않는 한 커서가 키 열이 없는 인덱스에 있는 경우 검색 키를 생성할 수 없습니다.

JET_errNotInitialized

세션과 연결된 instance 아직 초기화되지 않았기 때문에 작업을 완료할 수 없습니다.

JET_errRestoreInProgress

세션과 연결된 instance 복원 작업이 진행 중이므로 작업을 완료할 수 없습니다.

JET_errSessionSharingViolation

동시에 둘 이상의 스레드에 동일한 세션을 사용할 수 없습니다. 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.

JET_errTermInProgress

세션과 연결된 instance 종료 중이므로 작업을 완료할 수 없습니다.

성공하면 JET_bitNormalizedKey 및 JET_bitNewKey 지정되지 않은 경우 검색 키는 현재 인덱스에서 하나 이상의 키 열에 대한 검색 조건에 의해 빌드됩니다. JET_bitNormalizedKey 지정하지 않고 JET_bitNewKey 지정한 경우 기존 검색 키가 삭제되고 현재 인덱스에서 첫 번째 키 열의 검색 조건에 따라 새 검색 키가 빌드됩니다. JET_bitNormalizedKey 지정한 경우 기존 검색 키가 삭제되고 입력 버퍼에서 새 검색 키가 로드됩니다. 어떤 경우에도 데이터베이스 상태는 변경되지 않습니다.

실패 시 JET_bitNormalizedKey 또는 JET_bitNewKey 지정한 경우 검색 키의 상태가 정의되지 않습니다. JET_bitNormalizedKey 또는 JET_bitNewKey 지정되지 않은 경우 검색 키의 상태가 변경되지 않습니다. 어떤 경우에도 데이터베이스 상태는 변경되지 않습니다.

설명

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

  • memcmp를 사용하여 원본 인덱스 항목의 테이블에 대해 원래 인덱스에서 상대 순서를 설정하기 위해 키를 서로 비교할 수 있습니다.

  • 서로 다른 인덱스의 인덱스 항목 키를 서로 비교하는 것은 의미가 없습니다.

  • 키는 항상 Windows Vista 이전의 길이가 JET_cbKeyMost(255) 바이트보다 작거나 같습니다. Windows Vista 이상 릴리스에서는 키가 더 클 수 있습니다. 키의 최대 크기는 JET_paramKeyMost 현재 값과 같습니다.

와일드카드 옵션을 사용한 경우 검색 키는 1 바이트 이상일 수 있습니다. 이 경우 검색 키는 Windows Vista 이전 릴리스의 경우 최대 JET_cbLimitKeyMost(256) 바이트이고 Windows Vista 이상 릴리스의 경우 JET_paramKeyMost + 1바이트입니다.

이 최대 키 크기에 매우 중요한 파급 효과가 있습니다. 이 최대 크기보다 큰 인덱스에서 키가 생성될 만큼 충분히 큰 열 값이 있는 인덱스 항목이 있을 때마다 해당 키는 해당 최대 크기에서 자동으로 잘립니다. 이로 인해 다음 두 가지 효과가 발생합니다.

  • 고유 인덱스의 항목의 경우 고유하지 않은 항목이 중복으로 선언됩니다.

  • 모든 인덱스의 항목에 대해 키 잘림으로 인해 지정된 검색 키의 검색 조건과 일치하지 않는 인덱스 항목이 일치 항목으로 선언됩니다.

애플리케이션은 이 잘림을 예상하고 이를 방지하거나 효과를 보정해야 합니다. Windows Vista에서는 애플리케이션이 키 잘림을 보다 쉽게 방지할 수 있도록 새 인덱스 플래그 JET_bitIndexDisallowTruncation 추가되었습니다. 이 인덱싱 옵션에 대한 자세한 내용은 JET_INDEXCREATE 구조를 참조하세요.

요구 사항

요구 사항 값

클라이언트

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
JetCreateIndex
JetRetrieveKey
JetSeek
JetSetIndexRange