sp_OAMethod (Transact-SQL)sp_OAMethod (Transact-SQL)

APLICA-SE A: simSQL Server nãoBanco de Dados SQL do Azure nãoSQL Data Warehouse do Azure nãoParallel Data Warehouse APPLIES TO: yesSQL Server noAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Chama um método de um objeto OLE.Calls a method of an OLE object.

Ícone de link do tópico Convenções de sintaxe de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxeSyntax

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

ArgumentosArguments

objecttokenobjecttoken
É o token de objeto de um objeto OLE que foi criado anteriormente usando sp_OACreate.Is the object token of an OLE object that was previously created by using sp_OACreate.

MethodNamemethodname
É o nome de método do objeto OLE a ser chamado.Is the method name of the OLE object to call.

ReturnValuesaídareturnvalue OUTPUT
É o valor de retorno do método do objeto OLE.Is the return value of the method of the OLE object. Se for especificado, deverá ser uma variável local do tipo de dados apropriado.If specified, it must be a local variable of the appropriate data type.

Se o método retornar um único valor, especifique uma variável local para returnvalue, que retorna o método retorna o valor na variável local, ou seja, não especifique returnvalue, que retorna o método retorna o valor ao cliente como um conjunto de resultados de coluna única e uma linha.If the method returns a single value, either specify a local variable for returnvalue, which returns the method return value in the local variable, or do not specify returnvalue, which returns the method return value to the client as a single-column, single-row result set.

Se o método de valor de retorno é um objeto OLE, returnvalue deve ser uma variável local de 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.If the method return value is an OLE object, returnvalue must be a local variable of data type int. An object token is stored in the local variable, and this object token can be used with other OLE Automation stored procedures.

Quando o método de valor de retorno é uma matriz, se returnvalue for especificado, ele é definido como NULL.When the method return value is an array, if returnvalue is specified, it is set to NULL.

Um erro será gerado quando qualquer um dos seguintes ocorrer:An error is raised when any one of the following occurs:

  • ReturnValue for especificado, mas o método não retorna um valor.returnvalue is specified, but the method does not return a value.

  • O método retornar uma matriz com mais de duas dimensões.The method returns an array with more than two dimensions.

  • O método retornar uma matriz como um parâmetro de saída.The method returns an array as an output parameter.

[ _@parametername = ] parameter[ OUTPUT ] É um parâmetro de método.[ _@parametername = ] parameter[ OUTPUT ] Is a method parameter. Se especificado, parâmetro deve ser um valor de tipo de dados apropriado.If specified, parameter must be a value of the appropriate data type.

Para obter o valor retornado de um parâmetro de saída parâmetro deve ser uma variável local de tipo de dados apropriado, e saída deve ser especificado.To obtain the return value of an output parameter, parameter must be a local variable of the appropriate data type, and OUTPUT must be specified. Se um parâmetro constante for especificado, ou se saída não for especificado, qualquer retornar o valor de um parâmetro de saída é ignorado.If a constant parameter is specified, or if OUTPUT is not specified, any return value from an output parameter is ignored.

Se especificado, parametername deve ser o nome da MicrosoftMicrosoft Visual BasicVisual Basic parâmetro nomeado.If specified, parametername must be the name of the MicrosoftMicrosoft Visual BasicVisual Basic named parameter. Observe que @ _parametername_is não um Transact-SQLTransact-SQL variável local.Note that @_parametername_is not a Transact-SQLTransact-SQL local variable. O sinal de arroba ( @ ) é removido, e parameternameé passado para o objeto OLE como o nome do parâmetro.The at sign (@) is removed, and parameternameis passed to the OLE object as the parameter name. Todos os parâmetros nomeados deverão ser especificados depois que todos os parâmetros posicionais forem especificados.All named parameters must be specified after all positional parameters are specified.

nn
É um espaço reservado que indica que vários parâmetros podem ser especificados.Is a placeholder indicating that multiple parameters can be specified.

Observação

@parametername* pode ser um parâmetro nomeado porque ele faz parte do método especificado e é passado para o objeto.@parametername* can be a named parameter because it is part of the specified method and is passed through to the object. Os outros parâmetros deste procedimento armazenado são especificados por posição, não por nome.The other parameters for this stored procedure are specified by position, not name.

Valores do código de retornoReturn Code Values

0 (êxito) ou um número diferente de zero (falha) que é o valor inteiro do HRESULT retornado pelo objeto de Automação OLE.0 (success) or a nonzero number (failure) that is the integer value of the HRESULT returned by the OLE Automation object.

Para obter mais informações sobre códigos de retorno HRESULT OLE automação códigos de retorno e informações de erro.For more information about HRESULT Return Codes, OLE Automation Return Codes and Error Information.

Conjuntos de resultadosResult Sets

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:If the method return value is an array with one or two dimensions, the array is returned to the client as a result set:

  • Uma matriz unidimensional é retornada ao cliente como um conjunto de resultados de uma linha, com tantas colunas quanto houver elementos na matriz.A one-dimensional array is returned to the client as a single-row result set with as many columns as there are elements in the array. Em outras palavras, a matriz é retornada como (colunas).In other words, the array is returned as (columns).

  • 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.A two-dimensional array is returned to the client as a result set with as many columns as there are elements in the first dimension of the array and with as many rows as there are elements in the second dimension of the array. Em outras palavras, a matriz é retornada como (colunas, linhas).In other words, the array is returned as (columns, rows).

Quando o valor de retorno de uma propriedade ou valor de retorno de método é uma matriz sp_OAGetProperty ou sp_OAMethod retorna um conjunto de resultados para o cliente.When a property return value or method return value is an array, sp_OAGetProperty or sp_OAMethod returns a result set to the client. (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 ServerSQL Server e os tamanhos dos dados a serem usados para cada coluna no conjunto de resultados.(Method output parameters cannot be arrays.) These procedures scan all the data values in the array to determine the appropriate SQL ServerSQL Server data types and data lengths to use for each column in the result set. 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.For a particular column, these procedures use the data type and length required to represent all data values in that column.

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.When all data values in a column share the same data type, that data type is used for the whole column. 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.When data values in a column are of different data types, the data type of the whole column is chosen based on the following chart.

intint floatfloat moneymoney datetimedatetime varcharvarchar NVARCHARnvarchar
intint intint floatfloat moneymoney varcharvarchar varcharvarchar nvarcharnvarchar
floatfloat floatfloat floatfloat moneymoney varcharvarchar varcharvarchar nvarcharnvarchar
moneymoney moneymoney moneymoney moneymoney varcharvarchar varcharvarchar nvarcharnvarchar
datetimedatetime varcharvarchar varcharvarchar varcharvarchar datetimedatetime varcharvarchar nvarcharnvarchar
varcharvarchar varcharvarchar varcharvarchar varcharvarchar varcharvarchar varcharvarchar nvarcharnvarchar
nvarcharnvarchar nvarcharnvarchar nvarcharnvarchar nvarcharnvarchar nvarcharnvarchar nvarcharnvarchar nvarcharnvarchar

ComentáriosRemarks

Você também pode usar sp_OAMethod para obter um valor da propriedade.You can also use sp_OAMethod to get a property value.

PermissõesPermissions

Requer associação na sysadmin função de servidor fixa ou permissão de execução diretamente nesse procedimento armazenado.Requires membership in the sysadmin fixed server role or execute permission directly on this Stored Procedure. Ole Automation Procedures configuração deve estar habilitado usar qualquer procedimento de sistema relacionado à automação OLE.Ole Automation Procedures configuration must be enabled to use any system procedure related to OLE Automation.

ExemplosExamples

A.A. Chamando um métodoCalling a method

A exemplo a seguir chama o Connect método criado anteriormente SQLServer objeto.The following example calls the Connect method of the previously created SQLServer object.

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

B.B. Obtendo uma propriedadeGetting a property

O exemplo a seguir obtém a HostName propriedade (da criado anteriormente SQLServer objeto) e o armazena em uma variável local.The following example gets the HostName property (of the previously created SQLServer object) and stores it in a local variable.

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émSee Also

OLE procedimentos armazenados de automação (Transact-SQL) OLE Automation Stored Procedures (Transact-SQL)
Script de exemplo de automaçãoOLE Automation Sample Script