Udostępnij za pośrednictwem


JetSetColumn, funkcja

Dotyczy: Windows | Windows Server

JetSetColumn, funkcja

Funkcja JetSetColumn modyfikuje pojedynczą wartość kolumny w zmodyfikowanym rekordzie do wstawienia lub zaktualizowania bieżącego rekordu. Może zastąpić istniejącą wartość, dodać nową wartość do sekwencji wartości w kolumnie wielowartościowej, usunąć wartość z sekwencji wartości w kolumnie wielowartościowej lub zaktualizować całą lub część długiej wartości, kolumnę typu JET_coltypLongText lub 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
    );

Parametry

identyfikator sesid

Sesja do użycia dla tego wywołania.

tableid

Kursor do użycia dla tego wywołania.

columnid

JET_COLUMNID kolumny do pobrania. Alternatywnie można podać wartość columnid 0 (zero). Po podaniu kolumny columnid 0 (zero) wszystkie kolumny oznakowane, rozrzedzonych i wielowartych kolumn są traktowane jako pojedyncza kolumna. Ułatwia to pobieranie wszystkich rozrzednych kolumn, które znajdują się w rekordzie.

pvData

Bufor wejściowy zawierający dane do użycia dla wartości kolumny.

cbData

Rozmiar w bajtach buforu wejściowego.

grbit

Grupa bitów zawierająca opcje do użycia dla tego wywołania, które obejmują zero lub więcej z następujących elementów:

Wartość

Znaczenie

JET_bitSetAppendLV

Ta opcja służy do dołączania danych do kolumny typu JET_coltypLongText lub JET_coltypLongBinary. To samo zachowanie można osiągnąć, określając rozmiar istniejącej długiej wartości i określając wartość ibLongValue w pliku psetinfo. Jednak użycie tego grbitu jest prostsze, ponieważ znajomość rozmiaru istniejącej wartości kolumny nie jest konieczna.

JET_bitSetOverwriteLV

Ta opcja służy do zastępowania istniejącej długiej wartości nowo podanymi danymi. Gdy ta opcja jest używana, jest tak, jakby istniejąca długa wartość została ustawiona na 0 (zero) długości przed ustawieniem nowych danych.

JET_bitSetRevertToDefaultValue

Ta opcja ma zastosowanie tylko w przypadku kolumn oznaczonych tagami, rozrzedzonych lub wielowartych. Powoduje to zwrócenie domyślnej wartości kolumny podczas kolejnych operacji pobierania kolumn. Wszystkie istniejące wartości kolumn są usuwane.

JET_bitSetSeparateLV

Ta opcja służy do wymuszania przechowywania długiej wartości, kolumn typu JET_coltypLongText lub JET_coltypLongBinary, aby były przechowywane oddzielnie od pozostałych danych rekordu. Dzieje się tak zwykle, gdy rozmiar długiej wartości uniemożliwia przechowywanie ich z pozostałymi danymi rekordu. Można jednak użyć tej opcji, aby wymusić przechowywanie długiej wartości oddzielnie. Należy pamiętać, że długie wartości o rozmiarze czterech bajtów mniejszych nie mogą być wymuszane na oddzielne. W takich przypadkach opcja jest ignorowana.

JET_bitSetSizeLV

Ta opcja służy do interpretowania buforu wejściowego jako liczby całkowitej bajtów ustawionej jako długość długiej wartości opisanej przez podany identyfikator columnid i jeśli podano, numer sekwencji w pliku psetinfo-itagSequence>. Jeśli podany rozmiar jest większy niż istniejąca wartość kolumny, kolumna zostanie rozszerzona o 0s. Jeśli rozmiar jest mniejszy niż istniejąca wartość kolumny, wartość zostanie obcięta.

JET_bitSetUniqueMultiValues

Ta opcja służy do wymuszania, że wszystkie wartości w kolumnie wielowartościowej są odrębne. Ta opcja porównuje dane kolumny źródłowej bez żadnych przekształceń z innymi istniejącymi wartościami kolumn i zwracany jest błąd w przypadku znalezienia duplikatu. Jeśli ta opcja jest podana, nie można również podać JET_bitSetAppendLV, JET_bitSetOverwriteLV i JET_bitSetSizeLV.

JET_bitSetUniqueNormalizedMultiValues

Ta opcja służy do wymuszania, że wszystkie wartości w kolumnie wielowartościowej są odrębne. Ta opcja porównuje znormalizowaną transformację klucza danych kolumny z innymi podobnie przekształconymi istniejącymi wartościami kolumn i zwracany jest błąd w przypadku znalezienia duplikatu. Jeśli ta opcja jest podana, nie można również podać JET_bitSetAppendLV, JET_bitSetOverwriteLV i JET_bitSetSizeLV.

JET_bitSetZeroLength

