Microsoft KB Archive/120075

= How To Convert VB for MS-DOS Programs to VB for Windows =

Article ID: 120075

Article Last Modified on 8/16/2005

-

APPLIES TO


 * Microsoft Visual Basic 4.0 Standard Edition
 * Microsoft Visual Basic 4.0 Professional Edition
 * Microsoft Visual Basic 4.0 Enterprise Edition
 * Microsoft Visual Basic for MS-DOS
 * Microsoft Visual Basic 2.0 Standard Edition
 * Microsoft Visual Basic 3.0 Professional Edition
 * Microsoft Visual Basic 2.0 Professional Edition
 * Microsoft Visual Basic 3.0 Professional Edition

-



This article was previously published under Q120075



SUMMARY
This article provides information and tips for converting Microsoft Visual Basic version 1.0 for MS-DOS programs to Microsoft Visual Basic for Windows. To convert Visual Basic for MS-DOS programs, you must have both Visual Basic version 1.0 for MS-DOS and Visual Basic version 2.0 or higher for Windows.



MORE INFORMATION
WARNING: One or more of the following functions are discussed in this article; VarPtr, VarPtrArray, VarPtrStringArray, StrPtr, ObjPtr. These functions are not supported by Microsoft Technical Support. They are not documented in the Visual Basic documentation and are provided in this Knowledge Base article "as is." Microsoft does not guarantee that they will be available in future releases of Visual Basic.

Converting Visual Basic for MS-DOS Applications
If you have Visual Basic for MS-DOS, you can create applications that run under both MS-DOS and Windows. Such applications exist as separate .EXE files for each target environment. There is no way to create a single file that will run in both environments. When you convert a Visual Basic application from MS-DOS to Windows, you are faced with the following problems:
 * The binary file formats of the modules are different for the two products.
 * The appearance of some forms and controls is different.
 * There are language differences between Visual Basic for MS-DOS and Visual Basic for Windows.

Some of these language differences result because Windows and MS-DOS control their respective environments in very different ways. Other differences occur because some language components of Visual Basic for MS-DOS are simply not supported by Visual Basic for Windows.

You can resolve these problems using the following general procedure. The rest of this article includes specific information on these general steps.

To convert an application from MS-DOS to Windows:
 * 1) Start Visual Basic for MS-DOS and open the project to convert.
 * 2) Move all procedure declarations into an include file (.BI) and add a $INCLUDE metacommand at the module level of each file.
 * 3) Save each form and code module in text format.
 * 4) Copy the project's .MAK, .FRM, and .BAS files to a new directory.
 * 5) Edit the project file (.MAK) to change explicit path names--if used.
 * 6) Open the project in Visual Basic for Windows and view each form. If an error occurs reading the MS-DOS form definition, Visual Basic for Windows creates a .LOG file and displays a warning.
 * 7) Review the .LOG files (if any) to see a listing of incompatibilities. Fix these errors using Visual Basic for Windows or a text editor.
 * 8) Adjust the visual interface of the application to best match the capabilities of Windows.
 * 9) Resolve any conflicts between Visual Basic for Windows keywords and existing symbol names. (Symbols are the names of variables, constants, objects, procedures, parameters, or labels used in code.)
 * 10) Convert platform-specific code to work with the target environment.
 * 11) Run your application in the target environment to verify its behavior and to test your changes.

NOTE: Visual Basic capitalizes keywords automatically based on an internal convention. In MS-DOS, the convention is all uppercase. In Windows, the convention is to capitalize the first letter of each keyword. Although the appearance of your code may change, the content remains the same.

Moving Procedure Declarations to an Include File
Visual Basic for MS-DOS uses DECLARE statements to declare Basic and Quick library procedures (.QLB). Visual Basic for Windows uses Declare only for DLLs. To avoid syntax errors when you move your MS-DOS application to Windows, move DECLARE statements to a Visual Basic for MS-DOS include file (.BI) and add a $INCLUDE metacommand at the module level of each file. For example:

'$INCLUDE: 'DOSINC.BI'

Visual Basic for Windows does not recognize the $INCLUDE metacommand, so this statement is treated as a comment. The code will continue to run correctly in Visual Basic for MS-DOS, however.

Saving Form and Code Modules in Text Format
By default, all forms and code modules (.FRM and .BAS) are saved in a binary format. As mentioned previously, however, the binary format is not compatible between versions of Visual Basic. To load an MS-DOS project in Windows, you must first save all of the files in text format. Once a file is saved in text format, it will continue to be saved in that format by default.

To save a form or code module in text format:
 * 1) Start Visual Basic for MS-DOS and open the project to convert.
 * 2) From the File menu, choose Save File As. Visual Basic displays the Save File As dialog box.
 * 3) Select the Save as Text check box.
 * 4) Choose OK.

Copying Project Files
After you save the forms and code modules in text format, copy the entire project to a new location so you do not overwrite your source application. Copy only the .MAK file and the files listed in the .MAK file. Because Windows and MS-DOS custom controls are not compatible, there is no need to copy files with .QLB extensions. Portions of applications that depend on custom controls or Quick library procedures (.QLB files) must be rewritten.

Editing the Project File
If you saved your modules to a directory other than the current one, Visual Basic for MS-DOS includes the paths in your project file (.MAK). Load this file in a text editor, and change the paths to reflect the directory of the new project.

Opening the Project and Viewing Forms
After copying and editing the project files, start Visual Basic for Windows and open the project. View each form in the project by selecting the file in the Project window and choosing the View Form button.

If errors occur, Visual Basic for Windows displays a warning, "Errors during load." Refer to 'filename.LOG' for details. Make a note of the file name and choose the OK button to close the dialog box.

Reviewing the .LOG Files
Two types of errors (invalid form names and invalid properties) occur when loading an MS-DOS form in Visual Basic for Windows.

Forms in Visual Basic for Windows cannot be named MDIForm. If you have a form with this name in your MS-DOS project, it will generate the following error in Visual Basic for Windows and the form will not load:

MDIForm is a class name

You must change the form name in the .FRM file using a text editor. For example:

Version 1.00 BEGIN Form tMDIForm ' Added "t."

After making this change, reload the project.

When you view an MS-DOS form that has a property or property setting not supported by Visual Basic for Windows, Visual Basic for Windows creates a .LOG file similar to this one:

Line 120 :Property BorderStyle in control picJAW could not be set. Line 141 :Property Attached in control HScroll1 could not be loaded. Line 254 :Property Attached in control VScroll1 could not be loaded.

It is important to review the .LOG files to check for properties that may be used in code or that critically affect the appearance or behavior of your application.

When you save a form file in ASCII format, Visual Basic for Windows omits default property settings, invalid property settings, and invalid properties. Because Visual Basic for Windows treats omitted property settings as default values, invalid property settings revert to their default. For more information, see Appendix A, "ASCII File Formats" of the Visual Basic for Windows "Programmer's Guide."

Adjusting the Visual Interface
When Visual Basic for Windows loads a project created in Visual Basic for MS-DOS, it changes the appearance of forms as they are loaded. These changes are due to the differences between Visual Basic for MS- DOS and Visual Basic for Windows:
 * The position and size of controls may change because the Visual Basic for MS-DOS character coordinates are converted to twips in Visual Basic for Windows.
 * Colors may change because the Visual Basic for MS-DOS colors are converted to RGB values.
 * Custom controls are mapped to picture controls.

Use the Visual Basic for Windows design tools to adjust the appearance and placement of controls as appropriate.

You may be able to define global changes to the appearance of your application by editing the ASCII form description for each form module before you load the form in Visual Basic. For information about the format of the ASCII form description, see Appendix A, "ASCII File Formats" of the Visual Basic for Windows "Programmer's Guide."

Converting Platform-Specific Code
Some applications, such as the sample application CALC.FRM, will run fine on either MS-DOS or Windows without changing much code. However, more complex applications can require significant recoding. There are several categories of platform-specific code that you must change to move an application from MS-DOS to Windows:
 * System calls. Code that relies on MS-DOS interrupts must be rewritten.
 * Data type and scoping differences. Visual Basic for Windows and Visual Basic for MS-DOS have different default data types. The scoping rules for arrays are also different.
 * Unsupported keywords. Most of the Visual Basic for MS-DOS keywords that are not supported in Windows have functionality that is replaced by forms and event-driven programming style.
 * Different coding mechanisms. Some features, such as declaring global variables and displaying run-time graphics, require different coding mechanisms because of language differences between Visual Basic for Windows and MS-DOS.

The following four sections provide details on these differences:

System Calls
Many MS-DOS system calls have some equivalent under Windows. However, the mechanism for calling Windows functions is very different from using MS-DOS interrupts. For information on calling Windows functions, see "Calling Procedures in DLLs" in the Visual Basic for Windows "Programmer's Guide."

Data Type and Scoping Differences
In Visual Basic for MS-DOS, the default data type is SINGLE. In Visual Basic for Windows, the default data type is Variant. This difference can cause serious errors using Get and Put on existing data files, because the two data types are different sizes. To avoid this, add a DefSng statement to each module that doesn't already include a Deftype statement.

To remain consistent with earlier versions of Basic, Visual Basic for MS-DOS does not allow shared array variables to be shadowed at the procedure level. For example, the following code behaves differently in MS-DOS and Windows: ' Module level DIM SHARED Array AS INTEGER SUB ChangeArray

' In MS-DOS, dimensions shared array. In Windows, creates ' a new copy of the array (shadows shared array). DIM Array(10)

END SUB To avoid this unexpected behavior, rename the procedure-level array.

Unsupported Keywords
Visual Basic for Windows omits about 100 keywords that are supported by Visual Basic for MS-DOS. Using any of these keywords in the MS-DOS application that you convert to Windows results in omitted functionality. You must rewrite any code that relies on these keywords: 

