SQLDescribeParam

Aplica-se a: SQL ServerBase de Dados SQL do AzureAzure SQL Managed InstanceAzure Synapse AnalyticsSistema de Plataforma de Análise (PDW)

Para descrever os parâmetros de qualquer instrução SQL, o driver ODBC SQL Server Native Client constrói e executa uma instrução Transact-SQL SELECT quando o SQLDescribeParam é chamado num handle de instrução ODBC preparado. Os metadados do conjunto de resultados determinam as características dos parâmetros na declaração preparada. O SQLDescribeParam pode devolver qualquer código de erro que o SQLExecute ou SQLExecDirect possam devolver.

As melhorias no motor da base de dados a partir do SQL Server 2012 (11.x) permitem que o SQLDescribeParam obtenha descrições mais precisas dos resultados esperados. Estes resultados mais precisos podem diferir dos valores retornados pelo SQLDescribeParam em versões anteriores do SQL Server. Para mais informações, consulte Descoberta de Metadados.

Também novo no SQL Server 2012 (11.x), o ParameterSizePtr agora devolve 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 Cliente Nativo, o ParameterSizePtr podia ser o valor correspondente de SQL_DESC_OCTET_LENGTH para o tipo, ou um valor irrelevante do tamanho da coluna fornecido ao SQLBindParameter para um tipo, cujo valor deve ser ignorado (SQL_INTEGER, por exemplo).

O driver não suporta chamar SQLDescribeParam nas seguintes situações:

• Após SQLExecDirect para quaisquer Transact-SQL UPDATE ou DELETE instruções contendo a cláusula FROM.

• Para qualquer instrução ODBC ou Transact-SQL contendo um parâmetro numa cláusula HAVING, ou comparada com o resultado de uma função SUM.

• Para qualquer instrução ODBC ou Transact-SQL dependendo de uma subconsulta contendo parâmetros.

• Para instruções SQL ODBC que contêm marcadores de parâmetros em ambas as expressões de um predicado de comparação, como ou quantificado.

• Para quaisquer consultas em que um dos parâmetros seja um parâmetro de 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 suporta chamar SQLDescribeParam para marcadores de parâmetros nas instruções após a primeira instrução do lote.

Ao descrever os parâmetros dos procedimentos armazenados preparados, o SQLDescribeParam utiliza o sp_sproc_columns de procedimento armazenado do sistema para recuperar características dos parâmetros. sp_sproc_columns pode reportar dados de procedimentos armazenados dentro da base de dados de utilizador atual. Preparar um nome de procedimento armazenado totalmente qualificado permite que o SQLDescribeParam seja executado entre bases de dados. Por exemplo, o sp_who de procedimento armazenado do sistema pode ser preparado e executado em qualquer base de dados como:

SQLPrepare(hstmt, "{call sp_who(?)}", SQL_NTS);  

Executar o SQLDescribeParam após uma preparação bem-sucedida devolve um conjunto de linhas vazio quando ligado a qualquer base de dados exceto master. A mesma chamada, preparada da seguinte forma, faz com que o SQLDescribeParam tenha sucesso independentemente da base de dados de utilizador atual:

SQLPrepare(hstmt, "{call master..sp_who(?)}", SQL_NTS);  

Para tipos de dados de grande valor, o valor devolvido em DataTypePtr é SQL_VARCHAR, SQL_VARBINARY ou SQL_NVARCHAR. Para indicar que o tamanho do parâmetro do tipo de dado de grande valor é "ilimitado", o driver ODBC do SQL Server Native Client define o ParameterSizePtr a 0. Os valores reais de tamanho são devolvidos para parâmetros varchar padrão.

Para atribuir um parâmetro de entrada de tamanho "ilimitado", deve ser usado data-at-execution. Não é possível associar um parâmetro de saída de tamanho "ilimitado" (não existe método para transmitir dados a partir de um parâmetro de saída, como o SQLGetData faz para conjuntos de resultados).

Para os parâmetros de saída, um buffer deve ser limitado e, se o valor for demasiado grande, o buffer é preenchido e recebe uma mensagem SQL_SUCCESS_WITH_INFO e é devolvida juntamente com os "dados de cadeia"; Aviso de truncamento à direita". Os dados que foram truncados são depois descartados.

SQLDescribeParam e parâmetros Table-Valued

Uma aplicação pode obter informação de parâmetros com valores de tabela para uma instrução preparada com SQLDescribeParam. Para mais informações, consulte Table-Valued Metadados de Parâmetros para Declarações Preparadas.

Para mais informações sobre parâmetros de tabela em geral, consulte Table-Valued Parâmetros (ODBC).

Suporte SQLDescribeParam para funcionalidades melhoradas de data e hora

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

Para mais informações, consulte Melhorias de Data e Hora (ODBC).

Suporte SQLDescribeParam para UDTs CLR de grande porte

O SQLDescribeParam suporta grandes tipos CLR definidos pelo utilizador (UDTs). Para mais informações, consulte Grandes CLR User-Defined Tipos (ODBC).

Ver também

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