Chamando um procedimento armazenado (OLE DB)

Um procedimento armazenado pode ter zero ou mais parâmetros. Ele também pode retornar um valor. Ao usar o provedor OLE DB do SQL Server Native Client, os parâmetros para um procedimento armazenado podem ser passados por:

• Codificação rígida do valor de dados.

• Usando um marcador de parâmetro (?) para especificar parâmetros, associe uma variável de programa ao marcador de parâmetro e coloque o valor dos dados na variável de programa.

Para dar suporte a parâmetros, a interface ICommandWithParameters é exposta no objeto de comando. Para usar parâmetros, o consumidor descreve primeiro os parâmetros para o provedor chamando o método ICommandWithParameters::SetParameterInfo (ou, opcionalmente, prepara uma instrução de chamada que chama o método GetParameterInfo ). Em seguida, o consumidor cria um acessador que especifica a estrutura de um buffer e coloca valores de parâmetro nesse buffer. Por fim, ele passa o identificador do acessador e um ponteiro para o buffer para Executar. Em chamadas posteriores para Executar, o consumidor coloca novos valores de parâmetro no buffer e chama Executar com o identificador do acessador e o ponteiro do buffer.

Um comando que chama um procedimento armazenado temporário usando parâmetros deve primeiro chamar ICommandWithParameters::SetParameterInfo para definir as informações do parâmetro, antes que o comando possa ser preparado com êxito. Isso ocorre porque o nome interno de um procedimento armazenado temporário difere do nome externo usado por um cliente e o SQLOLEDB não pode consultar as tabelas do sistema para determinar as informações de parâmetro para um procedimento armazenado temporário.

Estas são as etapas no processo de associação de parâmetros:

1. Preencha as informações de parâmetro em uma matriz de estruturas DBPARAMBINDINFO; ou seja, nome do parâmetro, nome específico do provedor para o tipo de dados do parâmetro ou um nome de tipo de dados padrão e assim por diante. Cada estrutura na matriz descreve um parâmetro. Essa matriz é então passada para o método SetParameterInfo .

2. Chame o método ICommandWithParameters::SetParameterInfo para descrever parâmetros para o provedor. SetParameterInfo especifica o tipo de dados nativo de cada parâmetro. Os argumentos SetParameterInfo são:

   • O número de parâmetros para os quais definir informações de tipo.

   • Uma matriz de ordinais de parâmetro para o qual definir informações de tipo.

   • Uma matriz de estruturas DBPARAMBINDINFO.

3. Crie um acessador de parâmetro usando o comando IAccessor::CreateAccessor . O acessador especifica a estrutura de um buffer e coloca valores de parâmetro no buffer. O comando CreateAccessor cria um acessador de um conjunto de associações. Essas associações são descritas pelo consumidor usando uma matriz de estruturas DBBINDING. Cada associação associa um único parâmetro ao buffer do consumidor e contém informações como:

   • O ordinal do parâmetro ao qual a associação se aplica.

   • O que está associado (o valor dos dados, seu comprimento e seu status).

   • O deslocamento no buffer para cada uma dessas partes.

   • O comprimento e o tipo do valor de dados como ele existe no buffer do consumidor.

   Um acessador é identificado por seu identificador, que é do tipo HACCESSOR. Esse identificador é retornado pelo método CreateAccessor . Sempre que o consumidor terminar de usar um acessador, o consumidor deverá chamar o método ReleaseAccessor para liberar a memória que ele contém.

   Quando o consumidor chama um método, como ICommand::Execute, ele passa o identificador para um acessador e um ponteiro para um buffer propriamente dito. O provedor usa esse acessador para determinar como transferir os dados contidos no buffer.

4. Preencha a estrutura DBPARAMS. As variáveis de consumidor das quais os valores de parâmetro de entrada são obtidos e para as quais os valores de parâmetro de saída são gravados são passadas em tempo de execução para ICommand::Execute na estrutura DBPARAMS. A estrutura DBPARAMS inclui três elementos:

   • Um ponteiro para o buffer do qual o provedor recupera dados de parâmetro de entrada e para o qual o provedor retorna dados de parâmetro de saída, de acordo com as associações especificadas pelo identificador do acessador.

   • O número de conjuntos de parâmetros no buffer.

   • O identificador do acessador criado na Etapa 3.

5. Execute o comando usando ICommand::Execute.

Métodos de chamar um procedimento armazenado

Ao executar um procedimento armazenado no SQL Server, o provedor OLE DB do SQL Server Native Client dá suporte a:

• Sequência de escape de CHAMADA ODBC.

• Sequência de escape de RPC (chamada de procedimento remoto).

• Transact-SQL instrução EXECUTE.

Sequência de escape de chamada ODBC

Se você souber informações de parâmetro, chame o método ICommandWithParameters::SetParameterInfo para descrever os parâmetros para o provedor. Caso contrário, quando a sintaxe ODBC CALL é usada na chamada de um procedimento armazenado, o provedor chama uma função auxiliar para localizar as informações de parâmetro de procedimento armazenado.

Se você não tiver certeza sobre as informações de parâmetro (metadados de parâmetro), a sintaxe ODBC CALL será recomendada.

A sintaxe geral para chamar um procedimento usando a sequência de escape ODBC CALL é:

{[?=]chamarprocedure_name[([parâmetro][,[parâmetro]]... )]}

Por exemplo:

{call SalesByCategory('Produce', '1995')}  

Sequência de escape RPC

A sequência de escape RPC é semelhante à sintaxe ODBC CALL de chamar um procedimento armazenado. Se você chamar o procedimento várias vezes, a sequência de escape RPC fornecerá o melhor desempenho entre os três métodos de chamada de um procedimento armazenado.

Quando a sequência de escape RPC é usada para executar um procedimento armazenado, o provedor não chama nenhuma função auxiliar para determinar as informações do parâmetro (como faz no caso da sintaxe de CHAMADA ODBC). A sintaxe RPC é mais simples do que a sintaxe ODBC CALL, portanto, o comando é analisado mais rapidamente, melhorando o desempenho. Nesse caso, você precisa fornecer as informações de parâmetro executando ICommandWithParameters::SetParameterInfo.

A sequência de escape RPC exige que você tenha um valor retornado. Se o procedimento armazenado não retornar um valor, o servidor retornará um 0 por padrão. Além disso, não é possível abrir um cursor do SQL Server no procedimento armazenado. O procedimento armazenado é preparado implicitamente e a chamada para ICommandPrepare::P repare falhará. Devido à incapacidade de preparar uma chamada RPC, você não pode consultar metadados de coluna; IColumnsInfo::GetColumnInfo e IColumnsRowset::GetColumnsRowset retornarão DB_E_NOTPREPARED.

Se você souber todos os metadados de parâmetro, a sequência de escape RPC será a maneira recomendada de executar procedimentos armazenados.

Este é um exemplo de sequência de escape RPC para chamar um procedimento armazenado:

{rpc SalesByCategory}  

Para obter um aplicativo de exemplo que demonstra uma sequência de escape RPC, consulte Execute a Stored Procedure (Using RPC Syntax) and Process Return Codes and Output Parameters (OLE DB).

Instrução EXECUTE Transact-SQL

A sequência de escape ODBC CALL e a sequência de escape RPC são os métodos preferenciais para chamar um procedimento armazenado em vez da instrução EXECUTE . O provedor OLE DB do SQL Server Native Client usa o mecanismo RPC do SQL Server para otimizar o processamento de comandos. Esse protocolo RPC aumenta o desempenho eliminando grande parte do processamento de parâmetros e análise de instrução feita no servidor.

Este é um exemplo da instrução EXECUTE Transact-SQL:

EXECUTE SalesByCategory 'Produce', '1995'  

Consulte Também

Procedimentos armazenados