sp_OAMethod (Transact-SQL)

Se aplica a: SQL Server

Llama a un método de un objeto OLE.

Convenciones de sintaxis de Transact-SQL

Sintaxis

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

Argumentos

objecttoken

Token de objeto de un objeto OLE creado anteriormente mediante sp_OACreate.

methodname

Nombre del método del objeto OLE al que se va a llamar.

returnvalue OUTPUT

Valor devuelto del método del objeto OLE. Si se especifica, debe ser una variable local del tipo de datos adecuado.

Si el método devuelve un valor único, cualquiera de los siguientes:

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

Si el valor devuelto del método es un objeto OLE, returnvalue debe ser una variable local de tipo de datos int. Un token de objeto se almacena en la variable local y este token de objeto se puede usar con otros procedimientos almacenados de OLE Automation.

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 un 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 = ] parámetro [ OUTPUT ]

Parámetro de método. Si se especifica, el parámetro debe ser un valor del tipo de datos adecuado.

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

Si se especifica, parametername debe ser el nombre del parámetro con nombre de Microsoft Visual Basic. @parametername no es una variable local de Transact-SQL. El signo at (@) se quita y parametername se pasa al objeto OLE como nombre del parámetro. Todos los parámetros con nombre deben especificarse después de especificar todos los parámetros de posición.

n

Marcador de posición que indica que se pueden especificar varios parámetros.

Valores de código de retorno

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

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

Conjunto 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 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 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. En otras palabras, 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 devuelve un conjunto de resultados al cliente. (Los parámetros de salida del método no pueden ser matrices). Estos procedimientos examinan todos los valores de datos de la matriz para determinar los tipos de datos y las longitudes de datos de SQL Server adecuados que se usarán para cada columna del conjunto de resultados. Para una columna determinada, estos procedimientos utilizan el tipo y la longitud de datos 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 como se muestra a continuación.

Comentarios

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

Permisos

Requiere la pertenencia al rol fijo de servidor sysadmin o ejecutar el permiso directamente en este procedimiento almacenado. La opción de configuración del servidor Procedimientos de Ole Automation debe estar habilitada para usar cualquier procedimiento del sistema relacionado con OLE Automation.

Ejemplos

A Llamada a un método

En el ejemplo siguiente se llama al Connect método del objeto SQLServer creado 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. Obtener una propiedad

En el ejemplo siguiente se obtiene la HostName propiedad (del objeto creado SQLServer anteriormente) y se almacena en una variable 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;

Contenido relacionado

• Procedimientos almacenados de Automatización OLE (Transact-SQL)
• Ejemplo de script de automatización OLE