SQLSetCursorName, functie

conformance
Versie geïntroduceerd: NALEVING van ODBC 1.0-standaarden: ISO 92

Samenvattings-
SQLSetCursorName een cursornaam koppelt aan een actieve instructie. Als een toepassing geen SQLSetCursorNameaanroept, genereert het stuurprogramma indien nodig cursornamen voor verwerking van SQL-instructies.

Syntaxis

  
SQLRETURN SQLSetCursorName(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     CursorName,  
     SQLSMALLINT   NameLength);  

Argumenten

StatementHandle-
[Invoer] Instructiehandgreep.

CursorName-
[Invoer] Cursornaam. Voor efficiënte verwerking mag de cursornaam geen voorloop- of volgspaties in de cursornaam bevatten en als de cursornaam een id met scheidingstekens bevat, moet het scheidingsteken als het eerste teken in de cursornaam worden weergegeven.

NameLength-
[Invoer] Lengte in tekens van *CursorName.

Retourneert

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR of SQL_INVALID_HANDLE.

Diagnostiek

Wanneer SQLSetCursorName SQL_ERROR of SQL_SUCCESS_WITH_INFO retourneert, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec- aan te roepen met een HandleType- van SQL_HANDLE_STMT en een Handle van StatementHandle. De volgende tabel bevat de SQLSTATE-waarden die vaak worden geretourneerd door SQLSetCursorName- en legt elke waarden uit in de context van deze functie; de notatie (DM)' voorafgaat aan de beschrijvingen van SQLSTATEs die worden geretourneerd door Driver Manager. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

SQLSTATE	Fout	Beschrijving
01000	Algemene waarschuwing	Stuurprogrammaspecifiek informatiebericht. (Functie retourneert SQL_SUCCESS_WITH_INFO.)
01004	Tekenreeksgegevens, rechts afgekapt	De cursornaam heeft de maximumlimiet overschreden, dus alleen het maximaal toegestane aantal tekens is gebruikt.
24000	Ongeldige cursorstatus	De instructie die overeenkomt met StatementHandle- heeft al een uitgevoerde of cursorpositie.
34000	Ongeldige cursornaam	De naam van de cursor die is opgegeven in *CursorName is ongeldig omdat deze de maximumlengte heeft overschreden zoals gedefinieerd door het stuurprogramma of is gestart met 'SQLCUR' of 'SQL_CUR'.
3C000	Dubbele cursornaam	De cursornaam die is opgegeven in *CursorName al bestaat.
HY000	Algemene fout	Er is een fout opgetreden waarvoor er geen specifieke SQLSTATE is en waarvoor geen implementatiespecifieke SQLSTATE is gedefinieerd. Het foutbericht dat is geretourneerd door SQLGetDiagRec- in de *MessageText buffer beschrijft de fout en de oorzaak ervan.
HY001	Fout bij geheugentoewijzing	Het stuurprogramma kan geen geheugen toewijzen dat nodig is om de uitvoering of voltooiing van de functie te ondersteunen.
HY009	Ongeldig gebruik van null-aanwijzer	(DM) Het argument CursorName is een null-aanwijzer.
HY010	Fout in functiereeks	(DM) Er is een asynchroon uitgevoerde functie aangeroepen voor de verbindingsgreep die is gekoppeld aan de StatementHandle-. Deze asynchrone functie werd nog steeds uitgevoerd toen de SQLSetCursorName functie werd aangeroepen. (DM) Er is een asynchroon uitgevoerde functie aangeroepen voor de StatementHandle- en werd nog steeds uitgevoerd toen deze functie werd aangeroepen. (DM) SQLExecute, SQLExecDirect, SQLBulkOperationsof SQLSetPos is aangeroepen voor de StatementHandle- en SQL_NEED_DATA geretourneerd. Deze functie is aangeroepen voordat gegevens werden verzonden voor alle parameters of kolommen voor uitvoering van gegevens.
HY013	Fout bij geheugenbeheer	De functie-aanroep kan niet worden verwerkt omdat de onderliggende geheugenobjecten niet kunnen worden geopend, mogelijk vanwege weinig geheugen.
HY090	Ongeldige tekenreeks- of bufferlengte	(DM) Het argument NameLength was kleiner dan 0, maar niet gelijk aan SQL_NTS.
HY117	De verbinding is onderbroken vanwege een onbekende transactiestatus. Alleen de verbinding verbreken en alleen-lezenfuncties zijn toegestaan.	(DM) Zie SQLEndTran Functionvoor meer informatie over de onderbroken status.
HYT01	Time-out voor verbinding verlopen	De time-outperiode voor de verbinding is verlopen voordat de gegevensbron op de aanvraag heeft gereageerd. De time-outperiode voor de verbinding wordt ingesteld via SQLSetConnectAttr-, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Stuurprogramma biedt geen ondersteuning voor deze functie	(DM) Het stuurprogramma dat is gekoppeld aan de StatementHandle- biedt geen ondersteuning voor de functie.

Opmerkingen

Namen van cursors worden alleen gebruikt in instructies voor bijwerken en verwijderen (bijvoorbeeld UPDATEtabelnaam ...WHERE CURRENT OFcursor-name). Zie Positioned Update- en Delete-instructiesvoor meer informatie. Als de toepassing geen SQLSetCursorName aanroept om een cursornaam te definiëren, genereert het stuurprogramma bij het uitvoeren van een query-instructie een naam die begint met de letters SQL_CUR en niet langer is dan 18 tekens.

Alle cursornamen binnen de verbinding moeten uniek zijn. De maximale lengte van een cursornaam wordt gedefinieerd door het stuurprogramma. Voor maximale interoperabiliteit wordt aanbevolen dat toepassingen cursornamen beperken tot maximaal 18 tekens. Als in ODBC 3*.x* een aanhalingstekensnaam is, wordt deze op een hoofdlettergevoelige manier behandeld en kan deze tekens bevatten die de syntaxis van SQL niet toestaat of speciaal zou behandelen, zoals lege of gereserveerde trefwoorden. Als een cursornaam op een hoofdlettergevoelige manier moet worden behandeld, moet deze worden doorgegeven als een aanhalingsaanduiding.

Een cursornaam die expliciet of impliciet is ingesteld, blijft ingesteld totdat de instructie waaraan deze is gekoppeld, wordt verwijderd met behulp van SQLFreeHandle-. SQLSetCursorName kan worden aangeroepen om de naam van een cursor in een instructie te wijzigen zolang de cursor een toegewezen of voorbereide status heeft.

Codevoorbeeld

In het volgende voorbeeld gebruikt een toepassing SQLSetCursorName om een cursornaam voor een instructie in te stellen. Vervolgens wordt die instructie gebruikt om resultaten op te halen uit de tabel CUSTOMERS. Ten slotte wordt er een positioned update uitgevoerd om het telefoonnummer van John Smith te wijzigen. Houd er rekening mee dat de toepassing verschillende instructiegrepen gebruikt voor de SELECT- en UPDATE--instructies.

Zie SQLSetPosvoor een ander codevoorbeeld.

#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);  
}  

Verwante functies

Voor informatie over	Zien
Een SQL-instructie uitvoeren	SQLExecDirect-functie
Een voorbereide SQL-instructie uitvoeren	SQLExecute-functie
Een cursornaam retourneren	SQLGetCursorName-functie
Opties voor het schuiven van cursor instellen	SQLSetScrollOptions-functie

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden