sp_OAMethod (Transact-SQL)

Chama um método de um objeto OLE.

Aplica-se a: SQL Server (SQL Server 2008 à versão atual).

Convenções da sintaxe Transact-SQL

Sintaxe

sp_OAMethod objecttoken , methodname
    [ , returnvalue OUTPUT ] 
    [ , [ @parametername = ] parameter [ OUTPUT ] [ ...n ] ] 

Argumentos

• objecttoken
  É o token de objeto de um objeto OLE que foi criado anteriormente usando sp_OACreate.

• methodname
  É o nome de método do objeto OLE a ser chamado.

• returnvalue OUTPUT
  É o valor de retorno do método do objeto OLE. Se for especificado, deverá ser uma variável local do tipo de dados apropriado.

  Se o método retornar um único valor, especifique uma variável local para returnvalue, o que retorna o valor de retorno do método na variável local, ou não especifique returnvalue, o que retorna o valor de retorno do método para o cliente como um conjunto de resultados com uma coluna e uma linha.

  Se o valor de retorno do método for um objeto OLE, returnvalue deverá ser uma variável local do tipo de dados int. Um token de objeto é armazenado na variável local e pode ser usado com outros procedimentos armazenados de automação OLE.

  Quando o valor de retorno do método for uma matriz, se returnvalue for especificado, será definido como NULL.

  Um erro será gerado quando qualquer um dos seguintes ocorrer:

  • returnvalue for especificado, mas o método não retornar um valor.

  • O método retornar uma matriz com mais de duas dimensões.

  • O método retornar uma matriz como um parâmetro de saída.

• [ @parametername**=** ] parameter[ OUTPUT ]
  É um parâmetro de método. Se for especificado, parameter deverá ser um valor do tipo de dados apropriado.

  Para obter o valor de retorno de um parâmetro de saída, parameter deve ser uma variável local do tipo de dados apropriado e OUTPUT deve ser especificado. Se um parâmetro constante for especificado ou se OUTPUT não for especificado, qualquer valor de retorno de um parâmetro de saída será ignorado.

  Se for especificado, parametername deverá ser o nome do parâmetro nomeado do Microsoft Visual Basic. Observe que @parametername não é uma variável local Transact-SQL. A arroba (@) é removida e parametername é passado para o objeto OLE como o nome de parâmetro. Todos os parâmetros nomeados deverão ser especificados depois que todos os parâmetros posicionais forem especificados.

• n
  É um espaço reservado que indica que vários parâmetros podem ser especificados.

  Dica

  @parametername pode ser um parâmetro nomeado porque ele faz parte do método especificado e é passado para o objeto.Os outros parâmetros deste procedimento armazenado são especificados por posição, 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.

Conjuntos de resultados

Se o valor de retorno do método for uma matriz com uma ou duas dimensões, a matriz será retornada ao cliente como um conjunto de resultados:

• Uma matriz unidimensional é retornada ao cliente como um conjunto de resultados de uma linha, com tantas colunas quanto houver elementos na matriz. Em outras palavras, a matriz é retornada como (colunas).

• Uma matriz bidimensional é retornada ao cliente como um conjunto de resultados com tantas colunas quanto houver elementos na primeira dimensão da matriz e com tantas linhas quanto houver elementos na segunda dimensão da matriz. Em outras palavras, a matriz é retornada como (colunas, linhas).

Quando o valor de retorno de uma propriedade ou o valor de retorno de um método for uma matriz, sp_OAGetProperty ou sp_OAMethod retornará um conjunto de resultados ao cliente. (Os parâmetros de saída de método não podem ser matrizes.) Esses procedimentos examinam todos os valores de dados na matriz para determinar os tipos de dados apropriados do SQL Server e os tamanhos dos dados a serem usados para cada coluna no conjunto de resultados. Para uma coluna específica, esses procedimentos usam o tipo de dados e o tamanho necessários para representar todos os valores de dados nesta coluna.

Quando todos os valores de dados em uma coluna compartilharem o mesmo tipo de dados, esse tipo de dados será usado para a coluna inteira. Quando os valores de dados em uma coluna forem de tipos de dados diferentes, o tipo de dados da coluna inteira será escolhido com base no quadro a seguir.

	int	float	money	datetime	varchar	nvarchar
int	int	float	money	varchar	varchar	nvarchar
float	float	float	money	varchar	varchar	nvarchar
money	money	money	money	varchar	varchar	nvarchar
datetime	varchar	varchar	varchar	datetime	varchar	nvarchar
varchar	varchar	varchar	varchar	varchar	varchar	nvarchar
nvarchar	nvarchar	nvarchar	nvarchar	nvarchar	nvarchar	nvarchar

Comentários

Você também pode usar sp_OAMethod para obter o valor de uma propriedade.

Permissões

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

Exemplos

A.Chamando um método

O exemplo a seguir chama o método Connect do objeto SQLServer criado anteriormente.

EXEC @hr = sp_OAMethod @object, 'Connect', NULL, 'my_server',
    'my_login', 'my_password';
IF @hr <> 0
BEGIN
   EXEC sp_OAGetErrorInfo @object
    RETURN
END;

B.Obtendo uma propriedade

O exemplo a seguir obtém a propriedade HostName (do objeto SQLServer criado anteriormente) e a armazena em uma variável local.

DECLARE @property varchar(255);
EXEC @hr = sp_OAMethod @object, 'HostName', @property OUT;
IF @hr <> 0
BEGIN
   EXEC sp_OAGetErrorInfo @object
    RETURN
END;
PRINT @property;

Consulte também

Referência

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

Script de exemplo de automação OLE