JetSetCurrentIndex4 함수

아티클
06/13/2023

적용 대상: Windows | Windows Server

JetSetCurrentIndex4 함수

JetSetCurrentIndex4 함수는 커서의 현재 인덱스를 설정하는 데 사용됩니다. 커서의 현재 인덱스는 해당 커서에 표시되는 테이블의 레코드와 해당 레코드를 노출하는 데 사용할 인덱스 항목 집합을 선택하여 표시되는 순서를 정의합니다.

    JET_ERR JET_API JetSetCurrentIndex4(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in_opt      JET_INDEXID* pindexid,
      __in          JET_GRBIT grbit,
      __in          unsigned long itagSequence
    );

매개 변수

sesid

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

tableid

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

szIndexName

커서에 대해 선택할 인덱스의 이름입니다. 이 매개 변수가 NULL이거나 빈 문자열인 경우 클러스터형 인덱스가 선택됩니다. 테이블에 대해 기본 인덱스가 정의된 경우 클러스터형 인덱스와 동일하기 때문에 해당 인덱스가 선택됩니다. 테이블에 대해 기본 인덱스가 정의되지 않은 경우 순차적 인덱스가 선택됩니다. 순차 인덱스는 인덱스 정의가 없습니다. 자세한 내용은 JetCreateIndex 를 참조하세요.

pindexid가 NULL이 아니면 인덱스 이름이 무시되고 인덱스 ID로 인덱스가 선택됩니다.

pindexid

커서에 대해 선택할 인덱스의 ID입니다.

인덱스 ID는 인덱스 빠르게 선택하는 데 사용할 수 있는 휘발성 불투명 핸들입니다. 이 ID는 JET_IdxInfoIndexId 옵션을 사용하여 JetGetIndexInfo 또는 JetGetTableIndexInfo를 사용하여 검색할 수 있습니다.

pindexid가 NULL이면 인덱스 이름으로 인덱스가 선택되고 인덱스 ID는 무시됩니다.

이 매개 변수가 없으면 해당 값은 NULL로 추정됩니다.

grbit

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

값	의미
JET_bitMoveFirst	이 옵션은 지정된 인덱스의 첫 번째 항목에 커서를 배치해야 했음을 나타냅니다. 클러스터형 인덱스(기본 인덱스 또는 순차 인덱스)를 선택하고 현재 인덱스가 보조 인덱스인 경우 JET_bitMoveFirst 가정합니다. 현재 인덱스를 선택하는 경우 이 옵션은 무시되고 커서 위치는 변경되지 않습니다.
JET_bitNoMove	이 옵션은 커서가 이전 인덱스의 커서 현재 위치에 있는 인덱스 항목과 연결된 레코드에 해당하는 새 인덱스의 인덱스 항목에 배치되어야 했음을 나타냅니다. 새 인덱스에 대한 정의에 다중값 키 열이 하나 이상 포함되어 있으면 대상 인덱스 항목이 모호합니다. 이 경우 지정된 itagSequence 를 사용하여 커서를 배치하는 데 사용되는 가장 중요한 다중 값 키 열의 다중 값을 선택합니다. 엔진이 가장 중요한 다중 값 키 열에 대한 모든 값만 확장하므로 다중 값이 여러 키 열이 있는 경우에도 단일 itagSequence 를 전달하기만 하면 됩니다. 자세한 내용은 JetCreateIndex 를 참조하세요. JET_bitMoveFirst 지정되면 이 옵션은 무시됩니다. 현재 인덱스를 선택하는 경우 이 옵션은 무시되고 커서 위치는 변경되지 않습니다. 이 매개 변수가 없으면 해당 값은 JET_bitMoveFirst 것으로 추정됩니다.

값

의미

JET_bitMoveFirst

이 옵션은 지정된 인덱스의 첫 번째 항목에 커서를 배치해야 했음을 나타냅니다. 클러스터형 인덱스(기본 인덱스 또는 순차 인덱스)를 선택하고 현재 인덱스가 보조 인덱스인 경우 JET_bitMoveFirst 가정합니다. 현재 인덱스를 선택하는 경우 이 옵션은 무시되고 커서 위치는 변경되지 않습니다.

