sp_OAGetProperty (Transact-SQL)

Syntaxe

sp_OAGetProperty objecttoken , propertyname 
    [ , propertyvalue OUTPUT ]
    [ , index...] 

Arguments

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

• propertyname
  Nom de la propriété de l'objet OLE à renvoyer.

• propertyvalueOUTPUT
  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, le paramètre propertyvalue doit être une variable locale du 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.

  Si la propriété retourne une valeur unique, soit elle spécifie une variable locale pour le paramètre propertyvalue, ce qui retourne la valeur de la propriété dans la variable locale, soit elle ne spécifie pas le paramètre propertyvalue, ce qui retourne la valeur de la propriété au client sous la forme d'un jeu de résultats formé d'une seule colonne et d'une seule ligne.

  Quand la propriété retourne un tableau, si le paramètre propertyvalue est spécifié, il prend la valeur NULL.

  Si le paramètre propertyvalue est spécifié, 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. S'il est spécifié, 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.

  Notes

  Les paramètres pour cette procédure stockée sont spécifiés par position, et non par nom.

Valeurs des codes renvoyés

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, consultez Codes de retour OLE Automation et informations sur les erreurs.

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 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 ensemble 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.

Notes

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

Autorisations

Nécessite l'appartenance au rôle serveur fixe sysadmin.

Exemples

A. Utilisation d'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

EXEC @hr = sp_OAGetProperty @object, 'HostName'
IF @hr <> 0
BEGIN
   EXEC sp_OAGetErrorInfo @object
    RETURN
END

Voir aussi

Référence