badip Content-type: text/html MMAIL home
Your authorization to to this site has been removed.
Reason code /%reasoncode%/.
top Content-type: text/html Expires: 0 MMAIL home
Skip to main content  
  Easy400   |       IBM System i home   |   RSS feed
Freeware
 
Introduction
Main utilities
5250 utility
Windows utility
Commands
Service program
Sample code
CGI support
FAQ
WEBMail
Bibliography
 
Download
 
 

 
Search   

This open-source utility (library MMAIL) for IBM System i allows to create, send and receive MIME (Multipurpose Internet Mail Extensions) files. It is authored by Giovanni B. Perotti, Italy.

The contents of these pages are related to the release dated /%datereleased%/.



1. Prerequisites, installation, contents, distribution, updates
2. Objectives and Restrictions
3. MIME files
4. QtmmSendMail API
5. MIME & Mail 5250 Utility
6. MIME & Mail Windows Utility
7. MIME & Mail miscellaneous utilities
8. Spool file to PDF conversion tools
9. SendMail service program
10. Commands
11. Duplicating a MMAIL installation to other systems
12. Development libraries
13. Cloning library MMAIL
14. Troubleshooting and FAQs
15. WEBMail
 
 

Why not sending some of our examples of MIME messages to your e-mail address?

Just press this button.

 




  1. Prerequisites, installation, contents, distribution, updates
Prerequisites
  1. Installers must have a general knowledge of TCP/IP servers involved in IBM System i electronic-mail support. Information can be found in Redbook AS/400 Electronic-Mail Capabilities.
  2. Minimum requirement is OS/400 V5R2.
  3. RPG-ILE compiler (just for the installation)
  4. Library QHTTPSVR (product 57xxDG1)
  5. Library QFNTCPL (AFP Compatibility Fonts, product 57xxSS1, option 8, feature 5050) required for conversion of spool files to PDF's.
  6. Library QCTX (AFP to PDF transform, product 5761TS1 options *BASE and 01) required starting V6R1 for using the "i5 OS AFP TO PDF TRANSFORM", see this page.
  7. If Scott Klement's library LIBHTTP is installed and service program LIBHTTP/HTTPAPIR4 is available, the local MMAIL tool does occasionally check whether a newer MMAIL version is available from site www.easy400.net. If so, it will send an alert message to the current user.
  8. System value QCCSID 65535 is not recommended. Job CCSID 65535 inhibits automated character conversion from one CCSID to another CCSID. Automated EBCDIC to ASCII character conversion is used in many MMAIL commands and functions.
    This is why MMAIL commands and functions, whenever running in a job with CCSID 65535, try to change the job CCSID to the job default CCSID. However, to perform a CHGJOB command, the job user profile must have job control (*JOBCTL) special authority.
    This means that user profiles missing *JOBCTL special authority may face severe problems running MMAIL commands or functions.
    Please also note that MFS jobs must not run with CCSID 65535. See the following FAQ for a way to overcome this problem.
  9. System value QRETSVRSEC.
    Access to the webmail application AMailer is through validation lists. If you plan to use this webmail application, then you must set system value QRETSVRSEC to 1.
Installation
  • The installation instructions are available in the Readme.txt file when you unzip the downloaded file mmail.zip.
  • If you already have a library MMAIL, you must rename it as MMAILOLD or delete it before restoring library MMAIL. Please also read the topic MMAIL update dependencies.
  • After restoring library MMAIL, you must run REXX procedure INSTALL from MMAIL/QREXSRC. This procedure does the following:
    1. Creates service programs and programs in library MMAIL
    2. Creates and populates library MMAILDATA (local data)
    3. Restores IFS directory /mmail
    4. Creates and populates IFS directory /mmaildata (local data)
    5. Restores libraries HPT and TIFFLIB (used by command MMAIL/CVTSPLFPDF, Convert Spool File to PDF)
    6. Runs a number of MMAIL commands to let the user define the preferred MMAIL default values. These commands can be run at any time to change MMAIL default values:
      SETCONFID
      to define the Company-Confidential statement
      CVTTOPDF
      to select the default spool file-to-pdf conversion utility
      EMLDFTBODY
      to define the default text to be used for a message body of an e-mail message when no text is provided for it
      CHARSET
      to select the default character set
      NOSUBJECT
      to define the default subject when no subject is provided in an e-mail message
      DSPF STMF('/mmail/conf/httpd.conf')
      to display the HTTP directives for a HHTP instance related to the MMAIL manual
