Função SQLSetCursorName

Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92

Resumo
SQLSetCursorName associa um nome de cursor a uma instrução ativa. Se um aplicativo não chamar SQLSetCursorName, o driver gerará nomes de cursor conforme necessário para o processamento de instruções SQL.

Sintaxe

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

Argumentos

Identificador de declaração
[Entrada] Identificador de instrução.

Nome do cursor
[Entrada] Nome do cursor. Para um processamento eficiente, o nome do cursor não deve incluir espaços à esquerda ou à direita no nome do cursor e, se o nome do cursor incluir um identificador delimitado, o delimitador deve ser posicionado como o primeiro caractere no nome do cursor.

NameLength
[Entrada] Comprimento em caracteres de *CursorName.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando SQLSetCursorName retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLSetCursorName e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.

Comentários

Os nomes de cursor são usados apenas em instruções de atualização e exclusão posicionadas (por exemplo, UPDATEtable-name ...ONDE ATUAL DEnome do cursor). Para obter mais informações, consulte Instruções de atualização e exclusão posicionadas. Se o aplicativo não chamar SQLSetCursorName para definir um nome de cursor, na execução de uma instrução de consulta, o driver gerará um nome que começa com as letras SQL_CUR e não excede 18 caracteres de comprimento.

Todos os nomes de cursor dentro da conexão devem ser exclusivos. O comprimento máximo de um nome de cursor é definido pelo driver. Para máxima interoperabilidade, é recomendável que os aplicativos limitem os nomes dos cursores a não mais que 18 caracteres. No ODBC 3*.x*, se um nome de cursor for um identificador entre aspas, ele será tratado de maneira sensível a maiúsculas e minúsculas e poderá conter caracteres que a sintaxe do SQL não permitiria ou trataria especialmente, como espaços em branco ou palavras-chave reservadas. Se um nome de cursor precisar ser tratado de maneira que diferencia maiúsculas de minúsculas, ele deverá ser passado como um identificador entre aspas.

Um nome de cursor definido explícita ou implicitamente permanece definido até que a instrução à qual ele está associado seja descartada, usando SQLFreeHandle. SQLSetCursorName pode ser chamado para renomear um cursor em uma instrução, desde que o cursor esteja em um estado alocado ou preparado.

Exemplo de código

No exemplo a seguir, um aplicativo usa SQLSetCursorName para definir um nome de cursor para uma instrução. Em seguida, ele usa essa instrução para recuperar resultados da tabela CUSTOMERS. Por fim, ele executa uma atualização posicionada para alterar o número de telefone de John Smith. Observe que o aplicativo usa identificadores de instrução diferentes para as instruções SELECT e UPDATE .

Para outro exemplo de código, consulte 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);  
}  

Funções relacionadas

Confira também

Referência de API do ODBC
Arquivos de cabeçalho ODBC