Compartilhar via

Procedimentos armazenados estendidos do Engine de Banco de Dados de Programação

Aplica-se a:SQL Server

Importante

Esse recurso será removido em uma versão futura do SQL Server. Evite usar esse recurso em um novo trabalho de desenvolvimento e planeje modificar aplicativos que atualmente usam esse recurso. Use integração com CLR em vez disso.

Como funcionam os procedimentos armazenados estendidos

O processo pelo qual um procedimento armazenado estendido funciona é:

  1. Quando um cliente executa um procedimento armazenado estendido, a solicitação é transmitida em fluxo de dados tabulares (TDS) ou Protocolo de Acesso a Objetos Simples (SOAP) da aplicação cliente para o SQL Server.

  2. O SQL Server busca a DLL associada ao procedimento armazenado estendido e carrega a DLL se ela ainda não estiver carregada.

  3. O SQL Server chama o procedimento armazenado estendido solicitado (implementado como uma função dentro da DLL).

  4. O procedimento armazenado estendido repassa conjuntos de resultados e parâmetros de retorno ao servidor por meio da API de Procedimento Armazenado Estendido.

No passado, o Open Data Services era usado para escrever aplicações servidoras, como gateways para ambientes de banco de dados não SQL Server. O SQL Server não suporta as partes obsoletas da API Open Data Services. A única parte da API original de Serviços de Dados Abertos ainda suportada pelo SQL Server são as funções de procedimento armazenado estendido, então a API foi renomeada para API de Procedimentos Armazenados Estendidos.

Com o surgimento das consultas distribuídas e da integração com CLR, a necessidade de aplicações de API de Procedimentos Armazenados Estendidos foi em grande parte substituída.

Se você já tem aplicações gateway, não pode usar as opends60.dll que vêm com o SQL Server para rodar as aplicações. Aplicações de gateway não são mais suportadas.

Procedimentos armazenados estendidos vs. integração com CLR

A integração com CLR oferece uma alternativa mais robusta à escrita de lógica do lado do servidor, que era difícil de expressar ou impossível de escrever no Transact-SQL. Em versões anteriores do SQL Server, os procedimentos armazenados estendidos (XPs) forneciam o único mecanismo disponível para desenvolvedores de aplicativos de banco de dados escreverem tal código.

Com a integração do CLR, a lógica que antes era escrita na forma de procedimentos armazenados é frequentemente melhor expressa como funções de valores de tabela, que permitem que os resultados construídos pela função sejam consultados em SELECT sentencias ao incorporá-las na FROM cláusula.

Para mais informações, veja a visão geral da integração do CLR.

Características de execução de procedimentos armazenados estendidos

A execução de um procedimento armazenado estendido possui as seguintes características:

  • A função de procedimento armazenado estendido é executada sob o contexto de segurança do SQL Server.

  • A função de procedimento armazenado estendido roda no espaço de processos do SQL Server.

  • A thread associada à execução do procedimento armazenado estendido é a mesma usada para a conexão do cliente.

Importante

Antes de adicionar procedimentos armazenados estendidos ao servidor e conceder permissões de execução a outros usuários, o administrador do sistema deve revisar cuidadosamente cada procedimento armazenado estendido para garantir que ele não contenha código nocivo ou malicioso.

Após o carregamento da DLL do procedimento armazenado estendido, a DLL permanece carregada no espaço de endereçamento do servidor até que o SQL Server seja parado ou o administrador descarregue explicitamente a DLL usando DBCC <DLL_name> (FREE).

O procedimento armazenado estendido pode ser executado a partir de Transact-SQL como um procedimento armazenado usando a EXECUTE instrução:

EXECUTE @retval = xp_extendedProcName @param1, @param2 OUTPUT;

Parâmetros

@ Retval

Um valor de retorno.

@ parágrafo 1

Um parâmetro de entrada.

@ param2

Um parâmetro de entrada/saída.

Cuidado

Procedimentos armazenados estendidos oferecem melhorias de desempenho e ampliam a funcionalidade do SQL Server. No entanto, como o DLL de procedimento armazenado estendido e o SQL Server compartilham o mesmo espaço de endereçamento, um procedimento problemático pode afetar negativamente o funcionamento do SQL Server. Embora exceções lançadas pela DLL de procedimento armazenado estendido sejam tratadas pelo SQL Server, é possível danificar áreas de dados do SQL Server. Como precaução de segurança, apenas administradores de sistemas SQL Server podem adicionar procedimentos armazenados estendidos ao SQL Server. Esses procedimentos devem ser cuidadosamente testados antes de serem instalados.

Envie conjuntos de resultados para o servidor com a API de Procedimentos Armazenados Estendidos

Ao enviar um conjunto de resultados para o SQL Server, o procedimento armazenado estendido deve chamar a API apropriada da seguinte forma:

  • A srv_sendmsg função pode ser chamada em qualquer ordem antes ou depois de todas as linhas (se houver) serem com srv_sendrow. Todas as mensagens devem ser enviadas ao cliente antes que o status de conclusão seja enviado com srv_senddone.

  • A srv_sendrow função é chamada uma vez para cada linha enviada ao cliente. Todas as linhas devem ser enviadas ao cliente antes que quaisquer mensagens, valores de status ou status de conclusão sejam enviados com srv_sendmsg, o srv_status argumento de srv_pfield, ou srv_senddone.

  • Enviar uma linha que não tem todas as colunas definidas srv_describe faz com que a aplicação gere uma mensagem de erro informacional e retorne FAIL ao cliente. Nesse caso, a fileira não é enviada.

