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:

• SEE4F is a standard Windows DLL and is much smaller than a OCX or ActiveX control.
• SEE4F does NOT depend on ActiveX or similar "support" libraries.
• The WIN32 version of SEE is fully threadable.
• The SEE4F functions can be called from applications not capable of using controls.

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.

• SEE4F Programmer's Manual (SEE_4F.DOC, SEE_4F.TXT, SEE_4F.HTM)
• SEE User's Manual (SEE_USR.DOC, SEE_USR.TXT, SEE_USR.HTM)
• SEE Reference Manual (SEE_REF.DOC, SEE_REF.TXT, SEE_REF.HTM)

Each manual comes in three formats:

• Microsoft Word (files ending in .DOC). The best format for printing manuals.
• Hyper Text (files ending in .HTM). Use any web browser to read.
• ASCII Text (files ending in .TXT).

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:

• VAL : Operator used to return the value of a variable.
• LOC : Operator used to return the location of a variable.
• CHAR : Function which returns character equivalent of its integer argument.
• // : String concatenation operator.

For Compaq Visual Fortran, the extensions are:

• %VAL : Operator used to return the value of a variable.
• %LOC : Operator used to return the location of a variable.
• %CHAR : Function which returns character equivalent of its integer argument.
• // : String concatenation operator.

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.

• Initial release of SEE

Version 2.0: [Fortran version not released]

Version 2.1: [Fortran version not released]

Version 3.0: [Fortran version not released]

• Modified SEE to be fully threadable (adding seeAttach and seeRelease).
• Added seeGetEmailUID function.
• Handles "inline" email text properly.
• Optionally decodes unnamed attachments.
• Added ability to add header lines (SEE_SET_HEADER).
• Can use alternate ports for SMTP or POP3.
• Win16 version can get time zone from TZ environment variable.
• Quoted-printable messages can handle soft line breaks.
• Quoted-printable message can handle embedded HTML text.

Version 3.1: November 15, 1999.

• Support ISO-8859-1 (Q or B) encoded attachment filenames.
• Support ISO-8859-1 (Q only) on subject line
• SEE_SAVED_TO_MSG parameter added.
• "+OK" line not written to email message file.
• Added seeExtractLine function.

Version 3.2: [Fortran version not released].

• Added QUOTED_8859 processing (QUOTED_8859).
• Can decode printed quotable attachments!
• seeGetEmailLines can use internal memory.
• Added SEE_WRITE_TO_LOG to seeStringParam.
• Added SEE_GET_ATTACH_NAMES to seeDebug to get attachment filename list.
• Ability to reset the SEE_SET_HEADER header string to "nothing".
• Improvements in dynamic memory usage.
• Added GETRAW, READER2, and MAILER2 example programs.
• Added seeCommand function.

Version 3.3: December 19, 2000

• seeGetEmailLines can use internal memory.
• Added SEE_COPY_BUFFER [seeDebug] to copy internal buffer.
• Added SEE_WRITE_TO_LOG [seeStringParam] to allow user to write to LOG file.
• Added SEE_GET_ATTACH_NAMES [seeDebug] to get attachment filename list.
• Ability to reset the SEE_SET_HEADER [seeStringParam] to "nothing".
• Added seeCommand function.
• Allow TIC marks (0x27) in VerifyAddressChars().
• Added SEE_GET_LAST_RECIPIENT to seeDebug.
• Added seconds to date string on outgoing email.
• Attachment name is saved when attachment file is closed.
• Added SEE_PATH_DELIMITER to seeIntegerParam().
• Added seeAbort function.
• VerifyFormat rejects "@domain" and "name@" addresses.
• Added "SEE_SET_FROM" so can change "From:" header at runtime.
• Delimiters (CR/LF) sent with command in one network transmission [seeWriteLine].
• Added QUOTED_USER, SEE_SET_CONTENT_TYPE, and SEE_SET_TRANSFER_ENCODING.
• Added SEE_ATTACH_DELIMITER and ability to specify different attachment filename in email.
• Added SEE_ADD_HEADER to seeStringParam.
• Added SEE_WRITE_BUFFER to seeDebug (see seeGetEmailLines)
• Added SEE_ENABLE_IMAGE to send GIF/TIF/BMP/JPG images inside email.

Version 3.4: July 12, 2001

• Supports "AUTH LOGIN" and "AUTH CRAM-MD5" (SMTP) authentication.
• SmtpResponse accepts response line without message.
• Supports ISO-8859-1 (base-64) encoding on subject line.
• Supports "APOP" authentication (POP3 servers).

Version 3.5: May 3, 2002

• Added support for "AUTH PLAIN".
• Recognize multiple AUTH methods on one line, such as "AUTH PLAIN LOGIN CRAM-MD5".
• Added SEE_FORCE_INLINE -- attachments are inline text rather than base64 encoded.
• Added SEE_SET_ATTACH_CONTENT_TYPE -- user can specify content type for attachments.
• Added SEE_ATTACH_BASE_NUMBER -- attachments named "1.att", "2.att", etc.
• Don't close socket (seeClose) if socket is already closed.
• NBR_CHANS set to 128 for Win32.
• SEE_RAW_MODE reads complete lines rather than buffers.
• Added seeQuoteBuffer() -- used to prepare ISO-8859 headers.
• Will continue with sending DATA (rather than return error) if have at least one recipient.
• Call seeStatistics(Chan, SEE_GET_LAST_RECIPIENT) to get # recipients accepted by server.
• Added SEE_IGNORE_REJECTED to ignore error returned if recipient is rejected.
• Added BCAST example program.