Usando matrizes de parâmetros

Para usar arrays de parâmetros, a aplicação chama SQLSetStmtAttr com um argumento 'Attribute' de SQL_ATTR_PARAMSET_SIZE para especificar o número de conjuntos de parâmetros. Chama SQLSetStmtAttr com um argumento de atributo de SQL_ATTR_PARAMS_PROCESSED_PTR para especificar o endereço de uma variável na qual o driver pode devolver o número de conjuntos de parâmetros processados, incluindo conjuntos de erros. Chama SQLSetStmtAttr com o argumento Atributo de SQL_ATTR_PARAM_STATUS_PTR para apontar para uma matriz onde deve devolver a informação de estado para cada linha dos valores dos parâmetros. O driver armazena estes endereços na estrutura que mantém para a instrução.

Observação

No ODBC 2. x, SQLParamOptions foi chamado para especificar múltiplos valores para um parâmetro. No ODBC 3. x, a chamada para SQLParamOptions foi substituída por chamadas para SQLSetStmtAttr para definir os atributos SQL_ATTR_PARAMSET_SIZE e SQL_ATTR_PARAMS_PROCESSED_ARRAY.

Antes de executar a instrução, a aplicação define o valor de cada elemento de cada array limitado. Quando a instrução é executada, o driver utiliza a informação armazenada para recuperar os valores dos parâmetros e enviá-los para a fonte de dados; Se possível, o driver deve enviar estes valores como arrays. Embora a utilização de arrays de parâmetros seja melhor implementada executando a instrução SQL com todos os parâmetros do array com uma única chamada à fonte de dados, esta funcionalidade não está amplamente disponível nos SGBD atualmente. No entanto, os drivers podem simulá-lo executando uma instrução SQL várias vezes, cada uma com um único conjunto de parâmetros.

Antes de uma aplicação utilizar arrays de parâmetros, deve certificar-se de que são suportados pelos drivers usados pela aplicação. Há duas maneiras de fazer isso:

• Utilize apenas drivers reconhecidos por suportarem eficazmente arrays de parâmetros. A aplicação pode codificar diretamente os nomes destes drivers, ou o utilizador pode ser instruído a usar apenas esses drivers. Aplicações personalizadas e verticais utilizam normalmente um conjunto limitado de drivers.

• Verifique o suporte para matrizes de parâmetros em tempo de execução. Um driver suporta arrays de parâmetros se for possível definir o atributo da instrução SQL_ATTR_PARAMSET_SIZE para um valor superior a 1. Aplicações genéricas e verticais verificam frequentemente o suporte de arrays de parâmetros em tempo de execução.

A disponibilidade de contagens de linhas e conjuntos de resultados na execução parametrizada pode ser determinada chamando SQLGetInfo com as opções SQL_PARAM_ARRAY_ROW_COUNTS e SQL_PARAM_ARRAY_SELECTS. Para as instruções INSERT,UPDATE e DELETE , a opção SQL_PARAM_ARRAY_ROW_COUNTS indica se estão disponíveis contagens de linhas individuais (uma para cada conjunto de parâmetros) (SQL_PARC_BATCH) ou se as contagens de linhas são agrupadas numa só (SQL_PARC_NO_BATCH). Para as instruções SELECT , a opção SQL_PARAM_ARRAY_SELECTS indica se existe um conjunto de resultados disponível para cada conjunto de parâmetros (SQL_PAS_BATCH) ou se apenas um conjunto de resultados está disponível (SQL_PAS_NO_BATCH). Se o driver não permitir que instruções geradoras de conjuntos de resultados sejam executadas com um array de parâmetros, SQL_PARAM_ARRAY_SELECTS devolve SQL_PAS_NO_SELECT. Depende da fonte de dados se arrays de parâmetros podem ser usados com outros tipos de instruções, especialmente porque o uso de parâmetros nessas instruções seria específico da fonte de dados e não seguiria a gramática SQL ODBC.

A matriz referida pelo atributo da instrução SQL_ATTR_PARAM_OPERATION_PTR pode ser utilizada para ignorar as linhas de parâmetros. Se um elemento do array for definido para SQL_PARAM_IGNORE, o conjunto de parâmetros correspondente a esse elemento é excluído da chamada SQLExecute ou SQLExecDirect . O array a que o atributo SQL_ATTR_PARAM_OPERATION_PTR aponta é alocado e preenchido pela aplicação e lido pelo driver. Se as linhas buscadas forem usadas como parâmetros de entrada, os valores do array de estado das linhas podem ser usados no array de operações de parâmetros.

Processamento de erros