Criar procedimentos armazenados estendidos

Um procedimento armazenado estendido é uma função em C/C++ com um protótipo:

SRVRETCODE xp_extendedProcName (SRVPROC *);

Usar o prefixo xp_ é opcional. Nomes estendidos de procedimentos armazenados são sensíveis a maiúsculas minúsculas quando referenciados em Transact-SQL instruções, independentemente da página de código/ordem de ordenação instalada no servidor. Quando você constrói uma DLL:

  • Se for necessário um ponto de entrada, escreva uma DllMain função.

    Essa função é opcional. Se você não fornecer isso no código-fonte, o compilador faz o link da própria versão, que não faz nada além de retornar TRUE. Se você fornece uma DllMain função, o sistema operacional chama essa função quando uma thread ou processo se conecta ou se desconecta da DLL.

  • Todas as funções chamadas de fora da DLL (todas as Efunções de procedimentos armazenados estendidos) devem ser exportadas.

    Você pode exportar uma função listando seu nome na EXPORTS seção de um .def arquivo, ou pode prefixar o nome da função no código-fonte com __declspec(dllexport), uma extensão do compilador Microsoft (__declspec() começando com dois sublinhaduras).

Esses arquivos são necessários para criar uma DLL de procedimento armazenado estendido.

File Description
srv.h Arquivo de cabeçalho da API de Procedimento Armazenado Estendido
opends60.lib Biblioteca de importação para opends60.dll

Para criar uma DLL de procedimento armazenado estendido, crie um projeto do tipo Dynamic Link Library. Para mais informações sobre como criar uma DLL, veja a documentação do ambiente de desenvolvimento.

Todas as DLLs de procedimentos armazenados estendidos devem implementar e exportar a seguinte função:

__declspec(dllexport) ULONG __GetXpVersion()
{
   return ODS_VERSION;
}

__declspec(dllexport) é uma extensão de compilador específica da Microsoft. Se seu compilador não suportar essa diretiva, você deve exportar essa função no seu DEF arquivo na EXPORTS seção.

Quando o SQL Server é iniciado com a flag -T260 de rastreamento ou se um usuário com privilégios de administrador do sistema executa DBCC TRACEON (260), e se a DLL de procedimento armazenado estendido não suportar __GetXpVersion(), a seguinte mensagem de aviso é impressa no log de erros (__GetXpVersion() começa com dois sublinhados).

Error 8131: Extended stored procedure DLL '%' does not export __GetXpVersion().

Se a DLL do procedimento armazenado estendido exporta __GetXpVersion(), mas a versão retornada pela função for menor do que a versão exigida pelo servidor, uma mensagem de aviso informando a versão retornada pela função e a versão esperada pelo servidor é impressa no registro de erros. Se você receber essa mensagem, está retornando um valor incorreto de __GetXpVersion(), ou está compilando com uma versão mais antiga de srv.h.

Observação

SetErrorMode, uma função Win32, não deve ser chamada em procedimentos armazenados estendidos.

Procedimentos armazenados estendidos de longa duração devem ser chamados srv_got_attention periodicamente, para que o procedimento possa se encerrar se a conexão for interrompida ou o batch for abortado.

Para depurar uma DLL de procedimento armazenado estendido, copie-a para o diretório do SQL Server \Binn . Para especificar o executável da sessão de depuração, insira o caminho e o nome do arquivo executável do SQL Server (por exemplo, C:\Program Files\Microsoft SQL Server\MSSQL16.MSSQLSERVER\MSSQL\Binn\sqlservr.exe). Para informações sobre sqlservr argumentos, veja Aplicação sqlservr.

Adicionar um procedimento armazenado estendido ao SQL Server

Uma DLL que contém funções de procedimento armazenado estendidas atua como uma extensão do SQL Server. Para instalar a DLL, copie o arquivo para um diretório, como aquele que contém os arquivos DLL padrão do SQL Server (C:\Program Files\Microsoft SQL Server\MSSQL16.0.<x>\MSSQL\Binn por padrão).

Após a DLL do procedimento armazenado estendido ser copiada para o servidor, um administrador do sistema SQL Server deve registrar no SQL Server cada função do procedimento armazenado estendido na DLL. Isso é feito usando o sp_addextendedproc procedimento armazenado do sistema.

Importante

O administrador do sistema deve revisar cuidadosamente um procedimento armazenado estendido para garantir que ele não contenha código prejudicial ou malicioso antes de adicioná-lo ao servidor e conceder permissões de execução a outros usuários. Valide todas as entradas de usuário. Não concatene a entrada do usuário antes de validá-la. Nunca execute um comando construído por uma entrada de usuário inválida.

