Popis funkcí exportovaných z knihovny nddbe.dll

Transkript

1 Popis funkcí exportovaných z knihovny nddbe.dll Tato příloha obsahuje stručný popis jednotlivých funkcí dynamické knihovny nddbe.dll určené pro práci s datovými soubory aplikace Dorg. NDBAddEntry, NDBAddAEntry, NDBAddUEntry Funkce slouží k přidání nového záznamu do souboru. DWORD NDBAddEntry( LPODBS, PDBITEM pdbitemstruct, DWORD dwflags pdbitemstruct Pointer na strukturu DBITEM obsahující záznam, jenž má být přidán do souboru. dwflags Další volby funkce. Může nabývat hodnoty NDB_ADINODUPLDATE (výchozí, nepovolí duplicitní data funkce vrátí chybovou hodnotu), NDB_ADIOWDUPLDATE (vyhledá případné duplicitní záznamy a přepíše je), NDB_ADIALLOWDUPL (povolí duplicitní data). Funkce NDBAddAEntry a NDBAddUEntry jsou totožné, pouze je jiný druhý parametr místo PDBITEM je PDBAITEM resp. PDBUITEM. NDBCloseFile Funkce zavírá otevřený datový soubor. BOOL NDBCloseFile( LPODBS & Pokud funkce uspěje, vrátí hodnotu TRUE, pokud ne, vrátí FALSE. Po ukončení práce se souborem je nutné tuto funkci zavolat, aby došlo k uvolnění vytvořených objektů v paměti

2 NDBCreateFile Příloha č. 2 Popis funkcí knihovny nddbe.dll Funkce slouží k vytvoření nového datového souboru nebo změně hlavičky souboru. DWORD NDBCreateFile( LPCTSTR lpfilepath, LPODBS &, DWORD dwflags, PDBHEAD pdbh lpfilepath Pointer na nulou ukončený řetězec, obsahující jméno souboru, resp. celou cestu k souboru. Proměnná typu LPODBS identifikující nově vytvořený datový soubor. dwflags Upřesňuje požadovanou činnost funkce. Může nabývat tyto hodnoty: NDB_CRMCREATE (bude vytvořen nový soubor, pokud soubor existuje, bude přepsán), NDB_CRMCHANGEHEAD (umožní změnu hlavičky a otevře soubor pro zápis), NDB_CRMCLEAR (otevře existující soubor pro zápis, ale odstraní všechny existující záznamy v souboru, ponechá hlavičku). pdbh Pointer na strukturu DBHEAD obsahující data hlavičky souboru. NDBDelEntry Funkce odstraní ze souboru aktuální záznam. DWORD NDBDelEntry( LPODBS & Pokud funkce uspěje vrátí hodnotu NDB_SUCCESS, pokud ne, vrátí nenulovou hodnotu určující chybu, k níž došlo. NDBGetEntry, NDBGetAEntry, NDBGetUEntry Funkce přečte aktuální záznam ze souboru a uloží do struktury DBITEM. DWORD NDBGetEntry( LPODBS, PDBITEM pdbitemstruct - 2 -

3 pdbitemstruct Pointer na strukturu DBITEM, do níž bude vložen aktuální záznam. Funkce NDBGetAEntry a NDBGetUEntry jsou totožné, pouze je jiný druhý parametr místo PDBITEM je PDBAITEM resp. PDBUITEM. NDBGetCountEntries Vrací počet záznamů v souboru. UINT NDBGetCountEntries( LPODBS Hodnota počtu záznamů v souboru. NDBGetCurrentPos Vrací pozici aktuálního záznamu v souboru. UINT NDBGetCurrentPos( LPODBS Pozice aktuálního záznamu v souboru. Pokud vrátí nulu, došlo k chybě. NDBGetDataArrayPtr Funkce vrací pointer na datovou strukturu otevřeného souboru. PVOID NDBGetDataArrayPtr( LPODBS - 3 -

4 Pointer ukazující do otevřeného souboru na první záznam (za hlavičku souboru). Pokud vrátí NULL, nejsou v souboru žádné záznamy. Tato funkce je užitečná, pokud je nutné nějakým způsobem pracovat přímo s datovou strukturou souboru. Nedoporučuje se používat pro činnosti, které mohou provádět jiné funkce knihovny, protože obsahují řadu bezpečnostních a kontrolních mechanismů, na rozdíl od přímého zásahu do souboru. Tato funkce rovněž není dostupná pro datový soubor typu NDB_DBTYPE_ORGANIZER. NDBGetHead Funkce slouží k přečtení hlavičky souboru. BOOL NDBGetHead( LPODBS, PDBHEAD pdbh pdbh Pointer na strukturu DBHEAD, do níž bude vložena hlavička souboru. Pokud funkce uspěje, vrátí hodnotu TRUE, pokud ne, vrátí FALSE. NDBGetInfo Získání všech informací o otevřeném souboru. BOOL NDBGetInfo( LPODBS, LPINFODBS lpinfo lpinfo Pointer na strukturu INFODBSTRUCT, jejíž položky funkce vyplní informacemi o souboru. Pokud funkce uspěje, vrátí hodnotu TRUE, pokud ne, vrátí FALSE

5 NDBChangeEntry, NDBChangeAEntry, NDBChangeUEntry Změní (přepíše) aktuální záznam databáze. DWORD NDBChangeEntry( LPODBS, PDBITEM pdbitemstruct pdbitemstruct Pointer na strukturu DBITEM obsahující záznam, jímž bude aktuální záznam přepsán. Funkce NDBChangeAEntry a NDBChangeUEntry jsou totožné, pouze je jiný druhý parametr místo PDBITEM je PDBAITEM resp. PDBUITEM. NDBIsBOF Slouží ke zjištění, zda bylo dosaženo začátku souboru (prvního záznamu). BOOL NDBIsBOF( LPODBS Vrací TRUE, pokud je aktuální záznam první záznam v souboru, jinak FALSE. NDBIsEOF Slouží ke zjištění, zda bylo dosaženo konce souboru (posledního záznamu). BOOL NDBIsEOF( LPODBS Vrací TRUE, pokud je aktuální záznam poslední záznam v souboru, jinak FALSE

6 NDBMoveFirst Příloha č. 2 Popis funkcí knihovny nddbe.dll Nastaví aktuální záznam na první záznam souboru. BOOL NDBMoveFirst( LPODBS Vrací FALSE, pokud v souboru nejsou žádné záznamy. NDBMoveLast Nastaví aktuální záznam na poslední záznam souboru. BOOL NDBMoveLast( LPODBS Vrací FALSE, pokud v souboru nejsou žádné záznamy. NDBMoveNext Nastaví aktuální záznam na následující záznam souboru. BOOL NDBMoveNext( LPODBS Vrací FALSE, pokud v souboru nejsou žádné záznamy nebo je dosaženo konce souboru. NDBMovePrevious Nastaví aktuální záznam na předchozí záznam souboru. BOOL NDBMovePrevious( LPODBS - 6 -

7 Vrací FALSE, pokud v souboru nejsou žádné záznamy nebo je dosaženo začátku souboru. NDBOpenFile Funkce otevře existující soubor. DWORD NDBOpenFile( LPCTSTR lpfilepath, LPODBS &, DWORD dwflags lpfilepath Pointer na nulou ukončený řetězec, obsahující jméno souboru, resp. celou cestu k souboru. Proměnná typu LPODBS identifikující nově otevřený datový soubor. dwflags Určuje možnosti otevření souboru. Může nabývat tyto hodnoty: NDB_RWMREAD (soubor bude otevřen pouze pro čtení), NDB_RWMWRITE (soubor bude otevřen pro čtení i zápis), NDB_RWMOPEN (otevře soubor pro čtení, ale načtena bude pouze hlavička, záznamy ne). NDBSaveFile Funkce uloží otevřený soubor. DWORD NDBSaveFile( LPODBS &, BOOL bclose bclose Pokud je tento parametr nastaven na TRUE, bude soubor po uložení zavřen (jako by byla volána funkce NDBCloseFile). Pokud na FALSE, soubor zůstane po uložení otevřen. Veškeré změny provedené v otevřeném souboru jsou ukládány do dočasného bufferu. Fyzicky - 7 -

8 se změny uloží do souboru až po zavolání této funkce. NDBSetCurrentPos Přímé nastavení aktuálního záznamu v souboru. BOOL NDBSetCurrentPos( LPODBS, UINT unewpos unewpos Nová pozice aktuálního záznamu v souboru. Záznamy jsou číslovány od 1. Pokud funkce vrátí FALSE, pravděpodobně byl zadán chybný index záznamu (počet záznamů je menší). Tuto funkci není moc vhodné používat. Pro procházení záznamů v souboru je lepší použít funkcí NDBMove***. NDBSetDefaultHeadData Vyplní výchozí hodnoty hlavičky souboru strukturu DBHEAD. BOOL NDBSetDefaultHeadData( PDBHEAD pdbh pdbh Pointer na strukturu DBHEAD. Pokud funkce uspěje, vrátí hodnotu TRUE, pokud ne, vrátí FALSE. Slouží ke zjednodušení práce při vytváření nového souboru pomocí funkce NDBCreateFile, aby se nemusely jednotlivé informace obsažené v hlavičce vyplňovat ručně

9 Funkce pro soubor hlavní databáze činností Základní postupy jsou shodné s výše uvedenými, pouze je jiné pojmenování funkcí. Všechny funkce určené pro soubory tohoto typu začínají písmeny NDBOrg + název funkce. Např. funkce NDBOrgOpenFile je obdoba funkce NDBOpenFile a jejich činnost a použití je totožné. Jsou zde pouze 2 funkce navíc: NDBOrgGetEntrySize Tato funkce zjistí celkovou velikost (v bajtech) aktuálního záznamu, včetně kontrolního bajtu. DWORD NDBOrgGetEntrySize( LPODBS, LPDWORD lpdwlength lpdwlength Pointer na proměnnou typu DWORD, do níž bude vložena velikost záznamu. Tato funkce byla vytvořena, protože velikost každého záznamu v tomto typu souboru může být jiná na rozdíl od ostatních typů souborů, kde je konstantní. NDBOrgHashData Tato funkce zajišťuje propočtení začátků jednotlivých záznamů v souboru. Tuto činnost je nutné provést po každé změně v souboru. Knihovní funkce, ale toto dělají automaticky. DWORD NDBOrgHashData( LPODBS, BOOL bignorectrlbyte = FALSE bignorectrlbyte Musí být nastaven na hodnotu FALSE

10 Jedná se o funkci pro vnitřní účely knihovny. Exportována je pouze pro případ, že bylo zapotřebí vytvořit vlastní funkce pro úpravu záznamů v souboru, což v případě hlavní databáze činností není doporučeno. Další možnost je využít této funkce pro kontrolu souboru, zda se v něm nevyskytují chyby. PŘI POUŽITÍ FUNKCÍ KNIHOVNY NENÍ NUTNÉ NIKDY TUTO FUNKCI VOLAT. Použité datové typy a struktury jsou deklarovány v příslušných hlavičkových souborech, kde jsou i popsány jednotlivé položky. Rovněž jsou v nich definována použitá makra a konstanty