Chapter Contents

Previous

Next

Sending Electronic Mail from within the SAS System

The SAS System lets you send electronic mail either interactively (using a dialog box) or programmatically (using SAS statements in a DATA step or SCL). SAS supports these types of electronic mail interfaces: MAPI (such as Microsoft Exchange) and Vendor Independent Mail (VIM--such as Lotus cc:Mail and Lotus Notes).

To send e-mail from within SAS, select the File pull-down menu and then select Send.... Your electronic mail software provides the interface to send mail.

Note:   You need an electronic mail program that supports one of these protocols before you can take advantage of the SAS System's electronic mail support. Also, although you can use the SAS System to send messages, you must use your electronic mail program to view or read messages.  

Initializing Electronic Mail

The electronic mail feature of the SAS System supports the following SAS system options in the SAS configuration file or when invoking your SAS session:

-EMAILSYS MAPI | VIM

specifies which e-mail interface to use. By default, the SAS System uses MAPI.

Note:   The directory that contains the e-mail DLL file (for example, MAPI32.DLL or VIM32.DLL) must be specified in your Windows PATH environment variable. The SAS System will use the first e-mail DLL that it finds for the interface you specify. Your installed e-mail support must use 32-bit architecture.  

-EMAILDLG NATIVE | SAS

specifies whether to use the native e-mail interactive dialog box provided by your e-mail application or the e-mail interface provided by the SAS System. You can use the native dialog box with the SAS System only if the e-mail system supports the MAPI interface. SAS uses the native dialog box by default.

-EMAILID "name"

specifies your VIM e-mail login ID or MAPI profile used to access the underlying e-mail system. If name contains spaces, you must enclose it in double quotes.

-EMAILPW "password"

specifies your e-mail login password, where password is the login password for your login name. If password contains spaces, you must enclose it in double quotes.

For example, if your login ID is J.B. Smith and your password is rosebud, your SAS invocation might look like:

c:\sas\sas.exe -emailsys vim 
               -emailid "J.B. Smith" 
               -emailpw rosebud

Note:   If you don't specify the EMAILID and EMAILPW system options at invocation (and you are not otherwise logged in to your e-mail system already), the SAS System will prompt you for them when you initiate electronic mail.  

You must have a 32-bit e-mail client program to initiate e-mail from the SAS System.

Using the Send Mail Dialog Box to Send Electronic Mail

The default value of the EMAILDLG system option is NATIVE, which lets you take advantage of your own e-mail software when sending e-mail from within SAS. If the value of the EMAILDLG system option is set to SAS, you can send electronic mail using a dialog box provided by the SAS System. If you are using the native e-mail interface provided by your e-mail system vendor, this discussion about the Send Mail dialog box does not apply to you. For more information about using that interface, see the documentation from your e-mail vendor.

You can access the Send Mail dialog box by selecting the Send... item from the File menu. Send Mail Dialog Box shows the Send Mail dialog box.

Send Mail Dialog Box

The following are descriptions of the fields in the Send Mail dialog box:

To:

the primary recipients of your e-mail. You must specify one or more e-mail addresses that are valid for your mail system before you can send e-mail. Separate multiple recipients with a semicolon (;).

Cc:

the e-mail addresses of any users that you want to receive a copy of the mail you are sending. You can leave this field blank, if you want. Separate multiple recipients with a semicolon (;).

Subject:

the subject of your message. You can leave this field blank.

Note:

the body of your message. You can copy text from SAS application windows or other Windows applications and paste it here (using the CTRL+C and CTRL+V accelerator key combinations). If your note text exceeds the window space provided, you can scroll backward and forward using the arrow keys or the PgUp and PgDn keys.

Some e-mail systems currently limit the note length to 32K (or 32,768 characters). Text that you enter in the Note: area will automatically wrap at the right side.

For large amounts of text, attach a text file as described below.

Attachments:

icons and names of any files that you want to send with the message. You or the recipient can open an attached file by double-clicking on its icon, provided that its file extension has a File Manager association with a Windows application (for example, the .TXT extension might be associated with Notepad).

Use the [Attach File...] button to open a file selection dialog box that you can use to select files to attach. To remove an attachment, select the file's icon in the Attachments field and click on [Remove].

