MarshallSoft DUN Dialer
Users Manual
(MDD_USR)
Version 2.1
June 7, 2002
(Modified November 14, 2003)
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 USA
Voice : 1-256-881-4630
FAX : 1-256-880-0925
email : info@marshallsoft.com
web : www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Documentation2 Library Overview
1.2 User Support
1.3 ASP Ombudsman
1.4 Ordering
1.5 Updating
1.6 Customer ID
1.7 License File
2.1 Dynamic Link libraries3 Versions of MDD
2.2 GUI and Console Mode
2.3 Using the Library
2.4 Key Codes
3.1 Shareware Version4 Application Notes
3.2 Student Version
3.3 Professional Version
4.1 Using MDD with Other Languages5 Problems
4.2 Program Structure Overview
4.3 Monitoring Connection Status
4.4 Dialing "On The Fly"
6 Legal Issues
6.1 Registration7 Summary
6.2 License
6.3 Warranty
7.1 MDD Function Summary
7.2 MDD Error Return Code List
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.
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), and Alaska Xbase++ (MDD4XB). All versions of MDD use the same DLL (MDD32.DLL).
The complete set of documentation consists of three manuals in three formats. This is the second manual (MDD_USR) in the set.
Each manual comes in three formats:
The MDD_4x 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_4x Programmer's Manual.
The MDD Reference Manual (MDD_REF) contains details on each individual MDD function.
Use Microsoft Word or Microsoft WordPad to print the document files.
Check http://www.marshallsoft.com for the latest version of our dialer software.
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 DLL's 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.
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.
The professional version of MDD may be registered for $55 (US dollars) for email delivery. The professional version DLL is also branded internally with your company name.
MDD may be bought for $40 when purchased by a registered user of one of our other internet libraries (SEE, FCE, or PNG). In order to qualify for the $40 price, your registration must be current. That is, your purchase or last update must have been within the previous 12 months.
When ordering at the $40 price, put your 4 digit customer ID in the comments field of the order form. Your customer ID is the 4 digits following the product name (MDD, SEE, FCE, PNG) in your license file
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 (order@marshallsoft.com), mailing (see our address at top), or faxing (1-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 bank's). 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:
We offer an "academic price" of $30 for prepaid email orders to faculty and full time students currently enrolled in any accredited high school, college, or university. To qualify for the educational 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 are for educational purposes 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
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
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.
Your customer ID is the 4 digits following the product name (MDD) in your license file. For example, customer 1234 would receive license file MDD1234.LIC.
When you register MDD you will receive a license file named MDDxxxx.LIC, where "xxxx" is your 4-digit customer ID. The license file is an encrypted binary file used for updating MDD as explained in section 1.5 "Updates".
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.
MDD functions can be called from WIN32 console mode programs as well as GUI programs. A "console mode" program is a Windows 95/98/Me/2000/NT/XP 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 Window's address space.
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 MDD_4x Users Manual:
MDD_4C C/C++ MDD_4FP Visual FoxPro
MDD_4D Delphi MDD_4DB Visual dBase
MDD_4VB Visual Basic MDD_4XB Xbase++
MDD_4PB PowerBASIC
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. Note that it is not your Customer ID.
The MarshallSoft DUN Dialer (MDD) library is available in three versions. All three versions have identical functionality.
The shareware version can be differentiated from the other two versions by:
mddDebug(MDD_GET_REGISTRATION, Buffer, BufLen)
The Shareware version may not be used for commercial purposes.
The student version can be differentiated from the other two versions by:
" STUDENT VERSION [http://www.marshallsoft.com]"
The Student version may not be used for commercial purposes.
The professional version can be differentiated from the other two versions by:
The professional version may be distributed with your application as specified by the software license. See Section 1.4 "Ordering" for details on ordering.
The MarshallSoft DUN Dialer MDD32.DLL can be used with any application written in any language capable of calling the Windows (95/98/Me/NT/2000/XP) Win32 API
Declaration files have been defined by the following languages:
C/C++ MDD.H
Visual Basic MDD32.BAS
VBA (Excel, Access, etc) MDD32.BAS
PowerBASIC MDD32.PBI
Borland Delphi MDD32.PAS
Visual FoxPro MDD32.FOX
Visual dBase MDD32.CC
Alaska Xbase++ MDD32.CH
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!
The structure of most applications using MDD is as follows:
Once a connection has been made, the status of the connection may be monitored with mddDialStatus. An error (MDD_NOT_CONNECTED) will be returned if the line is dropped.
Refer to the DIAL or WDIAL example programs.
Provided that DUN is installed and has at least one dialing entry, you can specify dialing parameters at runtime by calling mddSetParms before calling mddBeginDial(0).
The mddSetParms function "borrows" dialing entry 0, inserting the parameters specified by mddSetParms. Calling mddHangup will restore the original values to entry 0.
Refer to the FLY example program.
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.
Verify that "Show Terminal Window" in the DUN Properties Window is unchecked. For Win/XP, click the "Network Connections" icon in the Control Panel window, then right-click your Dial-up icon, pick "Properties", then pick the "Security" tab.
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 except the one in your windows directory (C:\WINDOWS for Win 95/98/Me/XP or C:\WINNT for Win NT4/2000).
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, call us or email us at support@marshallsoft.com.
See Section 1.4 "Ordering" for information on ordering.
This license agreement (LICENSE) is a legal agreement between you (either an individual or a single entity) and MarshallSoft Computing, Inc. for this software product (SOFTWARE). This agreement also governs any later releases or updates of the SOFTWARE. By installing and using the SOFTWARE, you agree to be bound by the terms of this LICENSE. If you do not agree to the terms of this LICENSE, do not install or use the SOFTWARE.
MarshallSoft Computing, Inc. grants a nonexclusive license to use the SOFTWARE to the original purchaser for the purposes of designing, testing or developing software applications. Copies may be made for back-up or archival purposes only. This product is licensed for use by only one developer at a time.
The student registered DLL's may not be distributed under any circumstances, nor may they be used for any commercial purpose.
The professional registered DLL's may be redistributed (without royalty) as part of the user's compiled application. The registered DLL's may NOT be distributed as part of any software development system without our express written permission. When the software is registered, a key-code will be provided, which enables access to the registered DLL's. This key-code may NOT be distributed or made known.
The SOFTWARE is owned by MarshallSoft Computing, Inc. and is protected by United States copyright laws and international treating provisions. This SOFTWARE is being licensed and not sold.
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.
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 11 functions in the MDD library.
mddAttach Attaches (initializes) MDD. mddBeginDial Begin dialing. mddDebug Get debug information. mddDialStatus Get current dialing status code. mddErrorText Get text of error message. mddGetEntry Get entry name. mddHangup Hang up. mddLoadEntries Load all defined dial entries. mddRelease Releases MDD. mddSetParms Set entry parameters. mddStatusText Get text of dialing status code.
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_NOT_CONNECTED -5 #define MDD_BAD_KEY_CODE -74