sp_OAMethod (Transact-SQL)

Sintaxis

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

Argumentos

• objecttoken
  Es el token de un objeto OLE creado anteriormente mediante sp_OACreate.

• methodname
  Es el nombre de método del objeto OLE al que se llamará.

• returnvalue OUTPUT
  Es el valor devuelto del método del objeto OLE. Si se especifica, debe ser una variable local del tipo de datos apropiado.

  Si el método devuelve un valor único, especifique una variable local para returnvalue, lo que devuelve el valor del método en la variable local, o no especifique returnvalue, lo que devuelve el valor del método al cliente como un conjunto de resultados de columna única y fila única.

  Si el valor devuelto del método es un objeto OLE, returnvalue debe ser una variable local del tipo de datos int. En la variable local se almacena un token del objeto que se puede utilizar con otros procedimientos almacenados de automatización OLE.

  Cuando el valor devuelto del método es una matriz, si se especifica returnvalue, se establece en NULL.

  Se genera un error si se da uno de los casos siguientes:

  • Se especifica returnvalue, pero el método no devuelve ningún valor.

  • El método devuelve una matriz con más de dos dimensiones.

  • El método devuelve una matriz como parámetro de salida.

• [ @parametername**=** ] parameter[ OUTPUT ]
  Es un parámetro del método. Si se especifica parameter, debe ser un valor del tipo de datos adecuado.

  Para obtener el valor devuelto de un parámetro de salida, parameter debe ser una variable local del tipo de datos apropiado y se debe especificar OUTPUT. Si se especifica un parámetro constante o no se especifica OUTPUT, se omite cualquier valor devuelto del parámetro de salida.

  Si se especifica parametername, debe ser el nombre del parámetro con nombre de MicrosoftVisual Basic. Tenga en cuenta que @parameternameno es una variable local de Transact-SQL. Se quita la arroba (@) y se pasa parameternameal objeto OLE como el nombre del parámetro. Todos los parámetros con nombre deben especificarse después de especificar todos los parámetros posicionales.

• n
  Es un marcador de posición que indica que se pueden especificar varios parámetros.

  [!NOTA]

  @parametername puede ser un parámetro con nombre debido a que forma parte del método especificado y se pasa a través del objeto. Los demás parámetros de este procedimiento almacenado se especifican por la posición, no por el nombre.

Valores de código de retorno

0 (correcto) o un valor distinto de cero (error) que es el valor entero del HRESULT devuelto por el objeto de automatización OLE.

Para obtener más información sobre los códigos de retorno HRESULT, vea Códigos de retorno e información de error de automatización OLE.

Conjuntos de resultados

Si el valor devuelto del método es una matriz con una o dos dimensiones, se devuelve la matriz al cliente como un conjunto de resultados:

• Se devuelve al cliente una matriz unidimensional como un conjunto de resultados de fila única con tantas columnas como elementos tenga la matriz. Es decir, la matriz se devuelve como (columnas).

• Se devuelve al cliente una matriz bidimensional como un conjunto de resultados con tantas columnas como elementos haya en la primera dimensión de la matriz y con tantas filas como elementos haya en la segunda dimensión de la matriz. Es decir, la matriz se devuelve como (columnas, filas).

Cuando un valor devuelto por una propiedad o por un método es una matriz, sp_OAGetProperty o sp_OAMethod devuelven un conjunto de resultados al cliente. Los parámetros de salida del método no pueden ser matrices. Estos procedimientos recorren todos los valores de datos de la matriz para determinar los tipos de datos y las longitudes de datos de SQL Server adecuados para cada columna del conjunto de resultados. Para una columna en particular, estos procedimientos utilizan el tipo de datos y la longitud necesarios para representar todos los valores de los datos de la columna.

Cuando todos los valores de datos de una columna comparten el mismo tipo de datos, se utiliza ese tipo para toda la columna. Cuando los valores de datos de una columna utilizan tipos de datos diferentes, el tipo de datos de toda la columna se elige según el siguiente cuadro.

Notas

También se puede utilizar sp_OAMethod para obtener un valor de propiedad.

Permisos

Requiere la pertenencia a la función fija de servidor sysadmin.

Ejemplos

A. Llamar a un método

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

B. Obtener una propiedad

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

Vea también

Referencia