Note:   The attached files are sent as they exist on the disk; that is, if you edit a file before attaching it to an e-mail message, the saved version of the file is sent with the message.  

To verify whether the addresses you specified in the To: and Cc: fields are valid, click on [Check Names]. If one or more of the addresses is ambiguous (that is, the mail program cannot locate them in the address books) the SAS System displays an error message and highlights the first ambiguous address.

Note that an ambiguous address is not necessarily invalid. It is possible to send mail to recipients outside of your immediate LAN (using gateways), whose addresses might not be resolved by using [Check Names].

Whether an address is considered invalid or ambiguous depends on the e-mail program you are using and on the configuration of your network. For example, suppose you want to send e-mail to a colleague on the Internet. Your LAN might have a gateway to the Internet such that you can address the mail to JBrown@rhythm.com at Internet (where at is the gateway directive keyword and Internet is the name of a gateway on your LAN). Because your mail program uses the at keyword to direct your message to the Internet gateway, the address is considered valid. However, when you click on [Check Names], the address is considered ambiguous because the final destination address cannot be resolved using the local address book. You can still click on [Send] to send the message without an error.

Clicking on [Address...] invokes the address book facility for your e-mail program, provided the facility is accessible.

Using the DATA Step or SCL to Send Electronic Mail

Using the EMAIL access method, you can use the DATA step or SCL to send electronic mail from within the SAS System. This has several advantages:

• You can use the logic of the DATA step or SCL to subset e-mail distribution based on a large data set of e-mail addresses.

• You can automatically send e-mail upon completion of a SAS program that you submitted for batch processing.

• You can direct output through e-mail based on the results of processing.

• You can send e-mail messages from within a SAS/AF FRAME application, customizing the user interface.

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

• a FILENAME statement with the EMAIL device-type keyword

• options specified in the FILENAME or FILE statement 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).

To send e-mail using the DATA step or SCL, you must be signed on to your e-mail program. For more information about how to use your electronic mail program with the SAS System, see Sending Electronic Mail from within the SAS System.

Syntax

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

where:

fileref

is a valid fileref.

EMAIL

is the device-type keyword that indicates that you want to use e-mail.

'address'

is the valid destination e-mail address of the user you want to send mail to. You can specify 'nul' here, and then specify the destination addresses in the email-options.

email-options

can be any of the following:

Note:   Each e-mail option can be specified only in a FILENAME statement which overrides the corresponding SAS system option.   

EMAILID="name"

specifies your e-mail login ID or profile that is used to access the underlying e-mail system. If you specify MAPI in the EMAILSYS e-mail option, specify your profile name. If name contains a space, enclose it in double quotes. This e-mail option can be specified in the FILENAME statement which overrides the SAS system option.

EMAILPW="password"

specifies your e-mail login password, where password is the login password for your login name. If password contains a space, enclose it in double quotes. This e-mail option can be specified in the FILENAME statement which overrides the SAS system option.

EMAILSYS=MAPI | VIM

supports two types of electronic mail interfaces:

MAPI

interface supported by Windows and Windows NT, which is used by Microsoft Exchange. MAPI is the default.

VIM

Vendor Independent Mail, such as Lotus or cc:Mail.

TO=to-address

specifies the primary recipients of the electronic mail. If an address contains more than one word, you must enclose the address in double quotes. If you want to specify more than one address, you must enclose the group of addresses in parentheses and each address in double quotes. For example, to="John Smith" and to=("J. Callahan" "P. Sledge") 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, you must enclose the address in double quotes. If you want to specify more than one address, you must enclose the group of addresses in parentheses and each address in double quotes. For example, cc="John Smith" and cc=("J. Callahan" "P. Sledge") are valid CC values.

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 the text in double quotes. For example, subject=Sales and subject="June Report" are valid subjects.

ATTACH=filename.ext

specifies the full path name of one or more files to attach to the message. If you want to attach more than one file, you must enclose the group of filenames in parentheses and each filename in double quotes. For example, attach=opinion.txt and attach=("june94.txt" "july94.txt") are valid file attachments.

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. You can specify only one directive in each PUT statement; each PUT statement can contain only the text associated with the directive it specifies. Here are the directives that change your message attributes:

!EM_TO! addresses

replaces the current primary recipient addresses with addresses. If a single address contains more than one word, you must enclose that address in quotes. If you want to specify more than one address, you must enclose each address in quotes and the group of addresses in parentheses.

!EM_CC! addresses

replaces the current copied recipient addresses with addresses. If you want to specify more than one address, you must enclose each address in quotes and the group of addresses in parentheses.

!EM_SUBJECT! subject

replaces the current subject of the message with subject.

!EM_ATTACH! filename.ext

replaces the names of any attached files with filename.ext. If you want to specify more than one file, you must enclose each filename in quotes and the group of filenames in parentheses.

Here are the directives that perform actions:

!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. This directive is useful for writing DATA step programs that conditionally send messages or use a loop to send multiple messages.

!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. By default, SAS sends a message for each FILE statement.

!EM_NEWMSG!

clears all attributes of the current message that were set using PUT statement directives.

Example: Sending E-Mail from the DATA Step

Suppose you want to share a copy of your SAS configuration file with your coworker Jim, whose user ID is JBrown. Sending a File with the Data Step shows how to send the file with the DATA step.

Sending a File with the Data Step


filename mymail email "JBrown"
         subject="My SASV8.CFG file"
         attach="c:\sas\sasv8.cfg";
data _null_;
  file mymail;
  put 'Jim,';
  put 'This is my SAS configuration file.';
  put 'I think you might like the';
  put 'new options I added.';
run;

Attaching a File and Specifying Options in the FILE Statement sends a message and attaches a file to multiple recipients, and specifies the e-mail options in the FILE statement instead of the FILENAME statement.

Attaching a File and Specifying Options in the FILE Statement


filename outbox email "Ron B";
data _null_;
  file outbox
        /* Overrides value in */ 
        /* filename statement */
     to=("Ron B" "Lisa D")
     cc=("Margaret Z" "Lenny P")
     subject="My SAS output"
     attach="c:\sas\results.out"
     ;
  put 'Folks,';
  put 'Attached is my output from the SAS';
  put '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. Sending Customized Messages Using the Data Step shows such a DATA step.

Sending Customized Messages Using the Data Step


filename reports email "Jim";
data _null_;
  file reports;
  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 '!EM_ATTACH! c:\mktrept.txt';
  else  /* ATTACH the appropriate report */
    put '!EM_ATTACH! c:\devrept.txt';

     /* Send the message. */
  put '!EM_SEND!'; 
     /* Clear the message attributes.*/
  put '!EM_NEWMSG!'; 
     /* Abort the message before the */
     /* RUN statement causes it to   */
     /* be sent again.               */
  put '!EM_ABORT!';  
  cards;
  Susan          marketing
  Jim            marketing
  Rita           development
  Herb           development
  ;
run;

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.  

Overriding SAS System Options shows how to send a message and to attach a file to multiple recipients, and it specifies the e-mail options in the FILENAME statement instead of the FILE statement. This has the effect of overriding the values for the SAS system options EMAILID, EMAILPW, and EMAILSYS.

Overriding SAS System Options


filename outbox email "Ron B" emailsys=VIM 
 emailpw="mypassword" emailid="myuserid";
data _null_;
  file outbox
        /* Overrides value in */ 
        /* filename statement */
     to=("Ron B" "Lisa D")
     cc=("Margaret Z" "Lenny P")
     subject="My SAS output"
     attach="c:\sas\results.out"
     ;
  put 'Folks,';
  put 'Attached is my output from the SAS';
  put 'program I ran last night.'; 
  put 'It worked great!';
run;

Example: Sending E-Mail Using SCL Code

The following example is the SCL code behind a FRAME entry designed for e-mail. The FRAME entry might look similar to the one shown in An Example E-Mail FRAME Entry.

An Example E-Mail FRAME Entry

The FRAME entry has objects 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.

Invoking SCL Code from a FRAME Entry shows the FRAME entry which also contains a pushbutton called SEND that invokes this SCL code (marked by the send: label).

Invoking SCL Code from a FRAME Entry


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

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.