SAS Companion for the CMS Environment

Sending E-Mail from Within SAS

SAS lets you send electronic mail (e-mail) by using the DATA step, procedures, or SCL. Sending e-mail from within SAS 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.

SAS e-mail is implemented in the following language elements:

The EMAILSYS= system option, which specifies the name of the external CMS pipeline stage that delivers mail messages to the host mail system. See Using the Mail System Interface and the EMAILSYS= System Option for details.
The FILE and FILENAME statements, which are used to specify the name of an e-mail fileref and the mailing instructions, or directives, that are used to send it. See FILENAME Statement Syntax for Electronic Mail for details.
The PUT statement, which is used in the DATA step or SCL to create the e-mail message and to specify or change mailing directives. See PUT Statement Syntax for E-Mail for details.

To send an e-mail message from a SAS session, use these e-mail language elements in a DATA step, in a procedure, or in SCL code (see Using the DATA Step, Procedures, or SCL Code to Send E-Mail).

Using the Mail System Interface and the EMAILSYS= System Option

SAS sends all e-mail through an external CMS pipeline stage that is written as a REXX exec. The name of the exec is SASMAIL REXX, and it is stored on the SAS system disk.

Note: The SASMAIL REXX exec may need to be customized with site-specific information that is pertinent to your mail system. Comments at the beginning of the exec guide you through the customizations. Work with your system administrator and local SAS Support Consultant as needed. [cautionend]

You can use your own CMS pipeline stage instead of SASMAIL by specifying the name of your exec as the value of the EMAILSYS= system option. You can specify a value for EMAILSYS= in your SAS configuration file, in your SAS invocation command, or during your SAS session by using the OPTIONS statement or OPTIONS window. The syntax of the OPTIONS statement is as follows:

EMAILSYS='stage-specification'
The stage specification can be of the form filename filetype filemode. If the filetype is omitted, SAS assumes a filetype of REXX. If the filemode is omitted, SAS assumes a filemode of `*'. Quotes are required around the entire specification if anything more than a filename is specified.

FILENAME Statement Syntax for Electronic Mail

To send electronic mail from within a SAS session, issue a FILENAME statement of the following form:

FILENAME fileref EMAIL 'address' <e-mail-options>;
The arguments are defined as follows:

fileref

is a valid fileref.

'address'

is the e-mail address of the user to whom you want to send e-mail. This argument is optional, but you must specify at least one address, either here or with the TO= option or with the !EM_TO! PUT directive.

e-mail-options

can be any of the following:

TO=to-address

specifies the primary recipients of the e-mail message. If an address contains special characters or more than one word, enclose the address in single or double quotes, as follows:

to='joe@hisplace.org'

To specify more than one address, enclose the group of addresses in parentheses and each address in single or double quotes, as follows:

to=('joe@hisplace.org' 'jane@herplace.org')

To specify the recipient's name along with the address, enclose the address in angle brackets, as follows:

to="Joseph Smith <joe@hisplace.org>"

A recipient can also be specified as a nickname to be resolved from your NAMES file.

Specifying the TO= option overrides the address argument.

CC=cc-address

specifies the copy recipients of the e-mail message. If an address contains special characters or more than one word, enclose it in single or double quotes, as follows:

cc='joe@hisplace.org'

To specify more than one address, enclose the group of addresses in parentheses and each address in single or double quotes, as follows:

cc=('joe@hisplace.org' 'jane@herplace.org')

To specify the recipient's name along with the address, enclose the address in angle brackets, as follows:

cc="Joseph Smith <joe@hisplace.org>"

A recipient can also be specified as a nickname to be resolved from your NAMES file.

SUBJECT='subject'

specifies the subject of the message. If the subject text contains special characters or is longer than one word, enclose it in single or double quotes, as follows:

subject=Sales

subject='June Report'

Any subject not enclosed in quotes is converted to uppercase.

ATTACH='file-specification'

specifies, inside single or double quotes, one or more files to attach to the message. Specify filename and filetype and either the filemode or SFS directory name, as follows:

attach='opinion txt'

The filemode is `*' by default. To attach more than one file, enclose the group of file specifications in parentheses, as follows:

attach=('june98 txt .reports.june' 'july98 txt .reports.july')

TYPE='content-type'

specifies the content-type of the message, as follows:

type='text/plain'
type='text/html'
type='image/gif'

The TYPE value must be enclosed in quotes.

EMAILSYS='stage-specification'

specifies the name of a CMS pipeline stage to be used to send e-mail. This FILENAME option overrides the value of the EMAILSYS= system option, which is SASMAIL REXX by default.

EMAILID='from-user'

specifies the e-mail address that will appear on the From: header of the e-mail message. The default value is the userid and host name of the user running SAS. You may prefer to specify a different address for a server application. If the e-mail address contains special characters or more than one word, enclose the entire specification in quotes. To specify a name along with the address, enclose the address in angle brackets, as follows:

emailid='Joseph Smith <joe@hisplace.org>'

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.

PUT Statement Syntax for E-Mail

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 that is associated with the directive that it specifies.

The directives that change the attributes of your message are as follows:

!EM_TO! addresses

replaces the current primary recipient addresses with addresses. For example:

PUT "!EM_TO!" "joe@hisplace.org";

or:

user="joe@hisplace.org";
put '!EM_TO!' user;

To specify more than one address, enclose the list of addresses in parentheses and enclose each address in single or double quotes, as follows:

PUT "EM_TO!" '("joe@hisplace.org" "jane@herplace.org")';

or:

list='("joe@hisplace.org" "jane@herplace.org")';
put "!EM_TO!" list;

If you want to specify a recipient's name along with the e-mail address, include the address in angle brackets, as follows:

user='Joseph Smith <joe@hisplace.org>'
PUT "EM_TO!" user;

A recipient can also be specified as a nickname that will be resolved from your NAMES file.

!EM_CC! addresses

replace the current copied recipient addresses with addresses. For example:

PUT "!EM_CC!" "joe@hisplace.org";

or:

user="joe@hisplace.org";
put '!EM_CC!' user;

To specify more than one current copied recipient, enclose a list of addresses in parentheses and enclose each address in single or double quotes, as follows:

PUT "!EM_CC!" '("joe@hisplace.org" "jane@herplace.org")';

or:

list='("joe@hisplace.org" "jane@herplace.org")';
put '!EM_CC!' list;

If you want to specify a recipient's name along with the address, enclose the address in angle brackets, as follows:

ccuser='Joseph Smith <joe@hisplace.org>';
PUT "!EM_CC!" ccuser;

A recipient can also be specified as a nickname that will be resolved from your NAMES file.

!EM_SUBJECT! subject

replaces the current subject of the message with subject.

!EM_CONTENTTYPE! content-type

replaces the current content-type of the message with content-type.

!EM_ATTACH! file-specifications

replaces the names of any attached files with file-specifications. For each attachment, specify filename and filetype and either the filemode or the SFS directory name. The default filemode is `*', as follows:

PUT '!EM_ATTACH!' 'opinion txt';

To attach more than one file, enclose each file specification in single or double quotes and enclose the list of file specifications in parentheses, as follows:

mycfg='sasv8 config *';
syscfg='sasv8sys config *';
PUT '!EM_ATTACH!' '("'mycfg'"'  '"'syscffg'")';

The directives that perform actions are as follows:

!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, SAS sends the message when it encounters the directive, and sends it again at the end of the DATA step.
!EM_ABORT!: aborts 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, TYPE, ATTACH, and the message body.

Using the DATA Step, Procedures, or SCL Code to Send E-Mail

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

a FILENAME statement that specifies the EMAIL device-type
FILENAME or FILE statements that contain e-mail options that indicate the e-mail recipients, subject, and any attached files
for a DATA step or in SCL code, PUT statements that create the body of the message
for a DATA step or in SCL code, PUT statements that contain special e-mail directives that can override the e-mail attributes (TO, CC, SUBJECT, ATTACH) or perform actions (such as SEND, ABORT, and start a NEWMSG)
for procedures, ODS statements or graphics options that direct output to the EMAIL fileref.

Sending E-Mail from the DATA Step

Suppose that you want to share a copy of your SASV8 CONFIG file with your coworker Jim, whose user ID is JBrown. You could send it by submitting the following DATA step:

filename mymail email 'JBrown' 
         subject='My SASV8 CONFIG file'
         attach='sasv8 config';

data _null_;
   file mymail;
   put 'Jim,';
   put 'This is my SASV8 CONFIG 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 in 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' 
         'steve@abc.com')
      subject='My SAS output'
      attach=('results listing' '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 to control which recipients get which message. For example, suppose that you want to send customized reports to members of two different departments. 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 '.';
   
   /* ATTACH the appropriate report     */
   if dept='marketing' then
      put '!EM_ATTACH! mktrept txt';
   else                                  
      put '!EM_ATTACH! devrept txt';
                        
   /* 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]

Sending Procedure Output as E-Mail

Procedures that write to filerefs can be used to send e-mail. The following example shows how to use the Output Delivery System (ODS) to send HTML output in e-mail:

filename outbox email
   to=susan
   type='text/html'
   subject='Temperature conversions'
   ;

data temperatures
   do centigrade = -40 to 100 by 10;
      fahrenheit = centigrade*9/5+32;
      output;
   end;
run;

ods html
   body=outbox /* Mail it! */
   rs=none;

title 'Centigrade to Fahrenheit Conversion Table';
proc print;
id centigrade;
var fahrenheit;
run;

ods html close;

The following example shows how to create and send a GIF image in e-mail.

filename gsasfile email
   to=Jim
   type='image/gif'
   subject="SAS/GRAPH output"
   ;

goptions dev=gif gsfname=gsasfile;

proc gtestit pic=1; run;

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 the following 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 
            write the mail and the components,
            such as subject, address, 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