BYTE* / Microsoft Visual C++ 1.0 (16-bit) / TOOLS.WRI (converted & reformatted as text)

TOOLS.WRI File

Documentation for the Command-Line Tools for Microsoft(R) Visual C++, Version 1.0

Tools Overview and Update
for Microsoft Visual C++

The command-line tools (also called utilities) are programs run from an MS-DOS prompt or called by another program. This file provides a guide to the tools documentation and presents some highlights about the current versions.
Be sure to consult the release notes in README.WRI for information on the CL compiler and other Visual C++ components that may interact with these tools.

About This Document
Many features of the command-line tools are available as menu and dialog-box choices in the Microsoft Visual Workbench intergrated development environment. Visual Workbench Help provides brief descriptions of these choices. As you use Visual Workbench, you may want to consult additional documentation for a further understanding of these choices. This document provides a guide to other tools documentation.
Some tools such as LIB and IMPLIB do not have equivalents in Visual Workbench and are not described in Visual Workbench Help. This document describes the available documentation and provides additional updates.
If you develop programs outside of Visual Workbench, you should read this document and the other tools documentation to understand how to use the command-line tools to build your program.
Certain tools are MS-DOS extended and have special requirements. To understand how to run these tools, read Part 3 of this document. If you also use Microsoft MASM version 6.1, be sure to read Part 4 to avoid a conflict between MS-DOS extenders.
If you have Microsoft Visual C++, Professional Edition, you should read Part 7 for changes to the tools chapters in the Command-Line Utilities User's Guide.
If you are upgrading from Microsoft C/C++ version 7.0, you should read Part 8 to become familiar with the changes in the tools for Visual C++ and the documentation differences from Environment and Tools.

Contents
This file has the following sections:

Part 1: Command-Line Tools in Visual C++
Part 2: Overview of Changes to Tools
Part 3: 32-Bit MS-DOS-Extended Tools
Part 4: Microsoft MASM Version 6.1 Compatibility
Part 5: Obsolete Tools
Part 6: Errors Documentation
Part 7: Command-Line Utilities User's Guide Errata
Part 8: Environment and Tools Update
Part 9: Miscellaneous Notes

Part 1: Command-Line Tools in Visual C++

This section lists the tools provided in Visual C++, their version numbers, and the location of their primary documentation in the Command-Line Utilities User's Guide and various files.

Filename Version Documentation
BSCMAKE.EXE 2.50 BSCMAKE.WRI
CVPACK.EXE 4.10 CVPACK.WRI
EXEHDR.EXE 3.10 Chapter 5
IMPLIB.EXE 1.41 IMPLIB.WRI
LIB.EXE 3.30 LIB.WRI
LINK.EXE 5.50 Chapters 2-4; MOVEAPI.WRI
NMAKE.EXE 1.30 NMAKE.WRI
NMAKER.EXE 1.30 Part 3, below
SBRPACK.EXE 2.10 BSCMAKE.WRI
TRACE.EXE 1.10 MOVEAPI.WRI

The version numbers for the Visual C++ tools are higher than the version numbers for the same tools provided with Microsoft C/C++ version 7.0. If you are upgrading, be sure the latest version of each tool appears on the path. To see a version number, run the tool with the /? option.
Some tools are documented in Chapters 2-5 of the Command-Line Utilities User's Guide, which is provided with Microsoft Visual C++, Professional Edition. Part 7, below, contains additional information related to these chapters. Part 8 contains updates to the equivalent documentation in Environment and Tools in Microsoft C/C++ version 7.0.
Other tools documentation is in the form of .WRI files that can be accessed from the Tools TechNote Viewer in the online help file TOOLS.HLP. These files supersede the equivalent documentation in Environment and Tools in Microsoft C/C++ version 7.0.
The Visual Workbench online help summarizes the LINK options and describes .DEF file statements. To view this help, choose Build Tools from the Help Menu in Visual Workbench.
Errors are documented in the online help file ERRORS.HLP. This file is described in Part 6.

Part 2: Overview of Changes to Tools

The following changes apply to all tools in Visual C++:

Visual Workbench Replaces PWB
References in the Microsoft C/C++ 7.0 documentation to the Microsoft Programmer's Workbench (PWB) are replaced by Visual Workbench. If you are upgrading, consult Visual Workbench Help for more information.

