Função SQLGetData
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: ISO 92
Resumo
SQLGetData recupera dados para uma única coluna no conjunto de resultados ou para um único parâmetro depois que SQLParamData retorna SQL_PARAM_DATA_AVAILABLE. Ele pode ser chamado várias vezes para recuperar dados de comprimento variável em partes.
Sintaxe
SQLRETURN SQLGetData(
SQLHSTMT StatementHandle,
SQLUSMALLINT Col_or_Param_Num,
SQLSMALLINT TargetType,
SQLPOINTER TargetValuePtr,
SQLLEN BufferLength,
SQLLEN * StrLen_or_IndPtr);
Argumentos
StatementHandle
[Entrada] Identificador de instrução.
Col_or_Param_Num
[Entrada] Para recuperar dados de coluna, é o número da coluna para a qual retornar dados. As colunas do conjunto de resultados são numeradas em ordem de coluna crescente, começando em 1. A coluna de indicador é o número da coluna 0; isso só poderá ser especificado se os indicadores estiverem habilitados.
Para recuperar dados de parâmetro, é o ordinal do parâmetro , que começa em 1.
TargetType
[Entrada] O identificador de tipo do tipo de dados C do buffer *TargetValuePtr . Para obter uma lista de tipos de dados C válidos e identificadores de tipo, consulte a seção Tipos de dados C no Apêndice D: Tipos de Dados.
Se TargetType for SQL_ARD_TYPE, o driver usará o identificador de tipo especificado no campo SQL_DESC_CONCISE_TYPE do ARD. Se TargetType for SQL_APD_TYPE, SQLGetData usará o mesmo tipo de dados C especificado em SQLBindParameter. Caso contrário, o tipo de dados C especificado em SQLGetData substituirá o tipo de dados C especificado em SQLBindParameter. Se for SQL_C_DEFAULT, o driver selecionará o tipo de dados C padrão com base no tipo de dados SQL da origem.
Você também pode especificar um tipo de dados C estendido. Para obter mais informações, consulte Tipos de dados C em ODBC.
TargetValuePtr
[Saída] Ponteiro para o buffer no qual retornar os dados.
TargetValuePtr não pode ser NULL.
BufferLength
[Entrada] Comprimento do buffer *TargetValuePtr em bytes.
O driver usa BufferLength para evitar gravar além do final do buffer *TargetValuePtr ao retornar dados de comprimento variável, como dados binários ou caracteres. Observe que o driver conta o caractere de terminação nula ao retornar dados de caractere para *TargetValuePtr. *TargetValuePtr deve, portanto, conter espaço para o caractere de terminação nula ou o driver truncará os dados.
Quando o driver retorna dados de comprimento fixo, como um inteiro ou uma estrutura de data, o driver ignora BufferLength e pressupõe que o buffer é grande o suficiente para manter os dados. Portanto, é importante que o aplicativo aloque um buffer grande o suficiente para dados de comprimento fixo ou o driver gravará após o final do buffer.
SQLGetData retorna SQLSTATE HY090 (comprimento de buffer ou cadeia de caracteres inválido) quando BufferLength é menor que 0, mas não quando BufferLength é 0.
Strlen_or_indptr
[Saída] Ponteiro para o buffer no qual retornar o comprimento ou o valor do indicador. Se esse for um ponteiro nulo, nenhum valor de comprimento ou indicador será retornado. Isso retorna um erro quando os dados que estão sendo buscados são NULL.
SQLGetData pode retornar os seguintes valores no buffer de comprimento/indicador:
O comprimento dos dados disponíveis para retornar
SQL_NO_TOTAL
SQL_NULL_DATA
Para obter mais informações, consulte Usando valores de comprimento/indicador e "Comentários" neste tópico.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLGetData 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 SQLGetData 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 | Nem todos os dados da coluna especificada, Col_or_Param_Num, poderiam ser recuperados em uma única chamada para a função. SQL_NO_TOTAL ou o comprimento dos dados restantes na coluna especificada antes da chamada atual para SQLGetData é retornado em *StrLen_or_IndPtr. (A função retorna SQL_SUCCESS_WITH_INFO.) Para obter mais informações sobre como usar várias chamadas para SQLGetData para uma única coluna, confira "Comentários". |
| 01S07 | Truncamento fracionário | Os dados retornados para uma ou mais colunas foram truncados. Para tipos de dados numéricos, a parte fracionária do número foi truncada. Para tipos de dados time, timestamp e interval que contêm um componente de tempo, a parte fracionária do tempo foi truncada. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 07006 | Violação de atributo de tipo de dados restrito | O valor de dados de uma coluna no conjunto de resultados não pode ser convertido no tipo de dados C especificado pelo argumento TargetType. |
| 07009 | Índice de descritor inválido | O valor especificado para o argumento Col_or_Param_Num era 0 e o atributo de instrução SQL_ATTR_USE_BOOKMARKS foi definido como SQL_UB_OFF. O valor especificado para o argumento Col_or_Param_Num foi maior que o número de colunas no conjunto de resultados. O valor Col_or_Param_Num não era igual ao ordinal do parâmetro disponível. (DM) A coluna especificada foi associada. Essa descrição não se aplica a drivers que retornam a máscara de bits SQL_GD_BOUND para a opção SQL_GETDATA_EXTENSIONS no SQLGetInfo. (DM) O número da coluna especificada era menor ou igual ao número da coluna associada mais alta. Essa descrição não se aplica a drivers que retornam a máscara de bits SQL_GD_ANY_COLUMN para a opção SQL_GETDATA_EXTENSIONS no SQLGetInfo. (DM) O aplicativo já chamou SQLGetData para a linha atual; o número da coluna especificada na chamada atual foi menor que o número da coluna especificada na chamada anterior; e o driver não retorna a máscara de bits SQL_GD_ANY_ORDER para a opção SQL_GETDATA_EXTENSIONS no SQLGetInfo. (DM) O argumento TargetType foi SQL_ARD_TYPE e o registro do descritor Col_or_Param_Num no ARD falhou na verificação de consistência. (DM) O argumento TargetType foi SQL_ARD_TYPE e o valor no campo SQL_DESC_COUNT do ARD era menor que o argumento Col_or_Param_Num . |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver foi conectado falhou antes da função concluir o processamento. |
| 22002 | Variável de indicador necessária, mas não fornecida | StrLen_or_IndPtr era um ponteiro nulo e os dados NULL foram recuperados. |
| 22003 | Valor numérico fora do intervalo | Retornar o valor numérico (como numérico ou cadeia de caracteres) para a coluna teria feito com que toda a parte (em vez de fracionária) do número fosse truncada. Para obter mais informações, consulte Apêndice D: Tipos de dados. |
| 22007 | Formato de datetime inválido | A coluna de caracteres no conjunto de resultados estava associada a uma estrutura de data, hora ou carimbo de data/hora C e o valor na coluna era uma data, hora ou carimbo de data/hora inválido, respectivamente. Para obter mais informações, consulte Apêndice D: Tipos de dados. |
| 22012 | Divisão por zero | Um valor de uma expressão aritmética que resultou em divisão por zero foi retornado. |
| 22015 | Estouro de campo de intervalo | Atribuir de um tipo SQL numérico ou intervalo exato a um tipo C de intervalo causou uma perda de dígitos significativos no campo à esquerda. Ao retornar dados para um tipo C de intervalo, não houve representação do valor do tipo SQL no tipo C do intervalo. |
| 22018 | Valor de caractere inválido para especificação de conversão | Uma coluna de caracteres no conjunto de resultados foi retornada para um buffer C de caracteres e a coluna continha um caractere para o qual não havia representação no conjunto de caracteres do buffer. O tipo C era um numérico exato ou aproximado, um datetime ou um tipo de dados de intervalo; o tipo SQL da coluna era um tipo de dados de caractere; e o valor na coluna não era um literal válido do tipo C associado. |
| 24.000 | Estado de cursor inválido | (DM) A função foi chamada sem primeiro chamar SQLFetch ou SQLFetchScroll para posicionar o cursor na linha de dados necessária. (DM) O StatementHandle estava em um estado executado, mas nenhum conjunto de resultados foi associado ao StatementHandle. Um cursor foi aberto no StatementHandle e SQLFetch ou SQLFetchScroll havia sido chamado, mas o cursor foi posicionado antes do início do conjunto de resultados ou após o final do conjunto de resultados. |
| 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. |
| HY003 | Tipo de programa fora do intervalo | (DM) O argumento TargetType não era um tipo de dados válido, SQL_C_DEFAULT, SQL_ARD_TYPE (em caso de recuperação de dados de coluna) ou SQL_APD_TYPE (em caso de recuperação de dados de parâmetro). (DM) O argumento Col_or_Param_Num era 0 e o argumento TargetType não era SQL_C_BOOKMARK para um indicador de comprimento fixo ou SQL_C_VARBOOKMARK para um indicador de comprimento variável. |
| HY008 | Operação cancelada | O processamento assíncrono foi habilitado para StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle e, em seguida, 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 e, em seguida, a função foi chamada novamente no StatementHandle. |
| HY009 | Uso inválido de ponteiro nulo | (DM) O argumento TargetValuePtr era um ponteiro nulo. |
| HY010 | Erro de sequência de funções | (DM) O StatementHandle especificado não estava em um estado executado. A função foi chamada sem primeiro chamar SQLExecDirect, SQLExecute ou uma função de catálogo. (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 SQLGetData foi chamada. (DM) Uma função de execução assíncrona (não esta) 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. (DM) O StatementHandle estava em um estado executado, mas nenhum conjunto de resultados foi associado ao StatementHandle. Uma chamada para SQLExeceute, SQLExecDirect ou SQLMoreResults retornou SQL_PARAM_DATA_AVAILABLE, mas SQLGetData foi chamado, em vez de SQLParamData. |
| 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 valor especificado para o argumento BufferLength era menor que 0. O valor especificado para o argumento BufferLength era menor que 4, o argumento Col_or_Param_Num foi definido como 0 e o driver era um driver ODBC 2*.x*. |
| HY109 | Posição inválida do cursor | O cursor foi posicionado (por SQLSetPos, SQLFetch, SQLFetchScroll ou SQLBulkOperations) em uma linha que foi excluída ou não pôde ser buscada. O cursor era um cursor somente para frente e o tamanho do conjunto de linhas era maior que um. |
| 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. |
| HYC00 | Recurso opcional não implementado | O driver ou fonte de dados não dá suporte ao uso de SQLGetData com várias linhas no SQLFetchScroll. Essa descrição não se aplica a drivers que retornam a máscara de bits SQL_GD_BLOCK para a opção SQL_GETDATA_EXTENSIONS no SQLGetInfo. O driver ou a fonte de dados não dá suporte à conversão especificada pela combinação do argumento TargetType e do tipo de dados SQL da coluna correspondente. Esse erro se aplica somente quando o tipo de dados SQL da coluna foi mapeado para um tipo de dados SQL específico do driver. O driver dá suporte apenas ao ODBC 2*.x*, e o argumento TargetType foi um dos seguintes: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT e qualquer um dos tipos de dados C do intervalo listados em Tipos de Dados C no Apêndice D: Tipos de Dados. O driver dá suporte apenas a versões ODBC anteriores à 3.50 e o argumento TargetType foi SQL_C_GUID. |
| 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 correspondente 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. |
Comentários
SQLGetData retorna os dados em uma coluna especificada. SQLGetData pode ser chamado somente depois que uma ou mais linhas tiverem sido buscadas do conjunto de resultados por SQLFetch, SQLFetchScroll ou SQLExtendedFetch. Se os dados de comprimento variável forem muito grandes para serem retornados em uma única chamada para SQLGetData (devido a uma limitação no aplicativo), o SQLGetData poderá recuperá-los em partes. É possível associar algumas colunas em uma linha e chamar SQLGetData para outras, embora isso esteja sujeito a algumas restrições. Para obter mais informações, consulte Obtendo dados longos.
Para obter informações sobre como usar SQLGetData com parâmetros de saída transmitidos, consulte Recuperando parâmetros de saída usando SQLGetData.
Usando SQLGetData
Se o driver não der suporte a extensões para SQLGetData, a função poderá retornar dados somente para colunas não associadas com um número maior que o da última coluna associada. Além disso, dentro de uma linha de dados, o valor do argumento Col_or_Param_Num em cada chamada para SQLGetData deve ser maior ou igual ao valor de Col_or_Param_Num na chamada anterior; ou seja, os dados devem ser recuperados em ordem de número de coluna crescente. Por fim, se não houver suporte para extensões, SQLGetData não poderá ser chamado se o tamanho do conjunto de linhas for maior que 1.
Os motoristas podem relaxar qualquer uma dessas restrições. Para determinar quais restrições um driver relaxa, um aplicativo chama SQLGetInfo com qualquer uma das seguintes opções de SQL_GETDATA_EXTENSIONS:
SQL_GD_OUTPUT_PARAMS = SQLGetData pode ser chamado para retornar valores de parâmetro de saída. Para obter mais informações, consulte Recuperando parâmetros de saída usando SQLGetData.
SQL_GD_ANY_COLUMN. Se essa opção for retornada, SQLGetData poderá ser chamado para qualquer coluna não associada, incluindo aquelas antes da última coluna associada.
SQL_GD_ANY_ORDER. Se essa opção for retornada, SQLGetData poderá ser chamado para colunas não associadas em qualquer ordem.
SQL_GD_BLOCK. Se essa opção for retornada por SQLGetInfo para o SQL_GETDATA_EXTENSIONS InfoType, o driver oferecerá suporte a chamadas para SQLGetData quando o tamanho do conjunto de linhas for maior que 1 e o aplicativo puder chamar SQLSetPos com a opção SQL_POSITION para posicionar o cursor na linha correta antes de chamar SQLGetData.
SQL_GD_BOUND. Se essa opção for retornada, SQLGetData poderá ser chamado para colunas associadas, bem como colunas não associadas.
Há duas exceções a essas restrições e a capacidade de um motorista de relaxá-las. Primeiro, SQLGetData nunca deve ser chamado para um cursor somente de avanço quando o tamanho do conjunto de linhas for maior que 1. Em segundo lugar, se um driver der suporte a indicadores, ele sempre deverá dar suporte à capacidade de chamar SQLGetData para a coluna 0, mesmo que não permita que os aplicativos chamem SQLGetData para outras colunas antes da última coluna associada. (Quando um aplicativo estiver trabalhando com um driver ODBC 2*.x*, o SQLGetData retornará com êxito um indicador quando chamado com Col_or_Param_Num igual a 0 após uma chamada para SQLFetch, porque SQLFetch é mapeado pelo Gerenciador de Driver ODBC 3*.x* para SQLExtendedFetch com uma FetchOrientation de SQL_FETCH_NEXT e SQLGetData com um Col_or_Param_Num de 0 é mapeado pelo Gerenciador de Driver ODBC 3*.x* para SQLGetStmtOption com um fOption de SQL_GET_BOOKMARK.)
SQLGetData não pode ser usado para recuperar o indicador de uma linha que acabou de ser inserida chamando SQLBulkOperations com a opção SQL_ADD, pois o cursor não está posicionado na linha. Um aplicativo pode recuperar o indicador para essa linha associando a coluna 0 antes de chamar SQLBulkOperations com SQL_ADD; nesse caso, SQLBulkOperations retorna o indicador no buffer associado. SQLFetchScroll pode ser chamado com SQL_FETCH_BOOKMARK para reposicionar o cursor nessa linha.
Se o argumento TargetType for um tipo de dados de intervalo, o intervalo padrão de precisão à esquerda (2) e a precisão de segundos de intervalo padrão (6), conforme definido nos campos SQL_DESC_DATETIME_INTERVAL_PRECISION e SQL_DESC_PRECISION do ARD, respectivamente, serão usados para os dados. Se o argumento TargetType for um tipo de dados SQL_C_NUMERIC, a precisão padrão (definida pelo driver) e a escala padrão (0), conforme definido nos campos SQL_DESC_PRECISION e SQL_DESC_SCALE do ARD, serão usados para os dados. Se qualquer precisão ou escala padrão não for apropriada, o aplicativo deverá definir explicitamente o campo de descritor apropriado por uma chamada para SQLSetDescField ou SQLSetDescRec. Ele pode definir o campo SQL_DESC_CONCISE_TYPE como SQL_C_NUMERIC e chamar SQLGetData com um argumento TargetType de SQL_ARD_TYPE, o que fará com que os valores de precisão e escala nos campos do descritor sejam usados.
Observação
No ODBC 2*.x*, os aplicativos definem TargetType como SQL_C_DATE, SQL_C_TIME ou SQL_C_TIMESTAMP para indicar que *TargetValuePtr é uma estrutura de data, hora ou carimbo de data/hora. No ODBC 3*.x*, os aplicativos definem TargetType como SQL_C_TYPE_DATE, SQL_C_TYPE_TIME ou SQL_C_TYPE_TIMESTAMP. O Gerenciador de Driver faz mapeamentos apropriados, se necessário, com base na versão do aplicativo e do driver.
Recuperando dados Variable-Length em partes
SQLGetData pode ser usado para recuperar dados de uma coluna que contém dados de comprimento variável em partes – ou seja, quando o identificador do tipo de dados SQL da coluna é SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY ou um identificador específico do driver para um tipo de comprimento variável.
Para recuperar dados de uma coluna em partes, o aplicativo chama SQLGetData várias vezes seguidas para a mesma coluna. Em cada chamada, SQLGetData retorna a próxima parte dos dados. Cabe ao aplicativo remontar as partes, tendo o cuidado de remover o caractere de terminação nula de partes intermediárias dos dados de caractere. Se houver mais dados para retornar ou não tiver sido alocado buffer suficiente para o caractere de terminação, SQLGetData retornará SQL_SUCCESS_WITH_INFO e SQLSTATE 01004 (Dados truncados). Quando ele retorna a última parte dos dados, SQLGetData retorna SQL_SUCCESS. Nem SQL_NO_TOTAL nem zero podem ser retornados na última chamada válida para recuperar dados de uma coluna, pois o aplicativo não teria como saber quanto dos dados no buffer de aplicativo é válido. Se SQLGetData for chamado depois disso, ele retornará SQL_NO_DATA. Para obter mais informações, confira a próxima seção, "Recuperando dados com SQLGetData".
Indicadores de comprimento variável podem ser retornados em partes por SQLGetData. Assim como acontece com outros dados, uma chamada para SQLGetData para retornar indicadores de comprimento variável em partes retornará SQLSTATE 01004 (dados de cadeia de caracteres, truncados à direita) e SQL_SUCCESS_WITH_INFO quando houver mais dados a serem retornados. Isso é diferente do caso quando um indicador de comprimento variável é truncado por uma chamada para SQLFetch ou SQLFetchScroll, que retorna SQL_ERROR e SQLSTATE 22001 (dados de cadeia de caracteres, truncados à direita).
SQLGetData não pode ser usado para retornar dados de comprimento fixo em partes. Se SQLGetData for chamado mais de uma vez em uma linha para uma coluna que contém dados de comprimento fixo, ele retornará SQL_NO_DATA para todas as chamadas após a primeira.
Recuperando parâmetros de saída transmitidos
Se um driver der suporte a parâmetros de saída transmitidos, um aplicativo poderá chamar SQLGetData com um buffer pequeno muitas vezes para recuperar um valor de parâmetro grande. Para obter mais informações sobre o parâmetro de saída transmitido, consulte Recuperando parâmetros de saída usando SQLGetData.
Recuperando dados com SQLGetData
Para retornar dados para a coluna especificada, SQLGetData executa a seguinte sequência de etapas:
Retorna SQL_NO_DATA se ele já tiver retornado todos os dados para a coluna.
Define *StrLen_or_IndPtr como SQL_NULL_DATA se os dados forem NULL. Se os dados forem NULL e StrLen_or_IndPtr for um ponteiro nulo, SQLGetData retornará SQLSTATE 22002 (variável de indicador necessária, mas não fornecida).
Se os dados da coluna não forem NULL, SQLGetData prosseguirá para a etapa 3.
Se o atributo de instrução SQL_ATTR_MAX_LENGTH estiver definido como um valor diferente de zero, se a coluna contiver dados binários ou caracteres e se SQLGetData não tiver sido chamado anteriormente para a coluna, os dados serão truncados para SQL_ATTR_MAX_LENGTH bytes.
Observação
O atributo de instrução SQL_ATTR_MAX_LENGTH destina-se a reduzir o tráfego de rede. Geralmente, ele é implementado pela fonte de dados, que trunca os dados antes de retorná-los pela rede. Drivers e fontes de dados não são necessários para dar suporte a ele. Portanto, para garantir que os dados sejam truncados para um tamanho específico, um aplicativo deve alocar um buffer desse tamanho e especificar o tamanho no argumento BufferLength .
Converte os dados no tipo especificado em TargetType. Os dados recebem a precisão e a escala padrão para esse tipo de dados. Se TargetType for SQL_ARD_TYPE, o tipo de dados no campo SQL_DESC_CONCISE_TYPE do ARD será usado. Se TargetType for SQL_ARD_TYPE, os dados receberão a precisão e a escala nos campos SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION e SQL_DESC_SCALE do ARD, dependendo do tipo de dados no campo SQL_DESC_CONCISE_TYPE. Se qualquer precisão ou escala padrão não for apropriada, o aplicativo deverá definir explicitamente o campo de descritor apropriado por uma chamada para SQLSetDescField ou SQLSetDescRec.
Se os dados foram convertidos em um tipo de dados de comprimento variável, como caractere ou binário, SQLGetData verifica se o comprimento dos dados excede BufferLength. Se o comprimento dos dados de caractere (incluindo o caractere de terminação nula) exceder BufferLength, SQLGetData truncará os dados para BufferLength menos o comprimento de um caractere de terminação nula. Em seguida, ele termina os dados em nulo. Se o comprimento dos dados binários exceder o comprimento do buffer de dados, SQLGetData o truncará em bytes BufferLength .
Se o buffer de dados fornecido for muito pequeno para conter o caractere de terminação nula, SQLGetData retornará SQL_SUCCESS_WITH_INFO e SQLSTATE 01004.
SQLGetData nunca trunca dados convertidos em tipos de dados de comprimento fixo; ele sempre pressupõe que o comprimento de *TargetValuePtr seja o tamanho do tipo de dados.
Coloca os dados convertidos (e possivelmente truncados) em *TargetValuePtr. Observe que SQLGetData não pode retornar dados fora de linha.
Coloca o comprimento dos dados em *StrLen_or_IndPtr. Se StrLen_or_IndPtr for um ponteiro nulo, SQLGetData não retornará o comprimento.
Para dados binários ou de caracteres, esse é o comprimento dos dados após a conversão e antes do truncamento devido a BufferLength. Se o driver não puder determinar o comprimento dos dados após a conversão, como às vezes é o caso com dados longos, ele retornará SQL_SUCCESS_WITH_INFO e definirá o comprimento como SQL_NO_TOTAL. (A última chamada para SQLGetData sempre deve retornar o comprimento dos dados, não zero ou SQL_NO_TOTAL.) Se os dados tiverem sido truncados devido ao atributo de instrução SQL_ATTR_MAX_LENGTH, o valor desse atributo , em vez do comprimento real, será colocado em *StrLen_or_IndPtr. Isso ocorre porque esse atributo foi projetado para truncar dados no servidor antes da conversão, portanto, o driver não tem como descobrir qual é o comprimento real. Quando SQLGetData é chamado várias vezes sucessivamente para a mesma coluna, esse é o comprimento dos dados disponíveis no início da chamada atual; ou seja, o comprimento diminui a cada chamada subsequente.
Para todos os outros tipos de dados, esse é o comprimento dos dados após a conversão; ou seja, é o tamanho do tipo no qual os dados foram convertidos.
Se os dados forem truncados sem perda de significância durante a conversão (por exemplo, o número real 1.234 é truncado quando convertido no inteiro 1) ou porque BufferLength é muito pequeno (por exemplo, a cadeia de caracteres "abcdef" é colocada em um buffer de 4 bytes), SQLGetData retorna SQLSTATE 01004 (Dados truncados) e SQL_SUCCESS_WITH_INFO. Se os dados forem truncados sem perda de significância devido ao atributo de instrução SQL_ATTR_MAX_LENGTH, SQLGetData retornará SQL_SUCCESS e não retornará SQLSTATE 01004 (Dados truncados).
O conteúdo do buffer de dados associado (se SQLGetData for chamado em uma coluna associada) e o buffer de comprimento/indicador serão indefinidos se SQLGetData não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO.
Chamadas sucessivas para SQLGetData recuperarão dados da última coluna solicitada; deslocamentos anteriores tornam-se inválidos. Por exemplo, quando a seguinte sequência é executada:
SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)
a segunda chamada para SQLGetData(icol=n) recupera dados do início da coluna n. Qualquer deslocamento nos dados devido a chamadas anteriores para SQLGetData para a coluna não é mais válido.
Descritores e SQLGetData
SQLGetData não interage diretamente com nenhum campo de descritor.
Se TargetType for SQL_ARD_TYPE, o tipo de dados no campo SQL_DESC_CONCISE_TYPE do ARD será usado. Se TargetType for SQL_ARD_TYPE ou SQL_C_DEFAULT, os dados receberão a precisão e a escala nos campos SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION e SQL_DESC_SCALE do ARD, dependendo do tipo de dados no campo SQL_DESC_CONCISE_TYPE.
Exemplo de código
No exemplo a seguir, um aplicativo executa uma instrução SELECT para retornar um conjunto de resultados das IDs, nomes e números de telefone do cliente classificados por nome, ID e número de telefone. Para cada linha de dados, ele chama SQLFetch para posicionar o cursor para a próxima linha. Ele chama SQLGetData para recuperar os dados buscados; os buffers para os dados e o número retornado de bytes são especificados na chamada para SQLGetData. Por fim, ele imprime o nome, a ID e o número de telefone de cada funcionário.
#define NAME_LEN 50
#define PHONE_LEN 50
SQLCHAR szName[NAME_LEN], szPhone[PHONE_LEN];
SQLINTEGER sCustID, cbName, cbAge, cbBirthday;
SQLRETURN retcode;
SQLHSTMT hstmt;
retcode = SQLExecDirect(hstmt,
"SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",
SQL_NTS);
if (retcode == SQL_SUCCESS) {
while (TRUE) {
retcode = SQLFetch(hstmt);
if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {
show_error();
}
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){
/* Get data for columns 1, 2, and 3 */
SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);
SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);
SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,
&cbPhone);
/* Print the row of data */
fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,
PHONE_LEN-1, szPhone);
} else {
break;
}
}
}
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Atribuindo armazenamento para uma coluna em um conjunto de resultados | SQLBindCol |
| Executando operações em massa que não estão relacionadas à posição do cursor de bloco | SQLBulkOperations |
| Cancelando o processamento da instrução | SQLCancel |
| Executando uma instrução SQL | SQLExecDirect |
| Executando uma instrução SQL preparada | SQLExecute |
| Buscar um bloco de dados ou rolar por um conjunto de resultados | SQLFetchScroll |
| Buscar uma única linha de dados ou um bloco de dados em uma direção somente encaminhamento | SQLFetch |
| Enviar dados de parâmetro no momento da execução | SQLPutData |
| Posicionando o cursor, atualizando dados no conjunto de linhas ou atualizando ou excluindo dados no conjunto de linhas | SQLSetPos |
Consulte Também
Referência de API do ODBC
Arquivos de cabeçalho ODBC
Recuperar parâmetros de saída usando SQLGetData
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