1.  Abstract

To view an abstract of this document, click here.

2.  Introduction

The majority of SMTP (internet) e-mail sent from the MIT R/3 systems is sent via the custom function module Z_SENDMAIL. This function has been modified from its original state to enable programmers to instruct Z_SENDMAIL to intercept and/or log outgoing e-mail that it processes.

Two custom tables, ZEHCAT and ZEMCTRL are used to control both interception and logging of e-mail, and the log is written to a third custom table, ZEMLOG.

Interception of e-mail is useful for debugging, testing, validating, and for providing training. The original motivation for adding this feature to Z_SENDMAIL was to provide a method of preventing e-mail from being sent from non-production systems. When a new R/3 system is set up or refreshed, two entries should be established in custom table ZEHCAT to initially discard all e-mail sent via Z_SENDMAIL. Later, changes can be made as needed to support specific tests.

Logging of e-mail, while useful for debugging purposes, particularly for intermittent problems or problems that occur in the R/3 production system, is intended to be used solely for short-term debugging purposes and should only be enabled when attempting to track down a problem. Logging is not intended, nor should it be used, as an audit trail of messages sent.

3.  How Interception and Logging Works

Each call to Z_SENDMAIL is associated with an e-mail handling category taken either from parameter P_HNCAT or, if this parameter is not included in the function call, from table ZEMCTRL (see below for details on this distinction). The handling category is referenced in control table ZEHCAT, which contains the following instructions for processing the Z_SENDMAIL call based on the assigned handling category:

1. Whether to log the call to Z_SENDMAIL.
2. Whether to intercept the e-mail message, and if so, whether to:
   1. Discard the message.
   2. Redirect the message to alternate "To" and "Cc" addresses.
      (The alternate addresses are provided by ZEHCAT).
   3. Write the message to a UNIX file.
      (The UNIX path suffixed after "/usr/bridges/<system>/saptmp/" is supplied by ZEHCAT).
   4. Write the message to an SAP printer spool file.
      (The printer name and spool settings are provided by ZEHCAT).

E-mail handling categories are assigned based on the type of e-mail and the class of recipient to receive the e-mail. The table of current handling category assignments can be found here. Requests for the assignment of an additional handling category should be directed to the FSS Infrastructure team.

There are currently two ways to specify the handling category associated with a call to Z_SENDMAIL:

1. Explicitly pass an e-mail handling category as parameter P_HNCAT.

   Every new call to Z_SENDMAIL should pass an explicit e-mail handling category as parameter P_HNCAT. Because many programs that call Z_SENDMAIL pre-date the intercepting and logging modifications, the P_HNCAT parameter is currently optional so that such programs do not require modification simply to add a handling category to the function call. It is intended, however, that every existing call to Z_SENDMAIL will eventually be modified to pass an explicit e-mail handling category.

   The table of current e-mail handling category assignments can be found here.

   The most direct way to associate a handling category with an existing call to Z_SENDMAIL is to modify the calling program to explicitly pass an e-mail handling category as parameter P_HNCAT, and then transport the modified program to the R/3 test and other environments.

   call function 'Z_SENDMAIL' exporting p_to p_cc p_bcc p_from p_reply_to p_subject p_hncat tables message exceptions error_in_send spaces_in_req_params invalid_email_address_syntax unable_to_open_unix_file unable_to_write_to_unix_file unable_to_execute_unix_program interception_control_tables interception_to_spool interception_process

   =  <TO ADDRESS> =  <CC ADDRESS> =  <BCC ADDRESS> =  <FROM ADDRESS> =  <REPLY-TO ADDRESS> =  <SUBJECT LINE> =  <HANDLING CATEGORY>  =  <MESSAGE TABLE> =  1 =  2 =  3 =  4 =  5 =  6 =  7 =  8 =  9.