QuickHelp is No Longer Available
The QuickHelp utility (QH.EXE) and QuickHelp-formatted help files are not provided in Visual C++. (An exception is Microsoft CodeView, which uses the QuickHelp-formatted file CV.HLP.) There is no online help for the command-line tools.
The /HELP option for each tool now behaves the same as the /? option. Both options display a brief summary of syntax and options for a tool.

Part 3: 32-Bit MS-DOS-Extended Tools

The following Visual C++ tools are 32-bit MS-DOS-extended programs:

� BSCMAKE.EXE
� CL.EXE
� CVPACK.EXE
� LINK.EXE
� NMAKE.EXE

These tools require an 80386 or higher processor running in protected mode. The file DOSXNT.EXE must be in the same directory as the tool or in a directory specified in the PATH environment variable. In addition, for these tools to run with the Microsoft Windows operating system, DOSXNT.386 must be specified in a DEVICE statement in the [386Enh] section of SYSTEM.INI.
The version of NMAKE provided with Visual C++ cannot run programs that use non-Microsoft MS-DOS extenders. If your makefile calls a 32-bit program that uses another MS-DOS extender, use NMAKER.EXE instead of NMAKE.EXE. NMAKER, which is a real-mode MS-DOS program, may run slower than NMAKE and has some memory limitations.
If you get a DXnnnn error when running an MS-DOS-extended tool, consult the errors help, described in Part 6 of this file.
Tools that are not MS-DOS-extended run under MS-DOS in real mode and do not require additional services.

Part 4: Microsoft MASM Version 6.1 Compatibility

Several Microsoft language products provide 32-bit MS-DOS-extended tools that use the Microsoft DOSXNT MS-DOS Extender. The version of DOSXNT used by Microsoft Visual C++ version 1.0 is not compatible with the version used by Microsoft MASM version 6.1.
To ensure that all MS-DOS-extended tools run successfully, it is recommended that you install
each language product in a separate directory and that you leave each version of DOSXNT.EXE in the subdirectory that contains the tools it supports. This allows each MS-DOS�extended tool to locate the appropriate version of DOSXNT.EXE. Make sure that the PATH environment variable specifies the directory in which you installed Visual C++ 1.0 before the directory that contains MASM 6.1. This ensures that you can run the latest versions of tools that are in common to both products.
If you install both Visual C++ and MASM 6.1 in one directory, you will not be able to run
MASM.EXE and ML.EXE from the command line. However, you will be able to run these tools
as commands executed by NMAKE.

Part 5: Obsolete Tools

The following tools were provided with Microsoft C/C++ version 7.0 and are not needed with Microsoft Visual C++ version 1.0 :

� BSCMAKEV.EXE
� EXP.EXE
� HELPMAKE.EXE
� ILINK.EXE
� PWBRMAKE.EXE
� QH.EXE
� RM.EXE
� UNDEL.EXE
� WX.EXE
� WXSRVR.EXE

If you are upgrading, be sure to modify your makefiles and batch files if they contain commands to run these programs. You should also remove these tools from your path or delete them from your disk.

Part 6: Errors Documentation

Errors are documented in the online help file ERRORS.HLP. To view this help file, do one of the following:

� To view help for an error that appears in the Output window in Visual Workbench, place the insertion point on the error number and press F1.
� To view help on all errors, click the Build Errors Help icon in the Microsoft Visual C++ program group, or open ERRORS.HLP from the File Manager.

Part 7: Command-Line Utilities User's Guide Errata

For users of Microsoft Visual C++ Professional Edition: The following additions and corrections apply to Chapters 2 through 5 of the Command-Line Utilities User's Guide. For changes to other chapters in this manual, see ERRATA.WRI, which is available in the Readme TechNote Viewer.

Chapter 2

Page 124, The /CO Option
Replace the last paragraph with the following:

Packaged functions compiled with /Zi or /Zd are referenced by the compiler and are not removed by /PACKF.

Page 126, The /EXEPACK Option
Delete the last sentence of the third paragraph. In the fourth paragraph, add "and programs for Windows" to the end of the last sentence.

Page 135, The /PACKF Option
Replace the last paragraph with the following:

Packaged functions compiled with /Zi or /Zd (to add debugging information) are referenced by the compiler. These functions are not removed by /PACKF.

Chapter 3

All references in this chapter to MOVEAPI.TXT should refer instead to MOVEAPI.WRI.

Page 148, Linking the Overlaid Program
Add the following paragraph:

If you link an overlaid program with GRAPHICS.LIB, LINK must search MOVE.LIB before it searches GRAPHICS.LIB. Because MOVE.LIB is in the default libraries, which are last in LINK's search order, you must specify the default library explicitly in the LINK command ahead of GRAPHICS.LIB. If you combine GRAPHICS.LIB with your default library, be sure to append GRAPHICS.LIB to the end of the default library.

Page 150, Limits and Requirements
Add the following paragraph:

Virtual functions cannot be placed into overlays.

Chapter 4

Page 156, Syntax Rules
Replace the first sentence in the last syntax rule with the following:

If a string argument matches a reserved word or begins with a character other than a letter of the alphabet or an underscore (_), it must be enclosed in double quotation marks (" ").

Part 8: Environment and Tools Update
For upgrade users: The following changes apply to Chapters 14-17 of Environment and Tools in Microsoft C/C++ version 7.0. These chapters document LINK and EXEHDR. For changes to other chapters, see the Update Reference. For documentation on other Visual C++ tools, see Part 1 of this document.

Chapter 14

Page 561, New Features
LINK no longer looks for CVPACK when linking a program for debugging.
ILINK.EXE is no longer provided or supported.
If you create an object file by specifying the /Zi option to the CL compiler (or you specify a library that contains a module created in this manner) and you link using /CO, the program database (.PDB) file for that object file must be available. LINK looks for .PDB files in the following locations in this order:

1. The absolute path written in the .OBJ file by CL.
2. The current directory that LINK is running from.
3. Any directories specified in the LIB environment variable.

LINK does not look in the directory that contains the object file or library, nor does it look in a directory specified in the libraries field. You cannot specify a .PDB file's name or location on the LINK command line.

The /r option has been removed.

Add the following new option:

The /PCODE Option

/PC[ODE][:NOMPC]

This option tells LINK to call the Make P-Code Utility (MPC). MPC is included with Microsoft C/C++ versions 7.0 and later. Previous versions of LINK required this option when linking a p-code program. The current version of LINK now automatically calls MPC when it detects p-code. In the unlikely situation that you need to prevent LINK from calling MPC, specify /PCODE:NOMPC.

Page 577, The /CO Option
Add the following paragraph:

You can use the /STRIP option of the CVPACK utility to remove debugging information from an executable file after linking. If you want to save the removed information in a .DBG file, specify a filename with /STRIP. For more information on CVPACK, see "Using CVPACK" in the Tools TechNote Viewer.

Page 580, The /EXEPACK Option
Delete the last sentence of the third paragraph. To the end of the fourth paragraph, add the following sentence:

LINK ignores the /EXEPACK option for overlaid programs and programs for Windows.

Page 581 "The /HELP Option"
The /HELP option now gives the same result as the /? option.

Page 589 "The /PACKF Option"
Add the following paragraph:

Packaged functions compiled with /Zi or /Zd (to add debugging information) are referenced by the compiler. These functions are not removed by /PACKF.

Chapter 15

All references in this chapter to MOVEAPI.TXT now should refer to MOVEAPI.WRI.

Page 601 Linking the Overlaid Program
Add the following paragraphs:

Page 603, Limits and Requirements
Add the following paragraphs:

A p-code program cannot be overlaid.
Virtual functions cannot be placed into overlays.

Chapter 16

Page 610, Syntax Rules
Replace the first sentence in the last syntax rule with the following:

If a string argument matches a reserved word or begins with a character other than a letter of the alphabet or an underscore (_), it must be enclosed in double quotation marks (" ").

Page 611, Reserved Words
LINK recognizes several new reserved words. To see the list of reserved words, choose Build Tools from the Help menu in Visual Workbench and choose Module-Definition File Statements.

Page 623, The EXPORTS Statement
The syntax for the EXPORTS statement accepts the optional keyword PRIVATE. This keyword was described in the file ERRATA1.TXT that was provided with Microsoft C/C++ version 7.0.

Chapter 17

Page 630 EXEHDR Options
The /HELP option now gives the same result as the /? option.

Part 9: Miscellaneous Notes

When you build an overlaid program in Visual Workbench, you must provide a .DEF file that specifies the overlays. If you omit the .DEF file from your project, the development environment does not warn you about the missing file.

You cannot run a 32-bit MS-DOS-extended tool from the MS-DOS shell in CodeView.

Object files created using Microsoft Pascal version 4.0 are not compatible with Microsoft Visual C++ 1.0 or the version of LINK it provides.