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

Determinados DBMSs permitem que um aplicativo especifique os parâmetros para um procedimento armazenado por nome em vez de por posição na chamada de procedimento. Esses parâmetros são chamados de parâmetros nomeados. O ODBC oferece suporte ao uso de parâmetros nomeados. No ODBC, os parâmetros nomeados são usados somente em chamadas para procedimentos armazenados e não podem ser usados em outras instruções SQL.

O driver verifica o valor do campo SQL_DESC_UNNAMED do IPD para determinar se os parâmetros nomeados são usados. Se SQL_DESC_UNNAMED não estiver definido como SQL_UNNAMED, o driver usará o nome no campo SQL_DESC_NAME do IPD para identificar o parâmetro. Para associar o parâmetro, um aplicativo pode chamar SQLBindParameter para especificar as informações do parâmetro e, em seguida, pode chamar SQLSetDescField para definir o campo SQL_DESC_NAME do IPD. Quando parâmetros nomeados são usados, a ordem do parâmetro na chamada de procedimento não é importante e o número de registro 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 registro do descritor e o número do parâmetro no procedimento. Quando parâmetros não nomeados são usados, o marcador do primeiro parâmetro é relacionado ao primeiro registro no descritor do parâmetro, que por sua vez, é relacionado ao primeiro parâmetro (em ordem de criação) na chamada de procedimento. Quando parâmetros nomeados são usados, o marcador do primeiro parâmetro ainda é relacionado ao primeiro registro do descritor do parâmetro, mas a relação entre o número de registro do descritor e o número do parâmetro no procedimento já não existe. Os parâmetros nomeados não usam o mapeamento do número de registro do descritor para a posição do parâmetro do procedimento. Em vez disso, o nome do registro do descritor é mapeado para o nome do parâmetro do procedimento.

Observação

Se o preenchimento automático do IPD estiver habilitado, o driver preencherá o descritor para que a ordem dos registros do descritor corresponda à ordem dos parâmetros na definição do procedimento, mesmo que parâmetros nomeados sejam usados.

Se um parâmetro nomeado for usado, 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 um parâmetro nomeado. Se houvesse uma mistura de parâmetros nomeados e parâmetros não nomeados, o comportamento dependeria do driver.

Como um exemplo de parâmetros nomeados, suponha que um procedimento armazenado do SQL Server tenha sido definido da seguinte maneira:

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. Um aplicativo pode usar o código a seguir para invocar esse procedimento de modo que ele especifique 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);