Função SQLNumResultCols
Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92
Resumo
SQLNumResultCols retorna o número de colunas em um conjunto de resultados.
Sintaxe
SQLRETURN SQLNumResultCols(
SQLHSTMT StatementHandle,
SQLSMALLINT * ColumnCountPtr);
Argumentos
Identificador de declaração
[Entrada] Identificador de instrução.
ColumnCountPtr
[Saída] Ponteiro para um buffer no qual retornar o número de colunas no conjunto de resultados. Essa contagem não inclui uma coluna de indicador associada.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLNumResultCols 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 SQLNumResultCols 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.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver estava conectado falhou antes que a função concluísse o processamento. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia 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. |
| HY008 | Operação cancelada | O processamento assíncrono foi habilitado para o StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle; a função foi chamada novamente no StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle de um thread diferente em um aplicativo multithread. |
| HY010 | Erro de sequência de função | (DM) Uma função de 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 SQLNumResultsCols foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. (DM) A função foi chamada antes de chamar SQLPrepare ou SQLExecDirect para o StatementHandle. (DM) Uma função de execução assíncrona (não esta) foi chamada para o StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para o StatementHandle e retornado SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem enviados para todos os parâmetros ou colunas de dados em execução. Consulte Função SQLPrepare para obter detalhes sobre quando um identificador de instrução pode ser liberado. |
| 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. |
| HY117 | A conexão está suspensa devido ao estado desconhecido da transação. Somente funções de desconexão 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 que a fonte de dados respondesse à 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 suporta esta função | (DM) O driver associado ao StatementHandle não dá suporte à função. |
| IM017 | A sondagem está desabilitada no modo de notificação assíncrona | Sempre que o modelo de notificação é usado, a sondagem é desabilitada. |
| IM018 | SQLCompleteAsync não foi chamado para concluir a operação assíncrona anterior nesse identificador. | Se a chamada de função anterior no identificador retornar SQL_STILL_EXECUTING e se o modo de notificação estiver habilitado, SQLCompleteAsync deverá ser chamado no identificador para fazer o pós-processamento e concluir a operação. |
SQLNumResultCols pode retornar qualquer SQLSTATE que possa ser retornado por SQLPrepare ou SQLExecute quando chamado após SQLPrepare e antes de SQLExecute, dependendo de quando a fonte de dados avalia a instrução SQL associada à instrução.
Comentários
SQLNumResultCols pode ser chamado com êxito somente quando a instrução está no estado preparado, executado ou posicionado.
Se a instrução associada a StatementHandle não retornar colunas, SQLNumResultCols definirá *ColumnCountPtr como 0.
O número de colunas retornadas por SQLNumResultCols é o mesmo valor que o campo SQL_DESC_COUNT do IRD.
Para obter mais informações, consulte Foi criado um conjunto de resultados? e Como os metadados são usados?.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associando um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| Cancelando o processamento de instruções | Função SQLCancel |
| Retornando informações sobre uma coluna em um conjunto de resultados | Função SQLColAttribute |
| Retornando informações sobre uma coluna em um conjunto de resultados | Função SQLDescribeCol |
| Executando uma instrução SQL | Função SQLExecDirect |
| Executando uma instrução SQL preparada | Função SQLExecute |
| Buscando um bloco de dados ou rolando por um conjunto de resultados | Função SQLFetchScroll |
| Buscando uma única linha ou um bloco de dados em uma direção somente para frente | Função SQLFetch |
| Buscando parte ou toda uma coluna de dados | Função SQLGetData |
| Preparando uma instrução SQL para execução | Função SQLPrepare |
| Configurando opções de rolagem do cursor | Função SQLSetStmtAttr |