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 INCLUDE Files
2.2 Compiling dBase Programs
2.3 Compiling dBase Projects
2.4 Dynamic Strings
2.5 Using Internal Memory
2.6 Key Codes

3 Example Programs

3.1 SeeVer
3.2 Hello
3.3 Mailer
3.4 Mailer2
3.5 Status
3.6 Status2
3.7 Reader
3.8 Reader2
3.9 Auto
3.10 GetRaw
3.11 From
3.12 Quick

4 Revision History

1 Introduction

SEE4DB is the easiest way to write email applications in Visual dBase !

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 SEE4DB, you can write programs that easily:

• Send email with optional MIME attachments.
• Get the number of messages on your email server.
• Get the header lines from any email on your server, without reading the entire email.
• Delete any email on the server with or without reading it first.
• Receive any email on your server including MIME attachments.

Twelve example programs are included, demonstrating SMTP and POP3 functions. All programs will compile using any version of Visual dBase. Two examples are organized as dBase projects.

Two Dynamic Link Libraries (SEE16.DLL for dBase 5.6/5.7and SEE32.DLL for dBase 7.X) are provided. SEE4DB can be used with Windows 3.X, 95/98, and NT/2000. The SEE4DB DLLs (SEE16.DLL and SEE32.DLL) can also be used from any language (C/C++, Delphi, VB, etc.) capable of calling the Windows API.

When comparing SEE against our competition, note that:

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

1.1 Documentation Set

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

• SEE4DB Programmer’s Manual (SEE4DB.DOC, SEE4DB.TXT, SEE4DB.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).

1.2 Example Program

The following example segment demonstrates the use of some of the 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 02/10/2000"
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 10 seconds
Code = seeIntegerParam(0, SEE_CONNECT_WAIT, 10000)
*** 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,"","","Hello from dBase","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 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 SEE4DB, your Visual dBase compiler (any version) should already be installed on your system and tested.
   
   
2. Create your SEE4DB project directory, copy the SEE4DB archive, and then unzip the archive.
   
   
3. Execute INSTALL.BAT, which will copy the proper files.

INSTALL

The INSTALL.BAT program copies SEE16.DLL and SEE32.DLL to either C:\WINDOWS (for Windows 3.X/95/98) or C:\WINNT (for Windows NT 4.0).

4. Edit the example programs with your email parameters. Change the include file reference from SEE32.CC to SEE16.CC if you are compiling using dBase 5.6 or dBase 5.7.
   
   
5. For a quick start, load project file SEEVER.PRG

Note that the Windows registry is not modified by the install process.

1.4 Uninstalling

Uninstalling SEE4DB 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.X/95/98 or C:\WINNT for Windows NT.

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

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 SEE4DB 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 INCLUDE Files

All example programs include two files; KEYCODE.CC and SEE32.CC (or SEE16.CC). The file SEE32.CC (or SEE16.DLL) contains all the necessary constants and function declarations for SEE4DB, while the file KEYCODE.CC contains your key code, as discussed in section 2.6 below.

2.2 Compiling dBase Programs

Visual 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 SEE User's Manual (SEE_USR). Programs can be edited within any text editor, and compiled from the VDB (Visual dBase) command window with the COMPILE command (eg: COMPILE STATUS.PRG) or executed from the VDB command window with the DO command (eg: 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 VDB command window must be displayed in order to see the output.

2.3 Compiling dBase Projects

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.

2.4 Dynamic Strings

The Visual dBase language use 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.

2.5 Using Internal Memory

This section applies ONLY to using DIRECT mode as discussed in the section "Theory Of Operation" in the SEE 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 get around this problem with Visual dBase (and other languages that do dynamic string management) , you can instruct seeGetEmailLines to use it's own memory:

Code = seeGetEmailLines(Chan, MessageNumber, 0, 0, max_buf_size)

If the 4th argument is 0, SEE will use it's 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.

2.6 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 zero), and will be found in the file KEYCODE.CC. The keycode for the shareware version is 0. You will receive a new key code when registering. Your keycode is not your customer ID (which is a 5 digit number).

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 SEEVER.PRG, must be editied with your TP/IP email parameters before compiling. Refer to the SEE User's Manual (SEE_USR) for details on email parameters.

In order to compile the example programs with dBase 5.6/5.7, change the include file reference from SEE32.CC to SEE16.CC in each example program.

3.1 SEEVER

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).

This is the first program that you should compile and run.

3.2 HELLO

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.

3.3 MAILER

The MAILER example program emails a message, including an optional MIME attachment. MAILER.PRG must be edited with your email parameters before compiling.

3.4 MAILER2

The MAILER2 example program operates the same as the MAILER program, except that it uses the "indirect" method. MAILER2.PRG must be edited with your email parameters before compiling.

3.5 STATUS

STATUS reads the number of email messages waiting on your POP3 server, and displays the "DATE:", "FROM:", and "SUBJECT:" header fields from each email. STATUS.PRG must be edited with your email parameters before compiling.

3.6 STATUS2

The STATUS2 example program operates the same as the STATUS program, except that it uses the "indirect" method. STATUS2.PRG must be edited with your email parameters before compiling.

3.7 READER

READER can read email, including multiple MIME attachments, from your POP3 server, deleting each email after being read. READER.PRG must be edited with your email parameters before compiling.

3.8 READER2

The READER2 example program operates the same as the READER program, except that it uses the "indirect" method. READER2.PRG must be edited with your email parameters before compiling.

3.9 AUTO

AUTO ("auto-responder") uses two channels concurrently to automatically respond to all new email. AUTO.PRG must be edited with your email parameters before compiling.

3.10 GETRAW

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. GETRAW.PRG must be edited with your email parameters before compiling.

3.11 QUICK

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.

3.12 FROM

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.

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

Version 3.0: May 10, 1999.

• Initial release of dBase version.

Version 3.1: August 5, 1999.

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

Version 3.2: February 17, 2000.

• 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 and AUTO examples.
• Added seeCommand function.
• Added internal memory usage support.