2. Create an entry in table ZEMCTRL with the calling program name and the desired e-mail handling category.

   If a program that calls Z_SENDMAIL pre-dates the intercepting and logging modifications, such programs do not require modification simply to add a handling category to the function call. Although it is intended that every existing call to Z_SENDMAIL will eventually be modified to pass an explicit e-mail handling category, programmers have the option of using table ZEMCTRL to map such programs to the appropriate handling category.

   To map a calling program to a handling category, an entry is made in table ZEMCTRL with the calling program name as it appears in SY-CPROG and the desired e-mail handling category. This method allows only a single handling category per program, and so is not suitable for programs that require more than one handling category. Also, this method does not require a transport to R/3 environments other than the environment in use.

   ZEMCTRL	Field Name	Data Element	Data Type	Length	Description
   	MANDT	MANDT	CLNT	3	Client
   	PROG	PROGRAMM	CHAR	40	Calling program name (SY-CPROG)
   	HNCAT	ZHNCAT	CHAR	2	Associated e-mail handling category

   The table of current e-mail handling category assignments can be found here.

   When a chain of programs is called, care should be taken in determining the value for field PROG, the calling program name as it appears in SY-CPROG. It is the first program within a chain of calls that is the calling program.

4.  E-mail Handling Categories

Each e-mail handling category is a unique, two-letter assignment designated for use by particular ABAP programs for their exclusive use. Handling categories are assigned based on the type of e-mail and the class of recipient to receive the e-mail, and so a program not explicitly assigned to a particular handling category may not use that category.

The handling category (either passed as parameter P_HNCAT or retrieved from table ZEMCTRL) is referenced in table ZEHCAT, and the following instructions for processing the Z_SENDMAIL call are retrieved:

1. Whether to log the call to Z_SENDMAIL.
2. Whether to intercept the e-mail message, and if so, whether to:
   1. Discard the message.
   2. Redirect the message to alternate "To" and "Cc" addresses.
      (The alternate addresses are provided by ZEHCAT).
   3. Write the message to a UNIX file.
      (The UNIX path suffixed after "/usr/bridges/<system>/saptmp/" is supplied by ZEHCAT).
   4. Write the message to an SAP printer spool file.
      (The printer name and spool settings are provided by ZEHCAT).

The table of current e-mail handling category assignments can be found here.

If there are no existing handling category assignments for a program or if the existing assignments are not suitable, a request may be sent to the FSS Infrastructure team for the assignment of a new handling category.

Under special circumstances, new handling categories may be needed on short notice or without prior determination of their precise use. In this case, a programmer or development team may arrange with the FSS Infrastructure team to receive one or more pre-assigned handling categories with the stipulation that the programmer will forward the following information to the FSS Infrastructure team as soon as the handling category's application is determined.

1. Calling program name (SY-CPROG)
2. Type of e-mail
3. Type of recipient

Special Handling Categories

Two particular e-mail handling categories are assigned to address the special circumstance where there is no correlation between a handling category and an entry in table ZEHCAT. This may occur either because no handling category is specified, or because no entry exists in table ZEHCAT for a specified handling category.

1. <space><space>

   Handling category <space><space> is imposed upon all e-mail sent via Z_SENDMAIL for which no handling category is specified for the calling program (neither explicitly as parameter P_HNCAT nor mapped via an entry in table ZEMCTRL).

2. 

   Handling category ++ is imposed upon all e-mail sent via Z_SENDMAIL for which a handling category is specified (either explicitly as parameter P_HNCAT or mapped via an entry in table ZEMCTRL), but no corresponding entry is found in table ZEHCAT.

How the imposed handling category is then processed depends on the contents of table ZEHCAT. If there are no entries in table ZEHCAT for the current R/3 system, all e-mail sent via Z_SENDMAIL will be delivered normally, that is, will neither be intercepted nor logged. Table ZEHCAT in the production system, for instance, should typically contain no entries to allow for normal e-mail delivery. If table ZEHCAT contains only the entries shown below for the <space><space> and ++ handling categories, all e-mail sent via Z_SENDMAIL will be intercepted and discarded. Upon creating or refreshing a non-production R/3 system, these entries should be established in table ZEHCAT so that all e-mail is discarded. Changes can later be made to support specific testing.

