JetSetCurrentIndex3 함수

아티클
06/13/2023

적용 대상: Windows | Windows Server

JetSetCurrentIndex3 함수

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

    JET_ERR JET_API JetSetCurrentIndex3(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in          JET_GRBIT grbit,
      __in          unsigned long itagSequence
    );

매개 변수

sesid

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

tableid

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

szIndexName

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

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

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

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의 내용이 잘못되었거나 만료되어 새로 고쳐야 합니다. 이 작업은 다음과 같은 경우 JetSetCurrentIndex3 에서 발생할 수 있습니다. 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 및 이전 릴리스)가 아닌 경우 JetSetCurrentIndex3에서 발생할 수 있습니다.
JET_errNoCurrentRecord	보조 인덱스는 JET_bitNoMove 옵션을 사용하여 선택되고 있으며 새 인덱스에는 이전 인덱스의 커서 현재 위치에 있는 인덱스 항목과 연결된 레코드에 해당하는 인덱스 항목이 없습니다.
JET_errNotInitialized	세션과 연결된 instance 아직 초기화되지 않았기 때문에 작업을 완료할 수 없습니다.
JET_errOutOfCursors	엔진이 커서를 여는 데 사용되는 리소스 풀을 모두 사용했습니다. 한 번에 열 수 있는 최대 커서 수는 JET_paramMaxCursors 사용하여 제어됩니다. 자세한 내용은 JetSetSystemParameter 를 참조하세요. 보조 인덱스가 선택되어 있고 엔진이 해당 인덱스를 사용하기 위해 내부 커서를 열 수 없는 경우 JetSetCurrentIndex3 에서 발생할 수 있습니다.
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 필요합니다.
유니코드	JetSetCurrentIndex3W(유니코드) 및 JetSetCurrentIndex3A(ANSI)로 구현됩니다.

참고 항목

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

다음을 통해 공유

JetSetCurrentIndex3 함수