 |
|
|
 | Kontextová proměnná klienta |  | Programování v externích jazycích | Typy pro komunikaci se serverem |  |
Nejnižší úroveň nástrojů pro čtení a zápis dat do databáze představují API funkce. Na vyšší úrovni lze použít příkazy jazyka SQL obsahující proměnné klienta pomocí funkcí cd_SQL_host_execute nebo cd_SQL_host_prepare - viz Proměnné z externích jazyků v příkazech SQL.
Pro čtení a zápis hodnot sloupců lze použít některé z těchto funkcí:
(cd_)Read, (cd_)Write - univerzální funkce pro práci s hodnotou sloupce,
(cd_)Read_ind, (cd_)Write_ind - práce se sloupcem pevné velikosti,
(cd_)Read_var, (cd_)Write_var - práce se sloupce proměnné velikosti,
(cd_)Read_len, (cd_)Write_len - práce s délkou hodnoty sloupce proměnné velikosti,
(cd_)Read_record, (cd_)Write_record - práce s celým záznamem najednou.
Funkcím se předávají tyto parametry:
Při zápisu hodnoty se dále udává její délka. Při práci s hodnotou proměnné velikosti se udává začátek a délka úseku, s nimž se pracuje.
Číslo tabulky lze získat pomocí funkce (cd_)Find_object, např.:
cd_Find_object(cdp, "MOJETABULKA", CATEG_TABLE, &tablenum);
Čísla systémových tabulek jsou v externích jazycích označena konstantami TAB_TABLENUM, OBJ_TABLENUM a USR_TABLENUM.
Číslo kurzoru vznikne při otevření kurzoru. Pevný kurzor vytvořený podle dotazu v databázi se otevírá příkazem (cd_)Open_cursor, proměnný kurzor z dynamicky sestrojeného dotazu se otevírá funkcí (cd_)Open_cursor_direct. Otevřený kurzor je nutno uzavřít funkcí Close_cursor. Při každém otevření vzniká nový kurzor, jehož číslo může být odlišné od předchozího (i v případě stejného dotazu).
Práce s tabulkou, pevným či proměnným kurzorem se může v konkrétních situacích lišit. Výrazně se omezena práce s needitovaelným kurzorem.
Záznam v tabulce resp. v kurzoru se v programu určuje pomocí svého čísla. Záznamy jsou očíslovány od nuly až po číslo o 1 menší, než je počet záznamů v tabulce resp. kurzoru. Číslo záznamu (někdy říkáme absolutní číslo záznamu pro odlišení od interních čísel záznamů ve formulářích) se uvádí ve všech operacích se záznamy. Číslo záznamu v tabulce je po celou dobu existence tohoto záznamu neměnné, s výjimkou operace zkompaktnění tabulky.
Počet záznamů v tabulce nebo kurzoru zjišťuje funkce (cd_)Rec_cnt. U tabulky vrácený počet zahrnuje i zrušené záznamy.
Pro vložení záznamu do tabulky nebo kurzoru slouží funkce (cd_)Insert, pro zrušení záznamu funkce (cd_)Delete. Všechny záznamy v tabulce nebo kurzoru lze zrušit najednou pomocí funkce (cd_)Delete_all_records nebo funkce cd_Truncate_table.
Záznamy kterékoli tabulky mají systémový sloupec typu Boolean pojmenovaný DELETED - vysvětlení níže. Číst a přepisovat lze nejen platné, ale i zrušené záznamy (server vydá varování). Do volných záznamů není dovoleno zapisovat a není definováno, co se z nich přečte.
Při otevírání kurzorů se do nich vybírají z tabulek pouze platné záznamy. V editovatelném kurzoru se za dobu jeho existence může stát, že některé jeho záznamy budou zrušeny; buď přímo v kurzoru majitelem kurzoru, nebo i jiným uživatelem v tabulce, z níž je kurzor odvozen (není-li tabulka zamčena). Číslo záznamu v kurzoru je definováno pouze po dobu otevření tohoto kurzoru a pouze po tuto dobu je neměnné. Čísla stejných záznamů v kurzoru mohou být různá při každém otevření kurzoru.
Jména sloupců databázových tabulek a kurzorů se používají pouze v SQL a ve vnitřním programovacím jazyce. Ve funkcích pro externí jazyky se sloupce označují svými pořadovými čísly.
Sloupce jsou očíslovány souvisle od nuly. Číslo nula má služební sloupec, který se v tabulkách jmenuje DELETED a v kurzorech __DELETED a nese informaci o tom, zda záznam je zrušený. Za nim následují případné další služební sloupce týkající se replikací, koloběhu dokumentů a práv k jednotlivým záznamům (jejich jména začínají _W5_). Za nimi jsou normální sloupce v tom pořadí, v němž jsou uvedeny v definici tabulky nebo v klauzuli SELECT v definici kurzoru.
Nultý sloupec má typ uns8. Nabývá tří hodnot:
* NOT_DELETED záznam existuje, není zrušen
* DELETED záznam je zrušený (lze jej obnovit funkcí (cd_)Undelete)
* RECORD_EMPTY záznam je uvolněný funkcí (cd_)Free_deleted (nelze jej již obnovit)
Ke zjištění čísla sloupce na základě jeho jména lze také využít tyto funkce:
Funkce (cd_)Attribute_info_ex vrací pro sloupec zadaný jménem jeho číslo, typ a další údaje. Funkce (cd_)Enum_attributes a (cd_)Enum_attributes_ex vracejí přehled všech sloupců. Tyto funkce se dají použít na tabulku nebo na otevřený kurzor.
Podrobné informace o sloupcích v tabulce poskytuje systémový informační dotaz _iv_table_columns.Pro dynamicky vznikající kurzory platí, že jejich sloupce jsou očíslovány zleva doprava v pořadí, v němž jsou uvedeny v klauzuli SELECT. První sloupec uvedený za SELECT má číslo 1, další 2 atd.
Nechť tabulka T1 obsahuje sloupce A a B, tabulka T2 sloupce C a D. Otevřete kurzor CU v jazyce C voláním funkce:
cd_Open_cursor_direct(cdp, "select A,D,B+C from T1,T2 where A<C order by D", &CU);
Pak přečíst hodnotu sloupce D ze záznamu REC v kurzoru CU lze funkcí:
cd_Read_ind(cdp, CU, REC, 2, NOINDEX, &buffer);
zatímco hodnotu součtu B+C přečtete
cd_Read_ind(cdp, CU, REC, 3, NOINDEX, &buffer);
Funkce pro zápis do databáze mají za poslední parametr údaj datasize. Hodnotou tohoto parametru je délka hodnoty zapisované do databáze v bajtech. Pokud píšete do sloupce pevné délky, pak tato hodnota musí být stejná jako velikost hodnoty tohoto sloupce, tedy např. pro typ CHAR, BOOLEAN a TINYINT je to 1, pro SMALLINT 2, pro DATE, TIME, TIMESTAMP a INTEGER 4, pro REAL a BIGINT 8, pro znakové a bajtové řetězce je to délka řetězce uvedená v definici tabulky (nikoli tedy skutečná délka zapisovaného řetězce).
Při čtení hodnoty je funkci nutno předat adresu dostatečně velkého bufferu. Přečtený řetězec znaků bude ukončen nulou.
Délky hodnoty sloupce proměnné velikosti je 4-bajtový celočíselný údaj, při jejím zápisu má tedy parametr datasize hodnotu 4.
| Kontextová proměnná klienta | | Programování v externích jazycích | Typy pro komunikaci se serverem | |