5.  The Tables

Programmers may view or modify the contents of the ZEMCTRL and ZEHCAT tables via utility program ZBRSMAIL. This program presents the following modification options for each table:

1. Delete all rows of the table.
2. Replace all table contents with the contents of a file.
3. Append a file to the table.
4. Write all table contents to a file.
5. Do nothing.

   In addition to the above options, ZBRSMAIL presents the following additional modification option for table ZEHCAT:

6. Modify all rows where e-mail handling category, HNCAT, matches a select-option.

The modification option selected is applied based on the following action options:

1. Report the contents of the table before the modification is made.
2. Report the contents of the table as they will appear after the modification is made.
3. Make the modification to the table.

View the ZBRSMAIL selection screen for the ZEMCTRL or the ZEHCAT tables.

A separate utility program is currently under development that will enable programmers to selectively display or delete entries in the ZEMLOG table. Until that utility is available, transaction SE16 may be used to view e-mail log entries in table ZEMLOG.

Table ZEMCTRL

For a program that does not pass an explicit P_HNCAT parameter in its call to Z_SENDMAIL, custom table ZEMCTRL is used to map the calling program to its assigned e-mail handling category. (If the P_HNCAT parameter is passed, ZEMCTRL is not referenced.) Eventually, all calls to Z_SENDMAIL will pass the P_HNCAT parameter and, at that time, table ZEMCTRL will no longer be needed.

To map a calling program to a handling category, an entry is made in table ZEMCTRL with the calling program name as it appears in SY-CPROG and the desired e-mail handling category. Table ZEMCTRL allows only a single handling category per program, and so is not suitable for programs that require more than one e-mail handling category.

When a chain of programs is called, care should be taken in determining the value for field PROG, the calling program name as it appears in SY-CPROG. It is the first program within a chain of calls that is the calling program.

Table ZEMCTRL contains the following fields:

Table ZEHCAT

For a program that passes an explicit P_HNCAT parameter in its call to Z_SENDMAIL, custom table ZEHCAT is referenced to determine how the call should be processed. This determination is made by reading the control field settings that correspond to the e-mail handling category specified in the P_HNCAT parameter.

The ZEHCAT control fields and what they specify are as follows:

1. LOG  Whether to log the call to Z_SENDMAIL.
2. CMODE  Whether to intercept the e-mail message.
   ACTION  If intercepted, whether to:
   1. Discard the message.
   2. Redirect the message to alternate "To" and "Cc" addresses.
      (The alternate addresses are provided by MAILTO and CCTO, respectively).
   3. Write the message to a UNIX file.
      (The UNIX path suffixed after "/usr/bridges/<system>/saptmp/" is supplied by MAILTO).
   4. Write the message to an SAP printer spool file.
      (The printer name is provided by PDEST, and the spool settings by PRIMM, PRREL, and PRNEW).

Table ZEHCAT contains the following fields:

Table ZEMLOG

E-mail logging uses the same e-mail handling categories as interception and, while logging is controlled by table ZEHCAT, the e-mail data to be logged is written to custom table ZEMLOG.

A utility program is currently under development that will enable programmers to selectively display or delete entries in the ZEMLOG table. Until that utility is available, transaction SE16 may be used to view e-mail logs.

Please note that logging e-mail is resource intensive and should only be enabled for diagnostic purposes. In order to manage the volume of data contained in this table, ZEMLOG is subject to periodic deletion of entries.

Table ZEMLOG contains the following fields:

TOP OF PAGE | E-MAIL HANDLING CATEGORIES | DEVELOPMENT RESOURCES

	© Copyright 2000, 2001 by the Massachusetts Institute of Technology, Cambridge, Massachusetts, USA. To view the full Copyright Notice and Disclaimer, go to http://web.mit.edu/sapr3/dev/abap/disclaimer.html.
	last updated: 1 May 2001 by Amy E. King Comments and questions about this web site to aeking@mit.edu