Using External Files and Devices

Sending Electronic Mail Using the FILENAME Statement (E-MAIL)

Advantages to Sending E-Mail from within SAS

SAS lets you send electronic mail using SAS functions in a DATA step or in SCL. Sending e-mail from within SAS enables you to

use the logic of the DATA step or SCL to subset e-mail distribution based on a large data set of e-mail addresses.
send e-mail automatically upon completion of a SAS program that you submitted for batch processing.
direct output through e-mail based on the results of processing.

Initializing Electronic Mail

By default, SAS uses SMTP to send e-mail. SMTP, unlike the VMS e-mail facility, supports attachments. This default is specified by the EMAILSYS system option. For information on how to change the e-mail protocol, see EMAILSYS= System Option: OpenVMS.

Before you can send e-mail from within SAS, your system administrator might need to set the EMAILHOST system option to point to the SMTP server. For more information about the EMAILHOST system option, see SAS Language Reference: Dictionary.

Components of the DATA Step or SCL Code Used to Send E-Mail

In general, a DATA step or SCL code that sends electronic mail has the following components:

a FILENAME statement with the EMAIL device-type keyword.
options specified on the FILENAME or FILE statements indicating the e-mail recipients and subject.
PUT statements that contain the body of the message.
PUT statements that contain special e-mail directives (of the form !EM_directive!) that can override the e-mail attributes (TO, CC, SUBJECT) or perform actions (such as SEND, ABORT, and start a NEWMSG).

Syntax of the FILENAME Statement for E-Mail

To send electronic mail from a DATA step or SCL, issue a FILENAME statement using the following syntax:

FILENAME fileref EMAIL 'address' <e-mail-options>

where

fileref

is a valid fileref.

EMAIL

specifies the EMAIL device type, which provides the access method that enables you to send electronic mail programmatically from SAS.

'address'

is the destination e-mail address of the user to whom you want to send e-mail. You must specify an address here, but you can override its value with the TO= e-mail option.

e-mail-options

can be any of the following:

TO=to-address

specifies the primary recipients of the electronic mail. If an address contains more than one word, you must enclose it in quotation marks. To specify more than one address, you must enclose the group of addresses in parentheses, enclose each address in double quotation marks, and separate each address with a space. For example, to='joe@someplace.org' and to=("joe@smplc.org" "jane@diffplc.org") are valid TO values.

Note: You can send an e-mail without specifying a recipient in the TO= option as long as you specify a recipient in either the CC= or BCC= option. [cautionend]

CC=cc-address

specifies the recipients you want to receive a copy of the electronic mail. If an address contains more than one word, you must enclose it in quotation marks. To specify more than one address, you must enclose the group of addresses in parentheses, enclose each address in quotation marks, and separate each address with a space. For example, cc='joe@someplace.org' and cc=("joe@smplc.org" "jane@diffplc.org") are valid CC values.

BCC=bcc-address

specifies the recipients you want to receive a blind copy of the electronic mail. The BCC field does not appear in the e-mail header, so that these e-mail addresses cannot be viewed by other recipients.

If an address contains more than one word, you must enclose it in quotation marks. To specify more than one address, you must enclose the group of addresses in parentheses, enclose each address in quotation marks, and separate each address with a space. For example, bcc='joe@someplace.org' and bcc=("joe@smplc.org" "jane@diffplc.org") are valid BCC values.

Note: The BCC option is valid only when using SMTP. The VMS e-mail facility does not support this option. [cautionend]

SUBJECT='subject'

specifies the subject of the message. If the subject text is longer than one word (that is, it contains at least one blank space), you must enclose it in quotation marks. You also must use quotation marks if the subject contains any special characters. For example, subject=Sales and subject="June Report" are valid SUBJECT values. Any subject text not enclosed in quotation marks is converted to uppercase.

ATTACH='filename' | ATTACH = ('filename' attachment-options)

specifies the physical name of the file(s) to be attached to the message and any options to modify the attachment specifications. Enclose filename in quotation marks. To attach more than one file, enclose the group of filenames in parentheses. For example, valid file attachments are attach='DISK1:[MYDIR]OPINION.TXT' and attach=("june2003.txt" "july2003.txt") .

By default, SMTP e-mail attachments are truncated at 256 characters. To send longer attachments, you can specify the LRECL= and RECFM= options from the FILENAME statement as attachment-options. For more information about the LRECL= and RECFM= options, see Host-Specific External I/O Statement Options. As an alternative to using the LRECL= host option , you can use the LRECL= system option to specify a longer logical record length.

For more information about the options that are valid when you are using SMTP, see FILENAME Statement, EMAIL (SMTP) Access Method in SAS Language Reference: Dictionary.

Specifying E-Mail Options in the FILE Statement

You can also specify the e-mail-options in the FILE statement inside the DATA step. Options that you specify in the FILE statement override any corresponding options that you specified in the FILENAME statement.

Defining the Body of the Message

In your DATA step, after using the FILE statement to define your e-mail fileref as the output destination, use PUT statements to define the body of the message.

Specifying E-Mail Directives in the PUT Statement

You can also use PUT statements to specify e-mail directives that changes the attributes of your electronic message or perform actions with it. Specify only one directive in each PUT statement; each PUT statement can contain only the text associated with the directive it specifies.

The directives that change the attributes of your message are the following:

!EM_TO! addresses: replaces the current primary recipient addresses with addresses. In the PUT statement, specify addresses without single quotation marks.
!EM_CC! addresses: replaces the current copied recipient addresses with addresses. In the PUT statement, specify addresses without single quotation marks.
!EM_BCC! addresses: Replace the current blind copied recipient addresses with addresses. In the PUT statement, specify addresses without single quotation marks.
!EM_SUBJECT! subject: replaces the current subject of the message with subject.

The directives that perform actions are the following:

!EM_SEND!: sends the message with the current attributes. By default, SAS sends a message when the fileref is closed. The fileref closes when the next FILE statement is encountered or the DATA step ends. If you use this directive, SAS sends the message when it encounters the directive, and again at the end of the DATA step.
!EM_ABORT!: interrupts the current message. You can use this directive to stop SAS from automatically sending the message at the end of the DATA step.
!EM_NEWMSG!: clears all attributes of the current message, including TO, CC, SUBJECT, and the message body.

Example: Sending E-Mail from the DATA Step

Suppose that you want to tell your coworker Jim, whose user ID is JBrown, about some changes you made to your CONFIG.SAS file. If your e-mail program handles alias names, you could send it by submitting the following DATA step:

filename mymail email 'JBrown'
         subject='My CONFIG.SAS file';

data _null_;
  file mymail;
  put 'Jim,';
  put 'This is my CONFIG.SAS file.';
  put 'I think you might like the 
       new options I added.';
run;

The following example sends a message to multiple recipients. It specifies the e-mail-options in the FILE statement instead of the FILENAME statement:

filename outbox email 'ron@acme.com';

data _null_;
  file outbox

        /* Overrides the value in  */
        /* the filename statement. */
     to=("ron@acme.com" "lisa@acme.com")
     
     cc=("margaret@yourcomp.com"
         "lenny@laverne.abc.com")
     subject='My SAS output';
  put 'Folks,';
  put 'Take a look at my output from the 
       SAS program I ran last night.';
  put 'It worked great!';
run;

You can use conditional logic in the DATA step to send multiple messages and control which recipients get which messages. For example, suppose you want to notify members of two different departments that their customized reports are available. If your e-mail program handles alias names, your DATA step might look like the following:

filename reports email 'Jim';

data _null_;
  file reports;
  infile cards eof=lastobs;
  length name dept $ 21;
  input name dept;

     /* Assign the TO attribute        */
  put '!EM_TO!' name;
   
     /* Assign the SUBJECT attribute   */
  put '!EM_SUBJECT! Report for ' dept;
   
  put name ',';
  put 'Here is the latest report for ' dept '.';
  if dept='marketing' then
    put 'ATTN: Sales Representatives';
  else
    put 'For Your Information';

     /* Send the message             */
  put '!EM_SEND!';
     
     /* Clear the message attributes */
  put '!EM_NEWMSG!';
     
  return;

     /* Abort the message before the */
     /* Run statement causes it to   */
     /* be sent again.               */
lastobs: put '!EM_ABORT!';
     
  datalines;
Susan          marketing
Jim            marketing
Rita           development
Herb           development
;
run;

The resulting e-mail message and its attachments are dependent on the department to which the recipient belongs.

Note: You must use the !EM_NEWMSG! directive to clear the message attributes between recipients. The !EM_ABORT! directive prevents the message from being automatically sent at the end of the DATA step. [cautionend]

Example: Sending E-Mail Using SCL Code

The following example is the SCL code behind a frame entry design for e-mail. The frame entry includes several text entry fields that let the user enter information:

mailto	the user ID to send mail to
copyto	the user ID to copy (CC) the mail to
subject	the subject of the mail message
line1	the text of the mail message

The frame entry also contains a pushbutton called SEND that causes this SCL code (marked by the send: label) to execute.

send:

   /* set up a fileref */
rc = filename('mailit','userid','email');

      /* if the fileref was successfully set up */
      /* open the file to write to              */
   if rc = 0 then do;
      fid = fopen('mailit','o');
      if fid >0 then do;

            /* fput statements are used to     */
            /* implement writing the mail      */
            /* and the components such as      */
            /* subject, who to mail to, etc.   */
         fputrc1 = fput(fid,line1);
         rc = fwrite(fid);

         fputrc2 = fput(fid,'!EM_TO! '||mailto);
         rc = fwrite(fid);
         fputrc3 = fput(fid,'!EM_CC! '||copyto);
         rc = fwrite(fid);

         fputrc4 = fput(fid,'!EM_SUBJECT! '||subject);
         rc = fwrite(fid);

         closerc = fclose(fid);
      end;
   end;
return;

cancel:
   call execcmd('end');
return;

Top of Page