Função SQLGetCursorName
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: ISO 92
Resumo
SQLGetCursorName retorna o nome do cursor associado a uma instrução especificada.
Sintaxe
SQLRETURN SQLGetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr);
Argumentos
StatementHandle
[Entrada] Identificador de instrução.
CursorName
[Saída] Ponteiro para um buffer no qual retornar o nome do cursor.
Se CursorName for NULL, NameLengthPtr ainda retornará o número total de caracteres (excluindo o caractere de terminação nula para dados de caractere) disponíveis para retornar no buffer apontado por CursorName.
BufferLength
[Entrada] Comprimento de *CursorName, em caracteres.
NameLengthPtr
[Saída] Ponteiro para a memória na qual retornar o número total de caracteres (excluindo o caractere de terminação nula) disponível para retornar em *CursorName. Se o número de caracteres disponíveis para retornar for maior ou igual a BufferLength, o nome do cursor em *CursorName será truncado para BufferLength menos o comprimento de um caractere de terminação nula.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLGetCursorName 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 SQLGetCursorName 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 buffer *CursorName não era grande o suficiente para retornar o nome inteiro do cursor, portanto, o nome do cursor foi truncado. O comprimento do nome do cursor não confiável é retornado em *NameLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 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. |
| 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 assíncrona ainda estava em execução quando a função SQLGetCursorName foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para StatementHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. (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. |
| HY015 | Nenhum nome de cursor disponível | (DM) O driver era um driver ODBC 2*.x*, não havia cursor aberto na instrução e nenhum nome de cursor havia sido definido com SQLSetCursorName. |
| HY090 | Comprimento de buffer ou cadeia de caracteres inválido | (DM) O valor especificado no argumento BufferLength era menor que 0. |
| 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, o driver gerará um nome. Esse nome começa com as letras SQL_CUR.
Observação
No ODBC 2*.x*, quando não havia nenhum cursor aberto e nenhum nome havia sido definido por uma chamada para SQLSetCursorName, uma chamada para SQLGetCursorName retornava SQLSTATE HY015 (nenhum nome de cursor disponível). No ODBC 3*.x*, isso não é mais verdadeiro; independentemente de quando SQLGetCursorName é chamado, o driver retorna o nome do cursor.
SQLGetCursorName retorna o nome de um cursor, independentemente de o nome ter sido criado explicitamente ou implicitamente. Um nome de cursor será gerado implicitamente se SQLSetCursorName não for chamado. SQLSetCursorName pode ser chamado para renomear um cursor em uma instrução, desde que o cursor esteja em um estado alocado ou preparado.
Um nome de cursor definido explicitamente ou implicitamente permanece definido até que StatementHandle ao qual ele está associado seja descartado, usando SQLFreeHandle com um HandleType de SQL_HANDLE_STMT.
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 |
| Preparando uma instrução para execução | Função SQLPrepare |
| Definindo um nome de cursor | Função SQLSetCursorName |
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