Se ocorrer um erro durante a execução da instrução, a função de execução devolve um erro e define a variável número de linha para o número da linha que contém o erro. Depende da fonte de dados se todas as linhas, exceto o conjunto de erros, são executadas ou se todas as linhas antes (mas não depois) do conjunto de erros são executadas. Como processa conjuntos de parâmetros, o driver define o buffer especificado pelo atributo da instrução SQL_ATTR_PARAMS_PROCESSED_PTR ao número da linha atualmente a ser processada. Se todos os conjuntos, exceto o conjunto de erros, forem executados, o driver define este buffer para SQL_ATTR_PARAMSET_SIZE depois de todas as linhas serem processadas.

Se o atributo da instrução SQL_ATTR_PARAM_STATUS_PTR tiver sido definido, SQLExecute ou SQLExecDirect devolve o array de estado de parâmetros, que fornece o estado de cada conjunto de parâmetros. O array de estado dos parâmetros é alocado pela aplicação e preenchido pelo driver. Os seus elementos indicam se a instrução SQL foi executada com sucesso para a linha de parâmetros ou se ocorreu um erro durante o processamento do conjunto de parâmetros. Se ocorrer um erro, o driver define o valor correspondente no array de estado dos parâmetros para SQL_PARAM_ERROR e devolve SQL_SUCCESS_WITH_INFO. A aplicação pode verificar o array de estado para determinar quais as linhas que foram processadas. Usando o número da linha, a aplicação pode frequentemente corrigir o erro e retomar o processamento.

A forma como o array de estado de parâmetros é utilizado é determinada pelas opções de SQL_PARAM_ARRAY_ROW_COUNTS e SQL_PARAM_ARRAY_SELECTS devolvidas por uma chamada ao SQLGetInfo. Para as instruções INSERT,UPDATE e DELETE , o array de estado dos parâmetros é preenchido com informação de estado se SQL_PARC_BATCH for devolvido para SQL_PARAM_ARRAY_ROW_COUNTS, mas não se SQL_PARC_NO_BATCH for devolvido. Para as instruções SELECT, o array de estado dos parâmetros é preenchido se SQL_PAS_BATCH for retornado para SQL_PARAM_ARRAY_SELECT, mas não será preenchido se for retornado SQL_PAS_NO_BATCH ou SQL_PAS_NO_SELECT.

Parâmetros de Dados na Execução

Se algum dos valores no array de comprimento/indicador for SQL_DATA_AT_EXEC ou resultar do macro SQL_LEN_DATA_AT_EXEC(comprimento), os dados para esses valores são enviados utilizando SQLPutData de forma habitual. Os seguintes aspetos deste processo merecem um comentário especial porque não são facilmente evidentes:

• Quando o driver retorna SQL_NEED_DATA, deve definir o endereço da variável número de linha para a linha para a qual necessita de dados. Tal como no caso de valor único, a aplicação não pode fazer quaisquer suposições sobre a ordem em que o driver irá solicitar valores de parâmetros dentro de um único conjunto de parâmetros. Se ocorrer um erro na execução de um parâmetro data-at-execution, o buffer especificado pelo atributo da instrução SQL_ATTR_PARAMS_PROCESSED_PTR é definido para o número da linha onde o erro ocorreu, o estado da linha no array de estado da linha especificado pelo atributo da instrução SQL_ATTR_PARAM_STATUS_PTR é definido para SQL_PARAM_ERROR, e a chamada a SQLExecute, SQLExecDirect, SQLParamData ou SQLPutData devolve SQL_ERROR. O conteúdo deste buffer não está definido se SQLExecute, SQLExecDirect ou SQLParamData retornarem SQL_STILL_EXECUTING.

• Como o driver não interpreta o valor no argumento ParameterValuePtr do SQLBindParameter para os parâmetros de dados na execução, se a aplicação fornecer um ponteiro para um array, o SQLParamData não extrai nem devolve um elemento deste array à aplicação. Em vez disso, devolve o valor escalar fornecido pela aplicação. Isto significa que o valor devolvido pelo SQLParamData não é suficiente para especificar o parâmetro para o qual a aplicação precisa de enviar dados; A aplicação também precisa de considerar o número da linha atual.

  Quando apenas alguns dos elementos de um array de parâmetros são parâmetros data-at-execution, a aplicação deve passar, no ParameterValuePtr, o endereço de um array que contenha elementos para todos os parâmetros. Este array é interpretado normalmente para os parâmetros que não são parâmetros de dados a executar. Para os parâmetros de dados na execução, o valor que o SQLParamData fornece à aplicação, que normalmente poderia ser usado para identificar os dados que o driver está a solicitar nesta ocasião, é sempre o endereço do array.