O primeiro parâmetro de sp_addextendedproc especifica o nome da função, e o segundo parâmetro especifica o nome da DLL na qual essa função reside. Você deve especificar o caminho completo da DLL.

Observação

DLLs existentes que não foram registradas com um caminho completo não funcionam após a atualização para SQL Server 2005 (9.x) ou uma versão posterior. Para corrigir o problema, use sp_dropextendedproc o registro da DLL e depois o reregistre especificando sp_addextendedproc, o caminho completo.

O nome da função especificada em sp_addextendedproc deve ser exatamente o mesmo, incluindo o caso, do nome da função na DLL. Por exemplo, esse comando registra uma função xp_hello, localizada em um dll chamado xp_hello.dll, como um procedimento armazenado estendido do SQL Server:

sp_addextendedproc 'xp_hello', 'c:\Program Files\Microsoft SQL Server\MSSQL13.0.MSSQLSERVER\MSSQL\Binn\xp_hello.dll';

Se o nome da função especificada em sp_addextendedproc não corresponder exatamente ao nome da função na DLL, o novo nome é registrado no SQL Server, mas o nome não é utilizável. Por exemplo, embora xp_Hello esteja registrado como um procedimento armazenado estendido do SQL Server localizado em xp_hello.dll, o SQL Server não consegue encontrar a função na DLL se você usar xp_Hello para chamá-la posteriormente.

-- Register the function (xp_hello) with an initial upper case
sp_addextendedproc 'xp_Hello', 'c:\xp_hello.dll';

-- Use the newly registered name to call the function
DECLARE @txt VARCHAR(33);
EXEC xp_Hello @txt OUTPUT;

Aqui está a mensagem de erro:

Server: Msg 17750, Level 16, State 1, Procedure xp_Hello, Line 1
Could not load the DLL xp_hello.dll, or one of the DLLs it references. Reason: 127(The specified procedure could not be found.).

Se o nome da função especificada em sp_addextendedproc corresponder exatamente ao nome da função na DLL, e a colação da instância do SQL Server for indistinta a maiúsculas e minúsculas, o usuário pode chamar o procedimento armazenado estendido usando qualquer combinação de letras minúsculas e maiúsculas do nome.

-- Register the function (xp_hello)
sp_addextendedproc 'xp_hello', 'c:\xp_hello.dll';

-- The following example succeeds in calling xp_hello
DECLARE @txt VARCHAR(33);
EXEC xp_Hello @txt OUTPUT;

DECLARE @txt VARCHAR(33);
EXEC xp_HelLO @txt OUTPUT;

DECLARE @txt VARCHAR(33);
EXEC xp_HELLO @txt OUTPUT;

Quando a colação da instância do SQL Server é sensível de maiúsculas e contas, o SQL Server não pode chamar o procedimento armazenado estendido se o procedimento for chamado com um caso diferente. Isso é verdade mesmo que tenha sido registrado com exatamente o mesmo nome e colação da função na DLL.

-- Register the function (xp_hello)
sp_addextendedproc 'xp_hello', 'c:\xp_hello.dll';

-- The following example results in an error
DECLARE @txt VARCHAR(33);
EXEC xp_HELLO @txt OUTPUT;

Aqui está a mensagem de erro:

Server: Msg 2812, Level 16, State 62, Line 1

Você não precisa parar e reiniciar o SQL Server.

Consultar procedimentos armazenados estendidos instalados no SQL Server

Um usuário autenticado no SQL Server pode exibir os procedimentos armazenados estendidos atualmente definidos e o nome da DLL à qual cada um pertence, executando o sp_helpextendedproc procedimento do sistema. Por exemplo, o exemplo a seguir retorna a DLL à qual xp_hello pertence:

sp_helpextendedproc 'xp_hello';

Se sp_helpextendedproc for executado sem especificar um procedimento armazenado estendido, todos os procedimentos armazenados estendidos e suas DLLs são exibidos.

Remover um procedimento armazenado estendido do SQL Server

Para eliminar cada função de procedimento armazenado estendido em uma DLL de procedimento armazenado estendido definida pelo usuário, um administrador do sistema SQL Server deve executar o sp_dropextendedproc procedimento armazenado do sistema, especificando o nome da função e o nome da DLL na qual essa função reside. Por exemplo, esse comando remove a função xp_hello, localizada em uma DLL nomeada xp_hello.dll, do SQL Server:

sp_dropextendedproc 'xp_hello';

sp_dropextendedproc Não elimina procedimentos armazenados estendidos do sistema. Em vez disso, o administrador do sistema deve negar EXECUTE permissão para o procedimento armazenado estendido ao papel público .

Descarregar uma DLL de procedimento armazenado estendido

O SQL Server carrega uma DLL de procedimento armazenado estendido assim que uma chamada é feita para uma das funções da DLL. A DLL permanece carregada até que o servidor seja desligado ou até que o administrador do sistema use a DBCC instrução para descarregá-la. Por exemplo, esse comando descarrega o xp_hello.dll, permitindo que o administrador do sistema copie uma versão mais recente desse arquivo para o diretório sem desligar o servidor:

DBCC xp_hello(FREE);

Conteúdo relacionado

  • Last updated on