IBM Books

Reference

DTW_SENDMAIL


AIX HP-UX Linux OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X X

Purpose

Dynamically builds and transmits electronic mail (e-mail) messages.

Format

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message, IN Subject, IN CarbonCopy, IN BlindCarbonCopy, IN ReplyTo, IN Organization)

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message, IN Subject, IN CarbonCopy, IN BlindCarbonCopy, IN ReplyTo)

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message, IN Subject, IN CarbonCopy, IN BlindCarbonCopy)

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message, IN Subject, IN CarbonCopy)

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message, IN Subject)

@DTW_SENDMAIL(IN Sender, IN Recipient, IN Message)

Parameters

Table 44. DTW_SENDMAIL Parameters

Data Type Parameter Use Description
string sender IN A variable or literal string that specifies the author's address. This parameter is required. Valid formats are:
  • Name <user@domain>
  • <user@domain>
  • user@domain
string recipient IN A variable or literal string that specifies the e-mail addresses to which this message will be sent. This value can contain multiple recipients, separated by a comma (,). This parameter is required. Valid recipient formats are:
  • Name <user@domain>
  • <user@domain>
  • user@domain
string message IN A variable or literal string that contains the text of the e-mail message. This parameter is required.
string subject IN A variable or literal string that contains the text of subject line. This is an optional parameter. You must specify a null string ("") to specify additional parameters.
string CarbonCopy IN A variable or literal string that contains the e-mail addresses, or names and e-mail addresses of additional recipients. This value can contain multiple additional recipients separated by a comma (,). See the Recipient parameter for valid recipient formats. This is an optional parameter. You must specify a null string ("") to specify additional parameters.
string BlindCarbonCopy IN A variable or literal string that contains the e-mail addresses, or names and e-mail addresses of additional recipients, but the recipients do not appear in the e-mail header. This value can contain multiple additional recipients separated by a comma (,). See the Recipient parameter for valid recipient formats. This is an optional parameter. You must specify a null string ("") to specify additional parameters.
string ReplyTo IN A variable or literal string that contains the e-mail address to which replies to this message should be sent. This is an optional parameter. You must specify a null string ("") to specify additional parameters. Valid ReplyTo formats are:
  • Name <user@domain>
  • <user@domain>
  • user@domain
string Organization IN A variable or literal string that contains the organization name of the sender. This is an optional parameter.

Return Codes

Table 45. DTW_SENDMAIL Return Codes

Return Code Explanation
-1001 The server could not process a Net.Data request to allocate memory.
1001 An input parameter contained a NULL value.
1002 An input parameter contained a string value which consisted of the null-terminating character.
1003 The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005 A parameter passed on a function call, required to be a string variable, was of a different variable type.
7000 Net.Data is unable to connect to the specified SMTP server.
7001 An SMTP error occurred while Net.Data tried to relay the e-mail message to the specified SMTP server.
7002 The specified SMTP server does not support the Extended Simple Mail Transfer Protocol (ESMTP).

Usage Notes

  1. You can use the optional configuration variable, DTW_SMTP_SERVER, to specify the SMTP server to use for transmitting e-mail messages. The value of this parameter can either be a host name, an IP address, or a node and name. When this variable is not defined, Net.Data uses the local host as the SMTP server. See the configuration chapter in the Net.Data Administration and Programming Guide for your operating system to learn more about this variable.
  2. OS/400, OS/2, Windows NT, and UNIX users: Standard Simple Mail Transfer Protocol (SMTP) servers accept only 7-bit data, such as U.S. ASCII characters. If your message has 8-bit characters, it is recommended that you specify an Extended Simple Mail Transfer Protocol (ESMTP) server; ESMTP servers accept 8-bit characters. Net.Data does not encode your 8-bit data into 7-bit data. If you do not have access to an ESMTP server, remove all 8-bit characters from the e-mail message.

    Net.Data for OS/390 users do not need to modify e-mail messages for SMTP servers.

  3. Character set support:
  4. The following list describes conditions under which Net.Data does not send an e-mail message:

Examples

Example 1: Function call that builds and sends a simple e-mail message

@DTW_SENDMAIL("<ibmuser1@ibm.com>", "<ibmuser2@ibm.com>", "There is a meeting at 9:30.", 
"Status meeting")

The DTW_SENDMAIL function sends an e-mail message with the following information:

Date: Mon, 3 Apr 1998 09:54:33 PST
To: <ibmuser2@ibm.com>
From: <ibmuser1@ibm.com>
Subject: Status meeting
 
There is a meeting at 9:30.
 

The information for Date is constructed by using the system date and time functions and is formatted in a SMTP-specific data format.

Example 2: Function call that builds and sends an e-mail message with multiple recipients, carbon copy and blind carbon copy recipients, and the company name

@DTW_SENDMAIL("IBM User 1 <ibmuser1@ibm.com>", "IBM User 2 <ibmuser2@ibm.com>, 
IBM User 3 <ibmuser3@ibm.com>, IBM User 4 <ibmuser4@ibm.com>", "There is a meeting at 9:30.", 
"Status meeting", "IBM User 5 <ibmuser5@ibm.com>", "IBM User 6 <ibmuser6@ibm.com", 
"meeting@ibm.com", "IBM")

The DTW_SENDMAIL function sends an e-mail message with the following information:

Date: Mon, 3 Apr 1998 09:54:33 PST
To: IBM User 2 <ibmuser2@ibm.com>, IBM User 3 <ibmuser3@ibm.com>, IBM User 4 <ibmuser4@ibm.com>
CC: IBM User 5 <ibmuser5@ibm.com>
BCC: IBM User 6 <ibmuser6@ibm.com>
From: IBM User 1 <ibmuser1@ibm.com>
ReplyTo: meeting@ibm.com
Organzation: IBM
Subject: Status meeting
 
There is a meeting at 9:30.

Example 3: Macro that builds and sends e-mail through a Web form interface

  %HTML(start) {
  <html>
  <body>
  <h1>Net.Data E-Mail Example</h1>
  <form method="post" action="sendemail">
  <p>To:<br><input name="recipient"><p>
  Subject:<br><input name="subject"><p> 
  Message:<br><textarea name=message rows=20 cols=40>
  </textarea><p>
  <input type="submit" value="Send E-mail"><br>
  </form>
  </body>
  </html>
  %}
 
  %HTML(sendemail) {
  <html>
  <body>
  <h1>Net.Data E-Mail Example</h1>
  @DTW_SENDMAIL("Net.Data E-mail Service <netdata@us.ibm.com>", recipient, message, subject)
  <p>E-mail has been sent out.
  </body>
  </html>
  %}

This macro sends e-mail through a Web form interface. The HTML start section displays a form into which the recipient's e-mail address, a subject, and a message can be typed. When the user clicks on the Send E-mail button, the message is sent out to the recipients specified in the HTML(sendemail) section. This section calls DTW_SENDMAIL and uses the parameters obtained from the Web form to determine the content of the e-mail message, as well as the sender and recipients. Once the e-mail messages have been sent, a confirmation notice is displayed.

Example 4: A macro that uses an SQL query to determine the list of recipients

%Function(DTW_SQL) mailing_list(IN message) {
  SELECT EMAIL_ADDRESS FROM CUSTOMERS WHERE ZIPCODE='CA'
    %REPORT {
      Sending out product information to all customers who live in California...<P>
      %ROW {
        @DTW_SENDMAIL("John Doe Corp. <John.Doe@doe.com>", V1, message, "New Product Release")
        E-mail sent out to customer $(V1).<BR>
      %}
    %}
  %}

This macro sends out an automated e-mail message to a specified group of customers determined by the results of a SQL query from the customer database. The SQL query also retrieves the e-mail addresses of the customers. The e-mail contents are determined by the value of message and can be static or dynamic (for example, you could use another SQL query to dynamically specify the version number of the product or the prices of various offerings).


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]