JetMove 함수

  • 아티클

적용 대상: Windows | Windows Server

JetMove 함수

JetMove 함수는 인덱스의 시작 또는 끝에 커서를 놓고 해당 인덱스의 항목을 앞으로 또는 뒤로 트래버스합니다. 지정된 개수의 인덱스 항목으로 현재 인덱스에서 커서를 앞으로 또는 뒤로 이동할 수도 있습니다. 또 다른 방법은 JetSetIndexRange를 사용하여 커서에서 인덱스 범위를 설정하여 JetMove를 사용하여 열거할 수 있는 인덱스 항목을 인위적으로 제한하는 것입니다.

    JET_ERR JET_API JetMove(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          long cRow,
      __in          JET_GRBIT grbit
    );

매개 변수

sesid

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

tableid

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

까마귀

현재 인덱스에서 커서의 원하는 이동을 나타내는 임의의 오프셋입니다.

표준 오프셋 외에도 다음 옵션 중 하나를 사용하여 이 매개 변수를 설정할 수도 있습니다.

값

의미

JET_MoveFirst

커서를 인덱스의 첫 번째 인덱스 항목으로 이동합니다(있는 경우). 이렇게 하면 JetSetIndexRange를 사용하여 설정된 인덱스 범위가 다시 설정됩니다.

참고 -2147483648 리터럴 값은 이 옵션을 나타내는 데 사용됩니다. 이 값을 일반 오프셋으로 사용하지 마세요. 그렇지 않으면 의도하지 않은 동작이 발생할 수 있습니다.

JET_MoveLast

커서를 인덱스의 마지막 인덱스 항목(있는 경우)으로 이동합니다. 이렇게 하면 JetSetIndexRange를 사용하여 설정된 인덱스 범위가 다시 설정됩니다.

참고 2147483647 리터럴 값은 이 옵션을 나타내는 데 사용됩니다. 이 값을 일반 오프셋으로 사용하지 마세요. 그렇지 않으면 의도하지 않은 동작이 발생할 수 있습니다.

JET_MoveNext

커서를 인덱스의 다음 인덱스 항목으로 이동합니다(있는 경우). 이 값은 +1의 일반 오프셋과 정확히 같습니다. JetSetIndexRange로 설정된 인덱스 범위를 준수합니다.

JET_MovePrevious

커서를 인덱스의 이전 인덱스 항목으로 이동합니다(있는 경우). JetSetIndexRange로 설정된 인덱스 범위를 준수합니다.

이 값은 -1 또는 0(영)의 일반 오프셋과 정확히 같습니다.

커서는 현재 논리 위치에 남아 있으며 해당 논리 위치에 해당하는 인덱스 항목의 존재가 테스트됩니다.

grbit

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

값

의미

JET_bitMoveKeyNE

인덱스에서 발생한 요청된 인덱스 키 값 수를 건너뛰는 데 필요한 인덱스 항목 수만큼 커서를 앞뒤로 이동합니다. 이렇게 하면 중복 키 값이 있는 인덱스 항목을 단일 인덱스 항목으로 축소하는 효과가 있습니다. 일반적으로 오프셋은 키 값에 관계없이 지정된 인덱스 항목 수만큼 커서를 이동합니다.

반환 값

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

반환 코드

설명

JET_errSuccess

작업이 성공적으로 완료되었습니다. JetMove의 경우 인덱스 항목이 현재 인덱스에서 요청된 위치 또는 오프셋에서 발견되었음을 의미합니다.

JET_errClientRequestToStopJetService

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

JET_errInstanceUnavailable

세션과 연결된 instance 해당 데이터의 무결성을 보호하기 위해 모든 데이터에 대한 액세스를 취소해야 하는 심각한 오류가 발생하여 작업을 완료할 수 없습니다.

Windows XP: 이 반환 값은 Windows XP에 도입되었습니다.

JET_errNoCurrentRecord

커서가 현재 인덱스 항목에 배치되지 않았습니다. JetMove의 경우 현재 인덱스에서 요청된 위치 또는 오프셋에서 인덱스 항목을 찾을 수 없음을 의미합니다.

JET_errNotInitialized

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

JET_errRecordDeleted

커서는 현재 삭제된 레코드에 해당하는 인덱스 항목에 논리적으로 배치됩니다.

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

동시에 둘 이상의 스레드에 동일한 세션을 사용할 수 없습니다.

Windows XP: 이 반환 값은 Windows XP에 도입되었습니다.

JET_errTermInProgress

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

이 함수가 성공하면 커서가 요청된 위치 또는 오프셋과 일치하는 인덱스 항목에 배치됩니다. 업데이트할 레코드가 준비되면 해당 업데이트가 취소됩니다. 인덱스 범위가 적용되고 JET_MoveFirst 또는 JET_MoveLast 지정된 경우 해당 인덱스 범위가 취소됩니다. 데이터베이스 상태는 변경되지 않습니다.