Ta opcja służy do ustawiania wartości na zero długości. Zwykle wartość kolumny jest ustawiona na wartość NULL , przekazując wartość cbMax z wartością 0 (zero). Jednak w przypadku niektórych typów, takich jak JET_coltypText, wartość kolumny może mieć długość 0 (zero) zamiast wartości NULL, a ta opcja służy do rozróżniania długości null i 0 (zero).

Nuta Ogólnie rzecz biorąc, jeśli kolumna jest kolumną o stałej długości, ten bit jest ignorowany, a kolumna ma wartość NULL. Jeśli jednak kolumna jest kolumną o stałej długości, długość kolumny jest ustawiona na 0. Gdy kolumna otagowana o stałej długości ma ustawioną długość 0, próby pobrania kolumny za pomocą klasy JetRetrieveColumn lub JetRetrieveColumns powiedzie się, ale rzeczywista długość zwrócona w parametrze cbActual wynosi 0.

JET_bitSetIntrinsicLV

Ta opcja służy do przechowywania całej długiej wartości w rekordzie.

JET_bitSetCompressed

Ta opcja służy do próby kompresji danych podczas przechowywania danych.

Windows 7: JET_bitSetCompressed jest wprowadzana w systemie Windows 7.

JET_bitSetUncompressed

Ta opcja nie służy do próby kompresji podczas przechowywania danych.

Windows 7: JET_bitSetUnCompressed jest wprowadzana w systemie Windows 7.

psetinfo

Wskaźnik do opcjonalnych parametrów wejściowych, które można ustawić dla tej funkcji przy użyciu struktury JET_SETINFO .

Jeśli parametr psetinfo ma wartość NULL , funkcja zachowuje się tak, jakby parametr itagSequence 1 i ibLongValue 0 (zero) zostały podane. Powoduje to ustawienie pierwszej wartości kolumny wielowartościowej i ustawienie długich danych rozpoczynających się od przesunięcia 0 (zero).

Dla tego parametru można ustawić następujące opcje:

Wartość

Znaczenie

ibLongValue

Przesunięcie binarne na wartość długiej kolumny, w której należy rozpocząć ustawianie danych.

itagSequence

Numer sekwencji żądanej wartości kolumny wielowartościowej do ustawienia. Jeśli parametr itagSequence ma wartość 0 (zero), podana wartość powinna zostać dołączona na końcu sekwencji wartości wielowartościowych. Jeśli podany numer sekwencji jest większy niż ostatnia istniejąca wartość wielowartościowa, ponownie dana wartość zostanie dołączona na końcu sekwencji wartości. Jeśli numer sekwencji odpowiada istniejącej wartości, ta wartość zostanie zamieniona na daną wartość.

Wartość zwracana

Ta funkcja zwraca JET_ERR typ danych z jednym z następujących kodów zwracanych. Aby uzyskać więcej informacji na temat możliwych błędów ESE, zobacz Extensible Storage Engine Errors and Error Handling Parameters (Błędy aparatu magazynu rozszerzalnego i parametry obsługi błędów).

Kod powrotny

Opis

JET_errSuccess

Operacja została ukończona pomyślnie.

JET_errBadColumnId

Podany identyfikator kolumny wykracza poza granice prawne identyfikatora kolumny.

JET_errClientRequestToStopJetService

Nie można ukończyć operacji, ponieważ wszystkie działania w wystąpieniu skojarzonym z sesją przestały działać w wyniku wywołania metody JetStopService.

JET_errColumnNotFound

Kolumna opisana przez podany identyfikator columnid nie istnieje w tabeli.

JET_errColumnNotUpdatable

Podjęto nielegalną próbę zaktualizowania długiej wartości podczas operacji wstawiania kopiowania usuwania oryginalnej aktualizacji.

JET_errColumnTooBig

Dane wartości danej kolumny podane w buforze wejściowym przekraczają ograniczenie rozmiaru naturalne dla kolumny o stałej długości lub skonfigurowane dla kolumn tekstowych o stałej długości lub kolumn binarnych. Ten błąd jest również zwracany podczas przekazywania ponad 1024 bajtów danych dla długiej kolumny i ustawiania flagi JET_bitSetIntrinsicLV.

JET_errInstanceUnavailable

Nie można ukończyć operacji, ponieważ wystąpienie skojarzone z sesją napotkało błąd krytyczny, który wymaga odwołania dostępu do wszystkich danych w celu ochrony integralności tych danych.

Windows XP: Ten błąd zostanie zwrócony tylko przez system Windows XP i nowsze wersje.

JET_errInvalidBufferSize

Rozmiar danych wartości danej kolumny jest niezgodny z naturalnym typem danych o stałej długości.

JET_errInvalidColumnType

Podjęto nielegalną próbę zaktualizowania kolumny automatycznego zwiększania podczas operacji wstawiania lub aktualizacji albo aktualizowania kolumny wersji podczas operacji zastępowania.

JET_errInvalidgrbit

Podane opcje są nieznane lub niedozwolona kombinacja znanych ustawień bitów.

JET_errInvalidParameter

Podany parametr psetinfo-cbStruct> nie jest prawidłowym rozmiarem struktury JET_SETINFO .

