JetSetColumn 함수

  • 아티클

적용 대상: Windows | Windows Server

JetSetColumn 함수

JetSetColumn 함수는 삽입하거나 현재 레코드를 업데이트하기 위해 수정된 레코드의 단일 열 값을 수정합니다. 기존 값을 덮어쓰거나, 다중값 열의 값 시퀀스에 새 값을 추가하거나, 다중값 열의 값 시퀀스에서 값을 제거하거나, 긴 값의 전체 또는 일부, JET_coltypLongText 또는 JET_coltypLongBinary 형식의 열을 업데이트할 수 있습니다.

    JET_ERR JET_API JetSetColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit,
      __in_opt      JET_SETINFO* psetinfo
    );

매개 변수

sesid

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

tableid

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

columnid

검색할 열의 JET_COLUMNID . 또는 columnid 값 0(0)을 지정할 수 있습니다. columnid 0이 지정되면 태그가 지정된 모든 열, 스파스 및 다중값 열이 단일 열로 처리됩니다. 이렇게 하면 레코드에 있는 모든 스파스 열을 쉽게 검색할 수 있습니다.

pvData

열 값에 사용할 데이터를 포함하는 입력 버퍼입니다.

cbData

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

grbit

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

값

의미

JET_bitSetAppendLV

이 옵션은 JET_coltypLongText 또는JET_coltypLongBinary 형식의 열에 데이터를 추가하는 데 사용됩니다. 기존 long 값의 크기를 확인하고 psetinfo에서 ibLongValue를 지정하여 동일한 동작을 수행할 수 있습니다. 그러나 기존 열 값의 크기를 알 필요가 없으므로 이 grbit 를 사용하는 것이 더 간단합니다.

JET_bitSetOverwriteLV

이 옵션은 기존 long 값을 새로 제공된 데이터로 바꾸는 데 사용됩니다. 이 옵션을 사용하면 새 데이터를 설정하기 전에 기존 long 값이 0으로 설정된 것처럼 표시됩니다.

JET_bitSetRevertToDefaultValue

이 옵션은 태그가 지정된, 스파스 또는 다중 값 열에만 적용됩니다. 그러면 열이 후속 열 검색 작업에서 기본 열 값을 반환합니다. 모든 기존 열 값이 제거됩니다.

JET_bitSetSeparateLV

이 옵션은 레코드 데이터의 나머지 부분과 별도로 긴 값, JET_coltypLongText 또는 JET_coltypLongBinary 형식의 열을 강제로 저장하는 데 사용됩니다. 이는 일반적으로 long 값의 크기가 나머지 레코드 데이터와 함께 저장되지 않도록 하는 경우에 발생합니다. 그러나 이 옵션은 long 값을 별도로 저장하도록 강제하는 데 사용할 수 있습니다. 더 작은 크기의 긴 값 4바이트는 강제로 분리할 수 없습니다. 이러한 경우 옵션은 무시됩니다.

JET_bitSetSizeLV

이 옵션은 입력 버퍼를 지정된 columnid 에서 설명하는 long 값의 길이로 설정하고 제공된 경우 psetinfo-itagSequence>의 시퀀스 번호로 설정하는 정수 바이트 수로 해석하는 데 사용됩니다. 지정된 크기가 기존 열 값보다 크면 열이 0으로 확장됩니다. 크기가 기존 열 값보다 작으면 값이 잘립니다.

JET_bitSetUniqueMultiValues

이 옵션은 다중값 열의 모든 값이 고유하도록 적용하는 데 사용됩니다. 이 옵션은 변환 없이 원본 열 데이터를 다른 기존 열 값과 비교하고 중복이 발견되면 오류가 반환됩니다. 이 옵션이 제공되면 JET_bitSetAppendLV, JET_bitSetOverwriteLV 및 JET_bitSetSizeLV 지정할 수도 없습니다.

JET_bitSetUniqueNormalizedMultiValues

이 옵션은 다중값 열의 모든 값이 고유하도록 적용하는 데 사용됩니다. 이 옵션은 열 데이터의 정규화된 주요 변환을 유사하게 변환된 다른 기존 열 값과 비교하고 중복이 발견되면 오류가 반환됩니다. 이 옵션이 제공되면 JET_bitSetAppendLV, JET_bitSetOverwriteLV 및 JET_bitSetSizeLV 지정할 수도 없습니다.

