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 INCLUDE Files
2.2 Compiling Programs
2.3 Dynamic Strings
2.4 Compiling to Executable
2.5 Key Codes (License Key)

3 Example Programs

3.1 MDDVER
3.2 DIAL
3.3 FLY

4 Revision History

1 Introduction

The MarshallSoft DUN Dialer (MDD) is a library of functions that allows your Win32 application program to dial up a local ISP (Internet Service Provider) using any existing DUN (Dialup Network) connection.

Three example programs are included. See Section 3.0 for details on each of the programs..

MDD4FP supports and has been tested with 32-bit Visual FoxPro compilers through VFP 6.

MDD4FP can be used with Windows 95/98/Me/NT/2000/XP. The MDD4VB DLL (MDD32.DLL) can also be called from any Win32 application (C/C++, Delphi, etc.) capable of calling the Windows API.

When comparing MDD against our competition, note that:

1. MDD4FP is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
2. MDD4FP does NOT depend on ActiveX or similar "support" libraries.
3. The MDD4FP functions can be called from applications not capable of using controls.
   
   
   

1.2 Documentation Set

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

• MDD4FP Programmer's Manual (MDD_4FP.DOC, MDD_4FP.TXT, MDD_4FP.HTM)
• MDD User's Manual (MDD_USR.DOC, MDD_USR.TXT, MDD_USR.HTM)
• MDD Reference Manual (MDD_REF.DOC, MDD_REF.TXT, MDD_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 MDD_4FP Programmer's Manual is the language specific (Visual FoxPro) manual. All language dependent programming issues such as compiling, compilers and example programs are discussed in this manual. Read this manual first.

The MDD User's Manual (MDD_USR) discusses email processing as well as language independent programming issues such as application notes and licensing. Read this manual second.

The MDD Reference Manual (MDD_REF) contains details on each individual MDD function.

Use Microsoft Word 97/99/2000 or Microsoft WordPad to print the document files.

1.3 Example Program

The following example segment demonstrates the use of some of the library functions. It is recommended that the INCLUDE files KEYCODE.FOX and MDD32CON.FOX be replaced with their contents.

     #INCLUDE KEYCODE.FOX
     #INCLUDE DEFINES.FOX

     *** partial list of MDD functions follows ***

     DECLARE INTEGER mddAttach in MDD32.DLL INTEGER KeyCode
     DECLARE INTEGER mddRelease in MDD32.DLL
     DECLARE INTEGER mddDebug in MDD32.DLL INTEGER Index, STRING @Buffer, INTEGER BufLen

     ? "MDDVER 6/28/2002"

     Code = mddAttach(MDD_KEY_CODE)
     if Code < 0
       ? "Cannot attach MDD"
     else
       * get MDD version number
       Buffer = SPACE(1)
       Version = mddDebug(MDD_GET_VERSION, @Buffer, 1)
       Build = mddDebug(MDD_GET_BUILD, @Buffer, 1)
       A = int(Version / 256)
       Version = Version - (256 * A)
       B = int(Version / 16)
       C = Version - (16 * B)
       ? "MDD Version: " + LTRIM(Str(A)) + "." + LTRIM(Str(B)) + "." + LTRIM(Str(C))
       ? "MDD Build #: " + LTRIM(Str(Build))
       * get registration
       Buffer = SPACE(50)
       Code = mddDebug(MDD_GET_REGISTRATION, @Buffer, 50)
       ? "Registration: " + Left(Buffer,Code)
       ?
       Code = mddRelease()
     endif
     return

In the example program above, mddAttach is called to initialize MDD, and then mddDebug is called to get the version, build, and registration strings..

Lastly, mddRelease is called to perform MDD termination processing and release the Winsock.

1.4 Installation

1. Before installation of MDD4FP, your 32-bit Visual FoxPro compiler (any version) should already be installed on your system and tested.
   
   
2. Unzip MDD4FP21.ZIP (or MDDxxxx.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 MDD4FP files, including copying MDD32.DLL to your Windows directory. No Windows system files are modified.
   
   
4. You're ready to compile and run! For a quick start, load project file MDDVER.FOX

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

1.5 Uninstalling

Uninstalling MDD4FP is very easy. MDD does not modify the registry.

First, run UINSTALL.BAT, which will delete MDD32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98/Me/XP or C:\WINNT for Windows NT/2000.

Second, delete the MDD project directory created when installing MDD4FP.

1.6 Ordering

See the Section 1.4 "Ordering" in the MDD User's Manual (MDD_USR) for details on ordering.

1.7 Updates

When you register MDD you will receive a set of registered DLLs plus a license file (MDDxxxx.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 $20 if ordered within one year from the original purchase (or previous update). After one year, licenses can be updated for $30.

Note that the registered DLL's never expire.

2 Compiler Issues

2.1 INCLUDE Files

All example programs include two files; KEYCODE.FOX and MDD32CON.FOX. The file MDD32CON.FOX contains all the necessary constants for MDD4FP, while the file KEYCODE.FOX contains your key code, as discussed in Section 2.5 below.

Since function declarations cannot be in an include file (at least through VFP version 5.0), they are listed in each program following the two include files. The complete list of function declarations is also in file MDD32FUN.FOX

It is highly recommended that INCLUDE statements in the example programs be replaced by their contents before compiling.

2.2 Compiling Programs

The example programs are compiled from the Visual FoxPro development environment.

2.3 Dynamic Strings

The Visual FoxPro language uses a technique known as "garbage collection" to manage string space at runtime, and may be called internally at any time by the FoxPro 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:

     ErrCode = mddDialStatus()
     if ErrCode < 0
       Temp = SPACE(128)
       N = mddErrorText(ErrCode, Temp, 128)
       if N > 0
        ? "ERROR " + Str(ErrCode) + ": " + Temp
       endif
     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.4 Compiling to an Executable

FoxPro programs end in ".PRG". They can be compiled to an executable using the FoxPro BUILD command.

For example, to create MDDVER.EXE from MDDVER.PRG in the C:\TEMP directory, type the following in the FoxPro command window:

     BUILD PROJECT C:\TEMP\MDDVER FROM C:\TEMP\MDDVER
     BUILD EXE C:\TEMP\MDDVER FROM C:\TEMP\MDDVER

FoxPro executables require VFP500.DLL and VFP5ENU.DLL (ENglish User), and may have to be copied from the VFP CDROM. If you are using an earlier or later version of FoxPro than version 5.0, substitute the appropriate DLL's for the above.

The FoxPro output display window will disappear as soon as your executable completes. In order to allow the user to control when the display window disappears, add the following code to your application, just before the final return.

     ?  " Type any key to exit..."
     X = InKey(0)

2.5 Key Codes (License Key)

MDD32.DLL has a keycode encoded within it. Your keycode is a 9 or 10 digit decimal number (unless it is zero), and will be found in the file KEYCODE.FOX. 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 4 or 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 MDD DLL's from the Windows search path.

3 Example Programs

It is highly recommended that INCLUDE statements in the example programs be replaced by their contents before compiling.

3.1 MDDVER

The MDDVER (MDD Version) program should be the first example program that you compile and run. It displays the MDD version, build number, and registration string.

3.2 DIAL

The DIAL example program demonstrates how to use DUN (Dialup Networking) to dial up an ISP (Internet Service Provider). DIAL uses the first (or only) dial entry, but can be modified to use any DUN entry.

3.4 FLY

The FLY example program operates like DIAL except that DUN parameters (user, password, and phone) are specified by the user at runtime.

At least one DUN entry must be previously installed on the computer. The FLY program inserts the specified parameters into DUN entry #0. After use, the original parameters for DUN entry #0 are restored.

4 Revision History

The MarshallSoft DUN Dialer (MDD32.DLL) is written in ANSI C. All language versions of MDD (C/C++, Delphi, Visual Basic, PowerBASIC, FoxPro, Delphi, Xbase++, dBase, COBOL) use the same MDD32.DLL.

Version 2.1: June 27, 2002.

• Initial Visual FoxPro release.