xp_sendmail (Transact-SQL)

Syntax

xp_sendmail { [ @recipients= ] 'recipients [ ;...n ]' } 
     [ ,[ @message= ] 'message' ] 
     [ ,[ @query= ] 'query' ] 
     [ ,[ @attachments= ] 'attachments [ ;...n ]' ] 
     [ ,[ @copy_recipients= ] 'copy_recipients [ ;...n ]'
     [ ,[ @blind_copy_recipients= ] 'blind_copy_recipients [ ;...n ]'
     [ ,[ @subject= ] 'subject' ]
     [ ,[ @type= ] 'type' ] 
     [ ,[ @attach_results= ] 'attach_value' ]
     [ ,[ @no_output= ] 'output_value' ] 
     [ ,[ @no_header= ] 'header_value' ] 
     [ ,[ @width= ] width ] 
     [ ,[ @separator= ] 'separator' ] 
     [ ,[ @echo_error= ] 'echo_value' ] 
     [ ,[ @set_user= ] 'user' ] 
     [ ,[ @dbuse= ] 'database' ]

Argumente

• [ @recipients=] **'**recipients [ ;... n] '
  Die durch Semikolons getrennte Liste der E-Mail-Empfänger.

• [ @message=] 'message'
  Die zu sendende Nachricht. messagekann aus bis zu 8.000 Byte bestehen.

• [ @query=] 'query'
  Eine gültige SQL Server-Abfrage, deren Ergebnis als E-Mail gesendet wird. xp_sendmail verwendet eine zusammengefasste Verbindung für den query-Parameter. Die von SQL Mail hergestellte query-Verbindung wird von Sperren der Clientverbindung, die die xp_sendmail-Anforderung ausgegeben hat, nicht blockiert. Dies erleichtert die Verwendung von xp_sendmail im Rahmen von Triggern. Die query-Anweisung kann sich jedoch nicht auf die logischen Tabellen inserted und deleted beziehen, da diese Tabellen nur innerhalb eines Triggers verfügbar sind. query kann aus bis zu 8.000 Byte bestehen.

• [ @attachments=] **'**attachments [ ;... n] '
  Die durch Semikolons getrennte Liste der Dateien, die an die E-Mail angehängt werden sollen. Wenn Sie den @query-Parameter verwenden und @attach_results den Wert TRUE hat, kann vom @attachments-Parameter nur eine Datei als Anlage für die E-Mail-Nachricht angegeben werden. In diesem Fall müssen Sie zum Senden mehrerer Dateien xp_sendmail separat für jede angefügte Datei ausführen.

• [ @copy_recipients=] **'**copy_recipients [ ;... n] '
  Die durch Semikolons getrennte Liste der Empfänger einer Kopie der E-Mail.

• [ @blind_copy_recipients=] **'**blind_copy_recipients[ ;... n] '
  Eine optionale, durch Semikolons getrennte Liste der Empfänger einer Kopie der E-Mail.

• [ @subject=] 'subject'
  Ein Parameter für den Betreff der E-Mail-Nachricht. Wenn Sie subject nicht angeben, wird standardmäßig "SQL Server-Nachricht" verwendet.

• [ @type=] 'type'
  Der Nachrichtentyp entsprechend der MAPI-Mail-Definition:

  IP[ M|C ].Vendorname.subclass

  Wenn type den Wert NULL aufweist, verwendet xp_sendmail den Nachrichtentyp IPM. Mit IPM beginnende Nachrichtentypen werden im Posteingang des Mailclients angezeigt und von xp_findnextmsg gesucht oder gelesen. Nachrichtentypen, die mit IPC beginnen, werden im Posteingang des Mailclients nicht angezeigt und müssen durch Festlegen des type-Parameters gesucht oder gelesen werden. Der Standardwert ist NULL. SQL Mail unterstützt die Nachrichtentypen IPM und IPC.

• [ @attach_results=] 'attach_value'
  Ein optionaler Parameter, der angibt, dass das Resultset einer Abfrage nicht in die E-Mail eingefügt, sondern als Anlagedatei angefügt werden soll. Wenn @attachments nicht den Wert NULL hat und @attach_results den Wert TRUE hat, wird der erste Dateiname in attachments als Dateiname für die Ergebnisse verwendet. Wenn @attachments den Wert NULL hat, wird ein Dateiname mit der Erweiterung TXT generiert. Der Standard ist FALSE, womit das Resultset an das Ende der E-Mail angefügt wird.

• [ @no_output=] 'output_value'
  Mit diesem optionalen Parameter wird festgelegt, dass nach dem Senden der Nachricht keine Ausgabe an die Clientsitzung zurückgegeben wird, die die Nachricht gesendet hat. Der Standardwert ist FALSE, womit eine Ausgabe an die Clientsitzung von SQL Server erfolgt.

• [ @no_header=] 'header_value'
  Dieser optionale Parameter sendet die Abfrageergebnisse in der Nachricht, wobei die Spaltenheader nicht eingeschlossen werden. Der Standard ist FALSE, womit die Spaltenheader zusammen mit dem Abfrageergebnis gesendet werden.

• [ @width=] width
  Ein optionaler Parameter, der die Zeilenbreite für den Ausgabetext einer Abfrage festlegt. Dieser Parameter hat dieselbe Funktion wie der /w-Parameter des Dienstprogramms isql. Verwenden Sie für Abfragen mit langen Ausgabezeilen width zusammen mit attach_results, um die Ausgabe ohne Zeilenumbrüche in den Ausgabezeilen zu senden. Die Standardbreite beträgt 80 Zeichen.

• [ @separator=] 'separator'
  Die Spaltentrennzeichenfolge für die Spalten des Resultsets. Standardmäßig wird als Spaltentrennzeichen ein Leerzeichen verwendet. Die Verwendung eines Spaltentrennzeichens ermöglicht eine einfachere Analyse des Resultsets in Kalkulationstabellen und anderen Anwendungen. Verwenden Sie z. B. separator zusammen mit attach_results, um Dateien mit durch Trennzeichen getrennten Werten zu senden.

• [ @echo_error=] 'echo_value'
  Wenn dieser Parameter den Wert TRUE hat, zeichnet SQL Mail während der Ausführung der Abfrage alle Servermeldungen oder DB-Library-Fehler auf und hängt sie an die Nachricht an, statt sie in das Fehlerprotokoll zu schreiben. Außerdem wird an das Ende der Nachricht angefügt, wie viele Zeilen zurückgegeben wurden bzw. davon betroffen waren.

  Hinweis
  Wenn echo_error den Wert TRUE hat, gibt xp_sendmail den Status 0 (Erfolg) zurück, wenn die E-Mail erfolgreich gesendet wurde, selbst wenn DB-Library-Fehler oder -Meldungen auftreten oder die Abfrage kein Ergebnis zurückgibt.

• [ @set_user=] 'user'
  Der Sicherheitskontext, in dem die Abfrage ausgeführt werden soll. Falls user nicht angegeben wurde, wird standardmäßig der Sicherheitskontext des Benutzers übernommen, der xp_sendmail ausführt.

• [ @dbuse=] 'database'
  Der Datenbankkontext, in dem die Abfrage ausgeführt werden soll. Der Standard ist NULL, womit der Benutzer die Standarddatenbank verwendet.

Rückgabecodewerte

0 (Erfolg) oder 1 (Fehler)

Resultsets

Bei Erfolg gibt xp_sendmail eine Nachricht zurück.

Hinweise

Die SQL Mail-Sitzung muss vor dem Ausführen von xp_sendmail gestartet werden. Sitzungen können automatisch oder mit xp_startmail gestartet werden. Weitere Informationen zum automatischen Einrichten einer SQL Mail-Sitzung finden Sie unter Konfigurieren von Extended MAPI-Mailprofilen. Zwar werden alle Benutzer der SQL Server-Instanz von einer SQL Mail-Sitzung unterstützt, jedoch können nicht mehrere Benutzer gleichzeitig Nachrichten senden. Wenn während eines Sendevorgangs ein weiterer Benutzer versucht, eine Nachricht zu senden, wird automatisch so lange gewartet, bis die Nachricht des ersten Benutzers gesendet wurde.

Falls query angegeben ist, meldet sich xp_sendmail an SQL Server als Client an und führt die angegebene Abfrage aus. SQL Mail stellt eine separate Verbindung zu SQL Server her und nutzt nicht die Clientverbindung, die xp_sendmail ausgeführt hat.

Hinweis

query kann durch eine Sperre der Clientverbindung, die xp_sendmail ausgegeben hat, blockiert werden. Wenn Sie z. B. eine Tabelle innerhalb einer Transaktion aktualisieren und einen Aktualisierungstrigger erstellen, der versucht, dieselben aktualisierten Zeileninformationen wie der query-Parameter auszuwählen, wird die SQL Mail-Verbindung durch die exklusive Sperre der betreffenden Zeile durch die ursprüngliche Clientverbindung blockiert.

xp_sendmail wird im Sicherheitskontext von SQL Server ausgeführt. Ein gültiger Benutzer von xp_sendmail kann auf Dateien im Sicherheitskontext eines Administrators zugreifen, um sie an eine Nachricht anzufügen. Wenn Nichtsystemadministratoren auf xp_sendmail zugreifen müssen und Sie den ungesicherten Zugriff auf Anlagendateien verhindern möchten, kann der Systemadministrator eine gespeicherte Prozedur erstellen, die xp_sendmail aufruft und die erforderliche Funktionalität bereitstellt, die den attachments-Parameter jedoch nicht offen legt. Diese gespeicherte Prozedur muss in der master-Datenbank definiert werden. Der Systemadministrator erteilt dann den entsprechenden Benutzern die Berechtigungen für die gespeicherte Prozedur, nicht jedoch für die zugrunde liegende xp_sendmail-Prozedur.

xp_sendmail sendet eine Nachricht und ein Abfrageresultset oder eine Anlage an die angegebenen Empfänger und verwendet für den query-Parameter eine zusammengefasste Verbindung. Die von SQL Mail hergestellte query-Verbindung wird von Sperren der Clientverbindung, die die xp_sendmail-Anforderung ausgegeben hat, nicht blockiert. Dies erleichtert die Verwendung von xp_sendmail im Rahmen von Triggern. Die query-Anweisung kann sich jedoch nicht auf die logischen Tabellen inserted und deleted beziehen, die lediglich innerhalb eines Triggers verfügbar sind.

Hinweis
Eine Zugriffsverletzung kann das Ergebnis des Versuchs sein, xp_sendmail auszuführen, wenn für das Postoffice und das Adressbuch eine Dateifreigabe besteht, auf die der MSSQLServer-Dienst wegen unzureichender Berechtigungen keinen Zugriff hat.

xp_sendmail unterstützt den xml-Datentyp nicht vollständig.Möglicherweise werden Abfragen, die den xml-Datentyp verwenden, nicht ordnungsgemäß formatiert. Verwenden Sie Datenbank-E-Mail zum Senden von E-Mail-Nachrichten, die xml-Daten enthalten.

Berechtigungen

Erfordert die Mitgliedschaft in der festen Serverrolle sysadmin, EXECUTE-Berechtigungen können jedoch auch anderen Benutzern erteilt werden. Aus Sicherheitsgründen wird jedoch empfohlen, die Berechtigungen für diese gespeicherte Prozedur auf Mitglieder der festen Serverrolle sysadmin zu beschränken.

Beispiele

A. Senden einer Nachricht an einen einzelnen Empfänger

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com',
    @message=N'The master database is full.' ;

B. Senden einer Nachricht an mehrere Empfänger

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com;ashvinis@Adventure-Works.com',
     @message=N'The master database is full.',
     @copy_recipients=N'peterc@Adventure-Works.com',
     @subject=N'Master database status' ;
GO

C. Senden von Ergebnissen

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com',
    @query = N'EXEC sp_configure' ;
GO

D. Senden von Ergebnissen als angefügte Datei

EXEC master.dbo.xp_sendmail
    @recipients = N'danw@Adventure-Works.com', 
    @query = N'SELECT * FROM INFORMATION_SCHEMA.TABLES',
    @subject = N'SQL Server Report',
    @message = N'The contents of INFORMATION_SCHEMA.TABLES:',
    @attach_results = 'TRUE',
    @width = 250 ;

E. Senden von Nachrichten, die länger als 7.990 Zeichen sind

CREATE TABLE ##mail_body(c1 NVARCHAR(4000)) ;

DECLARE @cmd VARCHAR(56) ;

INSERT ##mail_body(c1)
VALUES ('Put your long message here.') ;

SET @cmd = 'SELECT c1 FROM ##mail_body' ;

EXEC master.dbo.xp_sendmail 
    @recipients = 'danw@Adventure-Works.com', 
    @query = @cmd,
    @no_header= 'TRUE' ;

DROP TABLE ##mail_body ;

Siehe auch

Verweis