Partilhar via

SQLDescribeParam

  • Artigo

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure PDW (Sistema de Plataforma de Análise) do Azure Synapse Analytics

Para descrever os parâmetros de qualquer instrução SQL, o driver ODBC do SQL Server Native Client cria e executa uma instrução Transact-SQL SELECT 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.

Melhorias no mecanismo de banco de dados a partir do SQL Server 2012 (11.x) permitem que SQLDescribeParam obtenha descrições mais 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, veja Descoberta de metadados.

Outra novidade no SQL Server 2012 (11.x), ParameterSizePtr agora retorna um valor que se alinha com a definição do tamanho, em caracteres, da coluna ou expressão do marcador de parâmetro correspondente, conforme definido na especificação 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 que foi fornecido a SQLBindParameter para um tipo, cujo valor deve ser ignorado (SQL_INTEGER, por exemplo).

O driver não dá suporte à chamada SQLDescribeParam nas seguintes situações:

  • Após SQLExecDirect para qualquer instrução Transact-SQL UPDATE ou DELETE 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 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 à chamada 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 sp_sproc_columns de procedimento armazenado do sistema para recuperar características de parâmetro. sp_sproc_columns pode relatar dados para procedimentos armazenados no banco de dados de usuário atual. A preparação de um nome de procedimento armazenado totalmente qualificado permite que SQLDescribeParam seja executado em 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 o mestre. A mesma chamada, preparada da seguinte maneira, 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 real são retornados para parâmetros varchar padrã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á 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 ODBC (Parâmetros com valor de tabela).

Suporte SQLDescribeParam para recursos avançados de data e hora

Os valores retornados para tipos de data/hora são os seguintes:

Atributo 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 (tipos definidos pelo usuário) CLR grandes. Para obter mais informações, consulte ODBC (Tipos Definidos pelo Usuário) CLR Grandes.

Confira também

Função SQLDescribeParam
Detalhes da implementação da API do ODBC