Função SQLBindCol
Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: ISO 92
Resumo
SQLBindCol associa buffers de dados do aplicativo a colunas no conjunto de resultados.
Sintaxe
SQLRETURN SQLBindCol(
SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLSMALLINT TargetType,
SQLPOINTER TargetValuePtr,
SQLLEN BufferLength,
SQLLEN * StrLen_or_IndPtr);
Argumentos
StatementHandle
[Entrada] Identificador de instrução.
ColumnNumber
[Entrada] Número da coluna do conjunto de resultados a ser associada. As colunas são numeradas em ordem de coluna crescente começando em 0, em que a coluna 0 é a coluna de indicador. Se os indicadores não forem usados – ou seja, o atributo de instrução SQL_ATTR_USE_BOOKMARKS será definido como SQL_UB_OFF – os números de coluna começarão em 1.
TargetType
[Entrada] O identificador do tipo de dados C do buffer *TargetValuePtr . Quando ele está recuperando dados da fonte de dados com SQLFetch, SQLFetchScroll, SQLBulkOperations ou SQLSetPos, o driver converte os dados nesse tipo; quando ele envia dados para a fonte de dados com SQLBulkOperations ou SQLSetPos, o driver converte os dados desse tipo. 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 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 do ARD, respectivamente, serão usados para os dados. Se o argumento TargetType for 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 descritor apropriado por uma chamada para SQLSetDescField ou SQLSetDescRec.
Você também pode especificar um tipo de dados C estendido. Para obter mais informações, consulte Tipos de dados C em ODBC.
TargetValuePtr
[Entrada/saída adiada] Ponteiro para o buffer de dados a ser associado à coluna. SQLFetch e SQLFetchScroll retornam dados nesse buffer. SQLBulkOperations retorna dados nesse buffer quando a Operação é SQL_FETCH_BY_BOOKMARK; ele recupera dados desse buffer quando a Operação é SQL_ADD ou SQL_UPDATE_BY_BOOKMARK. SQLSetPos retorna dados nesse buffer quando a Operação é SQL_REFRESH; ele recupera dados desse buffer quando a Operação é SQL_UPDATE.
Se TargetValuePtr for um ponteiro nulo, o driver desvinculou o buffer de dados da coluna. Um aplicativo pode desassociar todas as colunas chamando SQLFreeStmt com a opção SQL_UNBIND. Um aplicativo pode desassociar o buffer de dados de uma coluna, mas ainda ter um buffer de comprimento/indicador associado à coluna, se o argumento TargetValuePtr na chamada para SQLBindCol for um ponteiro nulo, mas o argumento StrLen_or_IndPtr for um valor válido.
BufferLength
[Entrada] Comprimento do buffer *TargetValuePtr em bytes.
O driver usa BufferLength para evitar gravar após o final do buffer *TargetValuePtr quando retorna dados de comprimento variável, como dados binários ou caracteres. Observe que o driver conta o caractere de terminação nula quando retorna 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 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.
SQLBindCol retorna SQLSTATE HY090 (comprimento de buffer ou cadeia de caracteres inválida) quando BufferLength é menor que 0, mas não quando BufferLength é 0. No entanto, se TargetType especificar um tipo de caractere, um aplicativo não deverá definir BufferLength como 0, pois os drivers em conformidade com a CLI ISO retornam SQLSTATE HY090 (comprimento de buffer ou cadeia de caracteres inválida) nesse caso.
Strlen_or_indptr
[Entrada/saída adiada] Ponteiro para o buffer de comprimento/indicador a ser associado à coluna. SQLFetch e SQLFetchScroll retornam um valor nesse buffer. SQLBulkOperations recupera um valor desse buffer quando a Operação é SQL_ADD, SQL_UPDATE_BY_BOOKMARK ou SQL_DELETE_BY_BOOKMARK. SQLBulkOperations retorna um valor nesse buffer quando a Operação é SQL_FETCH_BY_BOOKMARK. SQLSetPos retorna um valor nesse buffer quando a Operação é SQL_REFRESH; ele recupera um valor desse buffer quando a Operação é SQL_UPDATE.
SQLFetch, SQLFetchScroll, SQLBulkOperations e SQLSetPos podem retornar os seguintes valores no buffer de comprimento/indicador:
O comprimento dos dados disponíveis para retornar
SQL_NO_TOTAL
SQL_NULL_DATA
O aplicativo pode colocar os seguintes valores no buffer de comprimento/indicador para uso com SQLBulkOperations ou SQLSetPos:
O comprimento dos dados que estão sendo enviados
SQL_NTS
SQL_NULL_DATA
SQL_DATA_AT_EXEC
O resultado da macro SQL_LEN_DATA_AT_EXEC
SQL_COLUMN_IGNORE
Se o buffer indicador e o buffer de comprimento forem buffers separados, o buffer de indicador poderá retornar apenas SQL_NULL_DATA, enquanto o buffer de comprimento poderá retornar todos os outros valores.
Para obter mais informações, consulte Função SQLBulkOperations, Função SQLFetch, Função SQLSetPos e Usando valores de comprimento/indicador.
Se StrLen_or_IndPtr for um ponteiro nulo, nenhum valor de indicador ou comprimento será usado. Esse é um erro ao buscar dados e os dados são NULL.
Consulte Informações do ODBC de 64 bits, se o aplicativo será executado em um sistema operacional de 64 bits.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLBindCol 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 SQLBindCol e explica cada um 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.) |
| 07006 | Violação de atributo de tipo de dados restrito | (DM) O argumento ColumnNumber era 0 e o argumento TargetType não era SQL_C_BOOKMARK ou SQL_C_VARBOOKMARK. |
| 07009 | Índice de descritor inválido | O valor especificado para o argumento ColumnNumber excedeu o número máximo de colunas no 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 memória necessária para dar suporte à execução ou à conclusão da função. |
| HY003 | Tipo de buffer de aplicativo inválido | O argumento TargetType não era um tipo de dados válido nem SQL_C_DEFAULT. |
| HY010 | Erro de sequência de funções | (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 SQLBindCol foi chamado. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornou SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. (DM) Uma função de execução assíncrona foi chamada para o StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para o StatementHandle e retornaram 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. |
| 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álida | (DM) O valor especificado para o argumento BufferLength foi menor que 0. (DM) O driver era um ODBC 2. x driver, o argumento ColumnNumber foi definido como 0 e o valor especificado para o argumento BufferLength não era igual a 4. |
| HY117 | A conexão é suspensa devido ao estado de transação desconhecido. 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 à conversão especificada pela combinação do argumento TargetType e do tipo de dados SQL específico do driver da coluna correspondente. O argumento ColumnNumber era 0 e o driver não dá suporte a indicadores. 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 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 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 associado ao StatementHandle não dá suporte à função. |
Comentários
SQLBindCol é usado para associar ou associar colunas no conjunto de resultados para buffers de dados e buffers de comprimento/indicador no aplicativo. Quando o aplicativo chama SQLFetch, SQLFetchScroll ou SQLSetPos para buscar dados, o driver retorna os dados das colunas associadas nos buffers especificados; para obter mais informações, consulte Função SQLFetch. Quando o aplicativo chama SQLBulkOperations para atualizar ou inserir uma linha ou SQLSetPos para atualizar uma linha, o driver recupera os dados das colunas associadas dos buffers especificados; para obter mais informações, consulte Função SQLBulkOperations ou Função SQLSetPos. Para obter mais informações sobre associação, consulte Recuperando resultados (básico).
Observe que as colunas não precisam ser associadas para recuperar dados delas. Um aplicativo também pode chamar SQLGetData para recuperar dados de colunas. Embora seja possível associar algumas colunas em uma linha e chamar SQLGetData para outras, isso está sujeito a algumas restrições. Para obter mais informações, consulte SQLGetData.
Associação, desassociação e vinculação de colunas
Uma coluna pode ser associada, desvinculada ou repercutida a qualquer momento, mesmo depois que os dados forem obtidos do conjunto de resultados. A nova associação entrará em vigor na próxima vez que uma função que usa associações for chamada. Por exemplo, suponha que um aplicativo associe as colunas em um conjunto de resultados e chame SQLFetch. O driver retorna os dados nos buffers associados. Agora suponha que o aplicativo associe as colunas a um conjunto diferente de buffers. O driver não coloca os dados para a linha recém-buscada nos buffers recém-associados. Em vez disso, ele aguarda até que SQLFetch seja chamado novamente e coloque os dados para a próxima linha nos buffers recém-associados.
Observação
O atributo de instrução SQL_ATTR_USE_BOOKMARKS deve ser sempre definido antes de associar uma coluna à coluna 0. Isso não é necessário, mas é altamente recomendado.
Colunas de associação
Para associar uma coluna, um aplicativo chama SQLBindCol e passa o número da coluna, o tipo, o endereço e o comprimento de um buffer de dados e o endereço de um buffer de comprimento/indicador. Para obter informações sobre como esses endereços são usados, consulte "Endereços de buffer", mais adiante nesta seção. Para obter mais informações sobre colunas de associação, consulte Usando SQLBindCol.
O uso desses buffers é adiado; ou seja, o aplicativo os associa no SQLBindCol , mas o driver os acessa de outras funções : ou seja, SQLBulkOperations, SQLFetch, SQLFetchScroll ou SQLSetPos. É responsabilidade do aplicativo garantir que os ponteiros especificados em SQLBindCol permaneçam válidos enquanto a associação permanecer em vigor. Se o aplicativo permitir que esses ponteiros se tornem inválidos - por exemplo, ele libera um buffer - e, em seguida, chama uma função que espera que eles sejam válidos, as consequências são indefinidas. Para obter mais informações, consulte Buffers adiados.
A associação permanece em vigor até ser substituída por uma nova associação, a coluna não for associada ou a instrução for liberada.
Desassociando colunas
Para desassociar uma única coluna, um aplicativo chama SQLBindCol com ColumnNumber definido como o número dessa coluna e TargetValuePtr definido como um ponteiro nulo. Se ColumnNumber se referir a uma coluna não associada, SQLBindCol ainda retornará SQL_SUCCESS.
Para desassociar todas as colunas, um aplicativo chama SQLFreeStmt com fOption definido como SQL_UNBIND. Isso também pode ser feito definindo o campo SQL_DESC_COUNT do ARD como zero.
Reassociando colunas
Um aplicativo pode executar uma das duas operações para alterar uma associação:
Chame SQLBindCol para especificar uma nova associação para uma coluna que já esteja associada. O driver substitui a associação antiga com a nova.
Especifique um deslocamento a ser adicionado ao endereço de buffer especificado pela chamada de associação para SQLBindCol. Para obter mais informações, consulte a próxima seção, "Deslocamentos de associação".
Deslocamentos de associação
Um deslocamento de associação é um valor que é adicionado aos endereços dos buffers de dados e comprimento/indicador (conforme especificado no argumento TargetValuePtr e StrLen_or_IndPtr ) antes de serem desreferenciados. Quando os deslocamentos são usados, as associações são um "modelo" de como os buffers do aplicativo são dispostos e o aplicativo pode mover esse "modelo" para diferentes áreas de memória alterando o deslocamento. Como o mesmo deslocamento é adicionado a cada endereço em cada associação, os deslocamentos relativos entre buffers para colunas diferentes devem ser os mesmos em cada conjunto de buffers. Isso sempre é verdadeiro quando a associação em linha é usada; o aplicativo deve definir cuidadosamente seus buffers para que isso seja verdadeiro quando a associação em termos de coluna for usada.
O uso de um deslocamento de associação tem basicamente o mesmo efeito que reassociar uma coluna chamando SQLBindCol. A diferença é que uma nova chamada para SQLBindCol especifica novos endereços para o buffer de dados e o buffer de comprimento/indicador, enquanto o uso de um deslocamento de associação não altera os endereços, mas apenas adiciona um deslocamento a eles. O aplicativo pode especificar um novo deslocamento sempre que quiser, e esse deslocamento sempre é adicionado aos endereços associados originalmente. Em particular, se o deslocamento for definido como 0 ou se o atributo de instrução estiver definido como um ponteiro nulo, o driver usará os endereços originalmente associados.
Para especificar um deslocamento de associação, o aplicativo define o atributo de instrução SQL_ATTR_ROW_BIND_OFFSET_PTR para o endereço de um buffer SQLINTEGER. Antes que o aplicativo chame uma função que usa associações, ele coloca um deslocamento em bytes nesse buffer. Para determinar o endereço do buffer a ser usado, o driver adiciona o deslocamento ao endereço na associação. A soma do endereço e do deslocamento deve ser um endereço válido, mas o endereço ao qual o deslocamento é adicionado não precisa ser válido. Para obter mais informações sobre como os deslocamentos de associação são usados, consulte "Endereços de buffer", mais adiante nesta seção.
Matrizes de associação
Se o tamanho do conjunto de linhas (o valor do atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE) for maior que 1, o aplicativo associará matrizes de buffers em vez de buffers únicos. Para obter mais informações, consulte Bloquear cursores.
O aplicativo pode associar matrizes de duas maneiras:
Associe uma matriz a cada coluna. Isso é chamado de associação em termos de coluna porque cada estrutura de dados (matriz) contém dados para uma única coluna.
Defina uma estrutura para manter os dados de uma linha inteira e associar uma matriz dessas estruturas. Isso é chamado de associação em linha porque cada estrutura de dados contém os dados de uma única linha.
Cada matriz de buffers deve ter pelo menos tantos elementos quanto o tamanho do conjunto de linhas.
Observação
Um aplicativo deve verificar se o alinhamento é válido. Para obter mais informações sobre considerações de alinhamento, consulte Alinhamento.
Associação de coluna
Na associação em termos de coluna, o aplicativo associa matrizes separadas de dados e comprimento/indicador a cada coluna.
Para usar a associação em termos de coluna, o aplicativo primeiro define o atributo de instrução SQL_ATTR_ROW_BIND_TYPE como SQL_BIND_BY_COLUMN. (Esse é o padrão.) Para que cada coluna seja associada, o aplicativo executa as seguintes etapas:
Aloca uma matriz de buffer de dados.
Aloca uma matriz de buffers de comprimento/indicador.
Observação
Se o aplicativo gravar diretamente em descritores quando a associação em termos de coluna for usada, matrizes separadas poderão ser usadas para dados de comprimento e indicador.
Chama SQLBindCol com os seguintes argumentos:
TargetType é o tipo de um único elemento na matriz de buffer de dados.
TargetValuePtr é o endereço da matriz de buffer de dados.
BufferLength é o tamanho de um único elemento na matriz de buffer de dados. O argumento BufferLength é ignorado quando os dados são dados de comprimento fixo.
StrLen_or_IndPtr é o endereço da matriz de comprimento/indicador.
Para obter mais informações sobre como essas informações são usadas, consulte "Endereços de buffer", mais adiante nesta seção. Para obter mais informações sobre a associação em termos de coluna, consulte Associação em termos de coluna.
Associação de linha
Na associação em linha, o aplicativo define uma estrutura que contém dados e buffers de comprimento/indicador para cada coluna a ser associada.
Para usar a associação em linha, o aplicativo executa as seguintes etapas:
Define uma estrutura para manter uma única linha de dados (incluindo buffers de dados e comprimento/indicador) e aloca uma matriz dessas estruturas.
Observação
Se o aplicativo gravar diretamente em descritores quando a associação em linha for usada, campos separados poderão ser usados para dados de comprimento e indicador.
Define o atributo de instrução SQL_ATTR_ROW_BIND_TYPE para o tamanho da estrutura que contém uma única linha de dados ou para o tamanho de uma instância de um buffer no qual as colunas de resultados serão associadas. O comprimento deve incluir espaço para todas as colunas associadas e qualquer preenchimento da estrutura ou buffer para garantir que, quando o endereço de uma coluna associada for incrementado com o comprimento especificado, o resultado apontará para o início da mesma coluna na próxima linha. Ao usar o operador sizeof no ANSI C, esse comportamento é garantido.
Chama SQLBindCol com os seguintes argumentos para cada coluna a ser associada:
TargetType é o tipo do membro do buffer de dados a ser associado à coluna.
TargetValuePtr é o endereço do membro do buffer de dados no primeiro elemento de matriz.
BufferLength é o tamanho do membro do buffer de dados.
StrLen_or_IndPtr é o endereço do membro de comprimento/indicador a ser associado.
Para obter mais informações sobre como essas informações são usadas, consulte "Endereços de buffer", mais adiante nesta seção. Para obter mais informações sobre a associação em termos de coluna, consulte Associação em termos de linha.
Endereços de buffer
O endereço do buffer é o endereço real dos dados ou do buffer de comprimento/indicador. O driver calcula o endereço do buffer pouco antes de gravar nos buffers (como durante o tempo de busca). Ele é calculado a partir da fórmula a seguir, que usa os endereços especificados nos argumentos TargetValuePtr e StrLen_or_IndPtr , o deslocamento de associação e o número da linha:
Endereço + Associado Deslocamento de associação + ((Número da Linha – 1) x Tamanho do Elemento)
em que as variáveis da fórmula são definidas conforme descrito na tabela a seguir.
| Variável | Descrição |
|---|---|
| Endereço Associado | Para buffers de dados, o endereço especificado com o argumento TargetValuePtr em SQLBindCol. Para buffers de comprimento/indicador, o endereço especificado com o argumento StrLen_or_IndPtr em SQLBindCol. Para obter mais informações, consulte "Comentários adicionais" na seção "Descritores e SQLBindCol". Se o endereço associado for 0, nenhum valor de dados será retornado, mesmo que o endereço calculado pela fórmula anterior seja diferente de zero. |
| Deslocamento de associação | Se a associação em linha for usada, o valor armazenado no endereço especificado com o atributo de instrução SQL_ATTR_ROW_BIND_OFFSET_PTR. Se a associação em termos de coluna for usada ou se o valor do atributo de instrução SQL_ATTR_ROW_BIND_OFFSET_PTR for um ponteiro nulo, Binding Offset será 0. |
| Row Number | O número baseado em 1 da linha no conjunto de linhas. Para buscas de linha única, que são o padrão, isso é 1. |
| Tamanho do elemento | O tamanho de um elemento na matriz associada. Se a associação em termos de coluna for usada, isso será sizeof (SQLINTEGER) para buffers de comprimento/indicador. Para buffers de dados, ele será o valor do argumento BufferLength em SQLBindCol se o tipo de dados for de comprimento variável e o tamanho do tipo de dados se o tipo de dados for de comprimento fixo. Se a associação em linha for usada, esse será o valor do atributo de instrução SQL_ATTR_ROW_BIND_TYPE para buffers de dados e comprimento/indicador. |
Descritores e SQLBindCol
As seções a seguir descrevem como o SQLBindCol interage com descritores.
Cuidado
Chamar SQLBindCol para uma instrução pode afetar outras instruções. Isso ocorre quando o ARD associado à instrução é explicitamente alocado e também está associado a outras instruções. Como SQLBindCol modifica o descritor, as modificações se aplicam a todas as instruções às quais esse descritor está associado. Se esse não for o comportamento necessário, o aplicativo deverá dissociar esse descritor das outras instruções antes de chamar SQLBindCol.
Mapeamentos de argumentos
Conceitualmente, SQLBindCol executa as seguintes etapas na sequência:
Chama SQLGetStmtAttr para obter o identificador ARD.
Chama SQLGetDescField para obter o campo SQL_DESC_COUNT desse descritor e, se o valor no argumento ColumnNumber exceder o valor de SQL_DESC_COUNT, chama SQLSetDescField para aumentar o valor de SQL_DESC_COUNT para ColumnNumber.
Chama SQLSetDescField várias vezes para atribuir valores aos seguintes campos do ARD:
Define SQL_DESC_TYPE e SQL_DESC_CONCISE_TYPE com o valor de TargetType, exceto que, se TargetType for um dos identificadores concisos de um subtipo datetime ou interval, ele define SQL_DESC_TYPE como SQL_DATETIME ou SQL_INTERVAL, respectivamente; define SQL_DESC_CONCISE_TYPE para o identificador conciso; e define SQL_DESC_DATETIME_INTERVAL_CODE para o subcódigo datetime ou intervalo correspondente.
Define uma ou mais SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE e SQL_DESC_DATETIME_INTERVAL_PRECISION, conforme apropriado para TargetType.
Define o campo SQL_DESC_OCTET_LENGTH como o valor de BufferLength.
Define o campo SQL_DESC_DATA_PTR como o valor de TargetValuePtr.
Define o campo SQL_DESC_INDICATOR_PTR como o valor de StrLen_or_IndPtr. (Consulte o parágrafo a seguir.)
Define o campo SQL_DESC_OCTET_LENGTH_PTR como o valor de StrLen_or_IndPtr. (Consulte o parágrafo a seguir.)
A variável à qual o argumento StrLen_or_IndPtr se refere é usada para informações de indicador e comprimento. Se um fetch encontrar um valor nulo para a coluna, ele armazenará SQL_NULL_DATA nessa variável; caso contrário, ele armazena o comprimento dos dados nessa variável. Passar um ponteiro nulo como StrLen_or_IndPtr impede que a operação de busca retorne o comprimento dos dados, mas faz com que a busca falhe se encontrar um valor nulo e não tiver como retornar SQL_NULL_DATA.
Se a chamada para SQLBindCol falhar, o conteúdo dos campos do descritor definidos no ARD será indefinido e o valor do campo SQL_DESC_COUNT do ARD permanecerá inalterado.
Redefinição implícita do campo COUNT
SQLBindCol define SQL_DESC_COUNT para o valor do argumento ColumnNumber somente quando isso aumentaria o valor de SQL_DESC_COUNT. Se o valor no argumento TargetValuePtr for um ponteiro nulo e o valor no argumento ColumnNumber for igual a SQL_DESC_COUNT (ou seja, ao desassociar a coluna associada mais alta), SQL_DESC_COUNT será definido como o número da coluna associada restante mais alta.
Cuidado com relação a SQL_DEFAULT
Para recuperar dados de coluna com êxito, o aplicativo deve determinar corretamente o comprimento e o ponto de partida dos dados no buffer do aplicativo. Quando o aplicativo especifica um TargetType explícito, os equívocos do aplicativo são facilmente detectados. No entanto, quando o aplicativo especifica um TargetType de SQL_DEFAULT, SQLBindCol pode ser aplicado a uma coluna de um tipo de dados diferente do pretendido pelo aplicativo, seja de alterações aos metadados ou aplicando o código a uma coluna diferente. Nesse caso, o aplicativo nem sempre pode determinar o início ou o comprimento dos dados de coluna buscados. Isso pode levar a erros de dados não relatados ou violações de memória.
Exemplo de código
No exemplo a seguir, um aplicativo executa uma instrução SELECT na tabela Clientes para retornar um conjunto de resultados das IDs, nomes e números de telefone do cliente, classificados por nome. Em seguida, ele chama SQLBindCol para associar as colunas de dados a buffers locais. Por fim, o aplicativo busca cada linha de dados com SQLFetch e imprime o nome, a ID e o número de telefone de cada cliente.
Para obter mais exemplos de código, consulte Função SQLBulkOperations, Função SQLColumns, Função SQLFetchScroll e Função SQLSetPos.
// SQLBindCol_ref.cpp
// compile with: odbc32.lib
#include <windows.h>
#include <stdio.h>
#define UNICODE
#include <sqlext.h>
#define NAME_LEN 50
#define PHONE_LEN 60
void show_error() {
printf("error\n");
}
int main() {
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt = 0;
SQLRETURN retcode;
SQLWCHAR szName[NAME_LEN], szPhone[PHONE_LEN], sCustID[NAME_LEN];
SQLLEN cbName = 0, cbCustID = 0, cbPhone = 0;
// Allocate environment handle
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
// Set the ODBC version environment attribute
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
// Allocate connection handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
// Set login timeout to 5 seconds
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
// Connect to data source
retcode = SQLConnect(hdbc, (SQLWCHAR*) L"NorthWind", SQL_NTS, (SQLWCHAR*) NULL, 0, NULL, 0);
// Allocate statement handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
retcode = SQLExecDirect(hstmt, (SQLWCHAR *) L"SELECT CustomerID, ContactName, Phone FROM CUSTOMERS ORDER BY 2, 1, 3", SQL_NTS);
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
// Bind columns 1, 2, and 3
retcode = SQLBindCol(hstmt, 1, SQL_C_WCHAR, &sCustID, 100, &cbCustID);
retcode = SQLBindCol(hstmt, 2, SQL_C_WCHAR, szName, NAME_LEN, &cbName);
retcode = SQLBindCol(hstmt, 3, SQL_C_WCHAR, szPhone, PHONE_LEN, &cbPhone);
// Fetch and print each row of data. On an error, display a message and exit.
for (int i=0 ; ; i++) {
retcode = SQLFetch(hstmt);
if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO)
show_error();
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)
{
//replace wprintf with printf
//%S with %ls
//warning C4477: 'wprintf' : format string '%S' requires an argument of type 'char *'
//but variadic argument 2 has type 'SQLWCHAR *'
//wprintf(L"%d: %S %S %S\n", i + 1, sCustID, szName, szPhone);
printf("%d: %ls %ls %ls\n", i + 1, sCustID, szName, szPhone);
}
else
break;
}
}
// Process data
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLCancel(hstmt);
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
}
SQLDisconnect(hdbc);
}
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
}
}
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
}
Confira também Exemplo de Programa ODBC.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Retornando informações sobre uma coluna em um conjunto de resultados | Função SQLDescribeCol |
| Buscar um bloco de dados ou rolar por um conjunto de resultados | Função SQLFetchScroll |
| Buscar várias linhas de dados | Função SQLFetch |
| Liberando buffers de coluna na instrução | Função SQLFreeStmt |
| Buscar parte ou todas as colunas de dados | Função SQLGetData |
| Retornando o número de colunas do conjunto de resultados | Função SQLNumResultCols |