Chapter Contents

Previous

Next

Sending E-Mail from within the SAS System

The SAS System lets you send e-mail either interactively (using a dialog box) or programmatically (using SAS statements in a DATA step or SCL). SAS supports the Vendor Independent Mail (VIM--such as Lotus cc:Mail and Lotus Notes) interface.

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

Note:   You need an e-mail program that supports VIM before you can take advantage of SAS e-mail support. Also, although you can use the SAS System to send messages, you must use your e-mail program to view or read messages.  

Initializing E-Mail

The SAS e-mail feature supports the following SAS system options in the SAS configuration file or in your SAS session:

-EMAILSYS VIM

specifies the Vendor Independent Mail interface.

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

-EMAILDLG SAS

specifies to use the e-mail interface that is provided by the SAS System.

-EMAILID "name"

specifies your e-mail login. 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 this:

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 signed on to your e-mail system already), the SAS System will prompt you for them when you initiate e-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 E-Mail

The default value of the EMAILDLG system option is SAS. The default lets you send e-mail by using a dialog box that is provided by the SAS System.

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 those who will receive a copy of the mail that 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 if you want.

Note:

the body of your message. You can copy text from SAS application windows or other OS/2 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 by using the arrow keys or the PgUp and PgDn keys.

Some e-mail systems 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 an OS/2 application (for example, the .TXT extension might be associated with a text editor).

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 that the addresses that 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 your immediate local-area network (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 that you are using and on the configuration of your network. For example, suppose that you want to send e-mail to a colleague on the Internet. Your LAN might have a gateway to the Internet so 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 e-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 by 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 that the facility is accessible.

Using the DATA Step or SCL to Send E-Mail

Using the EMAIL access method, you can use the DATA step or SCL to send e-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, by customizing the user interface.

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

• a FILENAME statement with the EMAIL device-type keyword

• options that are specified in the FILENAME or FILE statement and that indicate 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 NEWMSG).

To send e-mail by using the DATA step or SCL, you must be signed on to your e-mail program. For more information about how to use your e-mail program with the SAS System, see Sending E-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 that you want to send mail to. You can specify 'nul' here, and then specify the destination addresses in email-options.

email-options

can be any of the following:

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

EMAILID="name"

specifies your e-mail login ID or the profile that is used to access the underlying e-mail system. If name contains a space, enclose it in double quotes. You can specify this e-mail option in the FILENAME statement in order to override 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.You can specify this e-mail option in the FILENAME statement in order to override the SAS system option.

EMAILSYS=VIM

specifies the e-mail interface:

VIM

Vendor Independent Mail, such as Lotus Notes or cc:Mail, which is the default.

TO=to-address

specifies the primary recipients of the e-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 that you want to receive a copy of the e-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 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.

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

You can also use PUT statements to specify e-mail directives that change the attributes of your message or that perform actions with it. You can 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. 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 by 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 that 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. Specifying these options overrides 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 that is behind a FRAME entry that is 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 the following 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. This entry 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.