SMTP/POP3 Email Engine
Library for Visual dBase
Programmer's Manual
(SEE4DB)
Version 4.0
August 8, 2006
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2006
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 registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Features2 Library Overview
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates
2.1 Dynamic Link Libraries3 Compiler Issues
2.2 Keycode
2.3 Win32 STDCALL and DECLSPEC
2.4 INCLUDE Files
2.5 Visual dBase 5.6 and 5.7
2.6 Visual dBase 7.0 and above
2.7 Dynamic Strings
2.8 Using Internal Memory
2.9 Error Display
3.1 Compiling dBase Programs4 Example Programs
3.2 Compiling dBase Projects
3.3 Creating Executables
4.1 Connectionless Example Programs4 Revision History
4.2 SMTP Example Programs
4.3 POP3 Example Programs
The SMTP/POP3 Email Engine for Visual dBASE (SEE4DB) library is a powerful toolkit that allows software developers to quickly develop SMTP and POP3 email applications in Visual dBase. SEE4DB is a component library of functions providing direct and simple control of the SMTP (Simple Mail Transport Protocol) and POP3 (Post Office 3) protocols.
A straightforward interface allows sending and receiving email, including multiple MIME base64 and quoted-printable encoded attachments. Knowledge of Winsock and TCP/IP is not needed.
The SMTP/POP3 Email Engine for Visual dBASE component library supports both Win16 (dBASE 5.5 and 5.7) and Win32 (dBASE 7.0, 7.5 and dBASE Plus) versions of dBASE. Two Dynamic Link Libraries (SEE16.DLL for dBase 5.6/5.7 and SEE32.DLL for dBase 7.X and dBASE Plus) are provided. SEE4DB includes numerous example programs that demonstrate SMTP and POP3 functions to help software developers easily build software applications using the SEE4DB library.
SEE4DB runs under all versions of Windows (Windows 95, Windows 98, Windows ME, Windows 2000, Windows 2003, Windows NT and Windows XP). The SMTP/POP3 Email Engine SDK DLLs (SEE16.DLL and SEE32.DLL) can also be used from any language (C/C++, .NET, Visual Basic, VB. NET, VBA, Delphi, Visual FoxPro, COBOL, PowerBASIC, Xbase++, etc.) capable of calling the Windows API.
When comparing SMTP/POP3 Email component library against our competition, note that:
MarshallSoft also has versions of the SMTP/POP3 Email Engine library for C/C++ (SEE4C), Delphi (SEE4D), PowerBASIC (SEE4PB), Visual FoxPro (SEE4FP), Xbase++ (SEE4XB), and Visual Basic (SEE4VB). All versions of the SEE library use the same DLLs (SEE16.DLL or SEE32.DLL). However, the examples provided for each version are written for the specified computer language.
The latest versions of SMTP/POP3 Email Engine (SEE) can be downloaded from our web site at
http://www.marshallsoft.com/email-component-library.htm
Our goal is to provide a robust SMTP/POP3 email component library that you and your customers can depend upon. A fully functional evaluation version is available. Contact us if you have any questions.
Some of the many features of SMTP/POP3 Email Engine component library are as follows:
Registration includes one year of free updates.
The complete set of documentation consists of three manuals in three formats. This is the first manual (SEE_4DB) in the set.
Each manual comes in three formats:
The SEE_4DB Programmer's Manual is the language specific (Visual dBase) manual. All language dependent programming issues such as compiling, compilers and example programs are discussed in this manual.
The SEE User's Manual (SEE_USR) discusses email processing as well as language independent programming issues. Purchasing and license details are also provided.
The SEE Reference Manual (SEE_REF) contains details on each individual SEE function as well as error codes.
Use Microsoft Word or Microsoft WordPad to print the document files. The online documentation can be accessed on the SMTP/POP3 Email Engine for Visual dBase product page at:
http://www.marshallsoft.com/dbase-email-component.htm
The following example segment demonstrates the use of some of the SMTP/POP3 Email for Visual dBase component library functions:
#INCLUDE KEYCODE.CC
#INCLUDE SEE32.CC
*** PROGRAMMER: Edit these strings [use host name or IP address for server] ***
SmtpServer = "10.0.0.1"
SmtpFrom = "<mike@10.0.0.1>"
SmtpReply = ""
SmtpTo = "<mike@10.0.0.1>"
DiagFile = "HELLO.LOG"
*** END PROGRAMMER ***
? "HELLO 8/08/2006"
Code = seeAttach(1, SEE_KEY_CODE)
if Code < 0
? "Cannot attach SEE"
return
endif
Code = seeStringParam(0, SEE_LOG_FILE, DiagFile)
*** set maximum connect wait to 30 seconds
Code = seeIntegerParam(0, SEE_CONNECT_WAIT, 30000)
*** connect to POP3 server
? "Connecting to " + SmtpServer
Code = seeSmtpConnect(0, SmtpServer, SmtpFrom, SmtpReply)
if Code < 0
Temp = SPACE(128)
Code = seeErrorText(0,Code,Temp,128)
? Left(Temp,Code)
else
*** send email message
? "Sending email to " + SmtpTo
Code = seeSendEmail(0,SmtpTo,"","","Example Program","Hello from dBase","")
if Code < 0
Temp = SPACE(128)
Code = seeErrorText(0,Code,Temp,128)
? Left(Temp,Code)
else
? "Email has been sent."
endif
endif
? "Done."
Code = seeClose(0)
Code = seeRelease()
return
In the example program above, seeAttach is called to initialize SEE and then seeSmtpConnect is called to connect to the SMTP mail host. seeSendEmail is then called, passing the addressee lists. The primary addressee is provided in the "To List". Lastly, the filename of any ASCII or binary attachment is specified. All fields, except the first, in seeSendEmail are optional.
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 by the installation process.
Uninstalling SEE4DB is very easy since 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.X/95/98/Me or C:\WINNT for Windows NT/2000/XP.
Second, delete the SEE project directory created when installing SEE4DB.
A developer license for SEE4DB can be purchased for $115. Purchasing details can be found in Section 1.5 "How to Purchase" in the SEE User's Manual (SEE_USR.HTM). Also see INVOICE.TXT provided with the evaluation version or order directly on our web site at
http://www.marshallsoft.com/order.htm
Registration includes one year of free updates.
When a developer license is purchased, you will be sent a set of registered DLLs plus a license file (SEExxxx.LIC, where xxxx is your Customer ID). The license file can be used to update the 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 DLL's do not expire. Our update policy allows registered users to update to the most current release for a period of one year without charge.
The SMTP/POP3 Email component library includes both Win16 and a Win32 dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library that is bound to each and every application that uses it at link time.
An important advantage that DLL's have over other "popular" library formats such as VBX or OCX is that DLL's are callable by all Windows applications. Since DLL's are the building blocks of the Windows Operating System, they will not be replaced by a "newer technology".
SEE16.DLL and SEE32.DLL each 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.CC the keycode for the evaluation (shareware) version is 0. You will receive a new keycode and a set of new DLL's when registering. The KEYCODE is passed to SeeAttach.
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 evaluation version of the SEE32.DLL and SEE16.DLL from the Windows search path or delete them.
SEE32 is written in ANSI C and is compiled using the _stdcall and _declspec keywords. This means that SEE4DB uses the same calling conventions and file naming conventions as the Win32 API. In particular, function names are NOT decorated. There are neither leading underscores nor trailing "@size" strings added to function names.
The SEE32.DLL functions may be called by any Windows application program capable of calling the Windows API provided the proper declaration file is used.
All example programs include two files; KEYCODE.CC and SEE32.CC (or SEE16.CC). The file SEE32.CC (and SEE16.CC) contains all the necessary constants and function declarations for SEE4DB, while the file KEYCODE.CC contains your key code.
There are three recommended ways to handle these INCLUDE files in dBase programs.
Visual dBase 5.6 and 5.7 create 16-bit applications, and uses the 16-bit DLL, SEE16.DLL. Copy the 16-bit CC file SEE16.CC to the dBASE compiler's INCLUDE directory.
Visual dBase 7.0 and above, including dBASE Plus, create 32-bit applications, and use the 32-bit DLL, SEE32.DLL. Copy the 32-bit CC file, SEE32.CC to the dBASE compiler's INCLUDE directory.
The Visual dBase language uses a technique known as "garbage collection" to manage string space at runtime, and may be called internally at any time by the dBase runtime, asynchronous to what you may be doing in your code.
When passing a string buffer to a DLL function into which text will be copied, it is strongly recommended that the local string be allocated immediately before use. For example:
Code = seeSmtpConnect(0,SmtpServer,SmtpFrom,SmtpFrom)
if Code < 0
* allocate buffer just before call
Temp = SPACE(128)
* put text in Temp
Code = seeErrorText(1,Code,Temp,128)
? Left(Temp,Code)
endif
This technique is not necessary for passing a string to a DLL function, only when passing a buffer to a DLL into which data is to be placed by the DLL function.
This section applies ONLY to using DIRECT mode as discussed in the section "Theory of Operation" in the SMTP/POP3 User's Manual (SEE_USR).
The Visual dBase dynamic string management functions (as discussed in Section 2.4 above) have another side effect when running in DIRECT mode (calling seeDriver). If Visual dBase moves memory at runtime, then memory references by dBase will use the new (moved) memory location, although SEE itself will still be using the original memory location previously passed to it. To work around this problem with Visual dBase (and other languages that do dynamic string management), seeGetEmailLines can be instructed to use its own memory:
Code = seeGetEmailLines(Chan, MessageNumber, 0, 0, max_buf_size)
If the fourth argument is 0, SEE will use its own memory. After seeDriver has been called to completion, the internal buffer can be copied by calling
Buffer = SPACE(max_buf_size)
Code = seeDebug(0, SEE_COPY_BUFFER, Buffer, max_buf_size)
seeGetEmailLines is the only function which requires this technique, since there is no reason to use direct mode in other functions (such as seeErrorText) that use return buffers. See the program STATUS2.PRG for an example of using seeGetEmailLines in direct mode.
The error message text associated with SEE error codes can be displayed by calling SeeErrorText. Each sample program contains examples of error processing.
Also see the file seeErrors.txt for a list of all Winsock and SEE error codes.
The SMTP/POP3 Email Engine for Visual dBase component library compiles with all versions of dBASE.
dBASE programs end with the extension ".PRG". Before compiling any of the example programs, edit each file with your Internet TCP/IP parameters as specified in the SMTP/POP3 User's Manual (SEE_USR). Programs can be edited within any text editor, and compiled from the dBASE command window with the COMPILE command (e.g.: COMPILE STATUS.PRG) or executed from the dBASE command window with the DO command (e.g.: DO STATUS.PRG).
To open a program within Visual dBase source editor, choose "File", then "Open". When the "Open File" dialog box appears, choose "Programs" for "Files of Type", then choose the program (*.PRG) to open. Lastly, choose "Open in Source Editor" for "Action" and push the "Open" button.
After editing the source program with your internet (or TCP/IP) parameters, you are ready to compile. From the dBase menu bar, choose "Build", then "Compile". To run choose, "Run". The dBASE command window must be displayed in order to view the output.
Visual dBase projects consist of several types of files such as forms, reports, data modules, etc. The project file itself ends with the extension of ".PRJ".
There are two example Visual dBase projects (QUICK and FROM). Open QUICK (or FROM) by choosing "File", then "Open Project" from the dBase menu bar. To compile QUICK , choose "Build" from the menu bar, then "Rebuild All". This will create QUICK.EXE, which can be executed by choosing "Execute quick.exe" from the "Build" menu bar pulldown, or from the Windows command line prompt.
dBase programs end in ".PRG". They can be compiled to an executable using the dBase BUILD command.
For example, to create SEEVER.EXE from SEEVER.PRG in the C:\SEE4DB\APPS directory, type the following in the dBase command window:
BUILD PROJECT C:\SEE4DB\APPS\WSCVER FROM C:\SEE4DB\APPS\WSCVER
BUILD EXE C:\SEE4DB\APPS\WSCVER FROM C:\SEE4DB\APPS\WSCVER
Each example program, with the exception of SEEVER.PRG, must be edited with your TP/IP email parameters before compiling. Refer to the SMTP/POP3 User's Manual (SEE_USR) for details on email parameters.
Before writing your own programs, compile and run several of the example programs.
Several example programs do not require a connection to a server.
This simple program displays the SEE version number, build number, and registration string taken from SEE32.DLL (or SEE16.DLL). The SEEVER program does not connect to your LAN (or the Internet). Its purpose is display the SEE version, build, and registration string as well as to verify that SEE32.DLL (or SEE16.DLL) is being found and loaded by Windows.
This is the first program that you should compile and run.
The CODETEST example program demonstrates how to use seeEncodeBuffer and seeDecodeBuffer, which BASE64 encodes and decodes several test strings.
There are 12 SMTP email example programs. SMTP programs send email using an SMTP server.
AUTHEN is an example program that connects to an SMTP server using SMTP Authentication. You must connect to a SMTP server which allows authentication.
AUTHEN.PRG must be edited with your email parameters before compiling.
AUTO ("auto-responder") uses two channels to read email on the POP3 server and at the same time automatically responds to all new email using the SMTP server. AUTO.PRG must be edited with your email parameters before compiling.
The BCAST example program emails the same message (BCAST.TXT) to a list of addresses taken from the file, BCAST.EML, containing one email address per line. Along with your SMTP server and your email address, you must create the file containing the email message to send, and create another file containing the list of recipients. See BCAST.EML for an example.
The GB2312 example program sends a text message that is GB2312 (simplified Chinese) encoded. The recipient's email client will be able to display the email message using the specified GB2312 character set provided that it is capable of identifying GB2312 MIME parts (such as MS OutLook).
The HELLO program emails a short message. HELLO.PRG must be edited with your email parameters before compiling.
Compare HELLO with the MAILER example program.
The HTML example program connects to an SMTP server and emails an HTML file (TEST.HTM) containing inline graphics (IMAGE1.GIF and IMAGE2.GIF). The graphics files are attached to the HTML email message.
HTML.PRG must be edited with your email parameters before compiling.
The ISO8859 example program sends a text message and subject line that are ISO-8859 encoded. The recipient's email client will be able to display the email message using the specified ISO character set provided that it is capable of identifying ISO-8859 MIME parts (such as MS OutLook).
The MAILER example program emails a message, including an optional MIME attachment. MAILER.PRG must be edited with your email parameters before compiling.
The MAILER2 example program operates the same as the MAILER program, except that it uses the "direct" method of calling seeDriver. MAILER2.PRG must be edited with your email parameters before compiling.
The MParts example program sends a multipart MIME email in which the Content-Type headers for each attachment are specified by the programmer.
The two attachment types specified in this example are a sound file (.wav) and of PDF file (.pdf).
QUICK is similar to MAILER, except that it accepts all necessary Internet TCP/IP settings using a form at runtime. QUICK is organized as a Visual dBase project.
The FORWARD example program forwards an email message to a new recipient. Only undecoded email messages can be forwarded.
Undecoded email message can be downloaded using the GETRAW and READER example programs.
There are 8 POP3 example programs. These examples read email using a POP3 Server. Each example program, except FROM.PRG, must be edited with your email parameters before compiling.
AUTO ("auto-responder") uses two channels concurrently to automatically respond to all new email.
FROM is similar to STATUS, except that it accepts all necessary Internet TCP/IP settings using a form at runtime. FROM is organized as a Visual dBase project.
GETRAW is an example program that downloads a specified email message without decoding it (in "raw" format). This is used to see what the email looks like on the server.
READER can read email, including multiple MIME attachments, from your POP3 server, deleting each email after being read.
The READER2 example program operates the same as the READER program, except that it uses the "direct" method of calling seeDriver.
STATUS reads the number of email messages waiting on your POP3 server, and displays the "DATE:", "FROM:", and "SUBJECT:" header fields from each email
The STATUS2 example program operates the same as the STATUS program, except that it uses the "direct" method of calling seeDriver.
The Pop3Read example program uses the seePop3Source function to specify an (undecoded) email message file to be read and decoded. There is no connection to any server.
Undecoded email message can be downloaded using the GETRAW and READER example programs.
The SMTP/POP3 Email Engine DLLs (SEE16.DLL and SEE32.DLL) are written in ANSI C. All language versions of SEE (C/C++, Visual Basic, PowerBASIC, Delphi, Visual dBase, Visual dBase, Xbase++, COBOL, and Fortran) use the same identical DLLs.
Version 3.0: May 10, 1999.
Version 3.1: August 5, 1999.
Version 3.2: February 17, 2000.
Version 3.3: November 29, 2000
Version 3.4: August 10, 2001
Version 3.5: April 4, 2002
Version 3.6: April 14, 2003
Version 3.7: February 17, 2005.
Version 4.0: August 8, 2006.