Função SQLGetData

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.

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.

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:

1. Retorna SQL_NO_DATA se já tiver retornado todos os dados da coluna.

2. 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.

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 .

4. 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.

5. 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.

6. Coloca os dados convertidos (e possivelmente truncados) em *TargetValuePtr. Observe que SQLGetData não pode retornar dados fora da linha.

7. 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.

8. 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;  
      }  
   }  
}  

Funções relacionadas

Confira também

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