SAS Companion for UNIX Environments

Sending Electronic Mail from Within the SAS System (EMAIL)

The SAS System lets you send electronic mail using SAS functions in a DATA step or in SCL. Sending e-mail from within the SAS System allows 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.
send e-mail messages from within a SAS/AF frame application, customizing the user interface.

Initializing Electronic Mail

Because of the wide range of e-mail programs available, the SAS System sends all mail through an external shell script. The SAS System provides two scripts, located in !SASROOT/utilities/bin:

sasmailer: does not support aliases or attachments.
sasm.elm.mime: supports aliases using ELM and attachments using MIME.

Note: You or your system administrator will probably have to customize these scripts before you can use them with your specific e-mail program. [cautionend]

Specify the name of the script you will be using by setting the EMAILSYS system option. You can specify the EMAILSYS system option in the CONFIG.SAS file or when invoking your SAS session:

-EMAILSYS name-of-script

Using the DATA Step or SCL to Send Electronic 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, subject, and any attached files
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, ATTACH) or perform actions (such as SEND, ABORT, and start a NEWMSG).

Syntax of the FILENAME Statement for Electronic Mail

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

FILENAME fileref EMAIL 'address' <email-options>;

The FILENAME statement accepts the following email-options:

fileref

is a valid fileref.

'address'

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

email-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, enclose it in single quotes. To specify more than one address, enclose the group of addresses in parentheses and each address in single quotes. For example, to='joe@somplace.org' and to=('joe@smplc.org' 'jane@diffplc.org') are valid TO values.

CC=cc-address

specifies the recipients you want to receive a copy of the electronic mail. If an address contains more than one word, enclose it in single quotes. To specify more than one address, enclose the group of addresses in parentheses and each address in single quotes. For example, cc='joe@somplace.org' and

cc=('joe@smplc.org'
'jane@diffplc.org')

are valid CC values.

SUBJECT='subject'

specifies the subject of the message. If the subject text is longer than one word, enclose it in single quotes. For example, subject=Sales and subject='June Report' are valid subjects. Any subject not enclosed in quotes is converted to upper case.

ATTACH='pathname'

specifies the full pathname of one or more files to attach to the message. Enclose pathname in single quotes. To attach more than one file, enclose the group of file names in parentheses. For example, attach='opinion.txt' and attach=('june98.txt' 'july98.txt') are valid file attachments.

Note: Not all external scripts support file attachments or all types of file attachments. Scripts that do not accept attachments should not send mail if an attachment is attempted. Otherwise, the message could say "here's the graph you wanted," but the graph would not be included. [cautionend]

You can also specify the email-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.

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.

You can also use PUT statements to specify e-mail directives that change 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

!EM_TO! addresses: Replace the current primary recipient addresses with addresses. In the PUT statement, specify addresses without single quotes.
!EM_CC! addresses: Replace the current copied recipient addresses with addresses. In the PUT statement, specify addresses without single quotes.
!EM_SUBJECT! subject: Replace the current subject of the message with subject.
!EM_ATTACH! pathname: Replace the names of any attached files with pathname.

The directives that perform actions are

!EM_SEND!: Sends the message with the current attributes. By default, the message is automatically sent at the end of the DATA step. If you use this directive, the SAS System sends the message when it encounters the directive, and again at the end of the DATA step.
!EM_ABORT!: Aborts the current message. You can use this directive to stop the SAS System 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, ATTACH, and the message body.

Example: Sending E-Mail from the DATA Step

Suppose that you want to share a copy of your CONFIG.SAS file with your coworker Jim, whose user ID is JBrown. If your e-mail program handles alias names and attachments, you could send it by submitting the following DATA step:

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

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 and two attached files 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
     to=('ron@acme.com' 'lisa@acme.com')
     /* Overrides value in */
     /* filename statement */

     cc=('margaret@yourcomp.com' 
         'lenny@laverne.abc.com')
     subject='My SAS output'
     attach=('results.out' 'code.sas')
     ;
  put 'Folks,';
  put 'Attached is 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 message. For example, suppose you want to send customized reports to members of two different departments. If your e-mail program handles alias names and attachments, 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;
  put '!EM_TO!' name;
   /* Assign the TO attribute      */

  put '!EM_SUBJECT! Report for ' dept;  
   /* Assign the SUBJECT attribute */

  put name ',';
  put 'Here is the latest report for ' dept '.';
  if dept='marketing' then
    put '!EM_ATTACH! mktrept.txt';
  else                                  
    /* ATTACH the appropriate report */

    put '!EM_ATTACH! devrept.txt';
  put '!EM_SEND!';                      
    /* Send the message */

  put '!EM_NEWMSG!';                    
    /* Clear the message attributes */

  return;
lastobs: put '!EM_ABORT!';              
    /* Abort the message before the */ 
    /*   RUN statement causes it to */ 
    /*   be sent again.

  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

attach the name of a file to attach

subject the subject of the mail

line1 the text of the 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_ATTACH! '||attach);
         rc = fwrite(fid);
         fputrc5  = fput(fid,'!EM_SUBJECT! '||subject);
         rc = fwrite(fid);

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

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

Chapter Contents
Previous
Next
Top of Page

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