MarshallSoft DUN Dialer

Users Manual


(MDD_USR)


Version 1.0

April 10,  2000




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



Copyright (C) 2000
All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815 USA


Voice : 256-881-4630
FAX   : 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                      
  1.2 User Support                       
  1.3 ASP Ombudsman                      
  1.4 Ordering                           
2 Library Overview                       
  2.1 Dynamic Link libraries             
  2.2 GUI and Console Mode               
  2.3 Using the Library                  
  2.4 Key Codes                          
3 Versions of MDD                        
  3.1 Shareware Version                  
  3.2 Student Version                    
  3.3 Professional Version               
4 Application Notes                      
  4.1 Using MDD with Other Languages     
  4.2 Program Structure Overview         
5 Problems                               
6 Legal Issues                           
  6.1 Registration                       
  6.2 License                            
  6.3 Warranty                           
7 Summary                                
  7.1 MDD Function Summary               
  7.2 MDD Error Return Code List         



1  Introduction

This manual applies to the MarshallSoft DUN Dialer (MDD) for all supported languages. 

We have versions of MDD for C/C++ (MDD4C), Delphi (MDD4D), Visual Basic (MDD4VB), 
PowerBASIC (MDD4PB), Visual FoxPro (MDD4FP), Visual dBase (MDD4DB), Alaska Xbase++ 
(MDD4XB), COBOL (MDD4CB), and Fortran (MDD4F).  All versions of MDD use the same DLL 
(MDD32.DLL).

1.1  Documentation Set 

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

o MDD4x Programmers Manual (MDD4x.DOC, MDD4x.TXT, MDD4x.HTM) 
o MDD Users Manual (MDD_USR.DOC, MDD_USR.TXT, MDD_USR.HTM) 
o MDD Reference Manual (MDD_REF.DOC, MDD_REF.TXT, MDD_REF.HTM) 

Each manual comes in three formats:

o Microsoft Word (files ending in .DOC). The best format for printing manuals. 
o Hyper Text (files ending in .HTM). Use any web browser to read. 
o ASCII Text (files ending in .TXT). 

The MDD4x Programmers Manual is the language specific manual. All language dependent programming 
issues are discussed in this manual.  Read this manual first.

The MDD Users Manual (MDD_USR) discusses email processing as well as language independent 
programming issues.  Read this manual after reading the MDD4x Programmers Manual..

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

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



1.2  User Support

We want you to be successful in developing your applications using MDD!  We are committed to 
providing the best library that we can.  If you have any suggestions or comments, please let us know.

If you are having a problem using MDD, refer to Section 8.0 "Problems".  If you still cannot resolve your 
problem, email us at

support@marshallsoft.com

You can also reach us at 256-881-4630 between 7:00 AM and 7:00 PM CST Monday through Friday. You 
can also often reach us on Saturday.

The latest versions of our products are available on our web site at 

http://www.marshallsoft.com

and on our anonymous FTP site at

ftp://ftp.marshallsoft.com/pub

Registered users can update to the latest DLLs at

http://www.marshallsoft.com/oem.htm

The MarshallSoft Computing newsletter "Comm Talk" is published quarterly on our web site.  It discusses 
various communications problems and solutions using our products as well as related information.

1.3  ASP Ombudsman

MarshallSoft Computing, Inc. is a member of the Association of Shareware Professionals (ASP).  ASP 
wants to make sure that the shareware principle works for you.  If you are unable to resolve a shareware-
related problem with an ASP member by contacting the member directly, ASP may be able to help. The 
ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide 
technical support for members' products. Please write to the ASP Ombudsman at 157-F Love Ave., 
Greenwood, IN 26142 USA, FAX 317-888-2195, or send email to omb@asp-shareware.org.


1.4  Ordering

The professional version of  MDD may be registered for $40 (US dollars) for email delivery. The 
professional version DLL is also branded with your company name.

The fastest and easiest way to order is on our web site at

http://www.marshallsoft.com/order.htm

You can also order by completing INVOICE.TXT and emailing (orders@marshallsoft.com), mailing (see 
our address at top), or faxing (256-880-0925) it to us.

Multiple copy discounts (3 or more) and site licenses are available. Please call for details.

We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, 
International Postal Money Orders, and purchase orders (POs) within the USA from recognized US 
schools and companies listed in Dun & Bradstreet.

