Função SQLSetCursorName
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: 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 da instrução SQL.
Sintaxe
SQLRETURN SQLSetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT NameLength);
Argumentos
StatementHandle
[Entrada] Identificador de instrução.
CursorName
[Entrada] Nome do cursor. Para 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 deverá ser posicionado como o primeiro caractere no nome do cursor.
NameLength
[Entrada] Comprimento em caracteres de *CursorName.
Retornos
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 Identificador 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 o contrário.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01004 | Dados de cadeia de caracteres, truncados à direita | O nome do cursor excedeu o limite máximo, portanto, somente o número máximo permitido de caracteres foi usado. |
| 24.000 | Estado de cursor inválido | A instrução correspondente a StatementHandle já estava em um estado executado ou posicionado pelo cursor. |
| 34000 | Nome de cursor inválido | O nome do cursor especificado em *CursorName era inválido porque excedeu o comprimento máximo conforme definido pelo driver ou começou com "SQLCUR" ou "SQL_CUR". |
| 3C000 | Nome do cursor duplicado | O nome do cursor especificado em *CursorName já existe. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia nenhum SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa. |
| HY001 | Erro de alocação de memória | O driver não pôde alocar a memória necessária para dar suporte à execução ou à conclusão da função. |
| HY009 | Uso inválido de ponteiro nulo | (DM) O argumento CursorName era um ponteiro nulo. |
| HY010 | Erro de sequência de funções | (DM) Uma função em execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função aynchronous ainda estava em execução quando a função SQLSetCursorName foi chamada. (DM) Uma função em execução assíncrona foi chamada para StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para StatementHandle e retornados SQL_NEED_DATA. Essa função foi chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados em execução. |
| HY013 | Erro de gerenciamento de memória | A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa. |
| HY090 | Comprimento de buffer ou cadeia de caracteres inválido | (DM) O argumento NameLength era menor que 0, mas não igual a SQL_NTS. |
| HY117 | A conexão está suspensa devido ao estado de transação desconhecido. Somente funções desconectar e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran. |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes da fonte de dados responder à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não dá suporte a essa função | (DM) O driver associado ao StatementHandle não dá suporte à função . |
Comentários
Os nomes de cursor são usados apenas em instruções de atualização e exclusão posicionadas (por exemplo, UPDATEtable-name ... WHERE CURRENT OFcursor-name). 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 a interoperabilidade máxima, é recomendável que os aplicativos limitem nomes de cursor a não mais do que 18 caracteres. No ODBC 3*.x*, se um nome de cursor for um identificador entre aspas, ele será tratado de maneira que diferencia maiúsculas de 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 explicitamente 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 os 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 obter 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
| Para obter informações sobre | Consulte |
|---|---|
| Executando uma instrução SQL | Função SQLExecDirect |
| Executando uma instrução SQL preparada | Função SQLExecute |
| Retornando um nome de cursor | Função SQLGetCursorName |
| Definindo opções de rolagem do cursor | Função SQLSetScrollOptions |
Consulte Também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de