Função SQLGetData

Conformidade
Versão introduzida: Conformidade com as normas 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 os dados devem ser retornados. As colunas do conjunto de resultados são numeradas em ordem crescente de colunas a partir de 1. A coluna de marcador é a coluna número 0; Isso só pode ser especificado se os favoritos estiverem habilitados.

Para recuperar dados de parâmetros, é o ordinal do parâmetro, que começa em 1.

TargetType
[Entrada] O identificador de tipo do tipo de dados C do buffer de *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 estiver SQL_ARD_TYPE, o driver usará o identificador de tipo especificado no campo SQL_DESC_CONCISE_TYPE da ARD. Se TargetType estiver 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 substitui o tipo de dados C especificado em SQLBindParameter. Se for SQL_C_DEFAULT, o driver seleciona o tipo de dados C padrão com base no tipo de dados SQL da fonte.

Você também pode especificar um tipo de dados C estendido. Para obter mais informações, consulte Tipos de dados C no ODBC.

TargetValuePtr
[Realização] Ponteiro para o buffer no qual retornar os dados.

TargetValuePtr não pode ser NULL.

BufferLength
[Entrada] Comprimento do buffer de *TargetValuePtr em bytes.

O driver usa BufferLength para evitar gravar após o final do buffer de 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 armazenar os dados. Portanto, é importante para o aplicativo alocar um buffer grande o suficiente para dados de comprimento fixo ou o driver irá gravar após o final do buffer.

SQLGetData retorna SQLSTATE HY090 (cadeia de caracteres inválida ou comprimento do buffer) quando BufferLength é menor que 0, mas não quando BufferLength é 0.

StrLen_or_IndPtr
[Realização] 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:

• A extensão dos dados disponíveis para retorno

• 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óstico

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 normalmente retornados por SQLGetData e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornados pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

Observações

SQLGetData retorna os dados em uma coluna especificada. SQLGetData pode ser chamado somente depois que uma ou mais linhas foram buscadas no conjunto de resultados por SQLFetch, SQLFetchScrollou 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 vincular 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 oferecer suporte a extensões para SQLGetData, a função poderá retornar dados somente para colunas não acopladas com um número maior que o da última coluna acoplada. 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 crescente de número de colunas. Finalmente, se nenhuma extensão for suportada, 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âmetros 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 chamada para qualquer coluna não acoplada, incluindo aquelas antes da última coluna acoplada.

• SQL_GD_ANY_ORDER. Se essa opção for retornada, SQLGetData poderá ser chamada para colunas não acopladas em qualquer ordem.

• SQL_GD_BLOCK. Se essa opção for retornada por SQLGetInfo para o SQL_GETDATA_EXTENSIONS InfoType, o driver suporta chamadas para SQLGetData quando o tamanho do conjunto de linhas é maior que 1 e o aplicativo pode 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 chamada para colunas acopladas, bem como colunas não acopladas.

Há duas exceções a essas restrições e a capacidade do motorista de relaxá-las. Primeiro, SQLGetData nunca deve ser chamado para um cursor somente para frente quando o tamanho do conjunto de linhas for maior que 1. Em segundo lugar, se um driver oferecer suporte a marcadores, ele sempre deverá oferecer 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 acoplada. (Quando um aplicativo está trabalhando com um driver ODBC 2*.x*, SQLGetData retornará com êxito um marcador 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 um FetchOrientation de SQL_FETCH_NEXT, e SQLGetData com uma Col_or_Param_Num de 0 é mapeada 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, porque o cursor não está posicionado na linha. Um aplicativo pode recuperar o indicador para tal linha vinculando a coluna 0 antes de chamar SQLBulkOperations com SQL_ADD, caso em que SQLBulkOperations retorna o indicador no buffer acoplado. 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, a precisão à esquerda do 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 da 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 da ARD, serão usadas para os dados. Se qualquer precisão ou escala padrão não for apropriada, o aplicativo deve definir explicitamente o campo descritor apropriado por uma chamada para SQLSetDescField ou SQLSetDescRec. Ele pode definir o campo SQL_DESC_CONCISE_TYPE para 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 descritor sejam usados.

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 sucessivas para a mesma coluna. Em cada chamada, SQLGetData retorna a próxima parte dos dados. Cabe ao aplicativo remontar as partes, tomando o cuidado de remover o caractere de terminação nula das partes intermediárias dos dados de caracteres. 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 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, porque 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".

Os marcadores de comprimento variável podem ser retornados em partes pelo SQLGetData. Como acontece com outros dados, uma chamada para SQLGetData para retornar marcadores de comprimento variável em partes retornará SQLSTATE 01004 (String data, truncado à 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 contendo 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 suporta parâmetros de saída transmitidos, um aplicativo pode 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:

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

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 chamada 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 suportá-lo. 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 estiver SQL_ARD_TYPE, o tipo de dados no campo SQL_DESC_CONCISE_TYPE da 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 da 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 deve 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 caracteres (incluindo o caractere de terminação nula) exceder BufferLength , SQLGetData truncará os dados para BufferLength menos o comprimento de um caractere de terminação nulo. Em seguida, ele termina nulo os dados. Se o comprimento dos dados binários exceder o comprimento do buffer de dados, SQLGetData truncará para BufferLength bytes.

   Se o buffer de dados fornecido for muito pequeno para manter 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 assume 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 de 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 de caracteres ou binários, este é 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 retorna SQL_SUCCESS_WITH_INFO e define o comprimento para 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 é projetado para truncar dados no servidor antes da conversão, de modo que o driver não tem como descobrir qual é o comprimento real. Quando SQLGetData é chamado várias vezes consecutivas 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, este é 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 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 acoplado (se SQLGetData for chamado em uma coluna acoplada) 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; as compensações anteriores tornam-se inválidas. 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 estiver SQL_ARD_TYPE, o tipo de dados no campo SQL_DESC_CONCISE_TYPE da 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 da 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, 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. Finalmente, imprime o nome, ID e 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

Ver também

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