JET_errMultiValuedDuplicate

Operacja ustawiania kolumny próbowała utworzyć zduplikowaną wartość i określić JET_bitSetUniqueMultiValues lub JET_bitSetUniqueNormalizedMultiValues.

JET_errNotInitialized

Nie można ukończyć operacji, ponieważ wystąpienie skojarzone z sesją nie zostało jeszcze zainicjowane.

JET_errNotInTransaction

Podjęto nielegalną próbę zaktualizowania długiej wartości kolumny, gdy sesja wywołująca nie była w transakcji.

JET_errNullInvalid

Podjęto nielegalną próbę ustawienia kolumny innej niż NULL na null.

JET_errColumnIllegalNull

Tak samo jak JET_errNullInvalid.

JET_errRecordTooBig

Nie można ustawić wartości kolumny na wartość w buforze wejściowym, ponieważ spowodowałoby to przekroczenie ograniczenia rozmiaru powiązanego z rozmiarem strony rekordu. Kolumny typu JET_coltypLongText lub JET_coltypLongBinary mogą być przechowywane oddzielnie od pozostałych danych rekordu. Jednak inne kolumny muszą być przechowywane z rekordem i mogą spowodować przekroczenie ograniczenia rozmiaru rekordu. Nawet długie kolumny wymagają 5 bajtów miejsca w rekordzie jako powiązania i może to również prowadzić do zwrócenia JET_errRecordTooBig.

JET_errRestoreInProgress

Nie można ukończyć operacji, ponieważ operacja przywracania jest w toku w wystąpieniu skojarzonym z sesją.

JET_errSessionSharingViolation

Tej samej sesji nie można używać w tym samym czasie dla więcej niż jednego wątku.

Windows XP: Ten błąd zostanie zwrócony tylko przez system Windows XP i nowsze wersje.

JET_errTermInProgress

Nie można ukończyć operacji, ponieważ wystąpienie skojarzone z sesją jest zamykane.

JET_errUpdateNotPrepared

Kursor nie jest obecnie w trakcie wstawiania nowego rekordu lub aktualizowania istniejącego rekordu.

JET_errVersionStoreOutOfMemory

Ten błąd wystąpi, gdy skonfigurowany rozmiar magazynu wersji jest niewystarczający do przechowywania wszystkich zaległych aktualizacji.

JET_wrnColumnMaxTruncated

Wartość kolumny w buforze wejściowym przekroczyła maksymalną skonfigurowaną długość kolumny o zmiennej długości i została obcięta.

W przypadku powodzenia żądana część wartości kolumny dla danej kolumny jest ustawiana z danymi skopiowanymi z buforu wejściowego. Zestaw danych mógł zostać obcięty, jeśli przekroczył maksymalną długość określoną dla kolumny o zmiennej długości.

Po awarii lokalizacja kursora pozostaje niezmieniona i żadne dane wartości kolumny nie są aktualizowane w buforze kopiowania.

Uwagi

Ustawienie długich wartości, wartości kolumn JET_coltypLongBinary typu JET_coltypLongText lub JET_coltypLongBinary, należy wykonać tylko wtedy, gdy sesja wywołująca znajduje się w transakcji. Jeśli sesja wywołująca nie znajduje się w transakcji, modyfikacje długich wartości przechowywanych oddzielnie mogą być zatwierdzane w pełni nawet wtedy, gdy operacja aktualizacji zostanie później anulowana. Jeśli sesja wywołująca znajduje się w transakcji, skutki aktualizacji można w pełni wycofać, anulując aktualizację i cofając transakcję sesji.

Aktualizacje indeksu nie są wykonywane w wyniku operacji JetSetColumn . Zamiast tego indeksy są aktualizowane dopiero po zakończeniu wszystkich modyfikacji kolumn i wywołaniu funkcji JetUpdate . Pozwala to na najbardziej efektywne aktualizowanie indeksów, gdy indeksy obejmują modyfikację więcej niż jednej kolumny.

Rekord jest ograniczony rozmiarem na podstawie rozmiaru strony bazy danych. Wszystkie długie wartości w rekordzie większym niż pięć bajtów będą przechowywane oddzielnie od rekordu, jeśli dane w rekordzie przekroczą limit w wyniku operacji JetSetColumn . Błąd JET_errRecordTooBig zostanie zwrócony tylko po tym, jak wszystkie dane kolumn rekordów z możliwością separowalnego rekordu były przechowywane oddzielnie od rekordu, a rekord nadal przekracza limit rozmiaru rekordu.

Wymagania

Wymaganie Wartość

Klient

Wymaga systemu Windows Vista, Windows XP lub Windows 2000 Professional.

Serwer

Wymaga systemu Windows Server 2008, Windows Server 2003 lub Windows 2000 Server.

Nagłówek

Zadeklarowany w Esent.h.

Biblioteka

Użyj biblioteki ESENT.lib.

DLL

Wymaga ESENT.dll.

Zobacz też

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns