Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
 
Log in  ::  Register  ::  Not logged in
 
 
 

Sending SQL Notifications with CDOSYS

By Desiree Harris,

Sending SQL notifications with CDOSYS
Desiree Harris
July, 27 2004

While SQL Server has a very mature set of tools, one thing that is lacking is the ability to send a simple email alert based on a pre-defined set of rules. At first glace, it appears that email notifications exist but what becomes a problem to many people is the requirement for a MAPI subsystem to be present on the server. This means that Outlook or an equivalent program has to be installed on the server. Not only that, to properly configure it, the administrator will need to log into the server as the user that the SQL Server service is running under. I have always found this inconvenient so I set out to create a stable, free, easy to configure means of accomplishing the same thing without installing anything special on the server. I've included steps below to complete this task successfully.

Before we start, a SMTP server needs to be available. This can be setup on the server itself, on another server within the local network, or outside the network. To install an SMTP service on the SQL Server, ensure that IIS SMTP Services are installed. You can do so from Add/Remove programs in the Control panel. Once it is installed, '127.0.0.1' will need to be added to 'relay' on the 'access' tab in the SMTP Properties. Alternately a SMTP server of another mail server can be used instead. This information will need to be added to the 'sp_send_cdosys' stored procedure we'll create later.

First we need to create the stored procedure to send the e-mail. This can be done with Enterprise Manager and Query Analyzer. For our example, we'll implement the job with Enterprise manager using the Northwind database.

In Enterprise Manager, expand the Northwind database, select and right-click on 'stored procedures', and then select 'New Stored Procedure… '. Note: This can also be added to the Master database so that it is available for all databases.

screen shot 1

Delete the contents in the box, and copy and paste the contents below in the stored procedure box (everything between ' --- ').

Note: The sp_send_cdosysmail stored procedure uses ‘sp_OACreate' and ‘sp_OASetProperty' stored procedures; this will require the user account running it to have SA permissions.

-------------------------------------

CREATE PROCEDURE [dbo].[sp_send_cdosysmail] @From varchar(100) , @To varchar(100) , @Subject varchar(100)=" ", @Body varchar(4000) =" " /******************************************

This stored procedure takes the parameters and sends an e-mail. All the mail configurations are hard-coded in the stored procedure. Comments are added to the stored procedure where necessary. References to the CDOSYS objects are at the following MSDN Web site: http://msdn.microsoft.com/library/default.asp?url=/ library/en-us/cdosys/html/_cdosys_messaging.asp

*******************************************/

AS Declare @iMsg int Declare @hr int Declare @source varchar(255) Declare @description varchar(500) Declare @output varchar(1000)

--***** Create the CDO.Message Object *****

EXEC @hr = sp_OACreate 'CDO.Message', @iMsg OUT

--*****Configuring the Message Object *****

-- This is to configure a remote SMTP server.
-- http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cdosys/html/_cdosys_schema_configuration_sendusing.asp
EXEC @hr = sp_OASetProperty @iMsg, 'Configuration.fields ("http://schemas.microsoft.com/cdo/configuration/sendusing").Value','2'

-- This is to configure the Server Name or IP address.

-- Replace MailServerName by the name or IP of your SMTP Server.
EXEC @hr = sp_OASetProperty @iMsg, 'Configuration.fields("http://schemas. microsoft.com/cdo/configuration/smtpserver").Value', 'MailServerName'

-- Save the configurations to the message object.
EXEC @hr = sp_OAMethod @iMsg, 'Configuration.Fields.Update', null

-- Set the e-mail parameters.
EXEC @hr = sp_OASetProperty @iMsg, 'To', @To
EXEC @hr = sp_OASetProperty @iMsg, 'From', @From
EXEC @hr = sp_OASetProperty @iMsg, 'Subject', @Subject

-- If you are using HTML e-mail, use 'HTMLBody' instead of 'TextBody'.
EXEC @hr = sp_OASetProperty @iMsg, 'TextBody', @Body
EXEC @hr = sp_OAMethod @iMsg, 'Send', NULL

-- Sample error handling.


            IF @hr <>0 
     select @hr
     BEGIN
       EXEC @hr = sp_OAGetErrorInfo NULL, @source OUT, @description OUT
       IF @hr = 0
         BEGIN
           SELECT @output = '  Source: ' + @source
           PRINT  @output
           SELECT @output = '  Description: ' + @description
           PRINT  @output
         END
       ELSE
         BEGIN
           PRINT '  sp_OAGetErrorInfo failed.'
           RETURN
         END
     END

-- Do some error handling after each step if you have to.
-- Clean up the objects created.
EXEC @hr = sp_OADestroy @iMsg
GO

-----------------------

Once you have copied the stored procedure into the box, find the line below within the code.

EXEC @hr = sp_OASetProperty @iMsg, 'Configuration.fields("http://schemas.microsoft.com/cdo/configuration/smtpserver").Value', 'MailServerName'

Replace 'MailServerName' with either 'localhost' or your 'SMTPMailServer'.

Be careful of word wrapping. When pasting from my example you may find that some lines wrap. You may need to double check the lines to make sure nothing wrapped that shouldn't have.

Next, as an example we will create a job that will backup the Northwind database, then send a notification via e-mail when it completes successfully.

In Enterprise Manager, open 'Management' à 'SQL Server Agent', and then select and right-click on 'Jobs', and select 'New Job… '.

screen shot 2