ALL            INKEY$          SEEKEQ BLOAD          INP             SEEKGE BOF            INSERT          SEEKGT BSAVE          IOCTL           SEG CALLS          IOCTL$          SETINDEX CDECL          ISAM            SETMEM CHAIN          KEY             SETUEVENT CHECKPOINT     LIST            SIGNAL COLOR          LOCATE          SLEEP COM            LPOS            SOUND COMMON         LPRINT          SSEG CREATEINDEX    MKC$            SSEGADD CSRLIN         MKDMBF$         STACK CVI            MKI$            STICK CVC            MKL$            STRIG CVD            MKS$            SWAP CVDMBF         MKSMBF$         SYSTEM CVL            OUT             TEXTCOMP CVS            PAINT           TRON CVSMBF         PALETTE         TROFF DELETEINDEX    PCOPY           UEVENT DELETETABLE    PEEK            UPDATE DRAW           PEN             VARPTR ERDEV          PLAY            VARPTR$ ERDEV$         PMAP            VARSEG EVENT          POS             VIEW FIELD          PRESET          WAIT FILES          RUN             WINDOW FN             SADD FRE            SAVEPOINT GETINDEX$      SCREEN NOTE: Visual Basic for Windows does not support DEF FN functions.

Different Coding Mechanisms
The scoping mechanisms in Visual Basic for MS-DOS are different from those in Visual Basic for Windows, as shown by this table:

Visual Basic for MS-DOS applications cannot display forms and graphics at the same time. This limitation does not exist in Visual Basic for Windows. Code that displays graphics must be completely rewritten for use in Windows.

Similarly, custom controls are very different in Visual Basic for MS-DOS and Windows. Custom controls and Basic code that rely on custom controls must be rewritten for Windows.

Running Your Converted Application
To complete the conversion, run your application in Visual Basic for Windows and test for errors. The following is a list of problems you may encounter. Only the most likely problems are listed here, along with the error message you may see.  Visual Basic for Windows reserves True and False as instrinsic constants.

Possible error message - Expected: identifier Remove or comment out the constant declarations for TRUE and FALSE.

 Visual Basic for Windows allows executable code only inside a procedure; there can be no executable code or labels at the module level of a Visual Basic application.

Possible error message - Invalid outside procedure Move module-level executable code into a Sub Main procedure and set it to be the startup procedure. Convert module-level error- handling code to local error handlers.

 Visual Basic for Windows does not recognize the DATA statement.

Possible error message - Expected: statement Convert the values in the DATA statement(s) to a sequential file; replace the DATA statement(s) with a block of code that opens, reads, and closes the file.

 Visual Basic for Windows does not recognize the COMMON keyword.

Possible error message - Expected: end-of-statement Replace the COMMON SHARED keywords with the keyword PUBLIC. Move module-level code into procedures.

 Visual Basic for Windows puts invalid procedure definitions at the Declarations level of a module.

Possible error message - Expected: parameter or ) Cut the procedure code from the Declarations level and paste it into a valid procedure definition. Delete the invalid procedure definition.



Techniques for Platform-Independent Applications
Writing an application that will convert easily from MS-DOS to Windows requires some planning. Here are some suggestions that make the process easier.
 * Start with MS-DOS. The appearance of MS-DOS forms requires less adjustment when converted to Windows. Also, because the forms-related features of Visual Basic for MS-DOS are a subset of those available in Windows, you are less likely to inadvertently use a feature for which there is no solution.
 * Use the portable subset of the language. The lists of unsupported keywords provided earlier in this chapter will give you an idea of features to avoid when planning a portable application.
 * Debug your MS-DOS application before you convert it to Windows. If you start with an application that runs without errors, you can assume that errors you encounter when converting are related to differences between the two platforms. This will save you a lot of time trouble-shooting.
 * Create parallel Include files. In Visual Basic for MS-DOS, place COMMON SHARED and constant declarations in an Include file (.BI). For the Visual Basic application, add a Basic module (.BAS) with parallel Global declarations and appropriate constants.
 * Package portable procedures in code modules. Procedures that will run in MS-DOS or Windows without modification should be placed in code modules (.BAS) that you can share between the two platforms.
 * Modularize run-time graphics. Place all run-time graphics procedures in a separate module. Visual Basic for MS-DOS does not support graphics while forms are showing, and code for MS-DOS graphics is more hardware- dependent than similar code for Windows.
 * Test portability. When developing a large application, periodically test its portability during development. This will help you develop a portable coding style.

Detecting the Platform at Startup
Applications created with Visual Basic for Windows include code that will automatically start Windows if it is not running on your system. This feature can be used to create an application that will run in either Windows or MS-DOS.

The following batch file starts CALCWIN.EXE. If Windows is not available or cannot start, the batch file runs CALCDOS.EXE instead:

@ECHO OFF

CALCWIN.EXE

IF ERRORLEVEL 1 CALCDOS.EXE

The application sets an MS-DOS error code of 1 if it can't start Windows. Otherwise, the error code is 0 when the application ends.

NOTE: This feature also applies to MS-DOS sessions. If Windows can't start because it is already running, the preceding batch file will start CALCDOS.EXE.

Additional query words: 1.00 2.00 3.00 4.00 B_VBMSDOS

Keywords: kbhowto KB120075

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.