JET_bitNoMove

이 옵션은 커서가 이전 인덱스의 커서 현재 위치에 있는 인덱스 항목과 연결된 레코드에 해당하는 새 인덱스의 인덱스 항목에 배치되어야 했음을 나타냅니다.

새 인덱스에 대한 정의에 다중값 키 열이 하나 이상 포함되어 있으면 대상 인덱스 항목이 모호합니다. 이 경우 지정된 itagSequence 를 사용하여 커서를 배치하는 데 사용되는 가장 중요한 다중 값 키 열의 다중 값을 선택합니다. 엔진이 가장 중요한 다중 값 키 열에 대한 모든 값만 확장하므로 다중 값이 여러 키 열이 있는 경우에도 단일 itagSequence 를 전달하기만 하면 됩니다. 자세한 내용은 JetCreateIndex 를 참조하세요.

JET_bitMoveFirst 지정되면 이 옵션은 무시됩니다.

현재 인덱스를 선택하는 경우 이 옵션은 무시되고 커서 위치는 변경되지 않습니다. 이 매개 변수가 없으면 해당 값은 JET_bitMoveFirst 것으로 추정됩니다.

itagSequence

커서를 새 인덱스에 배치하는 데 사용할 다중값 열 값의 시퀀스 번호입니다.

이 매개 변수는 JET_bitNoMove 함께만 사용됩니다. 자세한 내용은 이 옵션에 대한 설명을 참조하세요.

이 매개 변수가 없거나 0으로 설정된 경우 해당 값은 1로 추정됩니다.

반환 값

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

