Promotic

RsOpen - metoda objektu PmaAdo

Popis:
Provede SQL dotaz SELECT, výsledná data jsou v podobě objektu AdoRecordset (množina záznamů).
Syntaxe:
Object RsOpen(String sId, String sSource, String sParams)
Parametry:
sId(String) Jednoznačný identifikátor, pod kterým si objekt PmaAdo zapamatuje výsledná data v podobě objektu AdoRecordset.
Pokud je uveden prázdný řetězec (""), pak se SQL příkaz sice provede a data v podobě objektu AdoRecordset jsou vrácena, ale objekt PmaAdo si je nebude pamatovat. Je to výhodné zejména v případech, kdy ve skriptu je nutno provést SQL dotaz a data ve skriptu ihned zpracovat s tím, že objekt AdoRecordset se ihned poté uvolní.
sSource(String) Obvykle dotaz v syntaxi jazyka SQL (SELECT). Může ale také obsahovat název tabulky, volání uložené procedury, název nebo URL adresa souboru obsahující uložený objekt AdoRecordset.
sParams(String) Dodatečné parametry metody RsOpen. Údaje jsou zde ve formátu KeyVal, například "cursor:forwardonly;lock:readonly;command:text;return:map;".
"cursor:xxx;" (nepovinné) - Určuje typ kurzoru, který má použít ADO Provider při otevření objektu AdoRecordset.
forwardonly (přednastaveno) - Chová se stejně jako "static" kurzor s tou výjímkou, že je povoleno procházet záznamy pouze dopředu. To zlepšuje výkonnost v situacích, kdy je potřeba pouze jediného průchodu skrze objekt AdoRecordset. Vlastnost AdoRecordset.RecordCount vždy vrací hodnotu -1, protože ADO s tímto kurzorem nemůže určit počet záznamů.
Odpovídá hodnotě ADO adOpenForwardOnly.
keyset - Chová se stejně jako "dynamic" kurzor s tou výjímkou, že neobsahuje žádné přidané nebo smazané záznamy jinými uživali.
Všechny změny jinými uživateli v datech, dostupných při otevření objektu AdoRecordset, budou stále viditelné.
Bookmarks jsou vždy povoleny a proto lze využít všech možností pohybu uvnitř objektu AdoRecordset.
Odpovídá hodnotě ADO adOpenKeyset.
dynamic - Zobrazuje všechny přidání, změny, mazání jiných uživatelů a umožňuje všechny typy pohybu skrze objekt AdoRecordset, které nejsou založeny na Bookmarks.
Bookmarks jsou povoleny, pokud je podporuje ADO Provider. Tento typ kurzoru není podporován v Microsoft Jet 4.0 OLE DB Provider.
Odpovídá hodnotě ADO adOpenDynamic.
static - Poskytuje statickou, ale editovatelnou kopii záznamů.
Všechny změny, přidané a smazané záznamy jinými uživateli nebudou viditelné, dokud se nezavolá metoda AdoRecordset.Resync.
Jedná se také o jediný typ povoleného kurzoru, pokud se otevírá objekt AdoRecordset na klientské straně.
Bookmarks jsou vždy povoleny a proto lze využít všech možností pohybu uvnitř objektu AdoRecordset.
Odpovídá hodnotě ADO adOpenStatic.
"lock:xxx;" (nepovinné) - Určuje typ zámku (zabezpečení souběžného přístupu), který má použít ADO Provider při otevření objektu AdoRecordset.
readonly (přednastaveno) - Jen pro čtení. Data nelze editovat.
Odpovídá hodnotě ADO adLockReadOnly.
pessimistic - Pesimistické zamykání, záznam po záznamu, ADO Provider dělá to, co je potřebné pro zajištění uspěšné editace záznamů.
Obvykle zamknutím záznamů v datovém zdroji ihned při začátku editace.
Ostatní uživatelé nemohou ani číst nebo editovat data, dokud nebudou změny (editace, která zamkla data) potvrzeny metodou AdoRecordset.Update nebo zrušeny metodou AdoRecordset.CancelUpdate.
Odpovídá hodnotě ADO adLockPessimistic.
optimistic - Optimistické zamykání, záznam po záznam, ADO Provider zamkne záznamy v datovém zdroji až voláním metody AdoRecordset.Update. Ostatní uživatelé mohou číst, editovat i ukládat změny a to i stejného záznamu, který je již otevřený.
Odpovídá hodnotě ADO adLockOptimistic.
batchoptimistic - Optimistické zamykání, hromadné dávky, vyžadováno pro dávkový editační mód, jako protiklad k okamžitému editačnímu módu.
Odpovídá hodnotě ADO adLockBatchOptimistic.
"command:xxx;" (nepovinné) - Určuje, jak má příslušný ADO Provider vyhodnotit parametr sSource, zejména pokud obsahuje něco jiného, než dotaz/příkaz v syntaxi jazyka SQL (např. SELECT, INSERT, atd.).
text (přednastaveno) - Určuje, že ADO Provider má vyhodnotit parametr sSource jako textový zápis příkazu.
Odpovídá hodnotě ADO adCmdText.
table - Určuje, že ADO Provider má vygenerovat SQL dotaz tak, že budou vráceny všechny záznamy databázové tabulky, jejíž název je uvedené v parametru sSource.
Odpovídá hodnotě ADO adCmdTable.
storedproc - Určuje, že ADO Provider má vyhodnotit parametr sSource jako uloženou proceduru.
Odpovídá hodnotě ADO adCmdStoredProc.
file - Určuje, že uložený objekt AdoRecordset má být vyčten ze souboru, jehož název je uvedený v parametru sSource.
Odpovídá hodnotě ADO adCmdFile.
tabledirect - Určuje, že ADO Provider má vrátit všechny záznamy databázové tabulky, jejíž název je uvedené v parametru sSource.
Odpovídá hodnotě ADO adCmdTableDirect.
unknown - Určuje, že typ příkazu v parametru sSource není známý. ADO Provider se ho pokusí zjistit sám, ale spotřebuje se tím zbytečně čas.
Odpovídá hodnotě ADO adCmdUnknown.
"execute:xxx;" (nepovinné) - Určuje, jak má příslušný ADO Provider provést SQL dotaz. Implicitní je synchronní dotaz, to znamená, že metoda čeká na výsledek operace.
async - Asynchronní dotaz, to znamená, že metoda nečeká na výsledek operace.
Odpovídá hodnotě ADO adAsyncExecute.
asyncfetch - Určuje, že řádky určené vlastností ADO Recordset.CacheSize se mají načíst synchronně, a zbývající řádky se mají dočíst asynchronně.
Odpovídá hodnotě ADO adAsyncFetch.
asyncfetchnonblocking - Určuje, že hlavní vlákno (thread) nebude nikdy blokováno při čtení. Pokud požadovaný řádek nebyl načten, pak ukazovátko aktuálního záznamu bude přesunuto na konec.
Odpovídá hodnotě ADO adAsyncFetchNonBlocking.
norecords - Určuje, že volaný dotaz/příkaz nevrací žádná data. Pokud ano, pak data budou zahozena a nebudou vrácena (žádný objekt AdoRecordset = hodnota null pro JavaScript nebo Nothing pro VBScript).
Odpovídá hodnotě ADO adExecuteNoRecords.
record - Určuje, že volaný dotaz/příkaz vrací jeden řádek, který má být vrácen v podobě objektu AdoRecord.
Odpovídá hodnotě ADO adExecuteRecord.
"return:xxx;" (nepovinné) - Určuje, zda vrácená hodnota metody má být mapa s více vrácenými hodnotami současně (nový způsob) nebo jedna hodnota (starý způsob).
Pokud není nastaveno, pak se jedná o starý způsob.
map - Vrací mapu (objekt PmMap), která obsahuje více vrácených hodnot současně (nový způsob) (např. Result, AffectedRows, ErrorCode, ErrorText).
Vrácená hodnota:
Nový způsob: Vrací objekt PmMap s hodnotami v následujících položkách:
- "Result": výsledná data v podobě objektu AdoRecordset nebo chybová hodnota (null pro JavaScript nebo Nothing pro VBScript)
- "ErrorCode": číselný kód chyby, kde hodnota 0 znamená úspěšné vykonání metody bez chyby
- "ErrorText": text případné chyby


