Parâmetros de associação por nome (parâmetros nomeados)

Certos SGBD permitem que uma aplicação especifique os parâmetros de um procedimento armazenado pelo nome em vez de pela posição na chamada ao procedimento. Tais parâmetros são chamados parâmetros nomeados. O ODBC suporta a utilização de parâmetros nomeados. No ODBC, parâmetros nomeados são usados apenas em chamadas a procedimentos armazenados e não podem ser usados noutras instruções SQL.

O driver verifica o valor do campo SQL_DESC_UNNAMED do IPD para determinar se são usados parâmetros nomeados. Se SQL_DESC_UNNAMED não estiver definido para SQL_UNNAMED, o driver usa o nome no campo SQL_DESC_NAME do IPD para identificar o parâmetro. Para ligar o parâmetro, uma aplicação pode chamar SQLBindParameter para especificar a informação do parâmetro e depois pode chamar SQLSetDescField para definir o campo SQL_DESC_NAME do IPD. Quando são usados parâmetros nomeados, a ordem do parâmetro na chamada de procedimento não é importante e o número do registo do parâmetro é ignorado.

A diferença entre parâmetros não nomeados e parâmetros nomeados está na relação entre o número de registo do descritor e o número do parâmetro no procedimento. Quando são usados parâmetros não nomeados, o primeiro marcador de parâmetro está relacionado com o primeiro registo no descritor de parâmetros, que por sua vez está relacionado com o primeiro parâmetro (na ordem de criação) na chamada ao procedimento. Quando são usados parâmetros nomeados, o primeiro marcador de parâmetro ainda está relacionado com o primeiro registo do descritor de parâmetro, mas a relação entre o número de registo do descritor e o número do parâmetro no procedimento já não existe. Os parâmetros nomeados não utilizam o mapeamento do número do registo descritor para a posição do parâmetro do procedimento; em vez disso, o nome do registo descritor é mapeado para o nome do parâmetro do procedimento.

Observação

Se a população automática do IPD estiver ativada, o driver preencherá o descritor de modo a que a ordem dos registos do descritor corresponda à ordem dos parâmetros na definição do procedimento, mesmo que sejam usados parâmetros nomeados.

Se for usado um parâmetro nomeado, todos os parâmetros devem ser parâmetros nomeados. Se algum parâmetro não for um parâmetro nomeado, então nenhum dos parâmetros pode ser parâmetro nomeado. Se houvesse uma mistura de parâmetros nomeados e parâmetros não nomeados, o comportamento dependeria do driver.

Como exemplo de parâmetros nomeados, suponha que um procedimento armazenado SQL Server foi definido da seguinte forma:

CREATE PROCEDURE test @title_id int = 1, @quote char(30) AS <blah>  

Neste procedimento, o primeiro parâmetro, @title_id, tem um valor padrão de 1. Uma aplicação pode usar o seguinte código para invocar este procedimento de modo a especificar apenas um parâmetro dinâmico. Este parâmetro é um parâmetro nomeado com o nome "@quote".

// Prepare the procedure invocation statement.  
SQLPrepare(hstmt, "{call test(?)}", SQL_NTS);  
  
// Populate record 1 of ipd.  
SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,  
                  30, 0, szQuote, 0, &cbValue);  
  
// Get ipd handle and set the SQL_DESC_NAMED and SQL_DESC_UNNAMED fields  
// for record #1.  
SQLGetStmtAttr(hstmt, SQL_ATTR_IMP_PARAM_DESC, &hIpd, 0, 0);  
SQLSetDescField(hIpd, 1, SQL_DESC_NAME, "@quote", SQL_NTS);  
  
// Assuming that szQuote has been appropriately initialized,  
// execute.  
SQLExecute(hstmt);