반환 코드	설명
JET_errSuccess	작업이 성공적으로 완료되었습니다.
JET_errBadItagSequence	보조 인덱스는 JET_bitNoMove 옵션을 사용하여 선택되고 있으며 지정된 시퀀스 번호에 해당하는 새 인덱스에 대한 정의에 첫 번째 다중값 키 열에 대한 값이 없습니다.
JET_errClientRequestToStopJetService	JetStopService 호출로 인해 세션과 연결된 instance 모든 작업이 중단되었으므로 작업을 완료할 수 없습니다.
JET_errInstanceUnavailable	세션과 연결된 instance 해당 데이터의 무결성을 보호하기 위해 모든 데이터에 대한 액세스를 해지해야 하는 심각한 오류가 발생하여 작업을 완료할 수 없습니다. 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.
JET_errInvalidIndexId	인덱스 ID의 내용이 잘못되었거나 만료되어 새로 고쳐야 합니다. JetSetCurrentIndex4는 다음과 같은 경우에 발생할 수 있습니다. pindexid-cbStruct>는 예상 크기(Windows Server 2003 이상 릴리스)가 아닙니다. 인덱스 ID를 가져온 후 엔진이 종료되었습니다. 인덱스 ID에 해당하는 인덱스가 포함된 테이블을 참조하는 모든 커서가 닫혔으며 엔진이 스키마 캐시에서 해당 인덱스의 정의를 제거했습니다. 잘못된 테이블에서 열린 커서와 함께 인덱스 ID를 사용하고 있습니다. 인덱스가 삭제되었거나 아직 세션에 표시되지 않습니다.
JET_errInvalidName	지정한 개체 이름 중 하나가 잘못되었습니다. 모든 개체 이름은 동일한 규칙 집합을 준수해야 합니다. 이러한 규칙은 다음과 같습니다. 개체 이름은 ASCII 문자로 구성되어야 합니다. 개체 이름은 길이가 하나 이상이어야 합니다. 개체 이름은 길이가 JET_cbNameMost(64)를 초과할 수 없습니다. 개체 이름은 공백으로 시작할 수 없습니다. 개체 이름에는 ASCII 컨트롤 문자가 포함될 수 없습니다(0x1F 통해 0x00). 개체 이름에는 느낌표(!), 마침표(.), 왼쪽 대괄호([) 또는 오른쪽 대괄호(]) 문자가 포함될 수 없습니다. 유효성이 검사되면 첫 번째 공간(있는 경우)까지의 문자열 부분만 개체 이름에 사용됩니다. 이는 개체 이름에 공백도 포함되지 않을 수 있음을 의미합니다.
JET_errInvalidParameter	제공된 매개 변수 중 하나에 예기치 않은 값이 포함되어 있거나 다른 매개 변수의 값과 결합할 때 의미가 없는 값이 포함되어 있습니다. pindexid가 NULL이 아니고 pindexid-cbStruct>가 예상 크기(Windows XP 및 이전 릴리스)가 아닌 경우 JetSetCurrentIndex4에서 발생할 수 있습니다.
JET_errNoCurrentRecord	보조 인덱스는 JET_bitNoMove 옵션을 사용하여 선택되고 있으며 새 인덱스에는 이전 인덱스의 커서 현재 위치에 있는 인덱스 항목과 연결된 레코드에 해당하는 인덱스 항목이 없습니다.
JET_errNotInitialized	세션과 연결된 instance 아직 초기화되지 않았기 때문에 작업을 완료할 수 없습니다.
JET_errOutOfCursors	엔진이 커서를 여는 데 사용되는 리소스 풀을 모두 사용했습니다. 한 번에 열 수 있는 최대 커서 수는 JET_paramMaxCursors 사용하여 제어됩니다. 자세한 내용은 JetSetSystemParameter 를 참조하세요. 보조 인덱스를 선택하고 엔진에서 해당 인덱스를 사용하기 위해 내부 커서를 열 수 없는 경우 JetSetCurrentIndex4 에서 이 문제가 발생할 수 있습니다.
JET_errRestoreInProgress	세션과 연결된 instance 복원 작업이 진행 중이므로 작업을 완료할 수 없습니다.
JET_errSessionSharingViolation	두 개 이상의 스레드에 대해 동시에 동일한 세션을 사용할 수 없습니다. 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.
JET_errTermInProgress	세션과 연결된 instance 종료 중이므로 작업을 완료할 수 없습니다.

성공하면 커서의 현재 인덱스가 요청된 인덱스로 설정됩니다. 이제 요청된 인덱스의 인덱스 정의에 따라 JetSeek 을 사용하여 인덱스 항목을 찾을 수 있습니다. 인덱스 항목은 해당 인덱스 정의에 지정된 순서대로 JetMove 를 사용하여 열거할 수도 있습니다. 커서의 현재 위치는 인덱스의 첫 번째 인덱스 항목(JET_bitMoveFirst) 또는 이전 인덱스(JET_bitNoMove)에서 커서의 현재 위치와 관련된 특정 인덱스 항목으로 설정됩니다. 데이터베이스 상태는 변경되지 않습니다.

오류가 발생하면 커서의 현재 인덱스 및 현재 위치가 정의되지 않은 상태입니다. 데이터베이스 상태는 변경되지 않습니다.

설명

인덱스 ID 힌트가 부실하면 API는 단순히 실패합니다. 이 경우 예상한 대로 인덱스의 텍스트 이름을 대체하지 않습니다. 이 대체는 API의 호출자가 수동으로 수행해야 합니다.

요구 사항

요구 사항	값
클라이언트	Windows Vista, Windows XP 또는 Windows 2000 Professional이 필요합니다.
서버	Windows Server 2008, Windows Server 2003 또는 Windows 2000 Server가 필요합니다.
머리글	Esent.h에 선언되었습니다.
라이브러리	ESENT.lib를 사용합니다.
DLL	ESENT.dll 필요합니다.
유니코드	JetSetCurrentIndex4W(유니코드) 및 JetSetCurrentIndex4A(ANSI)로 구현됩니다.

참고 항목

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSeek
JetSetSystemParameter

JetSetCurrentIndex4 함수