Contents
  1. MMAIL is the base library.
    Two more libraries (HPT and TIFFLIB) are available. These libraries support the conversion of a spool file to a pdf.
    While library HPT is installed if the OS/400 release is at least V4R5, library TIFFLIB is installed only if the OS/400 release is at least V5R1.
  2. Service program mmail/sendmail is the base for all e-mail services provided. The functions of this service program are used in many utilities available in the package, are documented in a separate page and are available for your own developments.
  3. Service program mmail/gpsrvpgm is a duplicate of service program cgidev2/cgisrvpgm2. To develop ILE-RPG CGI programs providing e-mail services
    • include binding instructions via
      /copy mmail/qrpglesrc,hspecsbnd
    • include CGISRVPGM2 prototypes with a
      /copy mmail/qrpglesrc,prototypeb
    • include SENDMAIL prototypes with a
      /copy mmail/qrpglesrc,mailproto
  4. A general 5250 utility can be run via command mmail/mimemenu. It allows to:
    1. maintain an address book
    2. maintain groups (distribution lists)
    3. create a MIME message (some times also called "MIME file")
    4. send a MIME message
    5. maintain a catalog of existing MIME messages
    The functions of this utility are documented on separate pages. They provide very good examples of interfacing the base service program.
  5. A similar, very friendly utility is also available for Windows. This Client/Server utility requires Client Access Express and operates via service program mmail/wsendmail. It is documented on a separate page.
  6. A number of other commands are available through menu go mmail/mail. See this page for details. These commands can be easily used in your application programs. They allow to:
    1. e-mail a simple message
    2. e-mail a source member
    3. e-mail a spool file
    4. e-mail a save file
    5. another utility allows to capture given spool files from one (or more than one) output queues and to e-mail them to different distribution lists (groups).
Note 1- All functions supporting e-mailing of spool files include the ability to convert spool files to PDFs.
Note 2- The base service program includes the ability to customize messages by assigning values to user-provided variables. See procedure MimeVarTxt.
Note 3- All IBM System i programs and service programs are implemented either in ILE-RPG or CL. All sources are delivered. If you need to apply changes to a service program, you should run command mmail/compile after applying changes.
Sources are also available for the Windows Client/Server utility.

Distribution
  • Library MMAIL can be downloaded from the Easy400 site.

MMAIL updates
  • Whenever updates are necessary a new MMAIL version is released. Each MMAIL version has its own release date.
    • The current MMAIL version available is dated /%datereleased%/
    • To know the release date of the MMAIL version currently installed on your system, enter command MMAIL/RELEASED .
  • A list of changes in maintained in member MMAIL of source file MMAIL/WHATSNEW.
    Press here to display the latest changes.

MMAIL update dependencies
Some releases of MMAIL may include new subprocedures for service program MMAIL/SENDMAIL.
Since April 1, 2009 service program MMAIL/SENDMAIL has a zero signature.
If you already have installed MMAIL and you are going to install a new release of it, you should first check the release date of the existing MMAIL. You do that by running command
MMAIL/RELEASED.
  1. If the existing MMAIL carries a release date equal to or higher than April 1, 2009, your CGI programs bounded to service program SENDMAIL will have no problem with the new MMAIL release, as there will be no signature check with the new service program MMAIL/SENDMAIL.
  2. If you have a MMAIL version released prior to April 1, 2009 , after installing the new version of MMAIL you must run command
    MMAIL/REBIND library_name
    for each library containing programs bound to service program MMAIL/SENDMAIL.
    Command MMAIL/REBIND rebinds all service programs and CLLE/RPGLE programs in the user specified library.
  3. If you duplicated service program MMAIL/SENDMAIL to several program libraries (to make them independent from service program MMAIL/SENDMAIL, and be free to update library MMAIL in any moment), and you want to replace some of those duplicated SENDMAIL service programs with a more recent version available from library MMAIL, then you may use command
    MMAIL/DUPSRVPGM.
    This command:
    1. retrieves the libraries containing service program SENDMAIL
    2. lets you select the libraries to be processed
    3. for each selected library
      • replaces service program SENDMAIL in that library with a copy of service program MMAIL/SENDMAIL
      • rebinds all service programs of that library
      • rebinds all CLLE and RPGLE programs in that library.


  2. Objectives & Restrictions
  1. By using MMAIL you will be able to
    • Create MIME files embedding texts and images, and appending various type of attachments (source members, spool files, images, audios, videos, and any other type of binary objects, for instance OS/400 save files)
    • Send MIME files to addresses selected from an Address Book, and/or to selected Groups (distribution lists)
    After reading our service programs functions, you will be able to
    • write your own ILE-RPG programs to handle outgoing mail messages
    • write your own ILE-RPG programs to send out customized messages
  2. File systems restrictions
    MMAIL is just able to process objects residing in the "root" of the Integrated File system (IFS).
    Objects residing in other file systems (such as QDLS, QNCT, etc) cannot be processed by MMAIL.


  3. MIME files
