SQLSetCursorName-funktion

Efterlevnad
Version introducerad: ODBC 1.0 Standardefterlevnad: ISO 92

Sammanfattning
SQLSetCursorName associerar ett markörnamn med en aktiv instruktion. Om ett program inte anropar SQLSetCursorNamegenererar drivrutinen markörnamn efter behov för bearbetning av SQL-uttryck.

Syntax

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

Argument

StatementHandle
[Indata] Instruktionshandtag.

CursorName
[Indata] Markörnamn. För effektiv bearbetning bör markörens namn inte innehålla inledande eller avslutande blanksteg i markörens namn, och om markörens namn innehåller en avgränsad identifierare ska avgränsaren placeras som det första tecknet i markörens namn.

NameLength
[Indata] Längd i tecken i *CursorName.

Returnerar

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostik

När SQLSetCursorName returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan du hämta ett associerat SQLSTATE-värde genom att anropa SQLGetDiagRec med en HandleType- av SQL_HANDLE_STMT och en Hantera för StatementHandle. I följande tabell visas de SQLSTATE-värden som ofta returneras av SQLSetCursorName- och förklarar var och en i kontexten för den här funktionen. notationen "(DM)" föregår beskrivningarna av SQLSTATEs som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

Kommentarer

Markörnamn används endast i positionerade uppdaterings- och borttagningsuttryck (till exempel UPDATEtabellnamn ...WHERE CURRENT OFcursor-name). Mer information finns i Positioned Update and Delete Statements. Om programmet inte anropar SQLSetCursorName för att definiera ett markörnamn genererar drivrutinen vid körning av en frågeuttryck ett namn som börjar med bokstäverna SQL_CUR och inte överskrider 18 tecken.

Alla markörnamn i anslutningen måste vara unika. Den maximala längden på ett markörnamn definieras av drivrutinen. För maximal samverkan rekommenderar vi att program begränsar markörnamn till högst 18 tecken. Om ett markörnamn är en citerad identifierare i ODBC 3*.x* behandlas det på ett skiftlägeskänsligt sätt och kan innehålla tecken som syntaxen för SQL inte tillåter eller behandlar särskilt, till exempel tomma eller reserverade nyckelord. Om ett markörnamn måste behandlas på ett skiftlägeskänsligt sätt måste det skickas som en citerad identifierare.

Ett markörnamn som anges antingen explicit eller implicit förblir inställt tills instruktionen som den är associerad med tas bort med hjälp av SQLFreeHandle. SQLSetCursorName kan anropas för att byta namn på en markör på en instruktion så länge markören är i ett allokerat eller förberett tillstånd.

Kodexempel

I följande exempel använder ett program SQLSetCursorName- för att ange ett markörnamn för en -instruktion. Den använder sedan instruktionen för att hämta resultat från tabellen CUSTOMERS. Slutligen utför den en positionerad uppdatering för att ändra john Smiths telefonnummer. Observera att programmet använder olika instruktionsreferenser för SELECT-- och UPDATE--instruktioner.

Ett annat kodexempel finns i 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);  
}  

Relaterade funktioner

Se även

ODBC API-referens
ODBC-huvudfiler