JET_bitSetZeroLength

이 옵션은 값을 0 길이로 설정하는 데 사용됩니다. 일반적으로 열 값은 cbMax를 0으로 전달하여 NULL 로 설정됩니다. 그러나 JET_coltypText 같은 일부 형식의 경우 열 값은 NULL 대신 0 길이일 수 있으며 이 옵션은 NULL 과 0(0) 길이를 구분하는 데 사용됩니다.

참고 일반적으로 열이 고정 길이 열인 경우 이 비트는 무시되고 열은 NULL로 설정됩니다. 그러나 열이 고정 길이 태그가 지정된 열인 경우 열 길이는 0으로 설정됩니다. 고정 길이 태그가 지정된 열이 0 길이로 설정되면 JetRetrieveColumn 또는 JetRetrieveColumns를 사용하여 열을 검색하려고 시도하지만 cbActual 매개 변수에 반환되는 실제 길이는 0입니다.

JET_bitSetIntrinsicLV

이 옵션은 레코드에 전체 long 값을 저장하는 데 사용됩니다.

JET_bitSetCompressed

이 옵션은 데이터를 저장할 때 데이터 압축을 시도하는 데 사용됩니다.

Windows 7: JET_bitSetCompressed Windows 7에 도입되었습니다.

JET_bitSetUncompressed

이 옵션은 데이터를 저장할 때 압축을 시도하지 않는 데 사용됩니다.

Windows 7: JET_bitSetUnCompressed Windows 7에 도입되었습니다.

psetinfo

JET_SETINFO 구조를 사용하여 이 함수에 대해 설정할 수 있는 선택적 입력 매개 변수에 대한 포인터입니다.

psetinfo가 NULL로 지정된 경우 함수는 itagSequence가 1이고 ibLongValue가 0인 것처럼 동작합니다. 이렇게 하면 열 집합이 다중값 열의 첫 번째 값을 설정하고 오프셋 0부터 긴 데이터를 설정합니다.

이 매개 변수에 대해 다음 옵션을 설정할 수 있습니다.

값

의미

ibLongValue

집합 데이터를 시작해야 하는 긴 열 값으로의 이진 오프셋입니다.

itagSequence

설정할 다중값 열 값의 시퀀스 번호입니다. itagSequence가 0으로 설정된 경우 제공된 값이 다중값 값 시퀀스의 끝에 추가되어야 합니다. 제공된 시퀀스 번호가 마지막 기존 다중값 값보다 크면 지정된 값이 값 시퀀스의 끝에 다시 추가됩니다. 시퀀스 번호가 기존 값에 해당하는 경우 해당 값은 지정된 값으로 바뀝니다.

반환 값

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

반환 코드

설명

JET_errSuccess

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

JET_errBadColumnId

지정된 열 ID가 열 ID의 법적 한도를 벗어났습니다.

JET_errClientRequestToStopJetService

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

JET_errColumnNotFound

지정된 columnid 에서 설명하는 열이 테이블에 없습니다.

JET_errColumnNotUpdatable

원본 업데이트 삽입 삭제 작업 중에 긴 값을 업데이트하려고 잘못 시도했습니다.

JET_errColumnTooBig

입력 버퍼에 지정된 지정된 열 값 데이터가 고정 길이 열에 대해 자연스럽거나 고정 길이 텍스트 또는 이진 열에 대해 구성된 크기 제한을 초과합니다. 이 오류는 긴 열에 대해 1024바이트 이상의 데이터를 전달하고 JET_bitSetIntrinsicLV 플래그를 설정할 때도 반환됩니다.

JET_errInstanceUnavailable

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

Windows XP: 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.

JET_errInvalidBufferSize

지정된 열 값 데이터 크기가 고정 길이 데이터 형식에 대한 자연 항목과 일치하지 않습니다.

JET_errInvalidColumnType

삽입 또는 업데이트 작업 중에 자동 증가 열을 업데이트하거나 바꾸기 작업 중에 버전 열을 업데이트하려는 시도가 잘못되었습니다.

JET_errInvalidgrbit

제공된 옵션은 알 수 없거나 알려진 비트 설정의 잘못된 조합입니다.

JET_errInvalidParameter