Starý způsob: Vrací výsledná data v podobě objektu AdoRecordset nebo chybová hodnota (null pro JavaScript nebo Nothing pro VBScript)
Poznámka:
Tato metoda slouží k přístupu k datům (fyzické databázové tabulky, atd.) v podobě objektu AdoRecordset pomocí SQL dotazu SELECT. Tato metoda by se neměla používat k provedení obecného SQL příkazu, který nevrací data v podobě objektu AdoRecordset, protože nelze otestovat úspěšnost provedení příkazu. K tomu slouží metoda DbExecute.

Objekt ADO Record:
V závislosti na konkrétním ADO Provider se může stát, že jednořádkový výsledek SQL dotazu nebude vrácen v podobě objektu AdoRecordset s jedním záznamem, ale v podobě objektu AdoRecord (představuje jeden řádek). Není to ale typické pro nejběžněji užívané ADO Provider. Objekt AdoRecord je spíše vrácen při explicitních operacích, kdy z existujícího objektu AdoRecordset se vrátí konkrétní záznam v podobě objektu AdoRecord. Objekt AdoRecord se skládá z objektů AdoField stejně jako objekt AdoRecordset, na rozdíl od něj však nepodporuje metody pro přesun pozice aktuálního záznamu (např. MoveFirst).
V dokumentaci PROMOTIC se pro zjednodušení bude uvádět pouze běžnější vracený objekt AdoRecordset, přestože v určitých ojedinělých případech může být vrácen i objekt AdoRecord.
Viz také:
- PmaAdo.RsGet (metoda)
- PmaAdo.RsClose (metoda)
- PmaAdo.RsIsOpen (metoda)
- PmaAdo.DbOpen (metoda)
- PmaAdo.DbExecute (metoda)
- AdoRecordset (objekt)
- AdoRecord (objekt)
- AdoField (objekt)
Příklad:
Čtení dat v objektu PmaAdo ("/TestAdoDb"), který je již připojený k databázi (viz metoda DbOpen), pomocí SQL dotazu ("SELECT * FROM table1").
Výsledný objekt AdoRecordset bude zapamatován v objektu PmaAdo pod dodaným jednoznačným identifikátorem ("table1"), bude pouze obousměrný (static) a jen pro čtení (readonly).
Testuje se, zda nevznikla chyba a metoda vrátila platný objekt AdoRecordset. Pak se projdou všechny záznamy objektu AdoRecordset a u každého záznamu se vypíše se do INFO systému hodnota prvního sloupce.
Následují dvě varianty téhož příkladu lišící se směrem procházení záznamů v objektu AdoRecordset.
 
1) Dopředné procházení záznamů:
JavaScriptVBScriptVyber a zkopíruj do schránky

var oDb = pMe.Pm("/TestAdoDb");
var oRs = oDb.RsOpen("table1", "SELECT * FROM table1", "cursor:static;");
if (oRs)
{
oRs.MoveFirst();
while (! oRs.EOF)
{
Pm.Debug("Field name=" + oRs.Fields.Item(0).Name + ", value=" + oRs.Fields.Item(0).Value);
oRs.MoveNext();
}
}
 
2) Zpětné procházení záznamů:
JavaScriptVBScriptVyber a zkopíruj do schránky

var oDb = pMe.Pm("/TestAdoDb");
var oRs = oDb.RsOpen("table1", "SELECT * FROM table1", "cursor:static;");
if (oRs)
{
oRs.MoveLast();
while (! oRs.BOF)
{
Pm.Debug("Field name=" + oRs.Fields.Item(0).Name + ", value=" + oRs.Fields.Item(0).Value);
oRs.MovePrevious();
}
}

Historie:
Pm8.01.00: Vytvořeno
Pm8.03.22: Vrací objekt PmMap s hodnotami v položkách "Result", "ErrorCode" a "ErrorText".
© MICROSYS, spol. s r.o.