MarshallSoft

SMTP/POP3 Email Engine

Library for Fortran


Programmer's Manual


(SEE4F)


Version 3.5

May 3, 2002


This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2002
All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815


Voice : 1-256-881-4630

FAX : 1-256-880-0925

email : info@marshallsoft.com

web : www.marshallsoft.com


MarshallSoft is a member of the Association of Shareware Professionals

MARSHALLSOFT is a registered trademark of MarshallSoft Computing.



TABLE OF CONTENTS


1 Introduction
1.1 Features
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Ordering
1.7 Updates
2 Compiler Issues
2.1 Win32 Fortran Compilers
2.2 Compiling ABSOFT Fortran Programs
2.3 Compiling Compaq Visual Fortran Programs
2.4 Fortran Extensions
2.5 Other Win32 Fortran Programming Languages
2.6 Key Code (License Key)
3 Example Programs
3.1 Connectionless Example Programs
3.2 SMTP Example Programs
3.3 POP3 Example Programs
4 Revision History

1 Introduction

SEE4F is the easiest way to write email applications in Fortran !

The SMTP/POP3 Email Engine (SEE) is a library of functions providing direct and simple control of the SMTP (Simple Mail Transport Protocol) and POP3 (Post Office 3) protocols.

A simple interface allows sending and receiving email, including multiple MIME base64 and quoted-printable encoded attachments. Knowledge of Winsock and TCP/IP is not needed.

Several example programs are included, demonstrating SMTP and POP3 functions. All example programs will compile using Win 32 Fujitsu Fortran and any other Fortran (such as MicroFocus Fortran) capable of calling the Windows Win32 API.

A Win32 DLL (Dynamic Link Library) is provided. SEE4F can be used with Windows 95/98/Me, and NT/2000/XP. The SEE4F DLL (SEE32.DLL) can also be used from any language (C/C++, Delphi, Visual Basic, etc.) capable of calling the Windows API.

When comparing SEE against our competition, note that:

1.1 Features

Some of the many features of SEE4F are as follows:

  1. Send email with optional MIME or Quoted Printable attachments.
  2. Send email with inline HTML, GIF, TIF, JPG, BMP and Rich Text attachments.
  3. Get the number of messages on your email server.
  4. Get the header lines from any email on your server, without reading the entire email.
  5. Delete any email on the server without reading it first.
  6. Receive any email on your server including MIME attachments.
  7. Run up to 128 independent WIN32 threads concurrently.
  8. Supports SMTP and POP3 authentication.
  9. The same SEE32.DLL can be called from any supported language.
  10. Supports ISO-8859 messages.
  11. Royalty free distribution with your compiled application.

Registration includes one year of free updates.

1.2 Documentation Set

The complete set of documentation consists of three manuals in three formats. This is the first manual (SEE4F) in the set.

Each manual comes in three formats:

The SEE_4F Programmer's Manual is the language specific (Fortran) manual. All language dependent programming issues such as compiling, compilers and example programs are discussed in this manual. Read this manual first.

The SEE User's Manual (SEE_USR) discusses email processing as well as language independent programming issues such as application notes and licensing. Read this manual second.

The SEE Reference Manual (SEE_REF) contains details on each individual SEE function.

Use Microsoft Word 97/99/2000 or Microsoft WordPad to print the document files.


1.3 Example Program

The following example demonstrates the use of some of the library functions:

PROGRAM SEEVER
   !
   !     *** Coded for Compaq Visual Fortran (CVF) ***
   !
           IMPLICIT NONE
           INCLUDE 'SEE32DEC.INC'
           INCLUDE 'KEYCODE.INC'

           INTEGER*4 Code
           INTEGER*4 Version
           INTEGER*4 Digit1
           INTEGER*4 Digit2
           INTEGER*4 Digit3
           INTEGER*4 Build
           CHARACTER*50 String

   !       *****************************************************

   !       *** attach SEE
           Code = seeAttach(%VAL(1), %VAL(SEE_KEY_CODE))
           IF(Code .LT. 0) THEN
             WRITE(,) 'seeAttach fails (',Code,'). Check your key code.'
             STOP
           END IF

   !       *** get version  number
           Version = seeStatistics(%VAL(0), %VAL(SEE_GET_VERSION))
           Digit1 = Version / 256
           Version = Version - 256 * Digit1
           Digit2 = Version / 16
           Version = Version - 16 * Digit2
           Digit3 = Version
           WRITE(*,99) Digit1,Digit2,Digit3
        99 Format('  Version ',I1,'.',I1,'.',I2)

   !       *** get build number
           Build = seeStatistics(%VAL(0), %VAL(SEE_GET_BUILD))
           WRITE(,) ' Build ', Build

   !       *** put all blanks in string
           String = REPEAT(' ', 50)

   !       *** get registration string
           Code = seeDebug(%VAL(0), %VAL(SEE_GET_REGISTRATION), %VAL(LOC(String)),
                           %VAL(50) )
           WRITE(,) ' Registration  ', String

   !       *** release SEE
           Code = seeRelease()
           STOP
           END

