SQLDescribeParam
Para descrever os parâmetros de qualquer instrução SQL, o SQL Server Native Client driver ODBC compila 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 SQLExecute ou SQLExecDirect possa retornar.
Os aprimoramentos no mecanismo de banco de dados a partir do SQL Server 2012 permitem que SQLDescribeParam obtenha descrições mais precisas dos resultados esperados. Esses resultados mais precisos podem ser diferentes dos valores retornados por SQLDescribeParam em versões anteriores do SQL Server. Para obter mais informações, veja Descoberta de metadados.
Também novo no SQL Server 2012, ParameterSizePtr agora retorna um valor que se alinha com a definição para o tamanho, em caracteres, da coluna ou expressão do marcador de parâmetro correspondente, conforme definido na especificação ODBC. Em 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 que foi fornecido a SQLBindParameter para um tipo, cujo valor deve ser ignorado (SQL_INTEGERpor exemplo).
O driver não dá suporte à chamada de SQLDescribeParam nas seguintes situações:
Depois de SQLExecDirect para qualquer instrução UPDATE ou DELETE do Transact-SQL que contenha a cláusula FROM.
Para qualquer instrução ODBC ou Transact-SQL que contenha um parâmetro em uma cláusula HAVING ou em comparação com o resultado de uma função SUM.
Para qualquer instrução ODBC ou Transact-SQL, dependendo de uma subconsulta que contenha 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 houver comentários (/* */) no comando Transact-SQL.
Ao processar um lote de instruções Transact-SQL, o driver também não dá suporte à chamada de SQLDescribeParam para marcadores de parâmetro em instruções após a primeira instrução no lote.
Ao descrever os parâmetros de procedimentos armazenados preparados, SQLDescribeParam usa o procedimento armazenado do sistema sp_sproc_columns para recuperar características de parâmetro. sp_sproc_columns pode relatar dados para procedimentos armazenados no banco de dados de usuário atual. Preparar um nome de procedimento armazenado totalmente qualificado permite que SQLDescribeParam seja executado entre bancos de dados. Por exemplo, o procedimento armazenado do sistema sp_who pode ser preparado e executado em qualquer banco de dados como:
SQLPrepare(hstmt, "{call sp_who(?)}", SQL_NTS);
A execução de SQLDescribeParam após a preparação bem-sucedida retorna um conjunto de linhas vazio quando conectado a qualquer banco de dados, exceto master. A mesma chamada, preparada da seguinte maneira, faz com que SQLDescribeParam tenha êxito, 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 SQL Server Native Client ODBC define ParameterSizePtr como 0. Os valores de tamanho reais são retornados para os parâmetros padrão varchar.
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á nenhum método para transmitir 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 de 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 Melhorias de data e hora (ODBC).
Suporte SQLDescribeParam para UDTs CLR grandes
SQLDescribeParam dá suporte a UDTs grandes do CLR. Para obter mais informações, consulte Tipos de User-Defined CLR grandes (ODBC).