sp_OAMethod (Transact-SQL)

Appelle une méthode d'un objet OLE.

Conventions de la syntaxe de Transact-SQL

Syntaxe

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

Arguments

• objecttoken
  Jeton d'objet d'un objet OLE précédemment créé à l'aide de sp_OACreate.

• methodname
  Nom de la méthode de l'objet OLE à appeler.

• returnvalue OUTPUT
  Valeur renvoyée de la méthode de l'objet OLE. Si elle est spécifiée, il doit s'agir d'une variable locale du type de données approprié.

  Si la méthode renvoie une valeur unique, soit elle spécifie une variable locale pour le paramètre returnvalue, ce qui renvoie dans la variable locale la valeur renvoyée par la méthode, soit elle ne spécifie pas le paramètre returnvalue, ce qui renvoie au client la valeur renvoyée par la méthode sous la forme d'un jeu de résultats formé d'une seule colonne et d'une seule ligne.

  Si la valeur renvoyée par la méthode est un objet OLE, le paramètre returnvalue doit être une variable locale de type de données int. Un jeton d'objet est stocké dans la variable locale et il peut être utilisé avec d'autres procédures stockées OLE Automation.

  Quand la valeur renvoyée par la méthode est un tableau, si le paramètre returnvalue est spécifié, il prend la valeur NULL.

  Une erreur est générée lorsqu'un des événements suivants survient :

  • Le paramètre returnvalue est spécifié, mais la méthode ne renvoie pas de valeur.

  • La méthode renvoie un tableau qui possède plus de deux dimensions.

  • La méthode renvoie un tableau comme paramètre de sortie.

• [ @parametername**=** ] parameter[ OUTPUT ]
  Paramètre de la méthode. S'il est spécifié, parameter doit être une valeur du type de données approprié.

  Pour lire la valeur renvoyée d'un paramètre de sortie, parameter doit être une variable locale du type de données approprié et OUTPUT doit être spécifié. Si un paramètre constant est spécifié ou si OUTPUT n'est pas spécifié, toute valeur renvoyée à partir d'un paramètre de sortie est ignorée.

  S'il est indiqué, parametername doit être le nom du paramètre nommé Microsoft Visual Basic. Notez que @parametername n'est pas une variable locale Transact-SQL. L'arobase (@) est supprimée et parameternameest transmis à l'objet OLE en tant que nom du paramètre. Tous les paramètres nommés doivent être spécifiés après tous les paramètres positionnels.

• n
  Marque de réservation indiquant que plusieurs paramètres peuvent être spécifiés.

  Notes

  @parametername peut être un paramètre nommé car il fait partie de la méthode spécifiée et qu'il est transmis à l'objet. Les autres paramètres pour cette procédure stockée sont spécifiés par position, et non par nom.

Retourne les valeurs du code

0 (succès) ou un nombre différent de zéro (échec) qui représente la valeur entière de HRESULT renvoyée par l'objet OLE Automation.

Pour plus d'informations sur les codes renvoyés HRESULT, voir Codes de retour OLE Automation et informations sur les erreurs.

Jeux de résultats

Si la valeur renvoyée par la méthode est un tableau à une ou deux dimensions, le tableau sera renvoyé au client sous la forme d'un jeu de résultats :

• Un tableau à une dimension est renvoyé au client sous la forme d'un jeu de résultats d'une seule ligne avec autant de colonnes qu'il y a d'éléments dans le tableau. Autrement dit, le tableau est renvoyé sous forme de colonnes.

• Un tableau à deux dimensions est renvoyé au client sous la forme d'un jeu de résultats qui contient autant de colonnes qu'il y a d'éléments dans la première dimension du tableau et autant de lignes qu'il y a d'éléments dans la seconde dimension du tableau. Autrement dit, le tableau est renvoyé sous la forme (colonnes, lignes).

Lorsque la valeur de retour d'une propriété ou méthode est un tableau, sp_OAGetProperty ou sp_OAMethod renvoie un jeu de résultats au client. (Les paramètres de sortie de la méthode ne peuvent pas être des tableaux). Ces procédures analysent toutes les valeurs de données dans le tableau pour déterminer les types de données SQL Server et les longueurs de données appropriés à utiliser pour chaque colonne du jeu de résultats. Pour une colonne particulière, ces procédures utilisent le type de données et la longueur requis pour représenter toutes les valeurs des données de cette colonne.

Lorsque toutes les valeurs des données d'une colonne partagent le même type de données, ce type est utilisé pour toute la colonne. Lorsque les valeurs de données d'une colonne utilisent des types de données différents, le choix du type pour l'ensemble de la colonne se fait sur la base du tableau suivant.

	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

Notes

Il est possible d'utiliser également sp_OAMethod pour obtenir une valeur de la propriété.

Autorisations

Nécessite l'appartenance en tant que membre du rôle de serveur fixe sysadmin.

Exemples

A. Appel d'une méthode

Dans cet exemple la méthode Connect de l'objet SQLServer créé précédemment est appelée.

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

B. Obtention d'une propriété

Dans cet exemple la propriété HostName (de l'objet SQLServer créé précédemment) est lue et stockée dans une variable locale.

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

Voir aussi

Référence

Procédures stockées OLE Automation (Transact-SQL)

Exemple de script OLE Automation