sp_OACreate (Transact-SQL)

Cria uma instância de um objeto OLE.

Convenções da sintaxe Transact-SQL

Sintaxe

sp_OACreate { progid | clsid } , objecttoken OUTPUT [ , context ] 

Argumentos

• progid
  É o identificador programático (ProgID) do objeto OLE a ser criado. Essa cadeia de caracteres descreve a classe do objeto OLE e tem o formato: 'OLEComponent.Object'

  OLEComponent é o nome de componente do servidor de Automação OLE e Object é o nome do objeto OLE. O objeto OLE especificado deve ser válido e deve aceitar a interface IDispatch.

  Por exemplo, SQLDMO.SQLServer é o ProgID do objeto SQL-DMO do SQLServer. SQL-DMO tem um nome de componente de SQLDMO, o objeto SQLServer é válido e (como todos os objetos SQL-DMO) o objeto SQLServer oferece suporte a IDispatch.

• clsid
  É o CLSID (identificador de classe) do objeto OLE a ser criado. Essa cadeia de caracteres descreve a classe do objeto OLE e tem o formato: '{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}'. O objeto OLE especificado deve ser válido e deve aceitar a interface IDispatch.

  Por exemplo, {00026BA1-0000-0000-C000-000000000046} é o CLSID do objeto SQL-DMO do SQLServer.

• objecttoken OUTPUT
  É o token de objeto retornado e deve ser uma variável local de um tipo de dados int. Esse token de objeto identifica o objeto OLE criado e é usado em chamadas aos procedimentos armazenados de Automação OLE.

• context
  Especifica o contexto de execução no qual o objeto OLE recém-criado é executado. Se especificado, esse valor deve ser um dos seguintes:

  1 = Somente no servidor OLE em processo (.dll).

  4 = Somente no servidor OLE local (.exe).

  5 = Permitido tanto no servidor OLE local como em processo.

  Se não for especificado, o valor padrão será 5. Esse valor é passado como parâmetro dwClsContext da chamada para CoCreateInstance.

  Se um servidor OLE em processo for permitido (usando o valor de contexto de 1 ou 5, ou não especificando um valor de contexto), ele terá acesso à memória e a outros recursos pertencentes ao SQL Server. Um servidor OLE em processo pode danificar a memória ou os recursos do SQL Server e causar resultados imprevisíveis, como uma violação de acesso do SQL Server.

  Ao especificar um valor de contexto de 4, um servidor local OLE não tem acesso a nenhum recurso do SQL Server e não pode danificar a memória nem os recursos do SQL Server.

  Observação
  Os parâmetros deste procedimento armazenado são especificados por posição, e não por nome.

Valores de código de retorno

0 (êxito) ou um número diferente de zero (falha) que é o valor inteiro do HRESULT retornado pelo objeto de Automação OLE.

Para obter mais informações sobre Códigos de Retorno HRESULT, consulte Informações sobre erros e códigos de retorno de automação OLE.

Comentários

Se os procedimentos de automação OLE forem habilitados, uma chamada para sp_OACreate iniciará o ambiente de execução compartilhado de Automação OLE. Para obter mais informações sobre como habilitar a automação OLE, consulte Opção de configuração de servidor Ole Automation Procedures.

O OLE objeto criado é destruído automaticamente no término do lote de instrução Transact-SQL.

Permissões

Exige associação à função de servidor fixa sysadmin.

Exemplos

A.Usando ProgID

O exemplo a seguir cria um objeto SQL-DMO do SQLServer usando sua ProgID.

DECLARE @object int;
DECLARE @hr int;
DECLARE @src varchar(255), @desc varchar(255);
EXEC @hr = sp_OACreate 'SQLDMO.SQLServer', @object OUT;
IF @hr <> 0
BEGIN
   EXEC sp_OAGetErrorInfo @object, @src OUT, @desc OUT 
   raiserror('Error Creating COM Component 0x%x, %s, %s',16,1, @hr, @src, @desc)
    RETURN
END;
GO

B.Usando CLSID

O exemplo a seguir cria um objeto SQL-DMO do SQLServer usando sua CLSID.

DECLARE @object int;
DECLARE @hr int;
DECLARE @src varchar(255), @desc varchar(255);
EXEC @hr = sp_OACreate '{00026BA1-0000-0000-C000-000000000046}',
    @object OUT;
IF @hr <> 0
BEGIN
   EXEC sp_OAGetErrorInfo @object, @src OUT, @desc OUT 
   raiserror('Error Creating COM Component 0x%x, %s, %s',16,1, @hr, @src, @desc)
    RETURN
END;
GO

Consulte também

Referência

Procedimentos armazenados de automação OLE (Transact-SQL)

Script de exemplo de automação OLE

Conceitos

Opção de configuração de servidor Ole Automation Procedures