지정된 psetinfo-cbStruct>는 JET_SETINFO 구조체에 유효한 크기가 아닙니다.

JET_errMultiValuedDuplicate

열 설정 작업에서 중복 값을 만들려고 했고 JET_bitSetUniqueMultiValues 또는 JET_bitSetUniqueNormalizedMultiValues 지정했습니다.

JET_errNotInitialized

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

JET_errNotInTransaction

호출 세션이 트랜잭션에 없을 때 긴 열 값을 업데이트하려고 잘못 시도했습니다.

JET_errNullInvalid

NULL이 아닌 열을 NULL로 설정하려고 잘못 시도했습니다.

JET_errColumnIllegalNull

JET_errNullInvalid 동일합니다.

JET_errRecordTooBig

열 값은 레코드가 페이지 크기 관련 크기 제한을 초과하게 했기 때문에 입력 버퍼의 값으로 설정할 수 없습니다. JET_coltypLongText 또는 JET_coltypLongBinary 형식의 열은 나머지 레코드 데이터와 별도로 저장할 수 있습니다. 그러나 다른 열은 레코드와 함께 저장되어야 하며 레코드 크기 제한을 초과할 수 있습니다. 긴 열에도 링크로 레코드 내의 5바이트 공간이 필요하며 이로 인해 JET_errRecordTooBig 반환될 수 있습니다.

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

Windows XP: 이 오류는 Windows XP 이상 릴리스에서만 반환됩니다.

JET_errTermInProgress

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

JET_errUpdateNotPrepared

커서는 현재 새 레코드를 삽입하거나 기존 레코드를 업데이트하는 과정에 있지 않습니다.

JET_errVersionStoreOutOfMemory

이 오류는 버전 저장소의 구성된 크기가 미해결 업데이트를 모두 보유하기에 충분하지 않은 경우에 발생합니다.

JET_wrnColumnMaxTruncated

입력 버퍼의 열 값이 가변 길이 열에 대해 구성된 최대 길이를 초과하여 잘렸습니다.

성공하면 지정된 열 값의 원하는 부분이 입력 버퍼에서 복사된 데이터로 설정됩니다. 데이터 집합이 가변 길이 열에 대해 지정된 최대 길이를 초과하면 잘렸을 수 있습니다.

오류가 발생한 경우 커서 위치는 변경되지 않고 복사 버퍼에서 열 값 데이터가 업데이트되지 않습니다.

설명

긴 값, JET_coltypLongText 또는 JET_coltypLongBinary 형식의 열 JET_coltypLongBinary 값 설정은 호출 세션이 트랜잭션에 있는 경우에만 수행해야 합니다. 호출 세션이 트랜잭션에 없는 경우 업데이트 작업이 나중에 취소된 경우에도 별도로 저장된 long 값에 대한 수정이 완전히 커밋될 수 있습니다. 호출 세션이 트랜잭션에 있는 경우 업데이트를 취소하고 세션 트랜잭션을 롤백하여 업데이트의 효과를 완전히 롤백할 수 있습니다.

인덱스 업데이트는 JetSetColumn 작업의 결과로 수행되지 않습니다. 대신 모든 열 수정이 완료되고 JetUpdate 가 호출된 후에만 인덱스가 업데이트됩니다. 이렇게 하면 인덱스에 둘 이상의 열이 수정될 때 인덱스를 가장 효율적으로 업데이트할 수 있습니다.

레코드는 데이터베이스 페이지 크기에 따라 크기가 제한됩니다. 5바이트보다 큰 레코드의 긴 값은 JetSetColumn 작업의 결과로 레코드의 데이터가 해당 제한을 초과하는 경우 레코드와 별도로 저장됩니다. 모든 분리 가능한 레코드 열 데이터가 레코드와 별도로 저장되고 레코드가 여전히 레코드 크기 제한을 초과한 후에만 오류 JET_errRecordTooBig 반환됩니다.

요구 사항

요구 사항 값

클라이언트

Windows Vista, Windows XP 또는 Windows 2000 Professional이 필요합니다.

서버

Windows Server 2008, Windows Server 2003 또는 Windows 2000 Server가 필요합니다.

머리글

Esent.h에서 선언되었습니다.

라이브러리

ESENT.lib를 사용합니다.

DLL

ESENT.dll 필요합니다.

참고 항목

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns