SQLDescribeParam
Para descrever os parâmetros de qualquer instrução SQL, o driver ODBC do SQL Server Native Client cria e executa uma instrução SELECT Transact-SQL quando SQLDescribeParam é chamado em um identificador de instrução ODBC preparado. Os metadados do conjunto de resultados determinam as características dos parâmetros na instrução preparada. SQLDescribeParam pode retornar qualquer código de erro que pode ser retornado por SQLExecute ou SQLExecDirect.
Melhorias no mecanismo de banco de dados a partir do SQL Server 2012 permitem que SQLDescribeParam obtenha mais descrições precisas dos resultados esperados. Esses resultados mais precisos podem diferir dos valores retornados por SQLDescribeParam em versões anteriores do SQL Server. Para obter mais informações, consulte Descoberta de metadados.
Outro recurso novo no SQL Server 2012 é que, agora, ParameterSizePtr retorna um valor que se alinha à definição do tamanho, em caracteres, da coluna ou expressão do marcador de parâmetro correspondente, conforme definido na especificação de ODBC. Nas versões anteriores do SQL Server Native Client, ParameterSizePtr poderia ser o valor correspondente de SQL_DESC_OCTET_LENGTH para o tipo ou um valor de tamanho de coluna irrelevante fornecido a SQLBindParameter para um tipo, cujo valor deveria ser ignorado (SQL_INTEGER, por exemplo).
O driver não oferece suporte a chamadas para SQLDescribeParam nas seguintes situações:
Depois de SQLExecDirect para quaisquer instruções Transact-SQL UPDATE ou DELETE que contenham a cláusula FROM.
Para qualquer instrução ODBC ou Transact-SQL que contenha um parâmetro em uma cláusula HAVING, ou comparada ao resultado de uma função SUM.
Para qualquer instrução ODBC ou Transact-SQL que dependa de uma subconsulta que contém parâmetros.
Para instruções SQL ODBC que contenham marcadores de parâmetro em ambas as expressões de uma comparação, like, ou predicado quantificado.
Para qualquer consulta em que um dos parâmetros é um parâmetro para uma função.
Quando há comentários (/* */) no comando Transact-SQL.
Ao processar um lote de instruções Transact-SQL, o driver também não dá suporte a chamadas para SQLDescribeParam para marcadores de parâmetro em instruções depois da primeira instrução no lote.
Ao descrever os parâmetros de procedimentos armazenados preparados, SQLDescribeParam usa o procedimento armazenado de sistema sp_sproc_columns para recuperar características de parâmetro. sp_sproc_columns pode informar dados para procedimentos armazenados no banco de dados de usuário atual. Preparar um nome de procedimento armazenado totalmente qualificado permite que SQLDescribeParam seja executados nos bancos de dados. Por exemplo, o procedimento armazenado de sistema sp_who pode ser preparado e executado em qualquer banco de dados como:
SQLPrepare(hstmt, "{call sp_who(?)}", SQL_NTS);
Executar SQLDescribeParam depois de uma preparação bem-sucedida retorna um conjunto de linhas vazio quando conectado a qualquer banco de dados, com exceção de master. A mesma chamada, preparada como a seguir, faz com que SQLDescribeParam seja bem-sucedido independentemente do banco de dados de usuário atual.
SQLPrepare(hstmt, "{call master..sp_who(?)}", SQL_NTS);
Para tipos de dados de valor grande, o valor retornado em DataTypePtr é SQL_VARCHAR, SQL_VARBINARY ou SQL_NVARCHAR. Para indicar que o tamanho do parâmetro de tipo de dados de valor grande é "ilimitado", o driver ODBC do SQL Server Native Client define ParameterSizePtr como 0. Os valores de tamanho reais são retornados para os parâmetros padrão varchar.
.gif "Observação") Observação |
|---|
Se o parâmetro já tiver sido associado a um tamanho máximo para os parâmetros SQL_VARCHAR, SQL_VARBINARY ou SQL_WVARCHAR, o tamanho associado do parâmetro será retornado, não "ilimitado". |
Para associar um parâmetro de entrada de tamanho "ilimitado", dados em execução devem ser usados. Não é possível associar um parâmetro de saída de tamanho "ilimitado" (não há método para fazer o streaming de dados de um parâmetro de saída, como SQLGetData faz para conjuntos de resultados).
No caso de parâmetros de saída, um buffer deve ser associado e se o valor for muito extenso, o buffer será preenchido e uma mensagem SQL_SUCCESS_WITH_INFO será retornada junto com o aviso "dados de cadeia de caracteres; truncamento à direita". Os dados que foram truncados são descartados em seguida.
SQLDescribeParam e parâmetros com valor de tabela
Um aplicativo pode recuperar informações de parâmetro com valor de tabela para uma instrução preparada com SQLDescribeParam. Para obter mais informações, consulte Metadados do parâmetro com valor de tabela para instruções preparadas.
Para obter mais informações sobre parâmetros com valor de tabela em geral, consulte Parâmetros com valor de tabela (ODBC).
Suporte SQLDescribeParam para recursos avançados de data e hora
Os valores retornados para tipos de data/hora são os seguintes:
DataTypePtr |
ParameterSizePtr |
DecimalDigitsPtr |
|
|---|---|---|---|
datetime |
SQL_TYPE_TIMESTAMP |
23 |
3 |
smalldatetime |
SQL_TYPE_TIMESTAMP |
16 |
0 |
date |
SQL_TYPE_DATE |
10 |
0 |
time |
SQL_SS_TIME2 |
8, 10..16 |
0..7 |
datetime2 |
SQL_TYPE_TIMESTAMP |
19, 21..27 |
0..7 |
datetimeoffset |
SQL_SS_TIMESTAMPOFFSET |
26, 28..34 |
0..7 |
Para obter mais informações, consulte Aprimoramentos de data/hora (ODBC).
Suporte SQLDescribeParam para UDTs CLR grandes
O SQLDescribeParam dá suporte a UDTs (tipos definidos pelo usuário) CLR grandes. Para obter mais informações, consulte Tipos de dados CLR grandes definidos pelo usuário (ODBC).
Consulte também
Conceitos
Detalhes de implementação da API ODBC