FUNKCE SQLSetCursorName
shoda
Zavedená verze: Dodržování standardů ODBC 1.0: ISO 92
souhrnu
SQLSetCursorName přidruží název kurzoru k aktivnímu příkazu. Pokud aplikace nevolá SQLSetCursorName, ovladač vygeneruje názvy kurzorů podle potřeby pro zpracování příkazů SQL.
Syntax
SQLRETURN SQLSetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT NameLength);
Argumenty
StatementHandle
[Vstup] Popisovač příkazu
CursorName
[Vstup] Název kurzoru Pro efektivní zpracování by název kurzoru neměl obsahovat žádné úvodní ani koncové mezery v názvu kurzoru a pokud název kurzoru obsahuje identifikátor s oddělovači, měl by být oddělovač umístěn jako první znak v názvu kurzoru.
NameLength
[Vstup] Délka znaků *CursorName.
Návraty
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR nebo SQL_INVALID_HANDLE.
Diagnostika
Když SQLSetCursorName vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze přidruženou hodnotu SQLSTATE získat voláním SQLGetDiagRec s HandleType SQL_HANDLE_STMT a popisovačStatementHandle . Následující tabulka uvádí hodnoty SQLSTATE běžně vrácené SQLSetCursorName a vysvětluje každý z nich v kontextu této funkce; notace "(DM)" předchází popisy funkcí SQLSTATEs vrácených správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak.
| SQLSTATE | Chyba | Popis |
|---|---|---|
| 01000 | Obecné upozornění | Informační zpráva specifická pro řidiče (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 01004 | Řetězcová data, zkrácená vpravo | Název kurzoru překročil maximální limit, takže byl použit pouze maximální povolený počet znaků. |
| 24000 | Neplatný stav kurzoru | Příkaz odpovídající StatementHandle již byl spuštěný nebo umístěný kurzor. |
| 34000 | Neplatný název kurzoru | Název kurzoru zadaný v *CursorName byl neplatný, protože překročil maximální délku definovanou ovladačem nebo začal s "SQLCUR" nebo "SQL_CUR". |
| 3C000 | Duplicitní název kurzoru | Název kurzoru zadaný v *CursorName již existuje. |
| HY000 | Obecná chyba | Došlo k chybě, pro kterou nebyla definována žádná specifická funkce SQLSTATE a pro kterou nebyla definována žádná implementace sqlSTATE. Chybová zpráva vrácená sqlGetDiagRec v *MessageText vyrovnávací paměti popisuje chybu a její příčinu. |
| HY001 | Chyba přidělení paměti | Ovladač nemohl přidělit paměť potřebnou k podpoře provádění nebo dokončení funkce. |
| HY009 | Neplatné použití ukazatele null | (DM) Argument CursorName byl ukazatel null. |
| HY010 | Chyba posloupnosti funkcí | (DM) Byla volána asynchronně spouštěná funkce pro popisovač připojení, který je přidružen k StatementHandle. Tato asynchronní funkce se stále spouštěla, když byla volána funkce SQLSetCursorName. (DM) Byla volána asynchronně spouštěná funkce pro StatementHandle a stále se spouštěla při zavolání této funkce. (DM) |
| HY013 | Chyba správy paměti | Volání funkce nelze zpracovat, protože základní objekty paměti nelze získat přístup, pravděpodobně kvůli nedostatku paměti. |
| HY090 | Neplatná délka řetězce nebo vyrovnávací paměti | (DM) Argument NameLength byl menší než 0, ale nerovnal se SQL_NTS. |
| HY117 | Připojení je pozastaveno kvůli neznámému stavu transakce. Jsou povoleny pouze funkce pro odpojení a jen pro čtení. | (DM) Další informace o pozastaveném stavu naleznete v tématu FUNKCE SQLEndTran. |
| HYT01 | Vypršel časový limit připojení | Platnost časového limitu připojení vypršela, než zdroj dat odpověděl na žádost. Doba časového limitu připojení je nastavena prostřednictvím SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Ovladač tuto funkci nepodporuje. | (DM) Ovladač přidružený k StatementHandle funkci nepodporuje. |
Komentáře
Názvy kurzorů se používají pouze v pozičních příkazech update a delete (například UPDATEnázev tabulky ...WHERE CURRENT OFcursor-name). Další informace naleznete v tématu Positioned Update and Delete – příkazy. Pokud aplikace nevolá SQLSetCursorName definovat název kurzoru, při spuštění příkazu dotazu ovladač vygeneruje název, který začíná písmeny SQL_CUR a nepřekračuje délku 18 znaků.
Všechny názvy kurzorů v rámci připojení musí být jedinečné. Maximální délka názvu kurzoru je definována ovladačem. Pro maximální interoperabilitu se doporučuje, aby aplikace omezily názvy kurzorů na maximálně 18 znaků. V rozhraní ODBC 3*.x*, pokud je název kurzoru uvozovaný identifikátor, zpracovává se rozlišováním velkých a malých písmen a může obsahovat znaky, které syntaxe SQL nepovolila nebo by se s nimi chovala speciálně, například s prázdnými nebo rezervovanými klíčovými slovy. Pokud musí být název kurzoru považován za rozlišující velká a malá písmena, musí být předán jako identifikátor uvozen.
Název kurzoru, který je nastaven buď explicitně nebo implicitně, zůstane nastaven, dokud příkaz, ke kterému je přidružen, vynechá, pomocí SQLFreeHandle. SQLSetCursorName lze volat k přejmenování kurzoru na příkaz, pokud je kurzor v přiděleném nebo připraveném stavu.
Příklad kódu
V následujícím příkladu aplikace používá SQLSetCursorName k nastavení názvu kurzoru pro příkaz. Tento příkaz pak použije k načtení výsledků z tabulky CUSTOMERS. Nakonec provede změnu telefonního čísla Johna Smithe. Všimněte si, že aplikace používá různé popisovače příkazů pro SELECT a UPDATE příkazy.
Další příklad kódu najdete v tématu SQLSetPos.
#define NAME_LEN 50
#define PHONE_LEN 10
SQLHSTMT hstmtSelect,
SQLHSTMT hstmtUpdate;
SQLRETURN retcode;
SQLHDBC hdbc;
SQLCHAR szName[NAME_LEN], szPhone[PHONE_LEN];
SQLINTEGER cbName, cbPhone;
/* Allocate the statements and set the cursor name. */
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtSelect);
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtUpdate);
SQLSetCursorName(hstmtSelect, "C1", SQL_NTS);
/* SELECT the result set and bind its columns to local buffers. */
SQLExecDirect(hstmtSelect,
"SELECT NAME, PHONE FROM CUSTOMERS",
SQL_NTS);
SQLBindCol(hstmtSelect, 1, SQL_C_CHAR, szName, NAME_LEN, &cbName);
SQLBindCol(hstmtSelect, 2, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);
/* Read through the result set until the cursor is */
/* positioned on the row for John Smith. */
do
retcode = SQLFetch(hstmtSelect);
while ((retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) &&
(strcmp(szName, "Smith, John") != 0));
/* Perform a positioned update of John Smith's name. */
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLExecDirect(hstmtUpdate,
"UPDATE EMPLOYEE SET PHONE=\"2064890154\" WHERE CURRENT OF C1",
SQL_NTS);
}
Související funkce
| Informace o | Vidět |
|---|---|
| Spuštění příkazu SQL | funkce SQLExecDirect |
| Spuštění připraveného příkazu SQL | funkce SQLExecute |
| Vrácení názvu kurzoru | funkce SQLGetCursorName |
| Nastavení možností posouvání kurzoru | funkce SQLSetScrollOptions |
Viz také
Referenční
soubory hlaviček ODBC