SMTP/POP3 Email Engine
Library for COBOL


Programmer's Manual


(SEE4CB)


Version 3.2

February 28, 2000



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



Copyright (C) 2000
All rights reserved



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



Voice : 256-881-4630

FAX : 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 Documentation Set
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates
2 Compiler Issues
2.1 Versions of Win32 COBOL
2.2 Compiling Fujitsu COBOL Programs
2.3 Compiling Micro Focus COBOL Programs
2.4 Key Code
3 Example Programs
4 Revision History

1 Introduction

SEE4CB is the easiest way to write email applications in COBOL !

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.

With SEE4CB, you can write programs that easily:

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

A Win32 DLL (Dynamic Link Libraries) is provided. SEE4CB can be used with Windows 95/98, and NT/2000. The SEE4CB 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 Documentation Set

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

Each manual comes in three formats:

1.2 Example Program

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

*> attach SEE
CALL "seeAttach" WITH STDCALL USING
   BY VALUE     NBR_CHANS     *> number of channels
   BY VALUE     SEE_KEY_CODE  *> See KEYCODE.CBI
END-CALL.
*> connect to SMTP server
DISPLAY "Calling seeConnectTo()..."
CALL "seeConnectTo" WITH STDCALL USING
   BY VALUE     IS_ZERO       *> channel
   BY REFERENCE SMTP_SERVER   *> SMTP server
   BY REFERENCE EMAIL_FROM    *> sender's email address
   BY REFERENCE IS_ZERO       *> no Reply-To header
END-CALL.
*> send email
DISPLAY "Calling seeSendEmail()..."
CALL "seeSendEmail" WITH STDCALL USING
   BY VALUE     IS_ZERO       *> channel
   BY REFERENCE EMAIL_TO      *> recipient
   BY REFERENCE IS_ZERO       *> no CC list
   BY REFERENCE IS_ZERO       *> no BCC list
   BY REFERENCE EMAIL_SUBJ    *> email subject
   BY REFERENCE EMAIL_MSG     *> text of message
   BY REFERENCE IS_ZERO       *> no attachment
END-CALL.
*> close and release SEE
CALL "seeClose" WITH STDCALL USING
   BY VALUE     IS_ZERO       *> channel
END-CALL.
CALL "seeRelease" WITH STDCALL
END-CALL.

In the example program above, seeAttach is called to initialize SEE and then seeSmtpConnect is called to connect to the SMTP mail host. The SMTP server host name and your email address are required, while the "Reply-To" entry is optional.

seeSendEmail is then called, passing the addressee lists. The primary addressee is provided in the "To List". The CC ("Carbon Copy") lists additional recipients, as does the BCC (Blind Carbon Copy) list. The subject contains the email subject line. The message text is next. If it starts with the '@' symbol, it is considered the name of the file containing the email message. Lastly, the filename of any ASCII or binary attachment is specified. All fields in seeSendEmail are optional except the first.

After returning from seeSendEmail, the seeClose function is called to close the connection to the SMTP server. Lastly, seeRelease is called to perform SEE termination processing and release the Winsock.

1.3 Installation

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

  2. Create your SEE4CB project directory, copy the SEE4CB archive, and then unzip the archive.

  3. Run INSTALL.BAT which will copy SEE32.DLL to either C:\WINDOWS or C:\WINNT.

  4. Edit each example program with your email parameters, compile, and run.

Note that the Windows registry is not modified.

1.4 Uninstalling

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

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

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

1.5 Ordering

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

1.6 Updates

When you register SEE4CB 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, licenses can be updated for $30 for email delivery.


2 Compiler Issues

2.1 Versions of Win32 COBOL

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 COBOL compiler.

For Fujitsu, the function interface file is SEE32.CBI. For Micro Focus, the interface file is SEE32.MFI.

2.2 Compiling Fujitsu COBOL Programs

The Fujitsu COBOL Project Manager is used to compile and link the example programs. When linking, remember to include SEE32.LIB in the list of files to link.

Alternatively, the FCL.BAT file can be used to invoke the Fujitsu compiler and linker from the command line. Be sure to copy COBOL.CBI from the Fujitsu COBOL97 directory to the directory which contains the example programs.

FCL SEEVER
FCL MAILER
FCL MAILER2
FCL STATUS
FCL READER
FCL READER2
FCL GETRAW

2.3 Compiling Micro Focus COBOL Programs

We do not have Micro Focus COBOL, although we have many customers who use SEE4CB with it.

In order to compile for MicroFocus COBOL, examine the Micro Focus version of the SEEVER program (SEEVERMF.CBL). If you would like the complete example set for MicroFocus COBOL, send an email to cobol@marshallsoft.com. and we will be glad to send it to you.

2.4 Other Win32 COBOL Programming Languages.

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

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

2.5 Key Codes

SEE16.DLL and SEE32.DLL have a keycode encoded within them. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.CBI. 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

Each example program, with the exception of SERVER.CBL, must be edited with your email parameters before compiling. For example, suppose you want to change the "mail.hiwaay.net" below to "mail.mine.com". To do this, you must change

000360  01  SMTP_SERVER.
000370      05  FILLER PIC X(15) VALUE "mail.hiwaay.net".
000380      05  FILLER PIC X VALUE X'00'.

to

000360  01  SMTP_SERVER.
000370      05  FILLER PIC X(13) VALUE "mail.mine.net".
000380      05  FILLER PIC X VALUE X'00'.

Note that the length was changed from 15 characters to 13 to accommodate the shorter server name.

Before writing your own programs, compile and run several of the example programs. SMTP programs send email. POP3 programs read email.

3.1 SEEVER

The first example program SEEVER displays the SEE library version number and registration string. It does not require a connection. See SEEVER.CBL for Fujitsu or SEEVERMF.CBL for MicroFocus.

Compile and run SEEVER first. It will verify that SEE32.DLL can be found at runtime, and that your keycode is specified correctly.

3.2 MAILER

The MAILER example program emails a message, including an optional MIME attachment. The MAILER.CBL program must be edited with your email parameters before compiling. Note that <> brackets are required around all email addresses.

3.3 MAILER2

The MAILER2 example program operates like MAILER, except that it runs in direct mode rather than indirect mode like MAILER.CBL. The primary use of direct mode is to return control to the calling application code as the email is being sent for the purpose of displaying progress. See the User's Manual (SEE_USR) for details on direct mode.

The MAILER2.CBL program must be edited with your email parameters before compiling.

3.4 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.CBL program must be edited with your email parameters before compiling.

3.5 READER

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

The READER.CBL program must be edited with your email parameters before compiling.

3.6 READER2

The READER2 example program operates like READER, except that it runs in direct mode rather than indirect mode like READER.CBL. The READER2.CBL program must be edited with your email parameters before compiling.

3.7 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.CBL program must be edited with your email parameters before compiling.


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, COBOL, PowerBASIC, FoxPro, dBase, Xbase++, COBOL, and Fortran) use the same identical DLLs.

Version 1.0: June 8, 1998.

Version 2.0: [COBOL version not released]

Version 2.1: [COBOL version not released]

Version 3.0: [COBOL version not released]

Version 3.1: September 1, 1999.

Version 3.2: February 28, 2000.