Artikel
03/30/2012

xp_sendmail (Transact-SQL)

Sendet eine E-Mail-Nachricht, die ein Abfrageresultset als Anlage enthalten kann, an die angegebenen Empfänger. Diese erweiterte gespeicherte Prozedur verwendet SQL Mail zum Senden der Nachricht.

Hinweis
Diese Funktion wird in zukünftigen Versionen von Microsoft SQL Server nicht mehr bereitgestellt. Verwenden Sie diese Funktion beim Entwickeln neuer Anwendungen nicht, und planen Sie das Ändern von Anwendungen, in denen es zurzeit verwendet wird. Versenden Sie E-Mail-Nachrichten aus SQL Server mit Datenbank-E-Mail.

Themenlink (Symbol) Transact-SQL-Syntaxkonventionen

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.

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

Im folgenden Beispiel wird an den Benutzer Dan Wilson (E-Mail-Adresse: danw) die Nachricht gesendet, dass die master-Datenbank voll ist.

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

Im folgenden Beispiel wird die Nachricht an die Benutzer Dan Wilson und Ashvini Sharma (E-Mail-Adresse: ashvinis) gesendet, eine Kopie wird zudem an Peter Connelly (E-Mail-Adresse: peterc) gesendet. Außerdem wird im Beispiel eine Betreffzeile für die Nachricht angegeben.

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

Im folgenden Beispiel wird das Ergebnis von sp_configure an Dan Wilson gesendet.

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

Im folgenden Beispiel wird das Ergebnis der Abfrage SELECT * FROM INFORMATION_SCHEMA.TABLES als Anlage in Form einer Textdatei an Dan Wilson gesendet. Das Beispiel enthält eine Betreffzeile für die Nachricht und Text, der vor der Anlage eingefügt wird. Mit dem @width-Parameter werden Zeilenumbrüche in den Ausgabezeilen verhindert.

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

Das folgende Beispiel veranschaulicht, wie eine Nachricht gesendet wird, die länger als 7.990 Zeichen ist. Da der message-Parameter (wegen des geringeren Zeilenaufwands, wie alle Parameter von gespeicherten Prozeduren) auf die Länge einer VARCHAR-Variablen beschränkt ist, wird die Nachricht in eine globale temporäre Tabelle geschrieben, die aus einer einzelnen Textspalte besteht. Der Inhalt dieser temporären Tabelle wird dann mit dem @query-Parameter in einer E-Mail-Nachricht gesendet.

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 ;