Uwaga
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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