Multipurpose Internet Mail Extensions are a set of standards defining a message representation protocol. These standards have grown up since 1982 through a number of RFC's (Request for Comments). Two major of them are listed here:
Aug. 1982 RFC822 Standard for the format of ARPA Internet Text Messages
Sept. 1993 RFC1521 Mechanisms for Specifying and Describing the Format of Internet Message Bodies
Other references: Multipurpose Internet Mail Extensions
Media types
Image media types (IANA)
Audio media types (IANA)
Video media types (IANA)
In brief, usually a MIME document is made of:
  • A number of top headers describing sender, date, MIME version, distribution, subject, importance, priority, and sensitivity of the document:
    Sender: as400man@chris.com
    Date: Wed, 09 Oct 2002 19:08:25 +0100
    From: Mike Shumaker <as400man@chris.com>
    MIME-Version: 1.0
    To: Sergei Bertolds <sergiob@argo.com>
    Subject: Some examples
    Importance: medium
    Priority: normal
    Sensitivity: normal
  • A Content-type header describing the document as MULTIPART/MIXED. This means that the document may contain more than one piece (for instance some text and an attachment) and that the single pieces may have different types.
    The same header contains another keyword, BOUNDARY; it defines the boundary line that will be used to separate the single pieces.
    Content-Type: MULTIPART/MIXED; BOUNDARY="--PART.BOUNDARY.1"
  • The body of the message, usually some text, between boundaries and preceeded by appropriate Content-Type and Content-Disposition headers:
    ----PART.BOUNDARY.1
    Content-Type: text/plain; charset=US-ASCII
    Content-Disposition: inline

    Hello Sergei

    please find attached the example we were discussing today.

    Kind regards,
                     Mike
  • One or more attachments, as follow:
    ----PART.BOUNDARY.1
    Content-Type: application/octet-stream; name="example.exe"
    Content-Disposition: attachment; filename="example.exe"
    Content-Transfer-Encoding: base64
    Content-Description: example.exe
    (copy of the binary object translated to Base64 format)
Note 1. "Base64" is a standard way of embedding binary objects into ASCII MIME files. This is done by translating chunkes of 3-EBCDIC bytes to chunkes of 4-ASCII bytes. Our utility includes a function that performs this kind of translation.

  4. QtmmSendMail API
MIME files must be sent via the QtmmSendMail API. This API allows for multiple distributions.
For more information see this page.
Note 2. Our utility includes a function interfacing the QTmmSendMail API.

  5. MIME & Mail 5250 Utility
Creating MIME files and sending them via the QtmmSendMail API is not extremely easy. This is why we provide our MIME & Mail Utility.
This utility, while provides solutions for some initial mailing cases, through its code provides examples for writing your own code, if you wish or need to.
The utility is started from a 5250 session by entering command
     mmail/mimemenu
You will receive the following screen:
MIME files Menu
Select one of the following:
1. Work with Address Book WRKADDR
2. Work with Groups WRKGRP
 
3. Create (and send) a MIME file CRTMIME
4. Select and send a MIME file SNDMIME
5. Work with MIME files WRKMIME
 
6. Example of customized letters CUSTMAIL
 
Selection:   

F3=End F12=Cancel
See the 5250 Utility tutorial pages.

  6. MIME & Mail Windows Utility
A similar utility is provided for Windows. Through Client Access Express API's it would communicate with an IBM System i service program to provide similar services.

See the Windows Utility tutorial page.



  7. MIME & Mail miscellaneous utilities
Service program MMAIL/SENDMAIL allows to create your own mail utilities in a very easy way. However, it may happen that some interesting mail utility is suggested from our users. Any such utilities are embedded in library MMAIL and documented in page "Main utilities".

  8. Spool file to PDF conversion tools