On the 'General' tab name the job 'Backup Northwind'.
On the 'Steps' tab, click on 'New', enter the information below, and then click OK. (The path should be a path that exists on the SQL Server.)

screen shot 3

This is what you should see after you click 'OK'. Notice that the 'On Success' column says 'Goto next step' (this is ok, because we are about to create another step) and the 'On Failure' column says 'Quit with failure' (this is ok, because if the job fails, we don't want it to go to the next step).

screen shot 4

Now we'll add the job step that will notify us that the job has completed.

Click 'New…' and add the information below (everything between ' --- ').

----------------------------------------


Name: 	   SendNotification
Database:  Northwind
Command:   EXEC sp_send_cdosysmail
'from@emailaddress.com*',  
'to@emailaddress.com*', 
'subject*', 
'I've added an example message for you*
Team,

The Northwind database has been backed up successfully.

Thank you,
ORCS Web '

----------------------------------------

*fill in the fields with the desired information.

screen shot 5

Click on the 'Advanced' tab and change the 'On Success' box to 'Quit the job reporting success' and then click 'OK'.

screen shot 6

This is what the job should look like now.

screen shot 7

For our purposes, the 'Schedules' and 'Notifications' tabs default settings are fine; we will not need to make any changes. Click 'OK' and your job should appear in the job window.

screen shot 8

Now, right-click on the job we just created and click 'Start Job'.

screen shot 9

Make sure that the Job step named 'Backup' is selected then click start. When the job complete, you will be sent an email notification that looks like this.

screen shot 10

Now, even though email notifications can be setup as a 'job step' you can also setup an alert based on a SQL Server event that will send an email and include details of the event. Next we will setup an alert that will send an email notification with details.

In Enterprise Manager, open 'Management' à 'SQL Server Agent', and then select and right-click on 'Jobs', and select 'New Job… '.

screen shot 11

On the 'General' tab name the job 'SQL Server Severity Alert Notification'.

On the 'Steps' tab, click on 'New', name it 'SendEmail' and enter the script below (everything between '--').On the 'Advanced' tab, change the 'on success action' to 'Quit the job reporting success' and click 'OK'.

screen shot 12 ---------
DECLARE @msg nvarchar(4000)
Set @msg = REPLACE("Error: [A-ERR]
Severity: [A-SEV]
Date: [STRTDT]
Time: [STRTTM]
Database: [A-DBN]
Message: [A-MSG] ", "'", "") --'

EXEC sp_send_cdosysmail 'from@emailaddress.com*',
'to@emailaddress.com*',
'subject*',
@msg
----------

*fill in fields with desired information

I guess you're wondering what the script does. The script takes advantage of the power of agent tokens, which will be automatically filled in at runtime. You can get more information about agent tokens here http://www.sqldev.net/sqlagent/SQLAgentStepTokens.htm

The 'Schedules' and 'Notifications' tab don't need any changes at this time; let's click 'OK' again to complete the job.

Next we'll create the alert that will run the job we just created when an event occurs. In Enterprise Manager, open 'Management' à 'SQL Server Agent', and then select and right-click on 'Alerts', and select 'New Alert… '.

screen shot 13

On the 'General' tab name the job 'SQL Server Severity Alert'. We'll leave the severity level at 010 as it will return information and isn't specific to an error and we'll let this alert fire for all databases.

On the 'Response' tab, put a check in the box for 'Execute job', select the job we just created, 'SQL Server Severity Notification', and then click 'OK'.

Now, we are ready to test. Let's backup the Northwind database in Query Analyzer with the script below:

Use master
BACKUP DATABASE Northwind TO DISK = 'c:\temp\northwind.bak*'

*ensure the path exists on the SQL Server

This task will execute the alert. At this point, an email should appear in the inbox of the email address you specified in the script. I've included an example below.

screen shot 14

You can find more information about sending e-mail notifications at http://support.microsoft.com/default.aspx?scid=kb;de;312839&sd=tech
You can read more about agent tokens here http://www.sqldev.net/sqlagent/SQLAgentStepTokens.htm
You can read more about severity levels here http://www.developer.com/db/article.php/724711

We've seen here how to setup email alerts on the server without being required to install the Outlook client email program or another MAPI program. Windows 2000 Server and greater already has CDOSYS installed on it. If installing this on Windows NT, replace the stored procedure with one that uses CDONTS instead.

Desiree Harris is a support specialist with ORCS Web, Inc. - a company that provides managed hosting services for clients who develop and deploy their applications on Microsoft Windows platforms.

Total article views: 13243 | Views in the last 30 days: 7
 
Related Articles
FORUM

create Procedure within Procedure

create Procedure within Procedure

FORUM

Creating Stored Procedure with SELECT ... inside

how to create a SP with select inside

FORUM

Create separate file for Procedure

Create separate file for Procedure

FORUM

create a stored procedure to create a txt file

create a stored procedure to create a txt file

FORUM

Creating view from stored procedure results

Creating view from stored procedure results

Tags
 
Contribute

Join the most active online SQL Server Community

SQL knowledge, delivered daily, free:

Email address:  

You make SSC a better place

As a member of SQLServerCentral, you get free access to loads of fresh content: thousands of articles and SQL scripts, a library of free eBooks, a weekly database news roundup, a great Q & A platform… And it’s our huge, buzzing community of SQL Server Professionals that makes it such a success.

Join us!

Steve Jones
Editor, SQLServerCentral.com

Already a member? Jump in:

Email address:   Password:   Remember me: Forgotten your password?
Steve Jones