"Send Internet Mail from an ILE Program," explains the QtmmSendMail API, a V4R2 API (also available via PTF for V4R1 and V3R7) that lets an Integrated Language Environment (ILE) program send Multipurpose Internet Mail Extensions (MIME) e-mail. At my company, we've put this API to work in an ILE RPG utility I developed, SNDEMAIL, that creates and sends text e-mail messages to internal users and customers. SNDEMAIL includes the SNDEMAIL command (Figure 1), which can be run either from an AS/400 command line or another program, and the ILE RPG program SNDEMAILR (Figure 2). (To download the code for SNDEMAIL.Go to SystemiNetwork.com/code and Select September 1998 from the drop-down menu.)
Program SNDEMAILR requires the following eight parameters to be passed into it from the SNDEMAIL command:
- FileName: a 255-character field that contains the name of the MIME header file to be created in the AS/400 IFS - for example, '/tmp/mimehdr.txt'.
- Addressee: a 256-character field containing the recipient's e-mail address.
- Originator: a 255-character field containing the sender's e-mail address.
- AddresseeName: a 256-character field containing the recipient's name.
- OriginName: an 80-character field containing the name of the sender of the e-mail message.
- Attachment: an array of file attachment names (from 0 to 30) of 256 characters each. The first two bytes of this array contain a binary number indicating the number of array elements being passed.
- Subject: a 256-character field containing the subject of the e-mail message.
- Message: a 512-character field containing the e-mail message text.
SNDEMAILR's logic is simple. First, in the WriteHdr subroutine, the program creates a MIME file and writes it to an integrated file system (IFS) directory. You can create the MIME file in any IFS directory other than QSYS.LIB. However, you should avoid creating MIME files in the QDLS directory because reading to and writing from QDLS is slower than with the other file systems and because with QDLS each e-mail sender must be registered in the AS/400 system distribution directory via the WRKDIRE (Work with Directory Entries) command. I normally create the MIME file in the '/tmp' directory of the root file system.
Note that SNDEMAILR's WriteHdr subroutine uses several IFS APIs, including open(), read(), write(), and close(). First, the MIME file is opened, closed, and then reopened. This is necessary to establish the correct code page (819, US-ASCII) for the MIME file so the data being written to it can be converted from EBCDIC to ASCII. SNDEMAILR then creates the header fields, such as Sender:, Date:, and From:, and the message text itself. Next, if the e-mail message includes attachments, SNDEMAILR retrieves them one at a time, reads each one, and writes it to the MIME header file. MIME e-mail attachments are actually embedded within the MIME file. Note that the SNDEMAIL utility supports only text attachments, which are sufficient for my company's purposes. However, as noted in "Send Internet Mail from an ILE Program," the QtmmSendMail API also supports binary attachments.
In a MIME message, the Date: field requires a particular format, as in the following example:
Thu, 19 Mar 1998 19:28:01 -0500
(The -0500 is the difference in hours between the current time zone and Greenwich Mean Time.) However, to keep the program short, SNDEMAILR does not build the date field. Doing so would require two additional procedures to retrieve the day of the week and month name. Also note that neither this program nor the QtmmSendMail API supports a return receipt function.
After subroutine WriteHdr builds the MIME message, SNDEMAILR calls the QtmmSendMail API to send the message, passing to the API the parameters it requires ("Send Internet Mail from an ILE Program" explains the required QtmmSendMail parameters).
Features You Could Add
SNDEMAIL provides a "plain-vanilla" example of how to use the QtmmSendMail API. However, you could enhance the utility by adding features such as
- support for multiple recipients (the API supports a theoretical limit of 32,767 recipients)
- support for carbon copy and blind carbon copy recipients
- error checking on the IFS APIs and the QtmmSendMail API
- support for binary attachments
- creation of a log of sent e-mail messages
- automatic generation of a unique name for the MIME header file, relieving a user from having to do this manually
SNDEMAIL is only the first step in a complete solution for sending e-mail from AS/400 ILE programs. Although it supports text attachments (which are an essential part of an e- mail system), it does not directly support the two most common types of AS/400 files - database and spool as attachments. Thus, to round out SNDEMAIL, you'd need ancillary programs to perform tasks such as copying a database file to a standard PC spreadsheet format (e.g., comma-separated variable, or CSV) and copying a spool file to a standard PC word processing format (e.g., Rich Text Format or text). Fortunately, tools to perform these tasks are widely available and range from vendor-supplied utilities to homegrown solutions (e.g., copying a spool file to a .TXT file by using the CPYSPLF (Copy Spooled File) and CPYTOSTMF (Copy to Stream File) commands). With your imagination and RPG programming skills, you'll surely find many uses for the handy QtmmSendMail API.
David Leland is MIS Director at The Harter Group in Middlebury, Indiana, and Fixtures Furniture in Kansas City, Missouri, manufacturers of high-quality seating products. You can reach him at (219) 825-5871 or email@example.com.