Conversion of spool files to PDF is not in the scope of MMAIL. However, as the user need to e-mail messages attaching printouts as PDF's is very common, a number of conversion tools have been integrated/interfaced by MMAIL.
  • We have integrated two open-source freewares taken from the Internet, CVTSPLHTMF (*SCS only) and CVTSPLFPDF (*SCS and *AFPDS). These utilities, however, may have problems in using overlays.
  • An extremely powerfull utility interfaced by MMAIL is iPDF (*SCS only), an open source product by Orati-Systems. It has an incredible number of features, but you can easily use it also for very simple PDF's.
  • Last, MMAIL interfaces two classic fee products, IBM Infoprint Server and AFPTOOL by Bradley V. Stone. They both support *SCS and *AFPDS spool files.
For more information about using these tools with MMAIL, please refer to this page.

  9. SendMail service program
To make our utility easy to read and to maintain, we have isolated a lot of functions into the MMAIL/SENDMAIL service program.
These functions are the ones you need in order to write your own mail-management programs.
See the SendMail service program page.

  10. Commands
Library mmail contains several commands. A separate page provides a quick summary of all available user commands.

  11. Duplicating a MMAIL installation to other systems
Once you have installed MMAIL on your IBM System i (equipped with the RPG-ILE compiler), you may duplicate the installation to other IBM System i's, even if they are missing the RPG-ILE compiler. This is how you do it:
  1. The source system (the system where MMAIL was originally installed) and the target system (the system where MMAIL is to be installed) must have the same system value QCCSID
  2. On the source system:
    1. save library MMAIL
  3. On the target system:
    1. logon with a user profile having USRCLS(*SECOFR)
    2. restore library MMAIL
    3. run command "mmail/install"


  12. Development libraries
Never create local objects (program, files, etc.) in library MMAIL, because you would loose them when installing a new release of library MMAIL.

If you plan to develop programs using subprocedures of MMAIL service programs, you are recomended to:

  1. Create your own development library, do not use library MMAIL.
  2. You have two ways to populate your development library with the objects you need to develop MMAIL-based programs:
    • Use command MMAIL/SETMAILLIB to populate your library with duplicates of MMAIL service programs, binding directories and QRPGLESRC /COPY members
    • Use comand MMAIL/CRTMMLIB (see the next topic, Cloning the MMAIL library) to clone your library with the same contents of library MMAIL
  3. When you create and run your programs, make sure that they refer to the service programs in your library, not to the service programs in library MMAIL. You do that by removing MMAIL from the library list, and adding your library instead.
Besides, by doing this you will not experience any "service program signature errors" when you install a new version of MMAIL.

  13. Cloning the MMAIL library
Some developers would like to customize the services provided from library MMAIL to their own needs. However, at the same time they may need to download the refreshes of library MMAIL.
The ability to create, on the same system, clones of library MMAIL would result in some advantages for developers:
  • customize a clone for the needs of a given application, while making it non-sensitive to future MMAIL updates
  • ability to install new versions of library MMAIL and to create new clones from there
Command mmail/crtmmlib allows to create a new clone of library MMAIL, or of a cloned library. Execute it after adding to the job library list
  • either library MMAIL
  • or the name of a cloned library
This library will be the master for the new cloned library.
           Create a MMAIL cloned library (CRTMMLIB)

Type choices, press Enter.

MMAIL cloned library  . . . . . . .  CLONELIB  __________    Name
  • use parameter CLONELIB to specify the name of the cloned library. This library must not exist.
Library QRPGLE is required on the system running this command.

Should you later on want to update your cloned MMAIL with fresh software from a new release of library MMAIL, you may run command mmail/updmmlib:
           Update a MMAIL cloned library (UPDMMLIB)

Type choices, press Enter.

Cloned library . . . . . . . . .  CLONELIB  __________    Name
Library QRPGLE is required on the system running this command.

  14. Troubleshooting and FAQs
Some troubleshooting FAQs are available at our FAQ page.

  15. WEBMail
Starting July 2007, MMail includes a free open source WEBMail utility, named AMailer.
It is an IBM System i WEB Mailer which (like many commercial mailers for PC) allows to receive and send e-mail messages.
AMailer supports multiple users and is fully integrated with MMail.
AMailer includes a facility to let you receive and process your own way on the System i the incoming mail of given mail accounts, see this page.
An AMailer tutorial is available.



    Contact