DTW_SENDMAIL

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

Purpose

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

Format
Note to Beta customers

The implementation of this feature is still under review and might change when the product is released for general availability.

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

@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 46. 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.
string Attachments
IN A variable or literal string that specifies the relative paths to the files to be sent. This value can contain multiple files, separated by a comma (,), but can not contain a ".." string. These files will be searched in the order of directories listed in the ATTACHMENT_PATH configuration variable.

The following content types can be sent as attachments:

  • image/jpeg
  • image/gif
  • audio/basic
  • application/octet-stream (general)

Return Codes

Table 47. 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 An incorrect number of parameters were passed on a function call.
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 hostname or an IP address. 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. DTW_SMTP_SERVER is ignored on OS/390.
  2. 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>
  <p>Subject:<br /><input name="subject" /></p> 
  <p>Message:<br /><textarea name=message rows=20 cols=40>
  </textarea></p>
  <p><input type="submit" value="Send E-mail"></p>
  </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.</p>
  </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 product information to our customers 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 | Index ]