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.
1 Introduction
1.1 Documentation Set2 Compiler Issues
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates
2.1 Versions of Win32 COBOL3 Example Programs
2.2 Compiling Fujitsu COBOL Programs
2.3 Compiling Micro Focus COBOL Programs
2.4 Key Code
4 Revision History
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:
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:
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.
Note that the Windows registry is not modified.
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.
See the section "Ordering" in the SEE User’s Manual (SEE_USR) for details on ordering.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.