In the example program above, seeAttach is called to initialize SEE and then seeStatistics is called in order to get the SEE version number and build number. Then seeDebug is called to get the registration string from SEE32.DLL. Lastly, seeRelease is called to perform SEE termination processing and release the Winsock.

1.4 Installation

  1. Before installation of SEE4F, your Fortran compiler should already be installed on your system and tested.

  2. Unzip SEE4F35.ZIP (or SEExxxx.ZIP where xxxx is your Customer ID) using PKUNZIP, WINZIP, or PKZIP for Windows.

  3. Run the WISE installation program SETUP.EXE which will install all SEE4F files, including copying SEE32.DLL to your Windows directory. No Windows system files are modified.

  4. Compile and run SEEVER to test your installation. The remaining example programs must be edited with your email parameters before compiling.

Note that the Windows registry is not modified.

1.5 Uninstalling

Uninstalling SEE4F is very easy. SEE does not modify the registry.

First, run UINSTALL.BAT, which will delete SEE32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98/Me or C:\WINNT for Windows NT/2000/XP.

Second, delete the SEE project directory created when installing SEE4F.

1.6 Ordering

See the section "Ordering" in the SEE User's Manual (SEE_USR) for details on ordering.

1.7 Updates

When you register SEE4F you will receive a set of registered DLLs plus a license file (SEExxxx.LIC) that can be used to update your registered DLL's for a period of one year from purchase. Updates can be downloaded from

     http://www.marshallsoft.com/oem.htm


After one year, your license must be updated if you want to be able to download updates. Your license can be updated for $30 if ordered within one year of the original purchase (or previous update). After one year, licenses can be updated for $55. Note that registered DLLs never expire.

2 Compiler Issues

2.1 Win32 Fortran Compilers

The email functions in SEE32.DLL can be called from any program which is capable of calling the Windows Win32 API. In order to call the email functions, the proper syntax for calling external Windows DLL's must be used. Unfortunately, this syntax is different for each Fortran compiler.

For ABSOFT, the function interface file is SEE32ABS.INC. For Compaq Visual Fortran (formerly Digital Visual Fortran), the interface file is SEE32DEC.INC.

2.2 Compiling ABSOFT Fortran Programs

ABSOFT example programs end with the extension ".F". The example programs can be compiled from the command line using the ABSOFT amake executable. That is:

     amake -f seever._a_
     amake -f bcast._a_
     amake -f mailer._a_
     amake -f stat._a_
     amake -f status._a_
     amake -f reads._a_
     amake -f reader._a_
     amake -f getraw._a_
     amake -f authen._a_
     amake -f html._a_

The ABSOFT integrated development environment can also be used to create console or GUI applications which use SEE4F.

ABSOFT can be located at http://www.absoft.com

2.3 Compiling Compaq Visual Fortran Programs

Compaq Visual Fortran (CVF) example programs end with the extension ".F90". The example programs can be compiled from Microsoft Developer Studio that is part of the Compaq Digital Fortran compiler package. Note that each subroutine in CVF source files must include SEE32DEC.INC.

To open an existing project, choose "File", then "Open Workspace", and then select "Projects" from the list of file types. Each example program has a Microsoft Visual Studio project file, ending with ".DSP":

     seever.dsp
     bcast.dsp
     mailer.dsp
     stat.dsp
     status.dsp
     reads.dsp
     reader.dsp
     getraw.dsp
     authen.dsp
     html.dsp

To create a new project, choose "File", then "New", then "Fortran Console Application" or "Fortran Windows Application " and your project name. Check "Create new workspace". Select "Project", then "Add to Project". Add all filenames including any resource file (.RC) and SEE32.LIB. Lastly, select "Rebuild All".


2.4 Fortran Extensions

There are several common extensions to the Fortran language which are necessary in order to call Windows API functions. For ABSOFT Fortran, these are:

For Compaq Visual Fortran, the extensions are:

2.5 Other Win32 Fortran Programming Languages.

If you develop an interface file for other Fortran languages, we would really appreciate a copy. Email the interface file, along with any example programs that you have converted, to fortran@marshallsoft.com.

