sp_OAGetProperty (Transact-SQL)
S’applique à : SQL Server
Donne une valeur de propriété d'un objet OLE.
Conventions de la syntaxe Transact-SQL
Syntaxe
sp_OAGetProperty objecttoken , propertyname
[ , propertyvalue OUTPUT ]
[ , index...]
Arguments
objecttoken
Jeton d’objet d’un objet OLE créé précédemment à l’aide de sp_OACreate.
propertyname
Nom de la propriété de l'objet OLE à renvoyer.
propertyvalue OUTPUT
Valeur de la propriété renvoyée. Si elle est spécifiée, il doit s'agir d'une variable locale du type de données approprié.
Si la propriété retourne un objet OLE, propertyvalue 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.
Si la propriété retourne une valeur unique, spécifiez une variable locale pour la valeur de propriété, qui retourne la valeur de propriété dans la variable locale ; ou ne spécifiez pas la valeur de propriété, qui retourne la valeur de propriété au client en tant que jeu de résultats à une seule colonne et à ligne unique.
Lorsque la propriété retourne un tableau, si la valeur de propriété est spécifiée, elle a la valeur NULL.
Si la valeur de propriété est spécifiée, mais que la propriété ne retourne pas de valeur, une erreur se produit. Si la propriété renvoie un tableau qui comprend plus de deux dimensions, une erreur se produit.
index
Paramètre d'index. Si spécifié, l’index doit être une valeur du type de données approprié.
Certaines propriétés possèdent des paramètres. Elles sont désignées sous le nom de propriétés indexées, et les paramètres s'appellent des paramètres d'index. Une propriété peut posséder plusieurs paramètres d'index.
Remarque
Les paramètres pour cette procédure stockée sont spécifiés par position et non pas 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, consultez OLE Automation Return Codes and Error Information.
Jeux de résultats
Si la propriété renvoie 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. Autrement dit, le tableau est renvoyé sous forme de 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. Utilisation d'une variable locale
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_OAGetProperty @object, 'HostName', @property OUT;
IF @hr <> 0
BEGIN
EXEC sp_OAGetErrorInfo @object
RETURN
END
PRINT @property;
B. Utilisation d'un jeu de résultats
L’exemple suivant obtient la HostName
propriété (de l’objet SQLServer créé précédemment) et la retourne au client en tant que jeu de résultats.
EXEC @hr = sp_OAGetProperty @object, 'HostName';
IF @hr <> 0
BEGIN
EXEC sp_OAGetErrorInfo @object
RETURN
END;
Voir aussi
Procédures stockées OLE Automation (Transact-SQL)
Exemple de script OLE Automation