sp_OAMethod (Transact-SQL)

  • Artigo

Aplica-se: SQL Server

Chama um método de um objeto OLE.

Convenções de sintaxe de 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.

nome do método

O nome do método do objeto OLE a ser chamado.

returnvalue SAÍDA

O valor retornado 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, que retorna o valor de retorno do método na variável local; ou
  • Não especifique returnvalue, que retorna o valor de retorno do método para o cliente como um conjunto de resultados de coluna única e linha única.

Se o valor retornado 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 esse token de objeto pode ser usado com outros procedimentos armazenados de Automação OLE.

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

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

  • returnValue é especificado, mas o método não retorna 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 [ = ] parâmetro [ SAÍDA ]

Um parâmetro de método. Se especificado, parameter deve ser um valor do tipo de dados apropriado.

Para obter o valor retornado 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 retornado de um parâmetro de saída será ignorado.

Se especificado, parametername deve ser o nome do parâmetro nomeado do Microsoft Visual Basic. @parametername não é uma variável local Transact-SQL. O sinal de arroba (@) é removido e parametername é passado para o objeto OLE como o nome do 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 indicando que vários parâmetros podem ser especificados.

Observação

@parametername pode ser um parâmetro nomeado porque 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 do código de retorno

0 (sucesso) 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, códigos de retorno de automação OLE e informações de erro.

Conjunto 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 um valor de retorno de propriedade ou de método é uma matriz, sp_OAGetProperty ou sp_OAMethod retorna um conjunto de resultados para o cliente. (Os parâmetros de saída do método não podem ser matrizes.) Esses procedimentos examinam todos os valores de dados na matriz para determinar os tipos de dados e comprimentos de dados apropriados do SQL Server 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 um valor de propriedade.

Permissões

Requer associação na função de servidor fixa sysadmin ou permissão de execução diretamente nesse procedimento armazenado. A opção de configuração do servidor Ole Automation Procedures deve ser habilitada para usar qualquer procedimento do sistema relacionado ao OLE Automation.

Exemplos

R. Chamar um método

O exemplo a seguir chama o Connect método 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. Obter um imóvel

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

DECLARE @property VARCHAR(255);

EXEC @hr = sp_OAMethod @object,
    'HostName',
    @property OUTPUT;

IF @hr <> 0
BEGIN
    EXEC sp_OAGetErrorInfo @object

    RETURN
END;

PRINT @property;

Conteúdo relacionado