If you are programming in another Win32 Fortran language, we may already have the necessary interface file. Let use know what Fortran you want to use.

2.6 Key Codes

SEE32.DLL has a keycode encoded within it. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.INC. The keycode for the shareware version is 0. You will receive a new key code when registering.

If you get an error message (value -74) when calling seeAttach, it means that the keycode in your application does not match the keycode in the DLL. After registering, it is best to remove the shareware version of the SEE DLL's from the Windows search path.

3 Example Programs

ABSOFT Fortran example program programs end with the extension ".F" and are compiled from the command line with the example program makefiles, which end with "._A_".

Compaq Visual Fortran example programs end with the extension ".F90" and are compiled from the Microsoft Developer environment. Each subroutine in CVF source files must include SEE32DEC.INC.

Important: All example programs must be edited with your email parameters before compiling!

3.1 Connectionless Example Programs

The SEEVER example program does not require a connection to a server.

3.1.1 SEEVER

The first example program SEEVER displays the SEE library version number and registration string. It does not require a connection.

Compile and run SEEVER first. It will verify that SEE32.DLL can be found at runtime, and that your keycode is specified correctly. Compile SEEVER.F (ABSOFT) or SEEVER.F90 (Compaq Visual Fortran).


3.2 SMTP Example Programs

There are four SMTP example programs. SMTP programs send email.

3.2.1 AUTHEN

The AUTHEN example programs connects to an SMTP server using SMTP Authentication.

The AUTHEN program must be edited with your email parameters before compiling. Compile AUTHEN.F (ABSOFT) or AUTHEN.F90 (Compaq Visual Fortran).

3.2.2 BCAST

The BCAST example program emails the same message to a list of addresses taken from the file, BCAST.EML, containing one email address per line.

The BCAST program must be edited with your email parameters before compiling. Compile BCAST.F (ABSOFT) or BCAST.F90 (Compaq Visual Fortran).

3.2.3 HTML

The HTML example program connects to an SMTP server and emails an HTML file containing inline graphics. The graphics files are attached to the HTML email message.

The HTML program must be edited with your email parameters before compiling. Compile HTML.F (ABSOFT) or HTML.F90 (Compaq Visual Fortran).

3.2.4 MAILER

The MAILER example program emails a message, including an optional MIME attachment. The MAILER program must be edited with your email parameters before compiling. Note that <> brackets are required around all email addresses. Compile MAILER.F (ABSOFT) or MAILER.F90 (Compaq Visual Fortran).

3.3 POP3 Example Programs

There are five POP3 example programs. These examples read email.

3.3.1 GETRAW

The GETRAW example program downloads a specified email message without decoding it. This program is used to see what the email looks like on the server.

The GETRAW program must be edited with your email parameters before compiling. Compile GETRAW.F (ABSOFT) or GETRAW.F90 (Compaq Visual Fortran).

3.3.2 STAT

The STAT example program reads the number of email messages waiting on your POP3 server.

The STAT program must be edited with your email parameters before compiling. Compile STAT.F (ABSOFT) or STAT.F90 (Compaq Visual Fortran).

3.3.3 STATUS

The STATUS example program reads the number of email messages waiting on your POP3 server, and displays the "DATE:", "FROM:", and "SUBJECT:" header fields from each email.

The STATUS program must be edited with your email parameters before compiling. Compile STATUS.F (ABSOFT) or STATUS.F90 (Compaq Visual Fortran).

3.3.4 READER

The READER example program can read email, including multiple MIME attachments, from your POP3 server, deleting each email after being read.

The READER program must be edited with your email parameters before compiling. Compile READER.F (ABSOFT) or READER.F90 (Compaq Visual Fortran).

3.3.5 READS

The READS example program reads all email, including multiple MIME attachments, from your POP3 server, deleting each email after being read.

The READS program must be edited with your email parameters before compiling. Compile READS.F (ABSOFT) or READS.F90 (Compaq Visual Fortran).


4 Revision History

The SMTP/POP3 Email Engine DLLs (SEE16.DLL and SEE32.DLL) are written in ANSI C. All language versions of SEE (C/C++, Delphi, Fortran, PowerBASIC, FoxPro, dBase, Xbase++, Fortran, and Fortran) use the same identical DLLs.

Version 1.0: June 8, 1998.

Version 2.0: [Fortran version not released]

Version 2.1: [Fortran version not released]

Version 3.0: [Fortran version not released]

Version 3.1: November 15, 1999.

Version 3.2: [Fortran version not released].

Version 3.3: December 19, 2000

Version 3.4: July 12, 2001

Version 3.5: May 3, 2002