MarshallSoft

MarshallSoft DUN Dialer
Library for PowerBASIC


Programmer's Manual


(MDD4PB)


Version 2.1

June 19, 2002



This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2002
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 member of the Association of Shareware Professionals

MARSHALLSOFT is a registered trademark of MarshallSoft Computing.



TABLE OF CONTENTS


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 Compiling Programs
2.2 INCLUDE Files
2.3 Key Code (License Key)
2.4 PowerBASIC DLL Compiler
3 Example Programs
3.1 MDDVER
3.2 DIAL32
3.3 FLY32
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..

MDD4PB supports and has been tested with the 32-bit PowerBASIC Console Compiler (PBCC) and the PowerBASIC DLL Compiler (PBDLL).

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

When comparing MDD against our competition, note that:

  1. MDD4PB is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
  2. MDD4PB does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar "support" libraries.
  3. The MDD4PB 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 (MDD4PB) in the set.

The MDD_4PB Programmer's Manual is the language specific manual. All language dependent programming issues 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. Read this manual after reading the MDD_4PB Programmer's Manual.

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

Each manual comes in three formats:

1.2 Example Program

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


     $INCLUDE "MDD32.PBI"
     $INCLUDE "KEYCODE.PBI"

     FUNCTION PbMain() AS LONG
     Dim Code As Integer
     Dim Version As Integer
     Dim S1 As String
     Dim S2 As String
     Dim S3 As String
     Dim Buffer As Asciiz * 81
     ' attach MDD
     Code = mddAttach(%MDD_KEY_CODE)
     If Code < 0 Then
       Print "ERROR: Cannot attach. Check %MDD_KEY_CODE."
       Return
     End If
     ' get MDD version number
     Version = mddDebug(%MDD_GET_VERSION, Buffer, 80)
     S1 = "MarshallSoft DUN Dialer Version "
     S2 = Hex$(Version)
     S3 = Mid$(S2, 1, 1) + "." + Mid$(S2, 2, 1) + "." + Mid$(S2, 3, 1)
     Print S1 + S3
     ' get registration string
     Code = mddDebug(%MDD_GET_REGISTRATION, Buffer, 80)
     Print Left$(Buffer, Code)
     Code = mddRelease()
     End Function

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 MDD4PB, your 32-bit PowerBASIC Console Compiler should already be installed on your system and tested.

  2. Unzip MDD4PB21.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 MDD4PB files, including copying MDD32.DLL to your Windows directory. No Windows system files are modified.

  4. You're ready to run! The program files are:
     MDDVER.BAS -- The MDD Version program.
     DIAL32.BAS -- The MDD Dial program.
     FLY32.BAS  -- The MDD "On The Fly" Dial program.

Note that the Windows registry is not modified.

1.4 Uninstalling

Uninstalling MDD4PB is very easy. MDD does NOT modify the registry.

First, delete the MDD project directory created when installing MDD4PB.

Second, delete MDD32.DLL from your Windows directory; typically C:\WINDOWS for Windows 95/98/Me/XP or C:\WINNT for Windows NT/2000. That's it!

1.5 Ordering

MDD4PB can be ordered for $55, or $40 for current customers who are registered for one of our other winsock libraries (such as SEE and FCE).

See Section_1.4 of 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 Compiling Programs

The example programs are compiled at the command line with the PowerBASIC Console Compiler:


      PBCC MDDVER.BAD
      PBCC DIAL32.BAS
      PBCC FLY32.BAS

Also see Section 3 "Example Programs" for more information on each of the example programs.

2.2 Include Files

There are two include files, and are included in all example programs.

2.3 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 0), and will be found in the file KEYCODE.PBI. The keycode for the shareware version is 0. You will receive a new key code when registering. Note that your keycode is not the same as your Customer ID/Registration ID.

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.

2.4 PowerBASIC DLL Compiler (PBDLL).

MDD4PB functions can also be called from DLL's created by the PowerBASIC DLL Compiler (PBDLL ).


3 Example Programs

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

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, and registration string. If you get the error "...wrong key", then you are not passing the correct keycode to mddAttach. Refer to Section 2.3 "Key Codes" for more information on key codes.

Compile the PowerBASIC program MDDVER32.BAS.

3.2 DIAL32

The DIAL32 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.

Compile the PowerBASIC program DIAL32.BAS.

3.2 FLY32

The FLY32 example program operates like DIAL32 except that DUN parameters (user, password, and phone) are specified by the user at runtime on the command line. The first DUN entry is "borrowed" in order to dial out, then returned to the initial state after connecting.

Compile the PowerBASIC program FLY32.BAS.

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 1.0: December 12, 2000.

Version 2.0: March 6, 2001.

Version 2.1: June 19, 2002.