Função SQLGetData

Artigo
05/23/2023

Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: 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

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

Col_or_Param_Num
[Entrada] Para recuperar dados de coluna, é o número da coluna para a qual os dados serão retornados. As colunas do conjunto de resultados são numeradas em ordem crescente de colunas, começando em 1. A coluna de indicador é a coluna número 0; Isso só pode ser especificado se os indicadores estiverem ativados.

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 a gravação após o final do buffer *TargetValuePtr ao retornar dados de comprimento variável, como caracteres ou dados binários. 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 assume que o buffer é grande o suficiente para conter 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 (cadeia de caracteres ou comprimento de buffer 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 este 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.

Devoluções

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 Handle de StatementHandle. A tabela a seguir lista os valores SQLSTATE comumente 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 de outra forma.

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, puderam 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, consulte "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 de tempo, carimbo de data/hora e intervalo contendo 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 era 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 acoplada. 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 em SQLGetInfo. (DM) O número da coluna especificada era menor ou igual ao número da coluna de limite mais alto. 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 em SQLGetInfo. (DM) O aplicativo já chamou SQLGetData para a linha atual; o número da coluna especificada na chamada atual era 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 em 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 foi 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 estava conectado falhou antes que a função concluísse o processamento.
22002	Variável indicadora 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 oposição à fracionária) do número fosse truncada. Para obter mais informações, consulte o Apêndice D: Tipos de dados.
22007	Formato de data e hora 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álidos, respectivamente. Para obter mais informações, consulte o Apêndice D: Tipos de dados.
22012	Divisão por zero	Um valor de uma expressão aritmética que resultou na divisão por zero foi retornado.
22015	Estouro de campo de intervalo	A atribuição de um tipo SQL numérico ou de intervalo exato a um tipo C de intervalo causou uma perda de dígitos significativos no campo principal. Ao retornar dados para um tipo C de intervalo, não houve representação do valor do tipo SQL no tipo C de intervalo.
22018	Valor de caractere inválido para especificação de conversão	Uma coluna de caracteres no conjunto de resultados foi retornada a um buffer de caracteres C 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 tipo de dados numérico exato ou aproximado, uma data/hora 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 estava associado ao StatementHandle. Um cursor estava aberto no StatementHandle e SQLFetch ou SQLFetchScroll havia sido chamado, mas o cursor estava 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 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 (no caso de recuperação de dados de coluna) ou SQL_APD_TYPE (no 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 o 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ção	(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 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 SQLGetData foi chamada. (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. (DM) O StatementHandle estava em um estado executado, mas nenhum conjunto de resultados estava 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	Cadeia de caracteres ou comprimento de buffer 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 havia sido 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 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.
HYC00	Recurso opcional não implementado	O driver ou a fonte de dados não dá suporte ao uso de SQLGetData com várias linhas em 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 em 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 a 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 de intervalo C listados em Tipos de Dados C no Apêndice D: Tipos de Dados. O driver só dá suporte 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 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 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), 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, em 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 crescente de número de coluna. 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 acopladas em qualquer ordem.
SQL_GD_BLOCK. Se essa opção for retornada por SQLGetInfo para o InfoType SQL_GETDATA_EXTENSIONS, o driver dará suporte a chamadas para SQLGetData quando o tamanho do conjunto de linhas for maior que 1 e o aplicativo poderá 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 acopladas, bem como colunas não acopladas.

Existem duas exceções a essas restrições e à capacidade do 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 está trabalhando com um driver ODBC 2*.x*, SQLGetData retornará com êxito um indicador quando chamado com Col_or_Param_Num igual a 0 após uma chamada para SQLFetch, pois SQLFetch é mapeado pelo Gerenciador de Driver ODBC 3*.x* para SQLExtendedFetch com um 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 recém-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, caso em que SQLBulkOperations retorna o indicador no buffer associado. SQLFetchScroll pode então ser chamado com SQL_FETCH_BOOKMARK para reposicionar o cursor nessa linha.

Se o argumento TargetType for um tipo de dados de intervalo, a precisão de entrelinha de intervalo padrão (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 usadas 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 usadas para os dados. Se qualquer precisão ou escala padrão não for apropriada, o aplicativo deverá definir explicitamente o campo 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 de 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 no aplicativo e na versão do driver.

Recuperação de dados de comprimento variável em peças

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 sucessivas para a mesma coluna. Em cada chamada, SQLGetData retorna a próxima parte dos dados. Cabe ao aplicativo remontar as partes, tomando cuidado para remover o caractere de terminação nula das partes intermediárias dos dados de caracteres. Se houver mais dados a serem retornados ou não houver buffer suficiente alocado 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 do aplicativo é válido. Se SQLGetData for chamado depois disso, ele retornará SQL_NO_DATA. Para obter mais informações, consulte 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 várias 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 já tiver retornado todos os dados da 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 indicadora 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 for definido como um valor diferente de zero, se a coluna contiver caracteres ou dados binários 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 é 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 para o 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 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 encerra os dados em nulo. Se o comprimento dos dados binários exceder o comprimento do buffer de dados, SQLGetData os truncará para 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 é o tamanho do tipo de dados.
Coloca os dados convertidos (e possivelmente truncados) em *TargetValuePtr. Observe que SQLGetData não pode retornar dados fora da linha.
Coloca o comprimento dos dados em *StrLen_or_IndPtr. Se StrLen_or_IndPtr era 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 foram truncados devido ao atributo de instrução SQL_ATTR_MAX_LENGTH, o valor desse atributo - em oposição ao comprimento real - é 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 com 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 para o 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 para o inteiro 1) ou porque BufferLength é muito pequeno (por exemplo, a cadeia de caracteres "abcdef" é colocada em um buffer de 4 bytes), SQLGetData retornará 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 se tornarão 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 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 de IDs de cliente, nomes e números de telefone classificados por nome, ID e número de telefone. Para cada linha de dados, ele chama SQLFetch para posicionar o cursor na 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, imprime o nome, o documento de identidade 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;  
      }  
   }  
}

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 se relacionam com a posição do cursor de bloco	SQLBulkOperations
Cancelando o processamento de instruções	SQLCancel
Executando uma instrução SQL	SQLExecDirect
Executando uma instrução SQL preparada	SQLExecute
Buscando um bloco de dados ou rolando por um conjunto de resultados	SQLFetchScroll
Buscando uma única linha de dados ou um bloco de dados em uma direção somente para frente	SQLFetch
Enviando dados de parâmetro em tempo de execução	SQLPutData
Posicionar o cursor, atualizar dados no conjunto de linhas ou atualizar ou excluir dados no conjunto de linhas	SQLSetPos

Confira também

Referência de API do ODBC
Arquivos de cabeçalho ODBC
Recuperando parâmetros de saída usando SQLGetData

Compartilhar via

Função SQLGetData

Sintaxe

Argumentos

Devoluções

Diagnósticos

Comentários

Usando SQLGetData

Recuperação de dados de comprimento variável em peças

Recuperando parâmetros de saída transmitidos

Recuperando dados com SQLGetData

Descritores e SQLGetData

Exemplo de código

Confira também

Comentários

Recursos adicionais

Compartilhar via

Função SQLGetData

Sintaxe

Argumentos

Devoluções

Diagnósticos

Comentários

Usando SQLGetData

Recuperação de dados de comprimento variável em peças

Recuperando parâmetros de saída transmitidos

Recuperando dados com SQLGetData

Descritores e SQLGetData

Exemplo de código

Funções relacionadas

Confira também

Comentários

Recursos adicionais