For credit card orders, be sure to include the account number, the expiration date, the exact name on the 
card, and the complete card billing address (the address to which the credit card bill is mailed- not the 
banks).  Please include card holder's signature on faxed orders.

Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. The registered package includes:

(1) Win32 MDD Library without the shareware screen.
(2) Telephone and email support for one year.

1.4.2  Academic Discount

We offer an "academic price" of 25% off the normal price for prepaid email orders to faculty and full time 
students currently enrolled in any accredited high school, college, or university. To qualify for the 
discount, your school must have a web site and you must have an email address at your school.

When ordering, ask for the "academic discount", or enter "student at" (or "faculty at") and your schools 
web site address (URL) in the comments field of the order form on our web site order page . Your order 
will be sent to your email address at your school.

This offer is not retroactive and cannot be used with any other discount.  Products bought with academic 
pricing can not be used for any commercial purpose.

1.4.3  Disk Only

When ordering MDD, a 3.5" HD disk can be purchased for $5 for delivery to the, US, Canada, and 
Mexico.  For all other destinations, the disk is $8.

See INVOICE.TXT or http://www.marshallsoft.com/order.htm

1.4.4  Disk and Printed Manuals

Printed manuals (see Section 1.1 "Documentation Set") are the same as in the MDD archive.  Printed 
manuals can be purchased for $20 for delivery to the US, Canada, and Mexico. For all other destinations, 
printed manuals are $25. Printed manuals also come with a 3.5" HD disk.

See INVOICE.TXT or http://www.marshallsoft.com/order.htm

2  Library Overview

2.1  Dynamic Link Libraries

The MarshallSoft DUN Dialer (MDD32.DLL) is implemented as 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 a static library which is bound at link time to each and every application that uses it.

2.2  GUI and Console Mode

MDD functions can be called from WIN32 console mode programs as well as GUI programs.  A "console 
mode" program is a Windows 95/98/2000/NT WIN32 command line program running in a command 
window. Although console mode programs look like DOS programs, they are WIN32 programs which 
have access to the entire Windows address space.

2.3  Using the Library

The first MDD function that should be called is mddAttach, which initializes the MDD library and 
allocates necessary resources. mddAttach is typically called in the initialization section of your 
application. 

Before exiting your application, mddRelease should be called. mddRelease should not be called if 
mddAttach failed.

The best way to get familiar with MDD is to try out one of the example programs.  The example programs 
are described in the MDD4x Users Manual:

MDD4C   C/C++               MDD4F   Fortran
MDD4D   Delphi              MDD4CB  COBOL
MDD4VB  Visual Basic        MDD4XB  Xbase++
MDD4PB  PowerBASIC
MDD4FP  Visual FoxPro
MDD4DB  Visual dBase

2.4   Key Codes

When you register MDD, you will receive a new MDD32.DLL and a key code for your DLL. Pass this 
keycode to mddAttach. The keycode will be found in the file named "KEYCODE".  The keycode for the 
shareware version is 0 and will be a 8 to 10 digit number for registered users.



3  Versions of MDD

The MarshallSoft DUN Dialer (MDD) library is available in three versions. All three versions have 
identical functionality.

3.1  Shareware Version

The shareware version can be differentiated from the other two versions by:

(1) The shareware reminder screen is displayed at startup.

(2) The string "SHAREWARE VERSION [http://www.marshallsoft.com]" is returned when calling 

	mddDebug(MDD_GET_REGISTRATION, Buffer, BufLen)

The Shareware version may not be used for commercial purposes.

3.2  Student Version

The student version can be differentiated from the other two versions by:

(1) There is no shareware reminder screen.

(2) The registration string is changed to

" STUDENT VERSION [http://www.marshallsoft.com]"

The Student version may not be used for commercial purposes.

3.3  Professional Version

The professional version can be differentiated from the other two versions by:

(1) There is no shareware reminder screen.

(2) The registration string is changed to your company name.

The professional version may be distributed with your application as specified by the software license. See 
Section 1.4 "Ordering" for details on ordering.

4.  Applications Notes

4.1  Using MDD with Other Languages

The MarshallSoft DUN Dialer MDD32.DLL can be used with any application written in any language 
capable of calling the Windows (95/98, NT,2000) Win32 API

Declaration files have been defined by the following languages:

C/C++                   MDD.H
Visual Basic            MDD32.BAS
VBA (Excel, Access,)   MDD32.BAS
PowerBASIC              MDD32.BAS [not the same as above]
Borland Delphi          MDD32.PAS
Fujitsu COBOL           MDD32.CBI
ABSOFT FORTRAN          MDD32.INC
Visual FoxPro           MDD32.FOX
Visual dBase            MDD32.CC
Alaska Xbase++          MDD32.CC [not the same as above]

Additional declaration files will be added. Give us a call if you need a declaration not listed above.

If you have interfaced MDD to an unusual language, email us the declaration file!

4.2   Program Structure Overview

The structure of most applications using MDD is as follows:

(1) Call mddAttach(KEY_CODE).
(2) Call mddLoadEntries() to get listing of all entry names.
(3) Choose an entry to dial.
(4) Begin dialing by calling mddBeginDial()
(5) Call mddDialStatus in a loop until connected.
(6) . . . run Winsock applications . . .
(7) Hang up (mddHangup) and release (mddRelease) MDD.


5  Problems

First, be sure you are passing the proper key code. See section 2.4 "Key Codes".

Be sure to test the code returned from MDD functions. 

If you still get the shareware screen after registering, the problem is that Windows is finding the shareware 
DLL before the registered DLL. The solution is to delete (or zip up) all shareware versions of 
MDD32.DLL.

If you get "error -74" when calling mddAttach, the problem is that the keycode passed to mddAttach does 
not match the keycode in the DLL's. This is caused by (1) using the shareware keycode (value = 0) with 
the registered DLL, or (2) using the registered keycode with the shareware DLL.

If you cannot get your application to run properly, first compile and run the example programs. If you call 
us to report a possible bug in the library, the first thing we will ask is if the example programs run 
correctly.

If you encounter a problem that you cannot resolve, give us a call or email us at 
support@marshallsoft.com.


6  Legal Issues

6.1  Registration

See Section 1.4 "Ordering" for information on ordering.

6.2  License

MarshallSoft Computing, Inc. grants the registered user of MDD the right to use one copy of the MDD 
DLL's on a single computer in the development of any software product. The user may not use the library 
on more than one computer at the same time.

The "student" ($30) registered DLL's may not be distributed under any circumstances, nor may they be 
used for any commercial purpose.

The "professional" ($40) registered DLL's may be distributed (without royalty) in object form only, as part 
of the user's compiled application. The registered DLL's may NOT be distributed as part of any software 
development system (compiler or interpreter) without our express written permission. When you register, 
you will be sent a "key code" which enables access to the registered DLL's.  You may NOT distribute or 
make known this key code. (see Section 2.4 "Key Code").

6.3  Warranty

MARSHALLSOFT COMPUTING, INC.  DISCLAIMS ALL WARRANTIES RELATING TO THIS 
SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY 
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY 
DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC.  NOR ANYONE ELSE WHO HAS 
BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE 
SHALL BE LIABLE FOR ANY INDIRECT,  CONSEQUENTIAL, OR INCIDENTAL DAMAGES 
ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF 
MARSHALLSOFT COMPUTING, INC.  HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 
DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S 
LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO 
USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE 
SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE 
SOFTWARE.

Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so 
the above limitation may not apply to you.

This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of 
MarshallSoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or 
proceeding brought by either party against the other arising out of or related to this agreement shall be 
brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County,  
Alabama. The parties hereby consent to in personam jurisdiction of said courts.

7  Summary

7.1  MDD Function Summary

Refer to the MDD Reference Manual (MDD_REF) for detailed information on the MDD functions.  A one 
line summary of each function follows.

There are 10 functions in the MDD library.

mddAttach         Attaches (initializes) MDD.
mddRelease        Releases MDD.
mddLoadEntries    Load all defined dial entries.
mddGetEntry       Get entry name.
mddBeginDial      Begin dialing.
mddHangup         Hang up.
mddDialStatus     Get current dialing status code.
mddStatusText     Get text of dialing status code.
mddErrorText      Get text of error message.
mddDebug          Get debug information.

7.2  MDD Error Return Code List

The complete list of MDD error codes follows. 

#define MDD_NO_ERROR              1
#define MDD_EOF                  -1
#define MDD_ABORTED              -2
#define MDD_ALREADY_ATTACHED     -3
#define MDD_NO_SUCH_ENTRY        -4
#define MDD_BAD_KEY_CODE        -74

