Função SQLDescribeParam
Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ODBC
Resumo
SQLDescribeParam retorna a descrição de um marcador de parâmetro associado a uma instrução SQL preparada. Esta informação também está disponível nos campos da DPI.
Sintaxe
SQLRETURN SQLDescribeParam(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT * DataTypePtr,
SQLULEN * ParameterSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Argumentos
Identificador de declaração
[Entrada] Identificador de instrução.
Número do parâmetro
[Entrada] Número do marcador de parâmetro ordenado sequencialmente em ordem crescente de parâmetro, começando em 1.
DataTypePtr
[Saída] Ponteiro para um buffer no qual retornar o tipo de dados SQL do parâmetro. Esse valor é lido no campo de registro SQL_DESC_CONCISE_TYPE do IPD. Esse será um dos valores na seção Tipos de Dados SQL do Apêndice D: Tipos de Dados ou um tipo de dados SQL específico do driver.
No ODBC 3.x, SQL_TYPE_DATE, SQL_TYPE_TIME ou SQL_TYPE_TIMESTAMP serão retornados em *DataTypePtr para dados de data, hora ou carimbo de data/hora, respectivamente; no ODBC 2.x, SQL_DATE, SQL_TIME ou SQL_TIMESTAMP serão retornados. O Gerenciador de Driver executa os mapeamentos necessários quando um ODBC 2.x está funcionando com um ODBC 3.x ou quando um driver ODBC 3.x está funcionando com um ODBC 2.x driver.
Quando ColumnNumber é igual a 0 (para uma coluna de indicador), SQL_BINARY é retornado em *DataTypePtr para indicadores de comprimento variável. (SQL_INTEGER será retornado se os indicadores forem usados por um ODBC 3.x aplicativo trabalhando com um aplicativo ODBC 2.x ou por um ODBC 2.x aplicativo trabalhando com um ODBC 3.x driver.)
Para obter mais informações, consulte Tipos de dados SQL no Apêndice D: Tipos de dados. Para informações sobre tipos de dados SQL específicos do driver, confira a documentação do driver.
ParameterSizePtr
[Saída] Ponteiro para um buffer no qual retornar o tamanho, em caracteres, da coluna ou expressão do marcador de parâmetro correspondente, conforme definido pela fonte de dados. Para obter mais informações sobre o tamanho da coluna, consulte Tamanho da coluna, Dígitos decimais, Comprimento do octeto de transferência e Tamanho de exibição.
DecimalDigitsPtr
[Saída] Ponteiro para um buffer no qual retornar o número de dígitos decimais da coluna ou expressão do parâmetro correspondente, conforme definido pela fonte de dados. Para obter mais informações sobre dígitos decimais, consulte Tamanho da coluna, Dígitos decimais, Comprimento do octeto de transferência e Tamanho de exibição.
NullablePtr
[Saída] Ponteiro para um buffer no qual retornar um valor que indica se o parâmetro permite valores NULL. Esse valor é lido no campo SQL_DESC_NULLABLE do IPD. Um dos seguintes:
SQL_NO_NULLS: O parâmetro não permite valores NULL (este é o valor padrão).
SQL_NULLABLE: O parâmetro permite valores NULL.
SQL_NULLABLE_UNKNOWN: O driver não pode determinar se o parâmetro permite valores NULL.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLDescribeParam 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 SQLDescribeParam 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.) |
| 07009 | Índice de descritor inválido | (DM) O valor especificado para o argumento ParameterNumber é menor que 1. O valor especificado para o argumento ParameterNumber era maior que o número de parâmetros na instrução SQL associada. O marcador de parâmetro fazia parte de uma instrução não DML. O marcador de parâmetro fazia parte de uma lista SELECT . |
| 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. |
| 21S01 | A lista de valores de inserção não corresponde à lista de colunas | O número de parâmetros na instrução INSERT não correspondeu ao número de colunas na tabela nomeada na instrução. |
| 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. |
| 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. 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. |
| HY010 | Erro de sequência de função | (DM) A função foi chamada antes de chamar SQLPrepare ou SQLExecDirect para o StatementHandle. (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 SQLDescribeParam 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. |
| 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. |
| 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. |
| 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 associado 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
Os marcadores de parâmetro são numerados em ordem crescente de parâmetros, começando com 1, na ordem em que aparecem na instrução SQL.
SQLDescribeParam não retorna o tipo (entrada, entrada/saída ou saída) de um parâmetro em uma instrução SQL. Exceto em chamadas para procedimentos, todos os parâmetros em instruções SQL são parâmetros de entrada. Para determinar o tipo de cada parâmetro em uma chamada para um procedimento, um aplicativo chama SQLProcedureColumns.
Para obter mais informações, consulte Descrevendo parâmetros.
Exemplo de código
O exemplo a seguir solicita ao usuário uma instrução SQL e, em seguida, prepara essa instrução. Em seguida, ele chama SQLNumParams para determinar se a instrução contém parâmetros. Se a instrução contiver parâmetros, ela chamará SQLDescribeParam para descrever esses parâmetros e SQLBindParameter para associá-los. Por fim, ele solicita ao usuário os valores de quaisquer parâmetros e, em seguida, executa a instrução.
SQLCHAR Statement[100];
SQLSMALLINT NumParams, i, DataType, DecimalDigits, Nullable;
SQLUINTEGER ParamSize;
SQLHSTMT hstmt;
// Prompt the user for a SQL statement and prepare it.
GetSQLStatement(Statement);
SQLPrepare(hstmt, Statement, SQL_NTS);
// Check to see if there are any parameters. If so, process them.
SQLNumParams(hstmt, &NumParams);
if (NumParams) {
// Allocate memory for three arrays. The first holds pointers to buffers in which
// each parameter value will be stored in character form. The second contains the
// length of each buffer. The third contains the length/indicator value for each
// parameter.
SQLPOINTER * PtrArray = (SQLPOINTER *) malloc(NumParams * sizeof(SQLPOINTER));
SQLINTEGER * BufferLenArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
SQLINTEGER * LenOrIndArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
for (i = 0; i < NumParams; i++) {
// Describe the parameter.
SQLDescribeParam(hstmt, i + 1, &DataType, &ParamSize, &DecimalDigits, &Nullable);
// Call a helper function to allocate a buffer in which to store the parameter
// value in character form. The function determines the size of the buffer from
// the SQL data type and parameter size returned by SQLDescribeParam and returns
// a pointer to the buffer and the length of the buffer.
AllocParamBuffer(DataType, ParamSize, &PtrArray[i], &BufferLenArray[i]);
// Bind the memory to the parameter. Assume that we only have input parameters.
SQLBindParameter(hstmt, i + 1, SQL_PARAM_INPUT, SQL_C_CHAR, DataType, ParamSize,
DecimalDigits, PtrArray[i], BufferLenArray[i],
&LenOrIndArray[i]);
// Prompt the user for the value of the parameter and store it in the memory
// allocated earlier. For simplicity, this function does not check the value
// against the information returned by SQLDescribeParam. Instead, the driver does
// this when the statement is executed.
GetParamValue(PtrArray[i], BufferLenArray[i], &LenOrIndArray[i]);
}
}
// Execute the statement.
SQLExecute(hstmt);
// Process the statement further, such as retrieving results (if any) and closing the
// cursor (if any). Code not shown.
// Free the memory allocated for each parameter and the memory allocated for the arrays
// of pointers, buffer lengths, and length/indicator values.
for (i = 0; i < NumParams; i++) free(PtrArray[i]);
free(PtrArray);
free(BufferLenArray);
free(LenOrIndArray);
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associando um buffer a um parâmetro | Função SQLBindParameter |
| Cancelando o processamento de instruções | Função SQLCancel |
| Executando uma instrução SQL preparada | Função SQLExecute |
| Preparando uma instrução para execução | Função SQLPrepare |