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 and Linking Programs
2.3 Dynamic Strings
2.4 Key Code
2.5 MDD Declaration File
2.6 Xbase++ Compiler

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.

See Section 3.0 for details on the example programs.

MDD4XB supports Alaska Xbase++.

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

When comparing MDD against our competition, note that:

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

Refer to http://www.marshallsoft.com/mdd4xb.htm for the latest version of this software.

1.1 Documentation Set

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

• MDD4XB Programmer's Manual (MDD_4XB.DOC, MDD_4XB.TXT, MDD_4XB.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_4XB Programmer's Manual is the language specific (Xbase++) 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 DUN in general 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.2 Example Program

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

     #INCLUDE "DLL.CH"
     #INCLUDE "KEYCODE.CH"
     #INCLUDE "MDD32.CH"

     FUNCTION XSleep(nMilliSecs)
     RETURN DLLCALL("KERNEL32.DLL",DLL_STDCALL,"Sleep",nMilliSecs)

     Procedure Main()

     ? "MDDVER 7/2/2002"

     Code = XmddAttach(MDD_KEY_CODE)
     if Code < 0
       ? "Cannot attach MDD (check MDD_KEY_CODE)."
       return
     endif
     * get version and build #
     cBuffer = SPACE(1)
     nSize = 1
     Version = XmddDebug(MDD_GET_VERSION,@cBuffer,nSize)
     Build = XmddDebug(MDD_GET_BUILD,@cBuffer,nSize)
     * get registration string
     cBuffer = SPACE(65)
     nSize = 65
     BufLen = XmddDebug(MDD_GET_REGISTRATION,@cBuffer,nSize)
     * display it all
     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))
     ? "Registration: " + Left(cBuffer,BufLen)
     ?
      all done, release MDD
     XmddRelease()
     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.3 Installation

1. Before installation of MDD4XB, your Xbase++ compiler should already be installed on your system and tested.
   
   
2. Unzip MDD4XB21.ZIP (or MDDxxxx.ZIP where xxxx is your Customer ID) using PKUNZIP, WINZIP, or PKZIP for Windows.
   
   

2. Run the WISE installation program SETUP.EXE which will install all MDD4XB files, including copying MDD32.DLL to your Windows directory. No Windows system files are modified.
   
   
3. Compile & run MDDVER.PRG.

1.4 Uninstalling

Uninstalling MDD4XB 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 MDD4XB.

1.5 Ordering

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

1.6 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.CH and MDD32.CH. The file MDD32.CH contains all the necessary constants and function declarations for MDD4XB, while the file KEYCODE.CH contains your key code, as discussed in section 2.4 below.

The Xbase++ include file DLL.CH is also required. For example,

     #INCLUDE "DLL.CH"
     #INCLUDE "KEYCODE.CH"
     #INCLUDE "MDD32.CH"

2.2 Compiling and Linking Programs

To compile and link console mode programs such as MDDVER.PRG, use:

     xpp mddver.prg
     alink /subsystem:console mddver.obj mdd32.lib

To compile and link windows GUI programs, use:

     xpp your-gui-pgm.prg
     alink /subsystem:windows your-gui-pgm.obj mdd32.lib

2.3 Dynamic Strings

A string in the C language (in which MDD and Windows are written) consists of a pointer to the first byte of a character buffer in which a zero byte ends the string characters.

When passing a string to a MDD function, it is best to always append the Chr(0) character to the end of the string. This will guarantee than the MDD functions will be able to detect the end of the string. The example in Section 1.2 above illustrates this.

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, a string buffer is passed to the user defined dllGetMessage function , which copies a text message into it. Note that SPACE(80) is called immediately before dllGetMessage.

     * allocate buffer just before call to dllGetMessage
     Buffer = SPACE(80)
     Code = dllGetMessage(@Buffer, 80)
     * message text is now in 'Buffer'

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 Key Codes

MDD32.DLL has a keycode encoded within it. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.CH. 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 mddAttach, 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 MDD32.DLL from the Windows search path. Note that your keycode is NOT the same as your Customer ID/Registration ID.

2.5 MDD Declaration File

All MDD functions are declared in the MDD declaration file MDD32.CH. This file can be copied to the Xbase++ INCLUDE directory (where Xbase++ can find it) if so desired.

Note that each function is declared with the prefix character of 'X'.

2.6 Xbase++ Compiler

If you don't have the Alaska Software Xbase++ compiler, you can find it on the web at

     http://www.alaska-software.com

3 Example Programs

Several example programs are included in MDD4XB.

Before writing your own programs, compile and run the example programs.

3.1 MDDVER

The first example program is the program MDDVER (MDD Version) which displays the MDD library version number and registration string. Compile with:

     xpp mddver.prg
     alink /subsystem:console mddver.obj mdd32.lib

3.2 DUN_DIAL

The DUN_DIAL example program demonstrates how to use DUN (Dialup Networking) to dial up an ISP (Internet Service Provider). After starting DIAL, the first five DUN connections will be displayed, and the first entry will be used for dialing. Compile with:

     xpp dial.prg
     alink /subsystem:console dial.obj mdd32.lib

3.3 FLY

The FLY example program operates like DIAL except that the DUN parameters (user, password, and phone) are specified by the programmer. There must be at least one entry already defined, although it is not used (rather, it is "borrowed"). Edit FLY with your user name, password, and phone number before compiling. Then, compile with:

     xpp fly.prg
     alink /subsystem:console fly.obj mdd32.lib

4 Revision History

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

Version 1.0: November 1, 2001.

• Initial Xbase++ release.

Version 2.1: July 2, 2002.

• mddDialStatus detects lost connection.

Refer to http://www.marshallsoft.com/mdd4xb.htm for the latest version of this software.