sp_OAMethod (Transact-SQL)

Ruft eine Methode eines OLE-Objekts auf.

Gilt für: SQL Server (SQL Server 2008 bis aktuelle Version).

Transact-SQL-Syntaxkonventionen

Syntax

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

Argumente

• objecttoken
  Das Objekttoken eines zuvor mit sp_OACreate erstellten OLE-Objekts.

• methodname
  Der Name der Methode des OLE-Objekts, das aufgerufen wird.

• returnvalue AUSGABE
  Der Rückgabewert der Methode des OLE-Objekts. Wenn angegeben, muss es sich um eine lokale Variable vom entsprechenden Datentyp handeln.

  Wenn die Methode einen einzigen Wert zurückgibt, geben Sie eine lokale Variable für returnvalue an, womit der Methodenrückgabewert in der lokalen Variablen zurückgegeben wird, oder geben Sie returnvalue nicht an, womit der Methodenrückgabewert als einspaltiges, einzeiliges Resultset an den Client zurückgegeben wird.

  Wenn der Methodenrückgabewert ein OLE-Objekt ist, müssen Sie für returnvalue eine lokale Variable vom Datentyp int angeben. Ein Objekttoken wird in der lokalen Variable gespeichert, und dieses Objekttoken kann in anderen gespeicherten Prozeduren der OLE-Automatisierung verwendet werden.

  Gibt die Methode ein Array zurück, wird returnvalue, sofern angegeben, auf NULL festgelegt.

  Unter folgenden Bedingungen wird ein Fehler ausgegeben:

  • returnvalue ist angegeben, aber die Methode gibt keinen Wert zurück.

  • Die Methode gibt ein Array mit mehr als zwei Dimensionen zurück.

  • Die Methode gibt ein Array als Ausgabeparameter zurück.

• [ @parametername**=** ] parameter[ OUTPUT ]
  Ein Parameter der Methode. Falls angegeben, muss parameter eine Variable vom entsprechenden Datentyp sein.

  Um den Rückgabewert eines Ausgabeparameters zu erhalten, muss parameter eine lokale Variable vom entsprechenden Datentyp sein, und OUTPUT muss angegeben werden. Ist der Parameter eine Konstante oder wird OUTPUT nicht angegeben, wird der Rückgabewert eines Ausgabeparameters ignoriert.

  Falls angegeben, muss parametername der Name des benannten Microsoft Visual Basic-Parameters sein. Beachten Sie, dass **@**parametername keine lokale Transact-SQL-Variable ist. Das @-Zeichen wird entfernt, und parametername wird als Parametername an das OLE-Objekt übergeben. Alle benannten Parameter müssen nach den Positionsparametern angegeben werden.

• n
  Ein Platzhalter, der anzeigt, dass mehrere Parameter angegeben werden können.

  Hinweis

  @parametername kann ein benannter Parameter sein, weil er Bestandteil der angegebenen Methode ist und an das Objekt übergeben wird.Die anderen Parameter für diese gespeicherte Prozedur werden nicht nach dem Namen, sondern nach der Position angegeben.

Rückgabecodewerte

0 (Erfolg) oder eine Zahl ungleich Null (Fehler), die dem ganzzahligen Wert von HRESULT entspricht, der vom OLE-Automatisierungsobjekt zurückgegeben wird.

Weitere Informationen zu HRESULT-Rückgabecodes finden Sie unter Rückgabecodes und Fehlerinformationen der OLE-Automatisierung.

Resultsets

Wenn die Methode ein Array mit ein oder zwei Dimensionen zurückgibt, wird das Array dem Client folgendermaßen als Resultset zurückgegeben:

• Ein eindimensionales Array wird dem Client als einzeiliges Resultset zurückgegeben, das so viele Spalten wie Elemente im Array enthält. Das Array wird also als (Spalten) zurückgegeben.

• Ein zweidimensionales Array wird dem Client als Resultset zurückgegeben, dessen Anzahl an Spalten der Anzahl der Elemente in der ersten Dimension des Arrays entspricht und dessen Anzahl an Zeilen der Anzahl der Elemente in der zweiten Dimension des Arrays entspricht. Das Array wird also als (Spalten, Zeilen) zurückgegeben.

Wenn der Rückgabewert für eine Eigenschaft oder eine Methode einem Array entspricht, gibt die Methode sp_OAGetProperty oder sp_OAMethod dem Client ein Resultset zurück. (Ausgabeparameter für Methoden können nicht einem Array entsprechen.) Diese Prozeduren durchsuchen alle Datenwerte des Arrays, um die geeigneten SQL Server-Datentypen und -Datenlängen für jede Spalte des Resultsets zu ermitteln. Für eine bestimmte Spalte verwenden diese Prozeduren den Datentyp und die -länge, die erforderlich sind, um alle Datenwerte in dieser Spalte darzustellen.

Wenn alle Datenwerte einer Spalte denselben Datentyp aufweisen, wird dieser Datentyp für die gesamte Spalte verwendet. Wenn Datenwerte in einer Spalte unterschiedliche Datentypen verwenden, wird der Datentyp für die gesamte Spalte entsprechend der folgenden Tabelle ausgewählt.

	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

Hinweise

Sie können einen Eigenschaftswert auch mit sp_OAMethod ermitteln.

Berechtigungen

Erfordert die Mitgliedschaft in der festen Serverrolle sysadmin.

Beispiele

A.Aufrufen einer Methode

Im folgenden Beispiel wird die Connect-Methode des zuvor erstellten SQLServer-Objekts aufgerufen.

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

B.Abrufen einer Eigenschaft

Im folgenden Beispiel wird die HostName-Eigenschaft (des zuvor erstellten SQLServer-Objekts) ermittelt und in einer lokalen Variable gespeichert.

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

Siehe auch

Verweis

Gespeicherte OLE-Automatisierungsprozeduren (Transact-SQL)

OLE-Automatisierungsbeispielskript