Creating HTML based email on the iSeries
Author: Raymond Everhart
One of the easiest ways to distribute information is via email. The various types of content that can be incorporated into email makes it an especially powerful tool for communication and collaboration. Email is also being used to deliver automated messages when a given event occurs. It is now common practice for the shipment of an order to generate an email with a tracking number and a link to the carrier's tracking page. It is not unusual for an email to contain images, formatted data and links to websites. The iSeries also has these same capabilities. The key to leveraging this capability is in the use of HTML based email. The use of HTML based email has its pros and cons, but it's use is widespread. It has been possible for some time to send email from the iSeries. The most common method has been the use of the SNADS architecture and the SNDDST(Send Distribution) command. The SNDDST command will create a "text-only" email and send it on its way.(see figure 1)
To View the Source Code Click Here
This technique is both fast and simple. While this approach works, it propagates the perception that the iSeries is a "Legacy System" and is technically inferior to other platforms that are available today. If you show the president of your company an automated "text-only" email and an email with your company logo, a nicely formatted table, a signature and his picture which do you think he will prefer? One thing that I learned a long time ago is that "value is perceived". If it looks better, it must be better. The purpose of this article is to help you incorporate a technique that adds "value" to your programs. Figure 2 shows the email from figure 1 but a few enhancements have been added using HTML.
HTML is a text-based method of describing how information should be displayed on the screen. Most email clients allow the use of HTML to make the content of an email message look like a web page. With just a little effort you can code in HTML. Since HTML is coded using alphanumeric characters, it can easily be accomplished on the iSeries in RPG. The only missing piece to this puzzle is the delivery mechanism. This is where the QtmmSendMail API comes in. The QtmmSendMail will send the contents of a file located on the IFS as an email. The 7 parameters that are required by the API are listed in the table below:
The QtmmSendMail API parameters
||Name of IFS File
||Length of IFS File name
||10 byte Integer|
||Sender's email Address
||Length of Sender's email address
||10 byte Integer|
||List of Recipients email addresses
||Number of recipients in list
||10 bye Integer|
||Error Data structure
In order to send HTML based email you need to be concerned with two issues. The text file containing the email needs to be properly formatted as a mime document, and the recipient list passed to the API also needs to be properly formatted. If you would like to explore the mime standard a little further, see "Email Attachments 101" at http://perl.about.com/library/weekly/aa032302a.htm .
To View the Source Code Click Here
The steps needed to utilize this technology are as follows:
Step 1. Create an empty file
This step is easily accomplished using the following embedded SQL statement in the BuildFile Subroutine:
Create table QTEMP/EMAIL (TEXT CHAR (80 ))
Now you have a file where you can compose your email message. I chose an arbitrary length of 80 just so it would be easily viewable on the screen when I needed to debug the final output.
Step 2. Write the Email header information
The email standard requires that certain lines of text be located at the beginning of the file. These items can be likened to the envelope used to mail a letter. In our example we are going to use the minimum number of lines required to create an email. The first two lines are obvious in their usage. The FROM and To lines indicate who the email is From and To and look like this:
From: "Spotlight Magazine"<firstname.lastname@example.org>
To: "Subscriber" <AllCustomers@Lab400.com>
The next line is the subject line. Once again this line is self-explanatory.
Subject: HTML Based Email from the iSeries
The next line allows you to specify a TimeStamp for when the email was sent and looks like this:
The line shown below indicates the version of mime encoding to use when processing this email. The email client uses this line when formatting the email for display.
The last line of our "envelope" indicates what type of content is contained in the email. For example, if you wanted to attach files, you would use a different content type.
Content-Type: Text/HTML; charset=US-ASCII
Step 3. Build the recipient list
In order for the API to process the file and route it to all of the recipients, a recipient list is passed as one of the parameters when the API is called. For each intended recipient of the email, there needs to an entry in the list. An entry in the list can be coded as a "To", "Carbon Copy"(CC) or "Blind Copy"(BC) address. The first 24 bytes of the list are a fixed length data structure that looks like this:
D ADDT0100 DS Based(ListPtr)
D NextOffset 9b 0
D AddrLen 9b 0
D AddrFmt 8
D DistType 9b 0
D Resrvd01 9b 0
D DestAddr 256
The NextOffset value contains a numeric value that represents the number of bytes to the next address in the list. The AddrLen field contains a numeric value that represents the number of bytes that the email address occupies in storage after the trailing blanks have been removed. The AddrFmt is a constant value of 'ADDT0100'. The DistType field contains a 0 if this is a "To" address, a 1 if this is a "Carbon Copy" address or a 2 if this is a "Blind Copy" address. The Resrvd01 field is not used but should be initialized to 0. The DestAddr field is the email address for this list entry. The DestAddr field is specified as 256 bytes in the data structure, but in the list, trailing blanks are removed. The total number of bytes used by a list entry is 24 + AddrLen. This data structure is repeated as many times as is necessary to define all of the email addresses in the list.
Step 4. Write the HTML header information
At this point you can begin writing HTML code to be included in the email. There are a number of HTML tags that can be included at this point. But for this example we're going to keep it simple and only code the necessities. In our example, we start with the <HTML> tag and then move right into the <BODY> section. The first object that we are going to define is a table to hold our image and header text. Notice that the image in figure 2 is also a link back to the iSeries website. Next we define another table that will hold the report. The HEADER subroutine defines the table and writes out the column headers to the first row of records.
Step 5. Write the Body of the email
Now you can write our detail records. In this example the 3 records are hard coded in the Body subroutine. In a production environment, this is where you would loop through your selected data and write it to the table. This subroutine was coded in Free format RPG to show how much easier it is to use Free Format RPG when long strings need to be manipulated.
Step 6. Write the Footer
Now that you have written your table we need to close out the HTML tags and indicate the end of the email. The Footer subroutine writes the ending tags for our table as well as the <BODY> and <HTML> tags.
Step 7. Move the file to the IFS
The QtmmSendMail only works with files stored on the IFS. So now you will need to move your file to the IFS. The easiest way to do this is with the CPYTOIMPF command. You could also have used the IFS APIs and written your file directly on the IFS, but that is the subject for another article. The CPYTOIMPF command will convert our DB2 file into ASCII and place it on the IFS. The command in the Move2IFS subroutine looks like this:
|CPYTOIMPF FROMFILE(QTEMP/EMAIL) |
MBROPT(*REPLACE) ' +
STMFCODPAG(*PCASCII) ' +
Step 8. Change the security settings for the IFS file
In order for the API to process and then delete the file on the IFS, we need to grant authority to QTCP and QMSF. The authority change is accomplished by using the following command from within the Move2IFS subroutine:
Step 9. Call the QtmmSendMail API
Now you are ready to call the API. All of your parameters are ready and now you use your prototyped call as follows:
|Callp SndEmail(%addr(IFSFile): |
Notice that the values passed to the API for the IFS Filename, Sender and the Recipient table are all pointers. When this API is called, the recipient table is used to send the email to everyone in the list. If the API is successful, the file on the IFS that contains the email is deleted.
The Fine Print
In order to create and run the program that accompanies this article; there are three prerequisites that must be met.
1) The SMTP Server must be configured and started. For information on configuring the SMTP server on the iSeries, go to the iSeries information center and search on SMTP.
2) A folder named EMAIL must exist on the IFS. To create the EMAIL folder, execute the following commands from an iSeries command line:
CHGAUT OBJ('email') USER(QMSF) DTAAUT(*X)
If you would like to change the location where the file is copied to or the name of the email file, change the value of the IFSFile variable and rerun the two previous commands.
3) Since the program contains embedded SQL statements, you will need the DB2 query manager and SQL development kit for iSeries installed on your iSeries order to create the program.
Imagine the possibilities
Just think of all the things you can do with this technique. You could alert the sales rep when a customer places a large order or falls behind on their payments. You could notify the production manager when a new item is incorrectly added to the system or if an item requires excessive cycle counts. If your applications are web enabled, you could even include a link to the program and display the customer or item record with one click. The possibilities are endless.
Raymond Everhart has over 18 years of IT experience with IBM midrange computers. He was a consultant, programmer, and educator for an IBM premier business partner in Upstate New York for 10 years, before relocating to the Dallas/Ft. Worth area in 1998. Since then, Raymond has been helping local companies implement new technologies with his consulting, programming and mentoring services. E-mail email@example.com