이 함수가 실패하면 JET_errNoCurrentRecord 반환되지 않는 한 커서의 위치는 변경되지 않은 상태로 유지됩니다. 이 경우 커서는 요청된 위치 또는 오프셋과 일치하는 인덱스 항목이 있는 위치에 배치됩니다. 커서는 해당 위치를 기준으로 이동할 수 있지만 유효한 인덱스 항목에는 없습니다. 업데이트할 레코드가 준비되면 해당 업데이트가 취소됩니다. 인덱스 범위가 적용되고 JET_MoveFirst 또는 JET_MoveLast 지정된 경우 해당 인덱스 범위가 취소됩니다. 데이터베이스 상태는 변경되지 않습니다.

설명

JetMove, Before First 및 After Last를 사용하여 커서를 두 개의 특수 위치로 이동할 수 있습니다. 커서가 테이블의 첫 번째 인덱스 항목에 있고 JetMove 가 JET_MovePrevious 함께 호출되면 JET_errNoCurrentRecord 호출이 실패하고 인덱스의 첫 번째 항목 앞에 커서가 논리적으로 배치됩니다. 이 논리적 위치는 인덱스에서 첫 번째 항목 이전에 다른 인덱스 항목이 삽입된 경우에도 유지됩니다. 인덱스의 끝을 기준으로 After Last에 대해 유사한 상황이 발생합니다. First 및 After Last 이전은 해당 요소를 사용하기 전에 항상 다음(또는 이전) 요소로 이동해야 하는 반복기 모델을 사용하여 JetMove를 사용하여 반복할 인덱스 항목 범위를 설정할 때 가장 유용합니다.

JetMove에서 방문할 수 있는 인덱스 항목 집합은 커서에서 인덱스 범위를 설정하여 제한할 수 있습니다. 이는 해당 인덱스에 대해 빌드된 검색 키 쌍을 통해 표현할 수 있는 간단한 조건과 일치하는 인덱스 항목 집합을 열거하는 애플리케이션에 유용합니다. 자세한 내용은 JetSetIndexRange를 참조하세요.

Windows Server 2003 SP1 이전 릴리스에서는 JetSetIndexRange 함수에 의해 설정된 인덱스 범위의 올바른 적용에 영향을 주는 일부 특정 경우에 발생하는 JetMove에 문제가 있습니다. 커서가 현재 첫 번째 인덱스 항목 앞에 있고 인덱스 범위가 첫 번째 인덱스 항목보다 작은 상한으로 설정된 경우 JetMove 에 대한 다음 호출은 예상대로 JET_errNoCurrentRecord 실패하는 대신 해당 인덱스 항목으로 잘못 이동합니다. 인덱스 끝에서 시작하는 유사한 상황에서도 동일한 오류가 발생합니다. 이 상황은 인덱스 범위를 설정하고 해당 집합의 첫 번째 인덱스 항목에서 시작하는 대신 열거할 항목 집합의 멤버인 첫 번째 인덱스 항목 앞에 시작될 것으로 예상되는 반복기를 사용하여 탐색하는 애플리케이션에서 발생할 수 있습니다. 이 상황은 인덱스 끝에서 시작하는 유사한 경우에도 발생합니다. 해결 방법은 애플리케이션이 현재 인덱스 항목의 키( JetRetrieveKey를 사용하여 검색됨)와 현재 인덱스 범위의 끝을 나타내는 키(JET_bitRetrieveCopy 사용하여 JetRetrieveKey 를 사용하여 검색됨)를 비교하여 획득한 인덱스 항목이 인덱스 범위 내에 있는지 수동으로 확인하는 것입니다.

계산된 오프셋을 JetMove에 전달할 때는 주의해야 합니다. 계산된 오프셋이 JET_MoveFirst 미만이거나 같은 경우 해당 오프셋은 각각 JetMove 에 개별적으로 전달되지만 원하는 효과를 얻으려면 단일 트랜잭션 내에 전달되는 여러 부분으로 나뉘어야 합니다. JET_MoveNext 보다 크거나 같은 오프셋의 경우에도 마찬가지입니다. 애플리케이션이 실제 세계에서 이를 겪을 가능성은 낮지만, JET_MoveFirst 및 JET_MoveLast 일반적인 오프셋과는 매우 다른 의미 체계를 감안할 때 이 사건에 대한 방어를 하는 것이 좋습니다.

cRow 매개 변수가 1000으로 설정된 경우와 같이 매우 큰 오프셋을 사용하여 JetMove 가 호출되면 JetMove 는 1000개의 인덱스 항목을 모두 트래버스하여 최종 위치에 도달합니다. 현재 ESE API는 각 인덱스 항목을 트래버스하지 않고 오프셋하여 지정된 인덱스 항목으로 직접 이동하는 효율적인 방법을 제공하지 않습니다.

요구 사항

요구 사항 값

클라이언트

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