SQLDescribeParam

Artigo
01/10/2024

Aplica-se a:SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics PDW (Analytics Platform System)

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 começando com o 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.

Também novo no SQL Server 2012 (11.x), 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_INTEGER, por exemplo).

O driver não oferece suporte a chamada SQLDescribeParam nas seguintes situações:

Após 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 comparado ao resultado de uma função SOMA.
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 oferece 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 do 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 sp_who de procedimento armazenado do sistema 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 ao mestre. A mesma chamada, preparada da seguinte maneira, faz com que SQLDescribeParam seja bem-sucedido, independentemente do banco de dados do 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 vincular 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 o 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:

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 Aprimoramentos de data e hora (ODBC).

Suporte SQLDescribeParam para UDTs CLR grandes

SQLDescribeParam oferece suporte a grandes tipos definidos pelo usuário (UDTs) CLR. Para obter mais informações, consulte Tipos definidos pelo usuário (ODBC) CLR grandes.

Confira também

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