sp_OAMethod (Transact-SQL)

Article
12/22/2023

S’applique à :SQL Server

Appelle une méthode d'un objet OLE.

Syntaxe

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

Arguments

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

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

returnvalueOUTPUT
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 retourne une valeur unique, spécifiez une variable locale pour returnvalue, qui retourne la valeur de retour de la méthode dans la variable locale ou ne spécifiez pas de valeur de retour, qui retourne la valeur de retour de la méthode au client en tant que jeu de résultats à une seule colonne et à ligne unique.

Si la valeur de retour de méthode est un objet OLE, la valeur de retour doit être une variable locale de type de données int. Un jeton d’objet est stocké dans la variable locale et ce jeton d’objet peut être utilisé avec d’autres procédures stockées OLE Automation.

Lorsque la valeur de retour de méthode est un tableau, si la valeur de retour est spécifiée, elle est définie sur NULL.

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

returnvalue est spécifiée, mais la méthode ne retourne 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 méthode. S’il est spécifié, le paramètre doit être une valeur du type de données approprié.

Pour obtenir la valeur de retour d’un paramètre de sortie, le paramètre 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 de retour d’un paramètre de sortie est ignorée.

S’il est spécifié, parametername doit être le nom du paramètre nommé Microsoft Visual Basic. Notez que @_parametername_is pas une variable locale Transact-SQL. Le signe at (@) est supprimé et parameternameest passé à l’objet OLE comme nom de 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.

Remarque

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

Codet de retour

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 de retour HRESULT, les codes de retour OLE Automation et les informations d’erreur.

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 retourné 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. En d’autres termes, le tableau est retourné en tant que (colonnes).
Un tableau à deux dimensions est retourné 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).

Lorsqu’une valeur de retour de propriété ou une valeur de retour de méthode est un tableau, sp_OAGetProperty ou sp_OAMethod retourne 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 du tableau pour déterminer les types de données et les longueurs de données SQL Server 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 de 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	virgule flottante	devise	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

Vous pouvez également utiliser sp_OAMethod pour obtenir une valeur de propriété.

Autorisations

Nécessite l’appartenance au rôle serveur fixe sysadmin ou l’autorisation d’exécution directement sur cette procédure stockée. Ole Automation Procedures la configuration doit être activée pour utiliser n’importe quelle procédure système liée à OLE Automation.

Exemples

R. Appel d'une méthode

L’exemple suivant appelle la Connect méthode de l’objet SQLServer créé précédemment.

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é

L’exemple suivant obtient la HostName propriété (de l’objet SQLServer précédemment créé) et la stocke 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

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