home *** CD-ROM | disk | FTP | other *** search
Text File | 1991-03-01 | 1.1 MB | 20,509 lines
Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents. %@1@%Microsoft Codeview and Utilities User's Guide%@EH@% ──────────────────────────────────────────────────────────────────────────── %@AB@%Microsoft(R) CodeView(R) and Utilities User's Guide%@AE@%%@NL@% %@NL@% %@AB@%Version 2.3%@AE@%%@NL@% %@NL@% %@AB@%for MS(R) OS/2 and MS-DOS(R) Operating Systems%@AE@%%@NL@% %@NL@% ──────────────────────────────────────────────────────────────────────────── MICROSOFT CORPORATION%@NL@% %@NL@% Information in this document is subject to change without notice and does not represent a commitment on the part of Microsoft Corporation. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the license or nondisclosure agreement. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the express written permission of Microsoft.%@NL@% %@NL@% (c)Copyright Microsoft Corporation, 1987, 1989. All rights reserved. Simultaneously published in the U.S. and Canada.%@NL@% %@NL@% Printed and bound in the United States of America.%@NL@% %@NL@% Microsoft, MS, MS-DOS, XENIX, and CodeView are registered trademarks of Microsoft Corporation.%@NL@% %@NL@% AT&T is a registered trademark of American Telephone and Telegraph Company.%@NL@% %@NL@% Eagle is a registered trademark of Eagle Computer, Inc.%@NL@% %@NL@% IBM is a registered trademark of International Business Machines Corporation.%@NL@% %@NL@% Intel is a registered trademark of Intel Corporation.%@NL@% %@NL@% Lotus is a registered trademark of Lotus Development Corporation.%@NL@% %@NL@% Tandy is a registered trademark of Tandy Corporation.%@NL@% %@NL@% Document No. LN0801A-500-R00-0889 Part No. 07824 10 9 8 7 6 5 4 3 2 1%@NL@%%@NL@% %@NL@% %@NL@% %@CR:MCVTOC00@%%@1@%%@AB@%Table of Contents%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@AB@%Introduction%@AE@%%@NL@% New Features of the CodeView(R) Debugger%@BO: 655f@%%@NL@% About this Manual%@BO: 6d22@%%@NL@% Document Conventions%@BO: 81a3@%%@NL@% %@NL@% %@AB@%Part 1%@BO: 92c3@% The CodeView Debugger%@AE@%%@NL@% %@NL@% %@AB@%Chapter 1%@BO: 9668@% Getting Started%@AE@%%@NL@% 1.1%@BO: 9a49@% Restrictions%@NL@% 1.2%@BO: a2d0@% The CodeView Environment%@NL@% 1.3%@BO: a4f5@% Preparing Programs for the CodeView Debugger%@NL@% 1.3.1%@BO: ab8b@% Programming Considerations%@NL@% 1.3.2%@BO: b4af@% CodeView Compile Options%@NL@% 1.3.3%@BO: bf17@% CodeView Link Options%@NL@% 1.3.4%@BO: c3f5@% Preparing C Programs%@NL@% 1.3.5%@BO: d503@% Preparing FORTRAN Programs%@NL@% 1.3.6%@BO: e15f@% Preparing BASIC Programs%@NL@% 1.3.7%@BO: ecfc@% Preparing Pascal Programs%@NL@% 1.3.8%@BO: fbcc@% Preparing Assembly Programs%@NL@% 1.4%@BO: 11843@% Starting the CodeView Debugger%@NL@% 1.5%@BO: 136bc@% Using CodeView Options%@NL@% 1.5.1%@BO: 14c56@% Using Two Video Adapters%@NL@% 1.5.2%@BO: 14f4e@% Using the Enhanced Graphics Adapter's 43-Line Mode%@NL@% 1.5.3%@BO: 154dc@% Using 50-Line Mode%@NL@% 1.5.4%@BO: 1590c@% Starting with a Black-and-White Display%@NL@% 1.5.5%@BO: 15ee7@% Specifying Start-Up Commands%@NL@% 1.5.6%@BO: 16a80@% Handling Interrupt Trapping (DOS Only)%@NL@% 1.5.7%@BO: 16f76@% Using Expanded Memory (DOS Only)%@NL@% 1.5.8%@BO: 17480@% Setting the Screen-Exchange Mode (DOS Only)%@NL@% 1.5.9%@BO: 1871d@% Loading Information from Dynamic-Link Libraries (OS/2 Only)%@NL@% 1.5.10%@BO: 18d58@% Turning Off the Mouse%@NL@% 1.5.11%@BO: 193ba@% Debugging Multiple Processes (OS/2 only)%@NL@% 1.5.12%@BO: 19679@% Extending EGA Compatibility%@NL@% 1.5.13%@BO: 19bb9@% Using Debug Registers (386 Only)%@NL@% 1.5.14%@BO: 19f30@% Enabling Window or Sequential Mode%@NL@% 1.6%@BO: 1a79f@% Debugging Large Programs%@NL@% 1.7%@BO: 1ab8d@% Working with Older Versions of the Assembler%@NL@% %@NL@% %@AB@%Chapter 2%@BO: 1b3d8@% The CodeView Display%@AE@%%@NL@% 2.1%@BO: 1b99f@% Using Window Mode%@NL@% 2.1.1%@BO: 1c85a@% Executing Window Commands with the Keyboard%@NL@% 2.1.2%@BO: 20854@% Executing Window Commands with the Mouse%@NL@% 2.1.3%@BO: 23f2f@% Using Menu Selections%@NL@% 2.1.4%@BO: 2bcdf@% Using On-Line Help%@NL@% 2.2%@BO: 2c28f@% Using Sequential Mode%@NL@% %@NL@% %@AB@%Chapter 3%@BO: 2d605@% Using Dialog Commands%@AE@%%@NL@% 3.1%@BO: 2dade@% Entering Commands and Arguments%@NL@% 3.1.1%@BO: 2dcbd@% Using Special Keys%@NL@% 3.1.2%@BO: 2e430@% Using the Command Buffer%@NL@% 3.2%@BO: 2ea51@% Format for CodeView Commands and Arguments%@NL@% 3.3%@BO: 2f609@% Selecting Text for Use with Commands%@NL@% %@NL@% %@AB@%Chapter 4%@BO: 2faf9@% CodeView Expressions%@AE@%%@NL@% 4.1%@BO: 30301@% C Expressions%@NL@% 4.1.1%@BO: 311e5@% C Symbols%@NL@% 4.1.2%@BO: 3174b@% C Constants%@NL@% 4.1.3%@BO: 32144@% C Strings%@NL@% 4.2%@BO: 3244c@% FORTRAN Expressions%@NL@% 4.2.1%@BO: 33079@% FORTRAN Symbols%@NL@% 4.2.2%@BO: 33624@% FORTRAN Constants%@NL@% 4.2.3%@BO: 34042@% FORTRAN Strings%@NL@% 4.2.4%@BO: 34369@% FORTRAN Intrinsic Functions%@NL@% 4.3%@BO: 3515a@% BASIC Expressions%@NL@% 4.3.1%@BO: 35f3f@% BASIC Symbols%@NL@% 4.3.2%@BO: 3628f@% BASIC Constants%@NL@% 4.3.3%@BO: 36fa6@% BASIC Strings%@NL@% 4.3.4%@BO: 37305@% BASIC Intrinsic Functions%@NL@% 4.4%@BO: 37e4e@% Assembly Expressions%@NL@% 4.5%@BO: 3924f@% Line Numbers%@NL@% 4.6%@BO: 39937@% Registers and Addresses%@NL@% 4.6.1%@BO: 39b52@% Registers%@NL@% 4.6.2%@BO: 3a308@% Addresses%@NL@% 4.6.3%@BO: 3ac1e@% Address Ranges%@NL@% 4.7%@BO: 3b6ea@% Memory Operators%@NL@% 4.7.1%@BO: 3bb32@% Accessing Bytes (BY)%@NL@% 4.7.2%@BO: 3c108@% Accessing Words (WO)%@NL@% 4.7.3%@BO: 3c569@% Accessing Double Words (DW)%@NL@% 4.8%@BO: 3cc47@% Switching Expression Evaluators%@NL@% %@NL@% %@AB@%Chapter 5%@BO: 3d63b@% Executing Code%@AE@%%@NL@% 5.1%@BO: 3daa3@% Window and Sequential Mode Commands%@NL@% 5.2%@BO: 3e3a8@% Trace Command%@NL@% 5.3%@BO: 3fb26@% Program Step Command%@NL@% 5.4%@BO: 40cd0@% Go Command%@NL@% 5.5%@BO: 4296f@% Execute Command%@NL@% 5.6%@BO: 4323d@% Restart Command%@NL@% %@NL@% %@AB@%Chapter 6%@BO: 43f5c@% Examining Data and Expressions%@AE@%%@NL@% 6.1%@BO: 44676@% Display Expression Command%@NL@% 6.2%@BO: 48adf@% The Graphic Display Command%@NL@% 6.2.1%@BO: 4922e@% Invoking the Graphic Display Command%@NL@% 6.2.2%@BO: 49b89@% Changing the Display%@NL@% 6.3%@BO: 4a9ef@% Examine Symbols Command%@NL@% 6.4%@BO: 4e3b9@% Dump Commands%@NL@% 6.4.1%@BO: 4f43b@% Dump%@NL@% 6.4.2%@BO: 4f89a@% Dump Bytes%@NL@% 6.4.3%@BO: 4ffa8@% Dump ASCII%@NL@% 6.4.4%@BO: 505cb@% Dump Integers%@NL@% 6.4.5%@BO: 50cc7@% Dump Unsigned Integers%@NL@% 6.4.6%@BO: 51252@% Dump Words%@NL@% 6.4.7%@BO: 51732@% Dump Double Words%@NL@% 6.4.8%@BO: 51cac@% Dump Short Reals%@NL@% 6.4.9%@BO: 523d8@% Dump Long Reals%@NL@% 6.4.10%@BO: 52b0f@% Dump 10-Byte Reals%@NL@% 6.5%@BO: 53254@% Compare Memory Command%@NL@% 6.6%@BO: 53cad@% Search Memory Command%@NL@% 6.7%@BO: 546bf@% Port Input Command%@NL@% 6.8%@BO: 54cca@% Register Command%@NL@% 6.9%@BO: 55d8a@% 8087 Command%@NL@% %@NL@% %@AB@%Chapter 7%@BO: 579f3@% Managing Breakpoints%@AE@%%@NL@% 7.1%@BO: 57fb9@% Breakpoint Set Command%@NL@% 7.2%@BO: 59aec@% Breakpoint Clear Command%@NL@% 7.3%@BO: 5a420@% Breakpoint Disable Command%@NL@% 7.4%@BO: 5ae0f@% Breakpoint Enable Command%@NL@% 7.5%@BO: 5b686@% Breakpoint List Command%@NL@% %@NL@% %@AB@%Chapter 8%@BO: 5c045@% Managing Watch Statements%@AE@%%@NL@% 8.1%@BO: 5c485@% Watch Statement Commands%@NL@% 8.2%@BO: 5ceb8@% Setting Watch-Expression and Watch-Memory Statements%@NL@% 8.3%@BO: 5ebff@% Setting Watchpoints%@NL@% 8.4%@BO: 6059c@% Setting Tracepoints%@NL@% 8.5%@BO: 62b98@% Deleting Watch Statements%@NL@% 8.6%@BO: 63917@% Listing Watchpoints and Tracepoints%@NL@% 8.7%@BO: 6416b@% C Examples%@NL@% 8.8%@BO: 645a6@% FORTRAN Examples%@NL@% 8.9%@BO: 64a01@% Assembly Examples%@NL@% %@NL@% %@AB@%Chapter 9%@BO: 6542b@% Examining Code%@AE@%%@NL@% 9.1%@BO: 6576d@% Set Mode Command%@NL@% 9.2%@BO: 6695d@% Unassemble Command%@NL@% 9.3%@BO: 67eda@% View Command%@NL@% 9.4%@BO: 69705@% Current Location Command%@NL@% 9.5%@BO: 69fb5@% Stack Trace Command%@NL@% %@NL@% %@AB@%Chapter 10%@BO: 6c3f1@% Modifying Code or Data%@AE@%%@NL@% 10.1%@BO: 6c86c@% Assemble Command%@NL@% 10.2%@BO: 6ea96@% Enter Commands%@NL@% 10.2.1%@BO: 707ab@% Enter Command%@NL@% 10.2.2%@BO: 70cc7@% Enter Bytes Command%@NL@% 10.2.3%@BO: 7124c@% Enter ASCII Command%@NL@% 10.2.4%@BO: 7164a@% Enter Integers Command%@NL@% 10.2.5%@BO: 71be1@% Enter Unsigned Integers Command%@NL@% 10.2.6%@BO: 72159@% Enter Words Command%@NL@% 10.2.7%@BO: 7264b@% Enter Double Words Command%@NL@% 10.2.8%@BO: 72ce6@% Enter Short Reals Command%@NL@% 10.2.9%@BO: 732a0@% Enter Long Reals Command%@NL@% 10.2.10%@BO: 73869@% Enter 10-Byte Reals Command%@NL@% 10.3%@BO: 73e3c@% Fill Memory Command%@NL@% 10.4%@BO: 74736@% Move Memory Command%@NL@% 10.5%@BO: 75046@% Port Output Command%@NL@% 10.6%@BO: 75739@% Register Command%@NL@% %@NL@% %@AB@%Chapter 11%@BO: 76d63@% CodeView Control Commands%@AE@%%@NL@% 11.1%@BO: 77201@% Help Command%@NL@% 11.2%@BO: 77713@% Quit Command%@NL@% 11.3%@BO: 77bd5@% Radix Command%@NL@% 11.4%@BO: 78bb2@% Redraw Comm and%@NL@% 11.5%@BO: 78f11@% Screen Exchange Command%@NL@% 11.6%@BO: 79472@% Search Command%@NL@% 11.7%@BO: 7b01d@% Shell Escape Command%@NL@% 11.8%@BO: 7c541@% Tab Set Command%@NL@% 11.9%@BO: 7cc9c@% Option Command%@NL@% 11.10%@BO: 7de27@% Redirection Commands%@NL@% 11.10.1%@BO: 7e1b9@% Redirecting CodeView Input%@NL@% 11.10.2%@BO: 7e758@% Redirecting CodeView Output%@NL@% 11.10.3%@BO: 7f0f6@% Redirecting CodeView Input and Output%@NL@% 11.10.4%@BO: 7f5cc@% Commands Used with Redirection%@NL@% %@NL@% %@AB@%Chapter 12%@BO: 80899@% Debugging in Protected Mode%@AE@%%@NL@% 12.1%@BO: 80e8a@% Using CodeView in Different Modes%@NL@% 12.2%@BO: 81470@% Debugging Dynamic-Link Libraries%@NL@% 12.3%@BO: 81b5e@% Debugging Multiple Processes%@NL@% 12.3.1%@BO: 828e2@% Viewing Status%@NL@% 12.3.2%@BO: 82cea@% Switching to a Child Process%@NL@% 12.4%@BO: 831dd@% Debugging Multiple Threads%@NL@% 12.5%@BO: 83f8a@% The Thread Command%@NL@% 12.5.1%@BO: 845f9@% Legal Values for Specifier%@NL@% 12.5.2%@BO: 84d1b@% Legal Values for yCommand%@NL@% 12.5.3%@BO: 86567@% Entries to the Thread Command%@NL@% 12.5.4%@BO: 86f50@% Effect of Threads on CodeView Commands%@NL@% %@NL@% %@AB@%Part 2%@BO: 87cd5@% Utilities%@AE@%%@NL@% %@NL@% %@AB@%Chapter 13%@BO: 8801e@% Linking Object Files with LINK%@AE@%%@NL@% 13.1%@BO: 88409@% Determining Linker Output%@NL@% 13.2%@BO: 88fe5@% Specifying Files for Linking%@NL@% 13.2.1%@BO: 892c3@% Specifying File Names%@NL@% 13.2.2%@BO: 89934@% Linking with the LINK Command Line%@NL@% 13.2.3%@BO: 8baf9@% Linking with the LINK Prompts%@NL@% 13.2.4%@BO: 8c8b2@% Linking with a Response File%@NL@% 13.2.5%@BO: 8d60c@% How LINK Searches for Libraries%@NL@% 13.2.6%@BO: 8ebda@% LINK Memory Requirements%@NL@% 13.3%@BO: 8f69e@% Specifying Linker Options%@NL@% 13.3.1%@BO: 900cf@% Aligning Segment Data (/A)%@NL@% 13.3.2%@BO: 903ae@% Running in Batch Mode (/BA)%@NL@% 13.3.3%@BO: 9093f@% Producing a .COM File (/BI)%@NL@% 13.3.4%@BO: 90dce@% Preparing for Debugging (/CO)%@NL@% 13.3.5%@BO: 910e0@% Setting the Maximum Allocation Space (/CP)%@NL@% 13.3.6%@BO: 91a23@% Ordering Segments (/DO)%@NL@% 13.3.7%@BO: 92097@% Controlling Data Loading (/DS)%@NL@% 13.3.8%@BO: 92560@% Packing Executable Files (/E)%@NL@% 13.3.9%@BO: 92ae0@% Optimizing Far Calls (/F)%@NL@% 13.3.10%@BO: 938d1@% Viewing the Options List (/HE)%@NL@% 13.3.11%@BO: 93a86@% Controlling Executable-File Loading (/HI)%@NL@% 13.3.12%@BO: 93dca@% Preparing for Incremental Linking (/INC)%@NL@% 13.3.13%@BO: 94034@% Displaying Linker Process Information (/INF)%@NL@% 13.3.14%@BO: 94620@% Including Line Numbers in the Map File (/LI)%@NL@% 13.3.15%@BO: 94a90@% Listing Public Symbols (/M)%@NL@% 13.3.16%@BO: 94e75@% Ignoring Default Libraries (/NOD)%@NL@% 13.3.17%@BO: 9516c@% Ignoring Extended Dictionary (/NOE)%@NL@% 13.3.18%@BO: 95405@% Disabling Far-Call Optimization (/NOF)%@NL@% 13.3.19%@BO: 95617@% Preserving Compatibility (/NOG)%@NL@% 13.3.20%@BO: 95967@% Preserving Case Sensitivity (/NOI)%@NL@% 13.3.21%@BO: 95ce4@% Ordering Segments without Inserting NULL Bytes (/NON)%@NL@% 13.3.22%@BO: 96061@% Disabling Segment Packing (/NOP)%@NL@% 13.3.23%@BO: 9624f@% Setting the Overlay Interrupt (/O)%@NL@% 13.3.24%@BO: 9661b@% Packing Contiguous Data Segments (/PACKC)%@NL@% 13.3.25%@BO: 97257@% Packing Contiguous Data Segments (/PACKD)%@NL@% 13.3.26%@BO: 978cc@% Padding Code Segments (/PADC)%@NL@% 13.3.27%@BO: 97ed1@% Padding Data Segments (/PADD)%@NL@% 13.3.28%@BO: 98338@% Pausing during Linking (/PAU)%@NL@% 13.3.29%@BO: 989e6@% Specifying User Libraries for Quick Languages (/Q)%@NL@% 13.3.30%@BO: 99437@% Setting Maximum Number of Segments (/SE)%@NL@% 13.3.31%@BO: 99af7@% Controlling Stack Size (/ST)%@NL@% 13.3.32%@BO: 9a01d@% Issuing Fixup Warnings (/W)%@NL@% 13.4%@BO: 9a2d0@% Selecting Options with the LINK Environment Variable%@NL@% 13.5%@BO: 9aae1@% Linker Operation%@NL@% 13.5.1%@BO: 9b071@% Alignment of Segments%@NL@% 13.5.2%@BO: 9b3d5@% Frame Number%@NL@% 13.5.3%@BO: 9b908@% Order of Segments%@NL@% 13.5.4%@BO: 9bb53@% Combined Segments%@NL@% 13.5.5%@BO: 9c3d0@% Groups%@NL@% 13.5.6%@BO: 9c7e0@% Fixups%@NL@% 13.6%@BO: 9d599@% Using Overlays%@NL@% 13.6.1%@BO: 9de28@% Restrictions on Overlays%@NL@% 13.6.2%@BO: 9e0bd@% Overlay-Manager Prompts%@NL@% %@NL@% %@AB@%Chapter 14%@BO: 9eada@% Incremental Linking with ILINK%@AE@%%@NL@% 14.1%@BO: 9f091@% Definitions%@NL@% 14.2%@BO: 9fa9a@% Guidelines for Using ILINK%@NL@% 14.3%@BO: a037d@% The Development Process%@NL@% 14.4%@BO: a0a6e@% Running ILINK%@NL@% 14.4.1%@BO: a0bd3@% Files Required for Using ILINK%@NL@% 14.4.2%@BO: a0ebd@% The ILINK Command Line%@NL@% 14.5%@BO: a197b@% How ILINK Works%@NL@% 14.6%@BO: a1dad@% Incremental Violations%@NL@% 14.6.1%@BO: a20bd@% Changing Libraries%@NL@% 14.6.2%@BO: a239b@% Exceeding Code/Data Padding%@NL@% 14.6.3%@BO: a25ce@% Moving/Deleting Data Symbols%@NL@% 14.6.4%@BO: a2719@% Deleting Code Symbols%@NL@% 14.6.5%@BO: a285b@% Changing Segment Definitions%@NL@% 14.6.6%@BO: a2a56@% Adding CodeView Debugger Information%@NL@% %@NL@% %@AB@%Chapter 15%@BO: a2cc3@% Managing Libraries with LIB%@AE@%%@NL@% 15.1%@BO: a348c@% Managing Libraries%@NL@% 15.1.1%@BO: a39b0@% Managing Libraries with the LIB Command Line%@NL@% 15.1.2%@BO: a74a1@% Managing Libraries with the LIB Prompts%@NL@% 15.1.3%@BO: a8274@% Managing Libraries with a Response File%@NL@% 15.1.4%@BO: a8c44@% Terminating the LIB Session%@NL@% 15.2%@BO: a8e05@% Performing Library-Management Tasks with LIB%@NL@% 15.2.1%@BO: a99e2@% Creating a Library File%@NL@% 15.2.2%@BO: aa066@% Changing a Library File%@NL@% 15.2.3%@BO: aa52d@% Adding Library Modules%@NL@% 15.2.4%@BO: aa89f@% Deleting Library Modules%@NL@% 15.2.5%@BO: aaa81@% Replacing Library Modules%@NL@% 15.2.6%@BO: aad0d@% Copying Library Modules%@NL@% 15.2.7%@BO: aafe3@% Moving Library Modules (Extracting)%@NL@% 15.2.8%@BO: ab138@% Combining Libraries%@NL@% 15.2.9%@BO: ab7b3@% Creating a Cross-Reference-Listing File%@NL@% 15.2.10%@BO: abc5d@% Performing Consistency Checks%@NL@% 15.2.11%@BO: abfb6@% Setting the Library-Page Size%@NL@% %@NL@% %@AB@%Chapter 16%@BO: ac80b@% NMAKE%@AE@%%@NL@% 16.1%@BO: acda3@% Invoking NMAKE%@NL@% 16.1.1%@BO: acf89@% Using a Command Line to Invoke NMAKE%@NL@% 16.1.2%@BO: ad98e@% Using a Command File to Invoke NMAKE%@NL@% 16.2%@BO: adfed@% NMAKE Options%@NL@% 16.3%@BO: af1b7@% Description Files%@NL@% 16.3.1%@BO: af441@% Description Blocks%@NL@% 16.3.2%@BO: b1bf8@% Macros%@NL@% 16.3.3%@BO: b4fe0@% Inference Rules%@NL@% 16.3.4%@BO: b66d0@% Directives%@NL@% 16.3.5%@BO: b8373@% Pseudotargets%@NL@% 16.4%@BO: b921d@% Response-File Generation%@NL@% 16.5%@BO: b992f@% Differences between NMAKE and MAKE%@NL@% %@NL@% %@AB@%Chapter 17%@BO: ba564@% Using Other Utilities%@AE@%%@NL@% 17.1%@BO: ba961@% Modifying Program Headers with the EXEMOD Utility%@NL@% 17.2%@BO: bd180@% Enlarging the DOS Environment with the SETENV Utility%@NL@% 17.3%@BO: bdfa9@% Saving Memory with the CVPACK Utility%@NL@% %@NL@% %@AB@%Chapter 18%@BO: be41d@% Linking for Windows and OS/2 Systems%@AE@%%@NL@% 18.1%@BO: be78c@% Dynamic-Link Libraries%@NL@% 18.2%@BO: bef80@% Linking without an Import Library%@NL@% 18.3%@BO: bf4f0@% Linking with an Import Library%@NL@% 18.4%@BO: bff48@% Why Use Import Libraries?%@NL@% 18.5%@BO: c05f4@% Advantages of Dynamic Linking%@NL@% 18.6%@BO: c0e10@% Creating Import Libraries with IMPLIB%@NL@% %@NL@% %@AB@%Chapter 19%@BO: c14f2@% Using Module-Definition Files%@AE@%%@NL@% 19.1%@BO: c16f2@% Module Statements%@NL@% 19.2%@BO: c249b@% The NAME Statement%@NL@% 19.3%@BO: c312c@% The LIBRARY Statement%@NL@% 19.4%@BO: c3a0a@% The DESCRIPTION Statement%@NL@% 19.5%@BO: c3e7c@% The CODE Statement%@NL@% 19.6%@BO: c53df@% The DATA Statement%@NL@% 19.7%@BO: c7332@% The SEGMENTS Statement%@NL@% 19.8%@BO: c914d@% The STACKSIZE Statement%@NL@% 19.9%@BO: c9500@% The EXPORTS Statement%@NL@% 19.10%@BO: ca38e@% The IMPORTS Statement%@NL@% 19.11%@BO: cb223@% The STUB Statement%@NL@% 19.12%@BO: cb722@% The HEAPSIZE Statement%@NL@% 19.13%@BO: cbc65@% The PROTMODE Statement%@NL@% 19.14%@BO: cbf52@% The OLD Statement%@NL@% 19.15%@BO: cc3a4@% The REALMODE Statement%@NL@% 19.16%@BO: cc64c@% The EXETYPE Statement%@NL@% %@NL@% %@AB@%Chapter 20%@BO: ccaeb@% Creating Dual-Mode Programs with BIND%@AE@%%@NL@% 20.1%@BO: cd327@% Binding Library Routines%@NL@% 20.2%@BO: cd791@% Binding Functions as Protected Mode Only%@NL@% 20.3%@BO: cddc2@% The BIND Command Line%@NL@% 20.4%@BO: ceb6c@% BIND Operation%@NL@% 20.5%@BO: cf15a@% Executable-File Layout%@NL@% 20.6%@BO: cf376@% How to Build a Dual-Mode Application%@NL@% %@NL@% %@AB@%Chapter 21%@BO: cf974@% Using EXEHDR%@AE@%%@NL@% 21.1%@BO: cfd99@% The EXEHDR Command Line%@NL@% 21.2%@BO: d003c@% EXEHDR Output%@NL@% 21.3%@BO: d13d9@% Output in Verbose Mode%@NL@% %@NL@% %@AB@%Appendix A Regular Expressions%@BO: d21a7@%%@AE@%%@NL@% A.1%@BO: d260f@% Special Characters in Regular Expressions%@NL@% A.2%@BO: d2e49@% Searching for Special Characters%@NL@% A.3%@BO: d3194@% Using the Period%@NL@% A.4%@BO: d3594@% Using Brackets%@NL@% A.4.1%@BO: d39c0@% Using the Dash within Brackets%@NL@% A.4.2%@BO: d3f77@% Using the Caret within Brackets%@NL@% A.4.3%@BO: d425c@% Matching Brackets within Brackets%@NL@% A.5%@BO: d4612@% Using the Asterisk%@NL@% A.6%@BO: d4e5b@% Matching the Start or End of a Line%@NL@% %@NL@% %@AB@%Appendix B Using Exit Codes%@BO: d5161@%%@AE@%%@NL@% B.1%@BO: d531e@% Exit Codes with NMAKE%@NL@% B.2%@BO: d583b@% Exit Codes with DOS Batch Files%@NL@% B.3%@BO: d5d29@% Exit Codes for Programs%@NL@% B.3.1%@BO: d5edc@% LINK Exit Codes%@NL@% B.3.2%@BO: d61d5@% LIB Exit Codes%@NL@% B.3.3%@BO: d646e@% NMAKE Exit Codes%@NL@% B.3.4%@BO: d666d@% EXEMOD and SETENV Exit Codes%@NL@% B.3.5%@BO: d690c@% CVPACK Exit Codes%@NL@% %@NL@% %@AB@%Appendix C Error Messages%@BO: d6a72@%%@AE@%%@NL@% C.1%@BO: d6b19@% CodeView Error Messages%@NL@% C.2%@BO: ddc92@% LINK Error Messages%@NL@% C.2.1%@BO: de32b@% LINK Fatal Error Messages%@NL@% C.2.2%@BO: e43a2@% LINK Nonfatal Error Messages%@NL@% C.2.3%@BO: e7025@% LINK Warning Messages%@NL@% C.3%@BO: ea5df@% ILINK Error Messages%@NL@% C.3.1%@BO: eac72@% ILINK Fatal Errors%@NL@% C.3.2%@BO: edd18@% Incremental Violations%@NL@% C.3.3%@BO: ef6d9@% ILINK Warning Messages%@NL@% C.4%@BO: efccf@% LIB Error Messages%@NL@% C.4.1%@BO: f0080@% Fatal LIB Error Messages%@NL@% C.4.2%@BO: f2164@% Nonfatal LIB Error Messages%@NL@% C.4.3%@BO: f2727@% Warning LIB Error Messages%@NL@% C.5%@BO: f307a@% NMAKE Error Messages%@NL@% C.5.1%@BO: f3337@% Fatal NMAKE Error Messages%@NL@% C.5.2%@BO: f6e78@% Warning NMAKE Error Messages%@NL@% C.6%@BO: f78cf@% EXEMOD Error Messages%@NL@% C.6.1%@BO: f7c31@% Fatal EXEMOD Error Messages%@NL@% C.6.2%@BO: f8448@% Warning EXEMOD Error Messages%@NL@% C.7%@BO: f88fb@% SETENV Error Messages%@NL@% %@NL@% %@AB@%Glossary%@BO: f9323@%%@AE@%%@NL@% %@NL@% %@AB@%Index%@BO: 102fa5@%%@AE@%%@NL@% %@NL@% %@AB@%Tables%@AE@% Table 1.1%@BO: 17dc5@% Default Exchange and Display Modes%@NL@% Table 4.1%@BO: 3059b@% CodeView C Expression Operators%@NL@% Table 4.2%@BO: 31fd3@% C Radix Examples%@NL@% Table 4.3%@BO: 32771@% CodeView FORTRAN Operators%@NL@% Table 4.4%@BO: 33ebd@% FORTRAN Radix Examples%@NL@% Table 4.5%@BO: 345f7@% FORTRAN Intrinsic Functions Supported by the CodeView Debugger%@NL@% Table 4.6%@BO: 3530b@% CodeView BASIC Operators%@NL@% Table 4.7%@BO: 36e23@% BASIC Radix Examples%@NL@% Table 4.8%@BO: 3752b@% BASIC Intrinsic Functions Supported by the CodeView Debugger%@NL@% Table 4.9%@BO: 3a08b@% Registers%@NL@% Table 6.1%@BO: 44e7b@% CodeView Format Specifiers%@NL@% Table 10.1%@BO: 7655d@% Flag-Value Mnemonics%@NL@% Table 16.1%@BO: b6044@% Predefined Inference Rules%@NL@% %@NL@% %@NL@% %@CR:MCV00000@%%@1@%%@AB@%Introduction%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV00001@%%@4@%Welcome to the Microsoft(R) CodeView(R) debugger and development utilities.%@EH@% These are executable programs that help you develop software written with the Microsoft BASIC, C, FORTRAN, and Pascal compilers, as well as with the Microsoft Macro Assembler.%@NL@% %@NL@% %@CR:MCV00002@%%@4@%The Microsoft CodeView debugger is a powerful, window-oriented tool that%@EH@% enables you to track down logical errors in programs; it allows you to analyze a program as the program is actually running. The CodeView debugger will display source code or assembly code, indicate which line is about to be executed, dynamically watch the values of variables (local or global), switch screens to display program output, and perform many other related functions. The debugger can be easily learned and used by assembly and high-level-language programmers alike.%@NL@% %@NL@% %@CR:MCV00003@%%@4@%The utilities are important at various stages of software development. After%@EH@% you use a compiler or assembler to produce one or more object files, use LINK to produce an executable file. (When a program is made into an executable file, it is finally in the form that can be loaded and executed by DOS.) In the process of linking, you may use software libraries. The LIB utility enables you to create, examine, and maintain these libraries. The process of compiling and linking can be automated──to a large degree──with the MAKE utility; MAKE keeps track of which source files have been changed, and then executes just the commands necessary to update the program.%@NL@% %@NL@% %@CR:MCV00004@%%@4@%Other utilities help you maintain executable files once they have been%@EH@% created. You can use EXEMOD to examine or modify the file's header. The executable-file header indicates stack size, load size, and other important items used by DOS each time it executes the file.%@NL@% %@NL@% %@CR:MCV00005@%%@4@%Finally, you can use the SETENV and ERROUT utilities to modify the DOS%@EH@% environment itself.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Microsoft documentation uses the term "OS/2" to refer to the OS/2 systems──Microsoft(R) OperatingSystem/2 (MS(R) OS/2) and IBM(R) OS/2. Similarly, the term "DOS" refers to both the MS-DOS(R) and IBM Personal Computer DOS operating systems. The name of a specific operating system is used when it is necessary to note features that are unique to that system.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV01000@%%@2@%%@AB@%New Features of the CodeView(R) Debugger%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV01001@% ■ Structure, pointer, and array display%@NL@% %@NL@% A new dialog box supports visual display of structures and arrays. Each%@NL@% member or element is displayed. You can also use this dialog box to%@NL@% examine local variables and nested structures and to trace pointer%@NL@% references.%@NL@% %@NL@% ■ Multilanguage expression evaluation%@NL@% %@NL@% The CodeView debugger has a built-in language interpreter that can%@NL@% evaluate either C, BASIC, or FORTRAN expressions.%@NL@% %@NL@% ■ 386 support%@NL@% %@NL@% The CodeView debugger now supports debugging of code written%@NL@% specifically for the 386 processor. You can now decode and assemble 386%@NL@% instructions, as well as view 386 registers.%@NL@% %@NL@% ■ Expanded memory support%@NL@% %@NL@% If you have expanded memory, you can substantially reduce the amount of%@NL@% main memory required to debug a program. Many programs that were%@NL@% previously too large can now be run with the CodeView debugger.%@NL@% %@NL@% ■ 8087 emulator support%@NL@% %@NL@% If you do not have an 8087 coprocessor in your machine, you can link to%@NL@% a Microsoft emulator library and take advantage of the 7 command. The%@NL@% debugger will display pseudo-8087 registers, as if you did have a math%@NL@% coprocessor in your machine.%@NL@% %@NL@% ■ Overlays and library modules%@NL@% %@NL@% The debugger is now fully compatible with programs that use overlays.%@NL@% You can also debug library modules.%@NL@% %@NL@% ■ New commands%@NL@% %@NL@% The SYMDEB (symbolic debugger) commands──Compare, Fill, Move, Input,%@NL@% and Output──have been added to the CodeView debugger's repertoire. The%@NL@% Option command provides more power for redirected input and start-up%@NL@% commands.%@NL@% %@NL@% %@NL@% %@CR:MCV02000@%%@2@%%@AB@%About this Manual%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV02001@%%@4@%This manual is intended as a companion volume to Microsoft language manuals.%@EH@% It is not language specific, except where examples are required; and in those cases, examples from several languages are typically given.%@NL@% %@NL@% %@CR:MCV02002@%%@4@%The manual is divided into two parts, followed by appendixes: Part 1%@EH@% (chapters 1-12) explains how to use the CodeView debugger to examine and locate program errors; Part 2 (chapters 13-21) explains how to use each of the utilities, including LINK, ILINK, LIB, NMAKE, EXEMOD, SETENV, and BIND. The appendixes at the end of the manual discuss exit codes and error messages for the CodeView debugger and all the utilities.%@NL@% %@NL@% %@CR:MCV02003@%%@4@%The following list indicates where to find different kinds of information in%@EH@% the manual. The list is by no means exhaustive, but is intended to serve as a starting place, particularly for the new user of the CodeView debugger.%@NL@% %@NL@% %@CR:MCV02004@%%@NL@% %@TH: 81 3727 2 28 49 @%%@AB@%Information Location%@AE@%%@EH@%Examining and locating Part 1%@BO: 92c3@% (chapters 1-12), "The CodeView Debugger,"program errors describes methods to help you track down errors in a program and analyze it while it runs. Exit codes and error messages are discussed in the appendixes at the back of this manual.Starting a debugging Chapter 1%@BO: 9668@%, "Getting Started," tells you howsession to compile and link programs so that you can run them with the debugger. It also explains each CodeView command-line option.Using the CodeView Chapter 2%@BO: 1b3d8@%, "The CodeView Display," describesinterface how to use the CodeView windows, pop-up menus, and the mouse.Specifying the CodeView Chapter 3%@BO: 2d605@%, "Using Dialog Commands," presents thecommands general form of commands, while Chapter 4%@BO: 2faf9@%, "CodeView Expressions," describes how to build complex expressions for use in commands.Controlling execution Chapter 5%@BO: 3d63b@%, "Executing Code," explains the basicsof your program of controlling program execution with the CodeView debugger; Chapter 7%@BO: 579f3@%, "Managing Breakpoints," explains how to use breakpoints to suspend execution.Watching the value of Chapter 6%@BO: 43f5c@%, "Examining Data and Expressions,"variables or shows how to display values; Chapter 8%@BO: 5c045@%,expressions "Managing Watch Statements," shows how to place variables in a window where you can watch their values change as the program runs.Using the utilities Part 2%@BO: 87cd5@% (chapters 13-21), "Utilities," describes the various utilities for producing and maintaining executable files, and for other tasks. Exit codes and error messages for the utilities are discussed in the appendixes at the back of this manual.Creating executable Chapter 13%@BO: 8801e@%, "Linking Object Files with LINK."filesUsing the incremental Chapter 14%@BO: 9eada@%, "Incremental Linking with ILINK."linker for fasterlinkingManaging software Chapter 15%@BO: a2cc3@%, "Managing Libraries with LIB."librariesAutomating projects Chapter 16%@BO: ac80b@%, "NMAKE."that have severalmodulesUsing EXEMOD, SETENV, Chapter 17%@BO: ba564@%, "Using Other Utilities."and CVPACKDynamic linking under Chapter 18%@BO: be41d@%, "Linking for Windows and OS/2OS/2 Systems."Module-definition Chapter 19%@BO: c14f2@%, "Using Module-Definition Files."statementsBinding programs to run Chapter 20%@BO: ccaeb@%, "Creating Dual-Mode Programs withunder both protected BIND."mode and real modeViewing the contents of Chapter 21%@BO: cf974@%, "Using EXEHDR."a segmented .EXE fileheaderSpecifying expressions Appendix A%@BO: d21a7@%, "Regular Expressions."for the CodeView SearchcommandCodes returned to DOS Appendix B%@BO: d5161@%, "Exit Codes."by each utilityA list of error Appendix C%@BO: d6a72@%, "Error Messages."messages%@TE: 81 3727 2 28 49 @% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%Important%@AE@%%@NL@% There may be additional information about the CodeView debugger in the%@NL@% %@AB@%README.DOC file.%@AE@% This file will describe changes made to the program%@NL@% after the manual was printed.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV03000@%%@2@%%@AB@%Document Conventions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV03001@%%@4@%The following document conventions are used throughout this manual and apply%@EH@% in particular to syntax displays.%@NL@% %@NL@% %@CR:MCV03002@%%@NL@% %@TH: 69 4014 2 28 49 @%%@AB@%Example Description%@AE@%%@AB@%BP%@AE@% %@AB@%Boldface type%@AE@% always marks standard features of either programming languages (keywords, operators, and functions) or CodeView sequential-mode commands. These terms and punctuation marks must be typed exactly as shown in order to have effect. However, the use of uppercase or lowercase letters is not always significant. Case-sensitive terms are noted in text.%@AI@%number%@AE@% %@AI@%Placeholders%@AE@% are words in italics that indicate a general kind of information; you are expected to provide the actual value. For example, consider the syntax display for the CodeView Radix command: %@AB@%N%@AE@%%@AI@%number%@AE@% This syntax display asks that you enter the Radix command by typing %@AS@%N%@AE@%, immediately followed by some value for %@AI@%number%@AE@%. You could, for example, type in the entry %@AS@%N8%@AE@%; but you could not legally type in the word "number" itself.%@AS@%Word Ptr%@AE@% %@AS@%This font%@AE@% is used to indicate all example programs, user input, and screen output.Program . . . Fragment A column of three dots tells you part of a program has been intentionally omitted.%@AS@%«%@AI@%optional items%@AE@%» Double brackets enclose optional fields in command-line and option syntax. Consider the following command-line syntax: %@AB@%R%@AE@% «%@AI@%register%@AE@%» ««=»%@AI@%value%@AE@%» The double brackets around the placeholders indicate that you may enter a %@AI@%register%@AE@% and you may enter a %@AI@%value%@AE@%. The equal sign (=) indicates that you may place an equal sign before the %@AI@%value%@AE@%, but only if you specify a %@AI@%value%@AE@%.«%@AI@%choice1%@AE@% | %@AI@%choice2%@AE@%» The vertical bar indicates that you may enter one of the entries shown on either side of the bar. The following command-line syntax illustrates the use of a vertical bar: %@AB@%DB%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%» The bar indicates that following the Dump Bytes command (%@AB@%DB%@AE@%), you can specify either an %@AI@%address%@AE@% or %@AI@%range%@AE@%. Since both are in double brackets, you can also give the command with no argument."Watch point" The first time a new term is defined, it is enclosed in quotation marks.ALT Small capital letters are used for the names of keys and key sequences, such as ENTER, CTRL+C, and ALT+F.Sample screens Sample screens are shown in black and white. Your screens will look like this if you have a monochrome monitor, or if you use the /B option in the CodeView command line (see Section 1.5.4%@BO: 1590c@%, "Starting with a Black-and-White Display").%@TE: 69 4014 2 28 49 @% %@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@CR:MCVP1000@%%@1@%%@AB@%Part 1 The CodeView Debugger%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVP1003@%%@4@%Part 1 explains the use of the CodeView debugger. Commands, display, and%@EH@% interface of the debugger are presented here, while other material relevant to the debugger such as error messages and exit codes is presented in the Appendixes.%@NL@% %@NL@% %@CR:MCVP1004@%%@4@%Chapter 1%@BO: 9668@% explains how to create a C, Fortran, BASIC, Pascal or assembly%@EH@% program that can be run with CodeView; it also explains how to start the debugger and select various command-line options.%@NL@% %@NL@% %@CR:MCVP1005@%%@4@%Chapter 2%@BO: 1b3d8@% discusses the CodeView display screen and interface, including%@EH@% function keys, keyboard commands, and the mouse.%@NL@% %@NL@% %@CR:MCVP1006@%%@4@%Chapters 3%@BO: 2d605@%-12 of Part 1 describe how to use each of the CodeView commands%@EH@% and expressions.%@NL@% %@NL@% %@NL@% %@CR:MCV10000@%%@1@%%@AB@%Chapter 1 Getting Started%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV10001@%%@4@%Getting started with the CodeView debugger requires several simple steps.%@EH@% First you must prepare a special-format executable file for the program you wish to debug; then you can invoke the debugger. You may also wish to specify options that will affect the debugger's operation.%@NL@% %@NL@% %@CR:MCV10002@%%@4@%This chapter describes how to produce executable files in the CodeView%@EH@% format using C, FORTRAN, BASIC, Pascal, or assembly language and describes how to load a program into the CodeView debugger. The chapter lists restrictions and programming considerations with regard to the debugger, which you may want to consult before compiling or assembling. Finally, the chapter describes how to use the debugger with Microsoft or IBM Macro Assembler, Versions 1.0 through 4.0.%@NL@% %@NL@% %@NL@% %@CR:MCV11000@%%@2@%%@AB@%1.1 Restrictions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV11001@%%@4@%This list describes files that are not directly supported by the debugger.%@EH@% The following restrictions apply generally to the use of the CodeView debugger, regardless of the language being used.%@NL@% %@NL@% %@AB@%Restriction Explanation%@AE@%%@NL@% %@NL@% Include files You will not be able to use the CodeView%@NL@% debugger to debug source code in include files.%@NL@% %@NL@% Packed files CodeView symbolic information cannot be put into%@NL@% a packed file.%@NL@% %@NL@% .COM files Files with the extension .COM can be debugged in%@NL@% assembly mode only; they can never contain%@NL@% symbolic information.%@NL@% %@NL@% Memory-resident The CodeView debugger can only work with%@NL@% programs disk-resident .EXE and .COM files. Debugging of%@NL@% memory-resident files is not supported.%@NL@% %@NL@% Programs that alter the Programs that run under the CodeView debugger%@NL@% environment can read the DOS environment, but they cannot%@NL@% permanently change it. Upon exit from CodeView,%@NL@% all changes to the environment are lost.%@NL@% %@NL@% Program Segment Prefix The CodeView debugger automatically preprocesses%@NL@% (PSP) a program's PSP the same way a C program does;%@NL@% quote marks are removed, and exactly one space%@NL@% is left between command-line arguments. This%@NL@% preprocessing only creates a problem if you are%@NL@% debugging a program not written in C──one that%@NL@% tries to access command-line arguments.%@NL@% %@NL@% %@CR:MCV11003@%%@4@%Some of the features now allowed by CodeView include debugging of library%@EH@% modules and debugging of overlaid code.%@NL@% %@NL@% %@NL@% %@CR:MCV12000@%%@2@%%@AB@%1.2 The CodeView Environment%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV12001@%%@4@%Work with CodeView can be optimized in several ways.%@EH@%%@NL@% %@NL@% %@CR:MCV12002@%%@4@%The CVPACK utility compresses CodeView information in an executable file.%@EH@% See Section 17.4%@BO: bdfa9@% for directions on how to use CVPACK.%@NL@% %@NL@% %@CR:MCV12003@%%@4@%In addition, the /E option enables CodeView to take advantage of expanded%@EH@% memory. Command-line options are described in Section 1.5%@BO: 136bc@%.%@NL@% %@NL@% %@NL@% %@CR:MCV13000@%%@2@%%@AB@%1.3 Preparing Programs for the CodeView Debugger%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13001@%%@4@%You must compile and link with the correct options in order to use a program%@EH@% with the CodeView debugger. These options direct the compiler and the linker to produce an executable file, which contains line-number information and a symbol table, in addition to the executable code.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% For the sake of brevity, Sections 1.3.1%@BO: ab8b@%-1.3.3 use the term "compiling"%@NL@% to refer to the process of producing object modules. However, almost%@NL@% everything said about compiling in this section applies equally well to%@NL@% assembling. Exceptions are noted in Section 1.3.8%@BO: fbcc@%, "Preparing Assembly%@NL@% Programs."%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV13002@%%@4@%Not all compiler and linker versions support CodeView options. (See the%@EH@% section on the appropriate language below for information about compiler versions.) Also, you will need to use the Microsoft Overlay Linker (Version 3.6 or later) or the Microsoft Segmented-Executable Linker. If you try to debug an executable file that was not compiled and linked with CodeView options, or if you use a compiler that does not support these options, then you will only be able to use the debugger in assembly mode. This means the CodeView debugger will not be able to display source code or understand source-level symbols, such as symbols for functions and variables.%@NL@% %@NL@% %@NL@% %@CR:MCV13100@%%@3@%%@AB@%1.3.1 Programming Considerations%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13101@%%@4@%Any source code that is legal in C, FORTRAN, BASIC, Pascal, or Microsoft%@EH@% Macro Assembler can be compiled or assembled to create an executable file and then debugged with the CodeView debugger. However, some programming practices make debugging more difficult.%@NL@% %@NL@% %@CR:MCV13102@%%@4@%Each of the Microsoft languages listed above permits you to put code in%@EH@% separate include files and read the files into your source file by using an include directive. However, you will not be able to use the CodeView debugger to debug source code in include files. The preferred method of developing programs is to create separate object modules and then link the object modules with your program. The CodeView debugger supports the debugging of separate object modules in the same session.%@NL@% %@NL@% %@CR:MCV13103@%%@4@%Also, the CodeView debugger is more effective and easier to use if you put%@EH@% each source statement on a separate line. A number of languages (C and BASIC in particular) permit you to place more than one statement on a single line of the source file. This practice does not prevent the CodeView debugger from functioning. However, the debugger must treat the line as a single unit; it cannot break the line down into separate statements. Therefore, if you have three statements on the same line, you will not be able to put a breakpoint or freeze execution on the individual statements. The best you will be able to do is to freeze execution at the beginning of the three statements or at the beginning of the next line.%@NL@% %@NL@% %@CR:MCV13104@%%@4@%Some languages (C and assembly in particular) support a type of macro%@EH@% expansion. However, the CodeView debugger will not help you debug macros in source mode. You will need to expand the macros yourself before debugging them; otherwise, the debugger will treat them as simple statements or instructions.%@NL@% %@NL@% %@CR:MCV13105@%%@4@%Finally, your segments should be declared according to the standard%@EH@% Microsoft format (as described in the %@AI@%Microsoft Mixed-Language%@AE@% %@AI@%Programming%@AE@% %@AI@%Guide%@AE@%). This is taken care of for you automatically with each of the Microsoft high-level languages.%@NL@% %@NL@% %@NL@% %@CR:MCV13200@%%@3@%%@AB@%1.3.2 CodeView Compile Options%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13201@%%@4@%Microsoft compilers accept command-line options preceded by either a forward%@EH@% slash (/) or a dash (-). For brevity, this manual lists only the forward slash when describing options, but you may use either symbol.%@NL@% %@NL@% %@CR:MCV13202@%%@4@%The use of uppercase or lowercase letters is significant for options used%@EH@% with the C, FORTRAN, BASIC, and Pascal compilers; you must type the letters exactly as given.%@NL@% %@NL@% %@CR:MCV13203@%%@4@%When you compile a source file for a program you want to debug, you must%@EH@% specify the /Zi option on the command line. The /Zi option instructs the compiler to include line-number and symbolic information in the object file.%@NL@% %@NL@% %@CR:MCV13204@%%@4@%If you do not need complete symbolic information in some modules, you can%@EH@% compile those modules with the /Zd option instead of /Zi. The /Zd option writes less symbolic information to the object file, so using this option will save disk space and memory. For example, if you are working on a program made up of five modules, but only need to debug one module, you can compile that module with the /Zi option and the other modules with the /Zd option. You will be able to examine global variables and see source lines in modules compiled with the /Zd option, but local variables will be unavailable.%@NL@% %@NL@% %@CR:MCV13205@%%@4@%In addition, if you are working with a high-level language, you will%@EH@% probably want to use the /Od option, which turns off optimization. Optimized code may be rearranged for greater efficiency and, as a result, the instructions in your program may not correspond closely to the source lines. After debugging, you can compile a final version of the program with the optimization level you prefer.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The %@AB@%/Zd%@AE@% option is not available with QuickBASIC. The %@AB@%/Od%@AE@% option is not%@NL@% available with QuickBASIC or the Macro Assembler.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV13206@%%@4@%You cannot debug a program until you compile it successfully. The CodeView%@EH@% debugger will not help you correct syntax or compiler errors. Once you successfully compile your program, you can use the debugger to locate logical errors in the program.%@NL@% %@NL@% %@CR:MCV13207@%%@4@%Compiling examples are given in the sections below on compiling and linking%@EH@% with specific languages.%@NL@% %@NL@% %@NL@% %@CR:MCV13300@%%@3@%%@AB@%1.3.3 CodeView Link Options%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13301@%%@4@%If you use LINK separately to link an object file or files for debugging,%@EH@% you should specify the /CODEVIEW option (it can be abbreviated as /CO). This instructs the linker to incorporate addresses for symbols and source lines into the executable file.%@NL@% %@NL@% %@CR:MCV13302@%%@4@%If you use a Microsoft driver program that automatically invokes the linker%@EH@% (such as CL with C, or FL with FORTRAN), the linker is automatically invoked with the /CO option whenever you specify /Zi on the command line. You do not use /CO unless you are invoking the linker directly, by typing LINK.%@NL@% %@NL@% %@CR:MCV13303@%%@4@%Although executable files prepared with the /CODEVIEW option can be%@EH@% executed from the DOS command line like any other executable files, they are larger because of the extra symbolic information in them. To minimize program size, you will probably want to recompile and link your final version without the /Zi option when you finish debugging a program.%@NL@% %@NL@% %@CR:MCV13304@%%@4@%Linking examples are given in the sections below on compiling and linking%@EH@% with specific languages.%@NL@% %@NL@% %@NL@% %@CR:MCV13400@%%@3@%%@AB@%1.3.4 Preparing C Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13401@%%@4@%In order to use the CodeView debugger with a program written in C, you need%@EH@% to compile it with the Microsoft C Compiler, Version 4.0 or later. Earlier versions of the compiler do not support the CodeView compile options. You also need to link with the Microsoft Overlay Linker, Version 3.6 or later.%@NL@% %@NL@% %@CR:MCV13410@%%@4@%%@AB@%Writing C Source Code%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13411@%%@4@%Microsoft C supports the use of include files through the use of the%@EH@% %@AB@%#include%@AE@% directive. However, you will not be able to debug source code put into include files. Therefore, you should reserve the use of include files for %@AB@%#define%@AE@% prototypes, macros, and structure definitions.%@NL@% %@NL@% %@CR:MCV13412@%%@4@%The C language permits you to put more than one statement on a line. This%@EH@% practice makes it difficult for you to debug such lines of code. For example, the following code is legal in C:%@NL@% %@NL@% code = buffer[count]; if (code == '\n') ++lines;%@NL@% %@NL@% %@CR:MCV13413@%%@4@%This code is made up of three separate source statements. When placed on the%@EH@% same line, the individual statements cannot be accessed during debugging. You could not, for example, stop program execution at %@AS@%++lines%@AE@%;. The same code would be easier to debug in the following form:%@NL@% %@NL@% code = buffer[count];%@NL@% if (code == '\n')%@NL@% ++lines;%@NL@% %@NL@% %@CR:MCV13414@%%@4@%This makes code easier to read and corresponds with what is generally%@EH@% considered good programming practice.%@NL@% %@NL@% %@CR:MCV13415@%%@4@%You cannot easily debug macros with the CodeView debugger. The debugger will%@EH@% not break down the macro for you. Therefore, if you have complex macros with potential side effects, you may need to write them first as regular source statements.%@NL@% %@NL@% %@CR:MCV13420@%%@4@%%@AB@%Compiling and Linking C Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13421@%%@4@%The /Zi, /Zd, and /Od options are all supported by the Microsoft C%@EH@% Compilers, Versions 4.0 and later. (For a description of these options, see Section 1.3.2%@BO: b4af@%, "CodeView Compile Options.") The options are accepted by the CL driver and the MSC driver, which was supplied with Version 4.0. Linking separately with /CO is necessary when you compile with MSC.%@NL@% %@NL@% %@CR:MCV13422@%%@4@%The CodeView debugger supports mixed-language programming. For an example of%@EH@% how to link a C module with modules from other languages, see Section 1.3.8%@BO: fbcc@%, "Preparing Assembly Programs."%@NL@% %@NL@% %@CR:MCV13423@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% CL /Zi /Od EXAMPLE.C%@NL@% %@NL@% CL /Zi /Od /c EXAMPLE.C%@NL@% LINK /CO EXAMPLE;%@NL@% %@NL@% CL /Zi /Od /c MOD1.C%@NL@% CL /Zd /Od /c MOD2.C%@NL@% CL /Zi MOD1 MOD2%@NL@% %@NL@% %@CR:MCV13424@%%@4@%In the first example, CL is used to compile and link EXAMPLE.C, the source%@EH@% file. The CL driver creates an object file, EXAMPLE.OBJ, in the CodeView format, and then automatically invokes the linker with the /CO option. The second example demonstrates how to compile and link source file EXAMPLE.C by using the MSC program provided with Version 4.0 of the compiler. Since MSC does not invoke the linker, you must invoke the linker directly and specify /CO on the command line. Both examples will result in an executable file, EXAMPLE.EXE, which has the line-number information, symbol table, and unoptimized code required by the CodeView debugger.%@NL@% %@NL@% %@CR:MCV13425@%%@4@%In the third example, the source module MOD1.C is compiled to produce an%@EH@% object file with full symbolic and line information, while MOD2.C is compiled to produce an object file with limited information. Then, CL is used again to link the resulting object files. (This time, CL does not recompile because the arguments have no .C extension.) Typing /Zi on the command line causes the linker to be invoked with the /CO option. The result is an executable file in which one of the modules, MOD2.C, will be harder to debug. However, the executable file will take up less space on disk than it would if both modules were compiled with full symbolic information.%@NL@% %@NL@% %@NL@% %@CR:MCV13500@%%@3@%%@AB@%1.3.5 Preparing FORTRAN Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13501@%%@4@%In order to use the CodeView debugger with a program written in FORTRAN, you%@EH@% will need to compile it with the Microsoft FORTRAN Compiler, Version 4.0 or later. Earlier versions of the compiler do not support CodeView compile options. You will also need to link with the Microsoft Overlay Linker, Version 3.6 or later.%@NL@% %@NL@% %@CR:MCV13510@%%@4@%%@AB@%Writing FORTRAN Source Code%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13511@%%@4@%The Microsoft FORTRAN Compiler supports the use of include files, through%@EH@% use of the %@AB@%$INCLUDE%@AE@% directive. However, you will not be able to debug source code in an include file. If you have source code that you wish to put in separate files, then you should use the technique of separately compiled modules. The CodeView debugger does support this technique by allowing you to trace through separate source files in the same session.%@NL@% %@NL@% %@CR:MCV13520@%%@4@%%@AB@%Compiling and Linking FORTRAN Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13521@%%@4@%The /Zi, /Zd, and /Od options are all supported by the Microsoft FORTRAN%@EH@% Compiler, Version 4.0 or later. For a description of these options, see Section 1.3.2%@BO: b4af@%, "CodeView Compile Options." The CodeView debugger supports mixed-language programming. For an example of how to link a FORTRAN module with modules from other languages, see Section 1.3.8%@BO: fbcc@%, "Preparing Assembly Programs."%@NL@% %@NL@% %@CR:MCV13522@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% FL /Zi /Od EXAMPLE.FOR%@NL@% %@NL@% FL /Zi /Od /c EXAMPLE.FOR%@NL@% LINK /CO EXAMPLE;%@NL@% %@NL@% FL /Zi /Od /c MOD1.FOR%@NL@% FL /Zd /Od /c MOD2.FOR%@NL@% FL /Zi MOD1 MOD2%@NL@% %@NL@% %@CR:MCV13523@%%@4@%In the first example, the FL driver is used to compile and link the source%@EH@% file EXAMPLE.FOR. The FL driver creates an object file in the CodeView format, EXAMPLE.OBJ, and then automatically invokes the linker with the /CO option. The second example demonstrates how to compile and link the source file EXAMPLE.FOR by using separate steps for compiling and linking. In this case, the /CO option must be given explicitly to the linker. Both examples result in an executable file, EXAMPLE.EXE, which has the line-number information, symbol table, and unoptimized code required by the CodeView debugger.%@NL@% %@NL@% %@CR:MCV13524@%%@4@%In the third example, the source module MOD1.FOR is compiled to produce an%@EH@% object file with full symbolic and line information, while MOD2.FOR is compiled to produce an object file with limited information. Then FL is used again to link the object files. (Note that this time, FL does not recompile because the arguments have no .FOR extension.) Typing /Zi on the command line causes the linker to be invoked with the /CO option. The result is an executable file in which one of the modules, MOD2.FOR, will be harder to debug. However, the executable file takes up less space on disk than it would if both modules were compiled with full symbolic information.%@NL@% %@NL@% %@NL@% %@CR:MCV13600@%%@3@%%@AB@%1.3.6 Preparing BASIC Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13601@%%@4@%In order to use the CodeView debugger with a program written in BASIC, you%@EH@% will need to compile it with Microsoft QuickBASIC, Version 4.0 or later. You will also need to link with the Microsoft Overlay Linker, Version 3.6 or later.%@NL@% %@NL@% %@CR:MCV13610@%%@4@%%@AB@%Writing BASIC Source Code%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13611@%%@4@%Microsoft BASIC supports the use of include files, through the use of the%@EH@% %@AB@%$INCLUDE%@AE@% directive. However, you will not be able to debug source code put into include files. The preferred practice for developing source code in separate files is to use separately compiled modules. The CodeView debugger does support this technique by allowing you to trace through separate source files in the same session.%@NL@% %@NL@% %@CR:MCV13612@%%@4@%BASIC also permits you to put more than one statement on a line. This%@EH@% practice makes it difficult for you to debug such lines of code. For example, the following code is legal, even common, in BASIC:%@NL@% %@NL@% SUM=0 : FOR I=1 TO N : SUM=SUM+ARRAY(I) : NEXT I%@NL@% %@NL@% %@CR:MCV13613@%%@4@%This code is actually made up of four separate BASIC statements. When placed%@EH@% on the same line, the individual statements cannot be accessed during debugging. You could not, for example, stop program execution at %@AS@%SUM=SUM+%@AE@% %@AS@%ARRAY(I)%@AE@%. The same code would be easier to debug if it were written in the following form:%@NL@% %@NL@% SUM=0%@NL@% FOR I=1 TO N%@NL@% SUM=SUM+ARRAY(I)%@NL@% NEXT I%@NL@% %@NL@% %@CR:MCV13620@%%@4@%%@AB@%Compiling and Linking BASIC Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13621@%%@4@%Microsoft QuickBASIC Versions 4.0 and later can prepare BASIC programs for%@EH@% use with the CodeView debugger, through the use of the BC command line.%@NL@% %@NL@% %@CR:MCV13622@%%@4@%You cannot prepare programs for use with CodeView when you are in the%@EH@% QuickBASIC editor itself. Instead, compile separately with the BC command-line option /Zi. The /Zi option is described in Section 1.3.2%@BO: b4af@%, "CodeView Compile Options." You must also link separately with /CO.%@NL@% %@NL@% %@CR:MCV13623@%%@4@%The CodeView debugger supports mixed-language programming. For an example of%@EH@% how to link a BASIC module with modules from other languages, see Section 1.3.8%@BO: fbcc@%, "Preparing Assembly Programs."%@NL@% %@NL@% %@CR:MCV13624@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% BC /Zi EXAMPLE;%@NL@% LINK /CO EXAMPLE;%@NL@% %@NL@% %@CR:MCV13625@%%@4@%The example above compiles the source file EXAMPLE.BAS to produce an object%@EH@% file, EXAMPLE.OBJ, which contains the symbol and line-number information required by the CodeView debugger. Then the linker is invoked with the /CO option to create an executable file that can be used with the debugger.%@NL@% %@NL@% %@NL@% %@CR:MCV13700@%%@3@%%@AB@%1.3.7 Preparing Pascal Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13701@%%@4@%In order to use the CodeView debugger with a program written in Pascal, you%@EH@% need to compile it with the Microsoft Pascal Compiler, Version 4.0 or later. Earlier versions of Pascal do not support the CodeView compile options. You also need to link with the Microsoft Overlay Linker, Version 3.6 or later.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% If you have a version of Microsoft Pascal earlier than Version 4.0, you%@NL@% can use the CodeView debugger to a limited extent. However, the debugger%@NL@% will not be able to evaluate program symbols in CodeView commands.%@NL@% Compile a program as you would normally, and then link with the %@AB@%/CO%@AE@% option as explained below. You will then be able to use CodeView to step through your program and set breakpoints.The debugger will also be able to display machine-level code and domemory dumps. This version of Code View does not include a Pascal expression evaluator.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV13710@%%@4@%%@AB@%Writing Pascal Source Code%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13711@%%@4@%Microsoft Pascal supports the use of include files by providing the %@AB@%$include%@AE@%%@EH@% metacommand. However, you will not be able to debug source code put into include files. You can easily debug code in separately compiled source files. Use this technique, rather than that of include files, to debug a large program.%@NL@% %@NL@% %@CR:MCV13712@%%@4@%Pascal allows you to put more than one statement on a line; yet it is%@EH@% difficult to debug programs with multiple statements on a single line. For example, the following code is legal in Pascal:%@NL@% %@NL@% if i = max then begin k := k+1; i = 0 end;%@NL@% %@NL@% %@CR:MCV13713@%%@4@%This code is actually made up of five separate source statements. When%@EH@% placed on the same line, the individual statements cannot be accessed during debugging. You could not, for example, stop program execution at %@AS@%k := k+1%@AE@%;. The same code would be easier to debug if it were written as the following:%@NL@% %@NL@% if i = max then%@NL@% begin%@NL@% k := k+1;%@NL@% i := 0%@NL@% end;%@NL@% %@NL@% %@CR:MCV13714@%%@4@%Writing only one statement on a line makes code easier to read and%@EH@% corresponds with what is generally considered good programming practice.%@NL@% %@NL@% %@CR:MCV13720@%%@4@%%@AB@%Compiling and Linking Pascal Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13721@%%@4@%Versions 4.0 and later of Microsoft Pascal support the CodeView options /Zi%@EH@% and /Zd when you use the PL driver program. (For a description of these options, see Section 1.3.2%@BO: b4af@%, "CodeView Compile Options.") The CodeView compile options are put on the command line when invoking the first pass of the Pascal compiler.%@NL@% %@NL@% %@CR:MCV13722@%%@4@%The /CO option is necessary only when you link separately.%@EH@%%@NL@% %@NL@% %@CR:MCV13723@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% PL /Zi /c TEST%@NL@% LINK /CO TEST;%@NL@% %@NL@% %@CR:MCV13724@%%@4@%The example above compiles the source file TEST.PAS to produce an object%@EH@% file, TEST.OBJ, which contains the symbol and line-number information required by the CodeView debugger. Then the linker is invoked with the /CO option.%@NL@% %@NL@% %@CR:MCV13725@%%@4@%The CodeView debugger supports mixed-language programming. For an example of%@EH@% how to link a Pascal module with modules from other languages, see Section 1.3.8%@BO: fbcc@% below.%@NL@% %@NL@% %@NL@% %@CR:MCV13800@%%@3@%%@AB@%1.3.8 Preparing Assembly Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13801@%%@4@%In order to use all the features of the CodeView debugger with assembly%@EH@% programs, you need to assemble with Microsoft Macro Assembler, Version 5.0 or later. (Section 1.7%@BO: 1ab8d@% discusses how to use earlier versions of Microsoft Macro Assembler with the debugger.) No matter what version of the assembler you use, you will need to link with the Microsoft Overlay Linker, Version 3.6 or later.%@NL@% %@NL@% %@CR:MCV13810@%%@4@%%@AB@%Writing Assembler Source Code%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13811@%%@4@%If you have Version 5.0 or later of the Microsoft Macro Assembler, you can%@EH@% use the simplified segment directives described in the %@AI@%Microsoft%@AE@% %@AI@%Macro%@AE@% %@AI@%Assembler Programmer's Guide.%@AE@% Use of these directives ensures that segments are declared in the correct way for use with the CodeView debugger. (These directives also aid mixed-language programming.) If you do not use these directives, make sure that the class name for the code segment ends with the letters %@AS@%CODE%@AE@%.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The CodeView debugger correctly recognizes floating-point values only%@NL@% when they are in the IEEE (Institute of Electrical and Electronics%@NL@% Engineers, Inc.) format. You should use the IEEE format with any program%@NL@% that you are going to run with the CodeView debugger if that program uses%@NL@% floating-point variables. The IEEE format is the default for Version 5.0%@NL@% or later of the Microsoft Macro Assembler. You can always specify IEEE%@NL@% format by using the %@AB@%.8087%@AE@% or %@AB@%.287%@AE@% directive, or by assembling with the%@NL@% %@AB@%/R%@AE@% option.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV13812@%%@4@%You will not be able to trace through macros while in source mode. Macros%@EH@% will be treated as single instructions unless you are in assembly or mixed mode, so you will not see comments or directives within macros. Therefore, you may want to debug code before putting it into a macro.%@NL@% %@NL@% %@CR:MCV13813@%%@4@%The Microsoft Macro Assembler also supports include files, but you will not%@EH@% be able to debug code in an include file. You are better off reserving include files for macro and structure definitions.%@NL@% %@NL@% %@CR:MCV13814@%%@4@%Because the assembler does not have its own expression evaluator, you will%@EH@% have to use either the C, FORTRAN, or BASIC expression evaluator. C is the default because it is the closest to assembly language. To make sure the expression evaluator recognizes your symbols and labels, you should observe the following guidelines when writing assembly modules:%@NL@% %@NL@% %@CR:MCV13815@% 1. The assembler has no explicit way to declare real numbers. However, it%@NL@% will pass the correct symbolic information for reals and integers if%@NL@% you initialize each real number with a decimal point and each integer%@NL@% without a decimal point. (The default type is integer.) For example,%@NL@% the following statements correctly initialize %@AS@%REALSUM%@AE@% as a real number%@NL@% and %@AS@%COUNTER%@AE@% as an integer:%@NL@% %@NL@% %@AS@%REALSUM DD 0.0%@AE@%%@NL@% %@AS@%COUNTER DD 0%@AE@%%@NL@% %@NL@% You must initialize real number data in data definitions. If you use %@AS@%?%@AE@%,%@NL@% the assembler will consider the variable an integer when it generates%@NL@% symbolic information. The CodeView debugger, in turn, will not properly%@NL@% evaluate the value of the variable.%@NL@% %@NL@% 2. Avoid the use of special characters in symbol names. The C, FORTRAN,%@NL@% and BASIC expression evaluators each apply their own standards in%@NL@% detemining what is a legal symbol name. Generally, only alphanumeric%@NL@% characters and the underscore (_) are recognized. BASIC accepts certain%@NL@% type-declaration characters at the end of a name, but C and FORTRAN do%@NL@% not.%@NL@% %@NL@% 3. Assemble with /MX or /ML to avoid conflicts due to case when you do%@NL@% mixed-language programming. By default, the assembler converts all%@NL@% symbols to uppercase when it generates object code. C, however, does%@NL@% not do this conversion. Therefore, the CodeView debugger will not%@NL@% recognize that %@AS@%var%@AE@% in a C program and %@AS@%var%@AE@% in an assembly program are%@NL@% the same variable unless you leave Case Sense off when using the%@NL@% debugger.%@NL@% %@NL@% 4. If you access command-line data in the Program Segment Prefix (PSP),%@NL@% note that the CodeView debugger changes the PSP; tabs, quote marks, and%@NL@% extra spaces are removed so that exactly one space separates each%@NL@% argument. The debugger retains quote marks (along with any quoted%@NL@% material) for command lines given with the %@AB@%L%@AE@% command.%@NL@% %@NL@% %@CR:MCV13820@%%@4@%%@AB@%Assembling and Linking%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV13821@%%@4@%The assembler supports the /Zi and /Zd assemble-time options. The /Od option%@EH@% does not apply, and so is not supported. Assembler options are not case sensitive. You may therefore enter /ZI or /ZD on the assembler command line to produce an object file in the CodeView format.%@NL@% %@NL@% %@CR:MCV13822@%%@4@%If you link your assembly program with a module written in C (which is case%@EH@% sensitive), you probably need to assemble with /MX or /ML.%@NL@% %@NL@% %@CR:MCV13823@%%@4@%After assembling, link with the /CO option to produce an executable file in%@EH@% the CodeView format.%@NL@% %@NL@% %@CR:MCV13824@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% MASM /ZI EXAMPLE;%@NL@% LINK /CO EXAMPLE;%@NL@% %@NL@% MASM /ZI MOD1;%@NL@% MASM /ZD MOD2;%@NL@% LINK /CO MOD1 MOD2;%@NL@% %@NL@% CL /Zi /Od /c /AL prog.c%@NL@% BC /Zi sub1;%@NL@% MASM /ZI /MX sub2;%@NL@% LINK /CO prog sub1 sub2%@NL@% %@NL@% %@CR:MCV13825@%%@4@%The first example assembles the source file EXAMPLE.ASM and produces the%@EH@% object file EXAMPLE.OBJ, which is in the CodeView format. The linker is then invoked with the /CO option and produces an executable file with the symbol table and line-number information required by the debugger.%@NL@% %@NL@% %@CR:MCV13826@%%@4@%The second example produces the object file MOD1.OBJ, which contains symbol%@EH@% and line-number information, and the object file MOD2.OBJ, which contains line-number information but no symbol table. The object files are then linked. The result is an executable file in which the second module will be harder to debug. This executable file, however, will be smaller than it would be if both modules were assembled with the /ZI option.%@NL@% %@NL@% %@CR:MCV13827@%%@4@%The last example demonstrates how to create a mixed-language executable file%@EH@% that can be used with the CodeView debugger. The debugger is able to trace through different source files in the same session, regardless of the language.%@NL@% %@NL@% %@NL@% %@CR:MCV14000@%%@2@%%@AB@%1.4 Starting the CodeView Debugger%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV14001@%%@4@%Before starting the debugger, make sure all the files it requires are%@EH@% available. The following files are recommended for source-level debugging:%@NL@% %@NL@% %@CR:MCV14002@%%@AB@%File Location%@AE@%%@NL@% %@NL@% CV.EXE The CodeView program file can be in the current%@NL@% directory or in any directory accessible with%@NL@% the PATH command. For example, if you are using%@NL@% a hard disk setup, you might put CV.EXE in the%@NL@% \BIN directory. If you have an older version of%@NL@% the debugger, take care to remove any copies of%@NL@% CV.EXE from directories in your PATH. The%@NL@% debugger has an overlay manager that reloads the%@NL@% file CV.EXE from time to time. If it reloads the%@NL@% wrong version of this file, your machine will%@NL@% likely crash.%@NL@% %@NL@% CV.HLP If you want to have the on-line help available%@NL@% during your session, you should have this file%@NL@% either in the current directory or in any%@NL@% directory accessible with the PATH command. For%@NL@% example, if you set up your compiler files on a%@NL@% hard disk using the SETUP program provided on%@NL@% the distribution disk, you might put CV.HLP in%@NL@% the \BIN directory. If the CodeView debugger%@NL@% cannot find the help file, you can still use the%@NL@% debugger, but you will see an error message if%@NL@% you use one of the help commands.%@NL@% %@NL@% %@AI@%program%@AE@%.EXE The executable file for the program you wish to%@NL@% debug must be in the current directory or in a%@NL@% drive and directory you specify as part of the%@NL@% start-up file specification. The CodeView%@NL@% debugger will display an error message and will%@NL@% not start unless the executable file is found.%@NL@% %@NL@% %@AI@%source%@AE@%%@AB@%.%@AE@%%@AI@%ext%@AE@% (extension Normally, source files should be in the current%@NL@% depends on language) directory. However, if you specify a file%@NL@% specification for the source file during%@NL@% compilation, that specification becomes part of%@NL@% the symbolic information stored in the%@NL@% executable file. For example, if you compiled%@NL@% with the command line argument %@AS@%DEMO%@AE@%, the%@NL@% CodeView debugger expects the source file to be%@NL@% in the current directory. However, if you%@NL@% compiled with the command line argument%@NL@% %@AS@%\SOURCE\DEMO%@AE@%, the debugger expects the source%@NL@% file to be in the directory %@AS@%%@AE@%%@AS@%\SOURCE%@AE@%. If the%@NL@% debugger cannot find the source file in the%@NL@% directory specified in the executable file%@NL@% (usually the current directory), the program%@NL@% prompts you for a new directory. You can either%@NL@% enter a new directory, or you can press ENTER%@NL@% to indicate that you do not want a source file%@NL@% to be used for this module. If no source file is%@NL@% specified, you must debug in assembly mode.%@NL@% %@NL@% %@CR:MCV14003@%%@4@%If the appropriate files are in the correct directories, you can enter the%@EH@% CodeView command line at the DOS command prompt. The command line has the following form:%@NL@% %@NL@% CV «%@AI@%options%@AE@%» %@AI@%executablefile%@AE@% «%@AI@%arguments%@AE@%»%@NL@% %@NL@% %@CR:MCV14004@%%@4@%The %@AI@%options%@AE@% are one or more of the options described in Section 1.5.%@BO: 136bc@% The%@EH@% %@AI@%executablefile%@AE@% is the name of an executable file to be loaded by the debugger. It must have the extension .EXE or .COM. If you try to load a nonexecutable file, the following message appears:%@NL@% %@NL@% Not an executable file%@NL@% %@NL@% %@CR:MCV14005@%%@4@%Compiled programs and assembly-language programs containing CodeView%@EH@% symbolic information will always have the extension .EXE. Files with the extension .COM can be debugged in assembly mode, but they can never contain symbolic information.%@NL@% %@NL@% %@CR:MCV14006@%%@4@%The optional %@AI@%arguments%@AE@% are parameters passed to the %@AI@%executablefile%@AE@%. If the%@EH@% program you are debugging does not accept command-line arguments, you do not need to pass any arguments.%@NL@% %@NL@% %@CR:MCV14007@%%@4@%If you specify the %@AI@%executablefile%@AE@% as a file name with no extension, the%@EH@% CodeView debugger searches for a file with the given base name and the extension .EXE. Therefore, you must specify the .COM extension if you are debugging a .COM file. If the file is not in the CodeView format, the debugger starts in assembly mode and displays the following message:%@NL@% %@NL@% No symbolic information%@NL@% %@NL@% %@CR:MCV14008@%%@4@%You must specify an executable file when you start the CodeView debugger. If%@EH@% you omit the executable file, the debugger displays a message showing the correct command-line format.%@NL@% %@NL@% %@CR:MCV14009@%%@4@%When you give the debugger a valid command line, the executable program and%@EH@% the source file are loaded, the address data are processed, and the CodeView display appears. The initial display will be in window mode or sequential mode, depending on the options you specify and the type of computer you have.%@NL@% %@NL@% %@CR:MCV1400A@%%@4@%For example, if you wanted to debug the program BENCHMRK.EXE, you could%@EH@% start the debugger with the following command line:%@NL@% %@NL@% CV BENCHMRK%@NL@% %@NL@% %@CR:MCV1400B@%%@4@%If you give this command line on an IBM Personal Computer, window mode is%@EH@% selected automatically. The display will look like Figure 1.1%@FN@% Figure 1.1 is found on page 19 of the printed version.%@EF@%.%@NL@% %@NL@% %@CR:MCV1400C@%%@4@%If you give the same command line on most non-IBM computers, sequential mode%@EH@% will be selected. The following lines appear:%@NL@% %@NL@% Microsoft (R) CodeView (R) Version 2.3%@NL@% (C) Copyright Microsoft Corp. 1986-1989. All rights reserved.%@NL@% %@NL@% >%@NL@% %@NL@% %@CR:MCV1400D@%%@4@%You can use CodeView options to override the default start-up mode.%@EH@%%@NL@% %@NL@% %@CR:MCV1400E@%%@4@%If your program is written in a high-level language, the CodeView debugger%@EH@% is now at the beginning of the start-up code that precedes your program. In source mode, you can enter an execution command (such as Trace or Program Step) to execute automatically through the start-up code to the beginning of your program. At this point, you are ready to start debugging your program, as described in Chapters 3%@BO: 2d605@%-11.%@NL@% %@NL@% %@NL@% %@CR:MCV15000@%%@2@%%@AB@%1.5 Using CodeView Options%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15001@%%@4@%You can change the start-up behavior of the debugger by specifying options%@EH@% in the command line. An option is a sequence of characters preceded by either a forward slash (/) or a dash (-).%@NL@% %@NL@% %@CR:MCV15002@%%@4@%For brevity, this manual will list only the forward slash when describing%@EH@% options, but you may use either. Unlike compiler command-line options, CodeView command-line options are not case sensitive.%@NL@% %@NL@% %@CR:MCV15003@%%@4@%A file whose name begins with a dash must be renamed before you use it with%@EH@% the CodeView debugger so the debugger will not interpret the dash as an option designator. You can use more than one option in a command line, but each option must have its own option designator, and spaces must separate each option from other elements of the line.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The CodeView debugger's defaults for IBM Personal Computers are different%@NL@% from the defaults it has for other computers. However, the debugger may%@NL@% not always recognize the difference between computers, and defaults may%@NL@% vary accordingly.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV15004@%%@4@%The following list suggests some situations in which you might want to use%@EH@% an option. If more than one condition applies, you can use more than one option (in any order). If none of the conditions applies, you need not use any options.%@NL@% %@NL@% %@CR:MCV15005@%%@AB@%Condition Option%@AE@%%@NL@% %@NL@% You want to use two monitors with the /2%@NL@% CodeView debugger. %@NL@% %@NL@% You want a 43-line display and you have an /43%@NL@% IBM or IBM-compatible computer with an %@NL@% enhanced graphics adapter (EGA) and an %@NL@% enhanced color display. %@NL@% %@NL@% You want a 50-line display and you have a /50%@NL@% graphics adapter card that supports 50-line %@NL@% mode. %@NL@% %@NL@% You have a two-color monitor, a color /B%@NL@% graphics adapter, and an IBM or %@NL@% IBM-compatible computer. %@NL@% %@NL@% You want the CodeView debugger to /C%@AI@%commands%@AE@%%@NL@% automatically execute a series of commands when %@NL@% it starts up. %@NL@% %@NL@% You are using an IBM-compatible computer /D%@NL@% that does not support certain IBM-specific %@NL@% interrupt-trapping functions. %@NL@% %@NL@% You have expanded memory and want the /E%@NL@% CodeView debugger to take advantage of it. %@NL@% %@NL@% You are using an IBM-compatible computer /F%@NL@% to debug a program that does not use graphics %@NL@% or multiple video-display pages, %@NL@% and you want to be able to see the output %@NL@% screen. %@NL@% %@NL@% You are using a non-IBM-compatible /I%@NL@% computer and want to enable CTRL+C and %@NL@% CTRL+BREAK. %@NL@% %@NL@% You run CodeView (CVP) in OS/2 protected mode /L%@NL@% and want to debug dynamic-link libraries. %@NL@% %@NL@% You have a mouse installed in your /M%@NL@% system, but do not want to use it during the %@NL@% debugging session. %@NL@% %@NL@% You run CodeView (CVP) with OS/2, Version 1.10 /O%@NL@% or later, and wish to debug multiple processes. %@NL@% %@NL@% You have a non-IBM EGA and have problems /P%@NL@% running the debugger. %@NL@% %@NL@% You have a 386 processor and wish to /R%@NL@% use the debug registers to speed up the %@NL@% execution of tracepoints. %@NL@% %@NL@% You are debugging a graphics program or a /S%@NL@% program that uses multiple video-display%@NL@% pages, and you want to be able to see the%@NL@% output screen.%@NL@% %@NL@% You are using a non-IBM-compatible /S%@NL@% computer and want to be able to see the output%@NL@% screen.%@NL@% %@NL@% You have an IBM computer, but wish to /T%@NL@% debug in sequential mode (for example, with redirection). %@NL@% You have an IBM-compatible computer /W%@NL@% and want to use window mode. %@NL@% %@CR:MCV15006@%%@4@%For example, assume you are using an IBM-compatible computer with a color%@EH@% graphics adapter (CGA) and a two-color monitor. The program you are debugging, which you could name GRAPHIX.EXE, plots points in graphics mode. You want to be able to see the output screen during the debugging session. Finally, you want to be able to start the debugger several times without having to remember all the options, and you want to execute the high-level language start-up code automatically each time. You could create a batch file consisting of the following line:%@NL@% %@NL@% CV /W /B /S /CGmain GRAPHIX%@NL@% %@NL@% %@CR:MCV15007@%%@4@%The CodeView options are described in more detail in Sections 1.5.1%@BO: 14c56@%-1.5.16%@EH@% below.%@NL@% %@NL@% %@NL@% %@CR:MCV15100@%%@3@%%@AB@%1.5.1 Using Two Video Adapters%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15101@%%@AB@%Option%@AE@%%@NL@% %@NL@% /2%@NL@% %@NL@% %@CR:MCV15102@%%@4@%The /2 option permits the use of two monitors with the CodeView debugger.%@EH@% The program display will appear on the current default monitor, while the CodeView display appears on the other monitor. You must have two monitors and two adapters to use the /2 option. For instance, if you have both a color graphics adapter and a monochrome adapter, you might want to set the CGA up as the default adapter. You could then debug a graphics program with the graphics display appearing on the graphics monitor and the debugging display appearing on the monochrome monitor.%@NL@% %@NL@% %@NL@% %@CR:MCV15200@%%@3@%%@AB@%1.5.2 Using the Enhanced Graphics Adapter's 43-Line Mode%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15201@%%@AB@%Option%@AE@%%@NL@% %@NL@% /43%@NL@% %@NL@% %@CR:MCV15202@%%@4@%If you have an enhanced graphics adapter (EGA) and a monochrome monitor or%@EH@% an enhanced color display monitor (or a compatible monitor), you can use the /43 option to enable a 43-line-by-80-column text mode. You cannot use this mode with other monitors, such as a CGA or a monochrome adapter (MA). The CodeView debugger will ignore the option if it does not detect an EGA.%@NL@% %@NL@% %@CR:MCV15203@%%@4@%The EGA's 43-line mode performs the same as the normal 25-line-by-80-column%@EH@% mode used by default on the EGA, CGA, and MA. The advantage of the 43-line mode is that more text fits on the CodeView display; the disadvantage is that the text is smaller and harder to read. If you have an EGA, you can experiment to see which size you prefer.%@NL@% %@NL@% %@CR:MCV15204@%%@4@%The video graphics adapter (VGA) card also supports this option.%@EH@%%@NL@% %@NL@% %@CR:MCV15205@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% CV /43 CALC CALC.DAT%@NL@% %@NL@% %@CR:MCV15206@%%@4@%The example above starts the CodeView debugger in 43-line mode if you have%@EH@% an EGA video adapter and an enhanced color or monochrome monitor. The option will be ignored if you lack the hardware to support it.%@NL@% %@NL@% %@NL@% %@CR:MCV15300@%%@3@%%@AB@%1.5.3 Using 50-Line Mode%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15301@%%@AB@%Option%@AE@%%@NL@% %@NL@% /50%@NL@% %@NL@% %@CR:MCV15302@%%@4@%If you have a graphics adapter card (such as a VGA) and monitor that support%@EH@% 50-line mode, then you can use the /50 option to enable a 50-line-by-80-column text mode. You cannot use this mode with most adapters, such as a CGA or an MA. The CodeView debugger will ignore the option if your hardware does not support 50-line mode.%@NL@% %@NL@% %@CR:MCV15303@%%@4@%The 50-line mode performs the same as the normal 25-line-by-80-column mode%@EH@% used by default on the EGA, VGA, CGA, and MA. The advantage of the 50-line mode is that more text fits on the CodeView display; the disadvantage is that the text is smaller and harder to read.%@NL@% %@NL@% %@CR:MCV15304@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% CV /50 CALC CALC.DAT%@NL@% %@NL@% %@CR:MCV15305@%%@4@%The example above starts the CodeView debugger in 50-line mode if this mode%@EH@% is supported by your hardware.%@NL@% %@NL@% %@NL@% %@CR:MCV15400@%%@3@%%@AB@%1.5.4 Starting with a Black-and-White Display%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15401@%%@AB@%Option%@AE@%%@NL@% %@NL@% /B%@NL@% %@NL@% %@CR:MCV15402@%%@4@%The /B option forces the CodeView debugger to display in two colors even if%@EH@% you have a color adapter (CGA, EGA, or compatible). By default, the debugger checks on start-up to see what kind of display adapter is attached to your computer. If the debugger detects an MA, it displays in two colors. If it detects a color adapter, it displays in multiple colors.%@NL@% %@NL@% %@CR:MCV15403@%%@4@%If you use a two-color monitor with a CGA or EGA, you may want to disable%@EH@% color. Monitors that display in only two colors (usually green and black, or amber and black) often attempt to show colors with different cross-hatching patterns, or in gray-scale shades of the display color. In either case, you may find the display easier to read if you use the /B option to force black-and-white display. Most two-color monitors still have four color distinctions: background (black), normal text, high-intensity text, and reverse-video text.%@NL@% %@NL@% %@CR:MCV15404@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% CV /B CALC CALC.DAT%@NL@% %@NL@% %@CR:MCV15405@%%@4@%The example above starts the CodeView debugger in black-and-white mode. This%@EH@% is the only mode available if you have an MA. The display is usually easier to read in this mode if you have a CGA and a two-color monitor.%@NL@% %@NL@% %@NL@% %@CR:MCV15500@%%@3@%%@AB@%1.5.5 Specifying Start-Up Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15501@%%@AB@%Option%@AE@%%@NL@% %@NL@% /C%@AI@%commands%@AE@%%@NL@% %@NL@% %@CR:MCV15502@%%@4@%The /C option allows you to specify one or more %@AI@%commands%@AE@% that will be%@EH@% executed automatically upon start-up. You can use these options to invoke the debugger from a batch or MAKE file. Each command is separated from the previous command by a semicolon.%@NL@% %@NL@% %@CR:MCV15503@%%@4@%If one or more of your start-up commands have arguments that require spaces%@EH@% between them, you should enclose the entire option in double quotation marks. Otherwise, the debugger will interpret each argument as a separate CodeView command-line argument rather than as a debugging-command argument.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%WARNING%@AE@%%@NL@% Any start-up option that uses the less-than (<) or greater-than (>)%@NL@% symbol must be enclosed in double quotation marks even if it does not%@NL@% require spaces. This ensures that the redirection command will be%@NL@% interpreted by the CodeView debugger rather than by DOS.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV15504@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% CV /CGmain CALC CALC.DAT%@NL@% %@NL@% %@CR:MCV15505@%%@4@%The example above loads the CodeView debugger with %@AS@%CALC%@AE@% as the executable%@EH@% file and %@AS@%CALC.DAT%@AE@% as the argument. Upon start-up, the debugger executes the high-level-language start-up code with the command %@AS@%Gmain%@AE@%. Since no space is required between the CodeView command %@AS@%(G)%@AE@% and its argument %@AS@%(main)%@AE@%, the option is not enclosed in double quotation marks.%@AS@%%@NL@% %@NL@% CV "/C;S&;G INTEGRAL;DS ARRAYX L 20" CALC CALC.DAT%@NL@% %@NL@% %@CR:MCV15506@%%@4@%The example above loads the same file with the same argument as the first%@EH@% example, but the command list is more extensive. The debugger starts in mixed source/assembly mode ( %@AS@%S&%@AE@%). It executes to the routine %@AS@%INTEGRAL%@AE@%(%@AS@%G%@AE@% %@AS@%INTEGRAL%@AE@%), and then dumps 20 short real numbers, starting at the address of the variable %@AS@%ARRAYX%@AE@% (%@AS@%DS ARRAYX%@AE@%%@AS@%L 20%@AE@%). Since several of the commands use spaces, the entire option is enclosed in double quotation marks.%@NL@% %@NL@% CV "/C<INPUT.FIL" CALC CALC.DAT%@NL@% %@NL@% %@CR:MCV15507@%%@4@%The example above loads the same file and argument as the first example, but%@EH@% the start-up command directs the debugger to accept the input from the file %@AS@%INPUT.FIL%@AE@% rather than from the keyboard. Although the option does not include any spaces, it must be enclosed in double quotation marks so that the less-than symbol will be read by the CodeView debugger rather than by DOS.%@NL@% %@NL@% %@NL@% %@CR:MCV15600@%%@3@%%@AB@%1.5.6 Handling Interrupt Trapping (DOS Only)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15601@%%@4@%%@AB@%Options%@AE@%%@EH@%%@NL@% %@NL@% /D%@NL@% %@NL@% %@CR:MCV15602@%%@4@%The /D option turns off nonmaskable interrupt (NMI) trapping and 8259%@EH@% interrupt trapping. If you are using an IBM PC Convertible, Tandy(R) 1000, or the AT&T(R) 6300 Plus and you are experiencing system crashes with CodeView, try starting with the /D option. To enable window mode, use /W with /D; otherwise sequential mode is set automatically. Note that because this option turns off interrupt trapping, CTRL+C and CTRL+BREAK will not work, and an external interrupt may occur during a trace operation. If this happens, you may find yourself tracing the interrupt handler instead of your program.%@NL@% %@NL@% %@CR:MCV15603@%%@4@%The /I option forces the debugger to handle NMI and 8259 interrupt trapping.%@EH@% Use this option to enable CTRL+C and CTRL+BREAK on computers not recognized as being IBM compatible by the debugger, such as the Eagle(R) PC. Window mode is set automatically with the /I option; you don't have to specify /W. Using the /I option lets you stop program execution at any point while you are using the CodeView debugger.%@NL@% %@NL@% %@NL@% %@CR:MCV15700@%%@3@%%@AB@%1.5.7 Using Expanded Memory (DOS Only)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15701@%%@AB@%Option%@AE@%%@NL@% %@NL@% /E%@NL@% %@NL@% %@CR:MCV15702@%%@4@%"Expanded memory" refers to memory made accessible according to the%@EH@% Microsoft/Lotus(R)/Intel(R) EMS specification. This access provides your system with memory above the 640K MS-DOS limitation on RAM. However, since MS-DOS will not recognize this additional memory, programs can make use of expanded memory in limited ways.%@NL@% %@NL@% %@CR:MCV15703@%%@4@%The /E option enables the use of expanded memory. If expanded memory is%@EH@% present, the CodeView debugger uses it to store the symbolic information of the program. This may be as much as 85% of the size of the executable file for the program, and represents space that would otherwise be taken up in main memory.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% This option enables only expanded memory, not %@AI@%extended%@AE@% memory. Extended memory makes use of protected-mode instructions,rather than the Microsoft/Lotus/Intel specification for memory paging.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV15800@%%@3@%%@AB@%1.5.8 Setting the Screen-Exchange Mode (DOS Only)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15801@%%@4@%%@AB@%Options%@AE@%%@EH@%%@NL@% %@NL@% /F%@NL@% /S%@NL@% %@NL@% %@CR:MCV15802@%%@4@%The CodeView debugger allows you to move quickly back and forth between the%@EH@% output screen, which contains the output from your program, and the debugging screen, which contains the debugging display. The debugger can handle this screen exchange in two ways: screen flipping or screen swapping. The /F option (screen flipping) and the /S option (screen swapping) allow you to choose the method from the command line. If neither method is specified (possible only on non-IBM computers), the Screen Exchange command will not work. No screen exchange is the default for non-IBM computers. Screen flipping is the default for IBM computers with graphics adapters, and screen swapping is the default for IBM computers with monochrome adapters. Screen flipping uses the video-display pages of the graphics adapter to store each screen of text. Video-display pages are a special memory buffer reserved for multiple screens of video output. This method is faster and uses less memory than screen swapping. However, screen flipping cannot be used with an MA, nor to debug programs that produce graphics or use the video-display pages. In addition, the CodeView debugger's screen flipping works only with IBM and IBM-compatible microcomputers.%@NL@% %@NL@% %@CR:MCV15803@%%@4@%Screen swapping has none of the limitations of screen flipping, but is%@EH@% significantly slower and requires more memory. In the screen-swapping method, the CodeView debugger creates a buffer in memory and uses it to store the screen that is not being used. When the user requests the other screen, the debugger swaps the screen in the display buffer for the one in the storage buffer.%@NL@% %@NL@% %@CR:MCV15804@%%@4@%When you use screen swapping, the buffer size is 16K for all adapters. The%@EH@% amount of memory used by the CodeView debugger is increased by the size of the buffer.%@NL@% %@NL@% %@CR:MCV15805@%%@4@%Table 1.1 shows the default exchange mode (swapping or flipping) and the%@EH@% default display mode (sequential or window) for various configurations. Display modes are discussed in Section 1.5.14%@BO: 19f30@%, "Enabling Window or Sequential Mode."%@NL@% %@NL@% %@CR:MCV1T100@%%@4@%%@AB@%Table 1.1 Default Exchange and Display Modes%@AE@%%@EH@%%@NL@% %@TH: 18 980 3 21 16 12 47 @%%@AB@% Display Default%@AE@%%@AB@%Computer Adapter Modes Alternate Modes%@AE@%IBM CGA or EGA /F /W /S if your program uses video- display pages or graphics; /T for sequential modeIBM compatible CGA or EGA /T /W for window mode; /F for screen flipping with text programs; or /S for screen swapping with programs that use video-display pages or graphicsIBM MA /S /W /T for sequential modeIBM compatible MA /T /W for window mode; /S for screen swappingNoncompatible Any /T /S for screen swapping%@TE: 18 980 3 21 16 12 47 @% %@NL@% %@CR:MCV15806@%%@4@%If you are not sure if your computer is completely IBM compatible, you can%@EH@% experiment. If the basic input/output system (BIOS) of your computer is not compatible enough, the CodeView debugger may not work with the /F option.%@NL@% %@NL@% %@CR:MCV15807@%%@4@%If you specify the /F option with an MA, the debugger ignores the option%@EH@% and uses screen swapping. If you try to use screen flipping to debug a program that produces graphics or uses the video-display pages, you may get unexpected results and have to start over with the /S option.%@NL@% %@NL@% %@CR:MCV15808@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% CV /F CALC CALC.DAT%@NL@% %@NL@% %@CR:MCV15809@%%@4@%The example above starts the CodeView debugger with screen flipping. You%@EH@% might use this command line if you have an IBM-compatible computer, and you want to override the default screen-exchange mode in order to use less memory and switch screens more quickly. The option would not be necessary on an IBM computer, since screen flipping is the default.%@NL@% %@NL@% CV /S GRAFIX%@NL@% %@NL@% %@CR:MCV1580A@%%@4@%The example above starts the debugger with screen swapping. You might use%@EH@% this command line if your program uses graphics mode.%@NL@% %@NL@% %@NL@% %@CR:MCV15900@%%@3@%%@AB@%1.5.9 Loading Information from Dynamic-Link Libraries (OS/2 Only)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15901@%%@AB@%Option%@AE@%%@NL@% %@NL@% /L %@AI@%dynlib%@AE@%%@NL@% %@NL@% %@CR:MCV15902@%%@4@%The /L option directs the protected-mode CodeView debugger (CVP) to search%@EH@% %@AI@%dynlib%@AE@% for symbolic information. At least one space must separate /L from %@AI@%dynlib%@AE@%.%@NL@% %@NL@% %@CR:MCV15903@%%@4@%CVP can debug dynamic-link libraries, but only if it is told what libraries%@EH@% to search at run time. When you place a module in a dynamic-link library, neither code nor symbolic information for that module is stored in an application's executable (.EXE) file. Instead, the code and symbols are stored in the library and are not brought together with the main program until run time.%@NL@% %@NL@% %@CR:MCV15904@%%@4@%Thus, the protected-mode debugger needs to search the dynamic-link library%@EH@% for symbolic information. Because the debugger does not automatically know which libraries to look for, use /L to load symbolic information for dynamic-link libraries. You should use this option only with libraries that you have created and wish to debug.%@NL@% %@NL@% %@CR:MCV15905@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% CVP /L DLIB1.DLL /L GRAFLIB.DLL PROG%@NL@% %@NL@% %@CR:MCV15906@%%@4@%In the example above, CVP is invoked to debug the program PROG.EXE. To find%@EH@% symbolic information needed for debugging each module, CVP searches libraries DLIB1.DLL and DLIB2.DLL, as well as the executable file PROG.EXE.%@NL@% %@NL@% %@NL@% %@CR:MCV15A00@%%@3@%%@AB@%1.5.10 Turning Off the Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15A01@%%@AB@%Option%@AE@%%@NL@% %@NL@% /M%@NL@% %@NL@% %@CR:MCV15A02@%%@4@%If you have a mouse installed on your system, you can tell the CodeView%@EH@% debugger to ignore it by using the /M option. You may need to use this option if you are debugging a program that uses the mouse and your mouse is not a Microsoft Mouse. This is due to a conflict between the program's use of the mouse and the debugger's use of it. Use of /M may possibly disable the program's use of the mouse, as well as CodeView's.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The same conflict between program and debugger applies if you are not%@NL@% using the current Microsoft Mouse driver program (%@AB@%MOUSE.SYS%@AE@%), which is%@NL@% included on the distribution disks for certain Microsoft products. You%@NL@% may want to replace your old mouse driver program with the updated%@NL@% version. You will then be able to use the mouse with both the CodeView%@NL@% debugger and the program you are debugging. If you did not install a%@NL@% mouse driver when you set up Version 4.0 of Microsoft FORTRAN, Version%@NL@% 5.0 or later of Microsoft C, or Version 5.0 or later of Macro Assembler,%@NL@% see your user's guide for information on installing %@AB@%MOUSE.SYS%@AE@%. These%@AE@%%@NL@% programs may not work with pointing devices from other manufacturers.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV15B00@%%@3@%%@AB@%1.5.11 Debugging Multiple Processes (OS/2 only)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15B01@%%@AB@%Option%@AE@%%@NL@% %@NL@% /O%@NL@% %@NL@% %@CR:MCV15B02@%%@4@%If you are running OS/2, version 1.10 or later, you can use the /O option to%@EH@% enable debugging of multiple processes. See Chapter 12%@BO: 80899@%, "Debugging in Protected Mode," for more information on how to debug multiple processes.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The /O option is incompatible with the /2 option.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV15C00@%%@3@%%@AB@%1.5.12 Extending EGA Compatibility%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15C01@%%@AB@%Option%@AE@%%@NL@% %@NL@% /P%@NL@% %@NL@% %@CR:MCV15C02@%%@4@%The use of the /P option may enable the CodeView debugger to run properly in%@EH@% window mode on a non-IBM version of the enhanced graphics adapter (EGA).%@NL@% %@NL@% %@CR:MCV15C03@%%@4@%Normally, the debugger saves and restores the palette registers of an EGA.%@EH@% However, although this procedure works perfectly well with an IBM EGA, it can create conflicts with other EGAs. The /P option prevents the saving and restoring of palette registers, and so may enhance compatibility.%@NL@% %@NL@% %@CR:MCV15C04@%%@4@%Symptoms that may indicate the need for using /P include the debugging%@EH@% screen starting in nonstandard colors and the debugger appearing to crash while in window mode.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The %@AB@%/P%@AE@% option may cause the program being debugged to lose some colors%@NL@% whenever you switch back and forth between the debugging screen and the%@NL@% output screen. Therefore, do not use the %@AB@%/P%@AE@% option unless necessary.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV15D00@%%@3@%%@AB@%1.5.13 Using Debug Registers (386 Only)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15D01@%%@AB@%Option%@AE@%%@NL@% %@NL@% /R%@NL@% %@NL@% %@CR:MCV15D02@%%@4@%If you have a 386 processor, you can enable the four debug registers by%@EH@% giving the /R option. The debug registers can hold up to four tracepoints. Normally, tracepoints slow down execution of the program substantially since CodeView must interrupt the program after each instruction and test all tracepoints and watchpoints. Use of debug registers lets CodeView implement tracepoints through the processor itself. CodeView can therefore execute the program at normal speed even though areas of memory are being monitored.%@NL@% %@NL@% %@CR:MCV15D03@%%@4@%If you specify more than four watchpoints or specify any watch expression,%@EH@% CodeView does not use the debug registers.%@NL@% %@NL@% %@NL@% %@CR:MCV15E00@%%@3@%%@AB@%1.5.14 Enabling Window or Sequential Mode%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV15E01@%%@4@%%@AB@%Options%@AE@%%@EH@%%@NL@% %@NL@% /T%@NL@% %@NL@% %@CR:MCV15E02@%%@4@%The CodeView debugger can operate in window mode or sequential mode. Window%@EH@% mode displays up to four windows, enabling you to see different aspects of the debugging-session program simultaneously. You can also use a mouse in window mode. Window mode requires an IBM or IBM-compatible microcomputer. Sequential mode works with any computer and is useful with redirection commands. Debugging information is displayed sequentially on the screen.%@NL@% %@NL@% %@CR:MCV15E03@%%@4@%The behavior of each mode is discussed in detail in Chapter 2%@BO: 1b3d8@%, "The%@EH@% CodeView Display." Refer back to Table 1.1 for the default and alternate modes for your computer. If you are not sure if your computer is completely IBM compatible, you can experiment with the options. If the BIOS of your computer is not compatible enough, you may not be able to use window mode (the /W option).%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Although window mode is more convenient, any debugging operation that can%@NL@% be done in window mode can also be done in sequential mode.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV15E04@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% CV /W SIEVE%@NL@% %@NL@% %@CR:MCV15E05@%%@4@%The example above starts the CodeView debugger in window mode. You will%@EH@% probably want to use the /W option if you have an IBM-compatible computer since the default sequential mode is less convenient for most debugging tasks.%@NL@% %@NL@% CV /T SIEVE%@NL@% %@NL@% %@CR:MCV15E06@%%@4@%The example above starts the debugger in sequential mode. You might want to%@EH@% use this option if you have an IBM computer and have a specific reason for using sequential mode. For instance, sequential mode usually works better if you are redirecting your debugging output to a remote terminal.%@NL@% %@NL@% %@NL@% %@CR:MCV16000@%%@2@%%@AB@%1.6 Debugging Large Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV16001@%%@4@%Because the CodeView debugger must reside in memory along with the program%@EH@% you are debugging, there may not be enough room to debug some large programs that could otherwise run in memory alone. However, there are at least three ways to get around memory limitations:%@NL@% %@NL@% %@CR:MCV16002@% 1. If you have expanded memory, use the /E option described earlier. This%@NL@% will enable CodeView to put the symbol table in expanded memory, thus%@NL@% freeing up a good deal of main memory.%@NL@% %@NL@% 2. Since CodeView now supports the debugging of overlaid programs, you can%@NL@% substantially reduce the amount of memory required to run your program%@NL@% by using overlays when you link your program.%@NL@% %@NL@% 3. Save space by using /Zi with modules you plan to focus on in the%@NL@% debugging session only, using /Zd with other modules.%@NL@% %@NL@% %@NL@% %@CR:MCV17000@%%@2@%%@AB@%1.7 Working with Older Versions of the Assembler%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV17001@%%@4@%You can run the CodeView debugger with files developed using older versions%@EH@% of the Microsoft or IBM assemblers (prior to 5.0). Since older versions do not write line numbers to object files, some of the CodeView debugger's features will not be available when you debug programs developed with the older assemblers. The following considerations apply in addition to the considerations mentioned in Section 1.3.8%@BO: fbcc@%, "Preparing Assembly Programs."%@NL@% %@NL@% %@CR:MCV17002@%%@4@%The procedure for assembling and debugging .EXE files by using older%@EH@% versions of the assembler is summarized below. The debugger can be used on either .EXE or .COM files, but you can only view symbolic information in .EXE files.%@NL@% %@NL@% %@CR:MCV17003@% 1. In your source file, declare public any symbols, such as labels and%@NL@% variables, that you want to reference in the debugger. If the file is%@NL@% small, you may want to declare all symbols public.%@NL@% %@NL@% 2. As mentioned earlier, make sure that the code segment class name ends%@NL@% with the letters %@AS@%CODE%@AE@%. (For example: %@AS@%'MYCODE%@AE@%.)%@NL@% %@NL@% 3. Assemble as usual. No special options are required, and all assembly%@NL@% options are allowed.%@NL@% %@NL@% 4. Use LINK, Version 3.6 or later. Do not use the linker provided with%@NL@% older assembler versions. Use the /CODEVIEW option when linking.%@NL@% %@NL@% 5. Debug in assembly mode (this is the start-up default if the debugger%@NL@% fails to find line-number information). You cannot use source mode for%@NL@% debugging, but you can load the source file into the display window and%@NL@% view it in source mode. Any labels or variables that you declared%@NL@% public in the source file can be displayed and referenced by name%@NL@% instead of by address. However, they cannot be used in expressions%@NL@% because type information is not written to the object file.%@NL@% %@NL@% %@NL@% %@CR:MCV20000@%%@1@%%@AB@%Chapter 2 The CodeView Display%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV20001@%%@4@%The Microsoft CodeView debugger screen display can appear in two different%@EH@% modes──window and sequential. Either mode provides a useful debugging environment, but window mode is more powerful and convenient. The CodeView debugger accepts either window commands or dialog commands. Dialog commands are entered as command lines following the CodeView prompt (%@AS@%>%@AE@%) in sequential mode. They are discussed in Chapter 3%@BO: 2d605@%, "Using Dialog Commands."%@NL@% %@NL@% %@CR:MCV20002@%%@4@%You will probably want to use window mode if you have the hardware to%@EH@% support it. In window mode, the pull-down menus, function keys, and mouse support offer fast access to the most common commands. Different aspects of the program and debugging environment can be seen in different windows simultaneously. Window mode is described in Section 2.1%@BO: 1b99f@% below.%@NL@% %@NL@% %@CR:MCV20003@%%@4@%Sequential mode is similar to the display mode of the CodeView debugger's%@EH@% forerunner, the Microsoft Symbolic Debug Utility (SYMDEB) and the DOS DEBUG utility. This mode is required if you do not have an IBM-compatible computer, and it is sometimes useful when redirecting command input or output. Sequential mode is described in Section 2.2.%@BO: 2c28f@%%@NL@% %@NL@% %@NL@% %@CR:MCV21000@%%@2@%%@AB@%2.1 Using Window Mode%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21001@%%@4@%The elements of the CodeView display marked in Figure 2.1%@FN@% Figure 2.1 is found on page 34 of the printed version.%@EF@% below include the%@EH@% following:%@NL@% %@NL@% %@CR:MCV21002@% 1. The display window shows the program being debugged. It can contain%@NL@% source code (as in the example), assembly-language instructions, or any%@NL@% specified text file.%@NL@% %@NL@% 2. The current location line (the next line the program will execute) is%@NL@% displayed in reverse video or in a different color. This line may not%@NL@% always be visible because you can scroll to earlier or later parts of%@NL@% the program.%@NL@% %@NL@% 3. Lines containing previously set breakpoints are shown in high-intensity%@NL@% text.%@NL@% %@NL@% 4. The dialog window is where you enter dialog commands. These are the%@NL@% commands with optional arguments that you can enter at the CodeView%@NL@% prompt (%@AS@%>%@AE@%). You can scroll up or down in this window to view previous%@NL@% dialog commands and command output.%@NL@% %@NL@% 5. The cursor is a thin, blinking line that shows the location at which%@NL@% you can enter commands from the keyboard. You can move the cursor up%@NL@% and down, and place it in either the dialog or display window.%@NL@% %@NL@% 6. The display/dialog separator line divides the dialog window from the%@NL@% display window.%@NL@% %@NL@% 7. The register window shows the current status of processor registers and%@NL@% flags. It is an optional window that can be opened or closed with one%@NL@% keystroke or with the mouse. If the 386 option is on, a much wider%@NL@% register window is displayed, with 32-bit registers. The register%@NL@% window also displays the effective address at the bottom; the effective%@NL@% address shows the actual location of an operand in physical memory. It%@NL@% is useful when debugging in assembly mode.%@NL@% %@NL@% 8. The scroll bars are the vertical bars on the right side of the screen.%@NL@% Each scroll bar has an up arrow and a down arrow you can use to scroll%@NL@% through the display with a mouse.%@NL@% %@NL@% 9. The optional watch window shows the current status of specified%@NL@% variables or expressions. The watch window appears automatically%@NL@% whenever you create watch statements.%@NL@% %@NL@% 10. The menu bar shows titles of menus and commands that you can activate%@NL@% with the keyboard or the mouse. "Trace" and "Go" represent commands;%@NL@% the other titles are all menus.%@NL@% %@NL@% 11. Menus can be opened by specifying the appropriate title on the menu%@NL@% bar. On the sample screen, the Watch menu has been opened.%@NL@% %@NL@% 12. The menu "highlight" is a reverse-video or colored strip indicating the%@NL@% current selection in a menu. You can move the highlight up or down to%@NL@% change the current selection.%@NL@% %@NL@% 13. The mouse pointer indicates the current position of the mouse. It is%@NL@% shown only if you have a mouse installed on your system.%@NL@% %@NL@% 14. Dialog boxes (not shown) appear in the center of the screen when you%@NL@% choose a menu selection that requires a response. The dialog box%@NL@% prompts you for a response and then it disappears when you enter your%@NL@% answer.%@NL@% %@NL@% 15. Message boxes (not shown) appear in the center of the screen to display%@NL@% errors or other messages.%@NL@% %@NL@% %@CR:MCV21003@%%@4@%The Microsoft CodeView debugger screen elements are described in greater%@EH@% detail in the rest of this chapter.%@NL@% %@NL@% %@NL@% %@CR:MCV21100@%%@3@%%@AB@%2.1.1 Executing Window Commands with the Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21101@%%@4@%The most common CodeView debugging commands, and all the commands for%@EH@% managing the CodeView display, are available with window commands. Window commands are one-keystroke commands that can be entered with CTRL-key combinations, ALT-key combinations, or the direction keys on the numeric keypad.%@NL@% %@NL@% %@CR:MCV21102@%%@4@%Most window commands can also be entered with a mouse, as described in%@EH@% Section 2.1.2.1%@BO: 20e91@%, "Changing the Screen with the Mouse." The window commands available from the keyboard are described by category in Sections 2.1.1.1%@BO: 1cb3e@%-2.1.1.4 below.%@NL@% %@NL@% %@CR:MCV21110@%%@4@%%@AB@%2.1.1.1 Moving the Cursor with Keyboard Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21111@%%@4@%The following keys move the cursor or scroll text up or down in the display%@EH@% or dialog window.%@NL@% %@CR:MCV21112@%%@NL@% %@TH: 97 5324 2 28 48 @%%@AB@%Key Function(Switch Cursor)%@AE@%F6 Moves the cursor between the display and dialog windows. If the cursor is in the dialog window when you press F6, it will move to its previous position in the display window. If the cursor is in the display window, it will move to its previous position in the dialog window.CTRL+G Makes the size of the dialog window or display window grow. This works for whichever window the cursor is in. If the cursor is in the display window, the display/dialog separator line will move down one line. If the cursor is in the dialog window, the separator line will move up one line.CTRL+T Makes the size of the dialog or display window smaller. This works for whichever window the cursor is in. If the cursor is in the display window, the display/dialog separator line will move up one line. If the cursor is in the dialog window, the separator line will move down one line.UP ARROW Moves the cursor up one line in either the display or dialog window.DOWN ARROW Moves the cursor down one line in either the display or dialog window.PGUP Scrolls up one page. If the cursor is in the display window, the source lines or assembly-language instructions scroll up. If the cursor is in the dialog window, the buffer of commands entered during the session scrolls up. The cursor remains at its current position in the window. The length of a page is the current number of lines in the window.PGDN Scrolls down one page. If the cursor is in the display window, the source lines or assembly-language instructions scroll down. If the cursor is in the dialog window, the buffer of commands entered during the session scrolls down. The cursor remains at its current position in the window. The length of a page is the current number of lines in the window.HOME Scrolls to the top of the file, first local variable, or beginning of the current command. If the cursor is in the display or locals window, the text scrolls to the start of the source file, program instructions, or local variables. If the cursor is in the dialog window and you are currently entering a command, the cursor moves to the beginning of the line, right after the prompt.CTRL+HOME Scrolls to the top of the file, first local variable, or beginning of the command buffer. This key produces the same effect that the HOME key does, except that in the dialog window it moves the cursor to the beginning of the command buffer. The top of the command buffer may be blank if you have not yet entered enough commands to fill the buffer. The cursor remains at its current position in the window.END Scrolls to the bottom of the file, last local variable, or the end of the current command. If the cursor is in the display or locals window, the text scrolls to the end of the source file, program instructions, or local variables. If the cursor is in the dialog window and you are entering a command, the cursor moves to the end of the command.CTRL+END Scrolls to the bottom of the file, to the last local variables, or to the end of the command buffer. This key produces the same effect that the END key does, except that in the dialog window, this key moves the cursor to the end of the command buffer.%@TE: 97 5324 2 28 48 @% %@NL@% %@CR:MCV21120@%%@4@%%@AB@%2.1.1.2 Changing the Screen with Keyboard Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21121@%%@4@%The following keys change the screen or switch to a different screen.%@EH@%%@NL@% %@NL@% %@CR:MCV21122@%%@NL@% %@TH: 30 1576 2 28 48 @%%@AB@%Key Function%@AE@%F1 Displays initial on-line Help screen. The Help system is discussed in Section 2.1.4.%@BO: 2bcdf@% You can also take advantage of the Help system by using the Help menu, as mentioned in Section 2.1.3.9.%@BO: 2ba10@%F2 Toggles the register window. The window disappears if present, or appears if absent. You can also toggle the register window with the Register selection from the View menu, as described in Section 2.1.3.2.%@BO: 250d8@%F3 Switches between source, mixed, and asse Source mode shows source code in the display window, whereas assembly mode shows assembly-language instructions. Mixed mode shows both. You can also change modes with the Source, Mixed, and Assembly selections from the View menu, as described in Section 2.1.3.2.%@BO: 250d8@%F4 Switches to the output screen. The output screen shows the output, if any, from your program. Press any key to return to the CodeView screen.%@TE: 30 1576 2 28 48 @% %@NL@% %@CR:MCV21130@%%@4@%%@AB@%2.1.1.3 Controlling Program Execution with Keyboard Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21131@%%@4@%The following keys set and clear breakpoints, trace through your program, or%@EH@% execute to a breakpoint.%@NL@% %@CR:MCV21132@%%@NL@% %@TH: 54 3123 2 28 48 @%%@AB@%Key Function%@AE@%F5 Executes to the next breakpoint or to the end of the program if no breakpoint is encountered. This keyboard command corresponds to the Go dialog command when it is given without a destination breakpoint argument.F7 Sets a temporary breakpoint on the line with the cursor, and executes to that line (or to a previously set breakpoint or the end of the program if either is encountered before the temporary breakpoint). In source mode, if the line does not correspond to code (for example, data declaration or comment lines), the CodeView debugger sounds a warning and ignores the command. This window command corresponds to the Go dialog command when it is given with a destination breakpoint.F8 Executes a Trace command. The CodeView debugger executes the next source line in source mode or the next instruction in assembly mode. If the source line or instruction contains a call to a routine or interrupt, the debugger starts tracing through the call (enters the call and is ready to execute the first source line or instruction). This command will not trace into DOS function calls.F9 Sets a breakpoint or clears a breakpoint on the line with the cursor. If the line does not currently have a breakpoint, one is set on that line. If the line already has a breakpoint, the breakpoint is cleared. If the cursor is in the dialog window, the CodeView debugger sounds a warning and ignores the command. This window command corresponds to the Breakpoint Set and Breakpoint Clear dialog commands.F10 Executes the Program Step command. The debugger executes the next source line in source mode or the next instruction in assembly mode. If the source line or instruction contains a call to a routine or interrupt, the debugger steps over the entire call (executes it to the return) and is ready to execute the line or instruction after the call.%@TE: 54 3123 2 28 48 @% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% You can usually interrupt program execution by pressing either CTRL+BREAK%@NL@% or CTRL+C. These key combinations can be used to exit endless loops or to%@NL@% interrupt loops slowed by the Watchpoint or Tracepoint commands (see%@NL@% Chapter 8%@BO: 5c045@%, "Managing Watch Statements"). CTRL+BREAK or CTRL+C may not%@NL@% work if your program has a special use for one or both of these key%@NL@% combinations. If you have an IBM Personal Computer AT (or an%@NL@% AT-compatible), you can use the SYSTEM-REQUEST key to interrupt execution%@NL@% regardless of your program's use of CTRL+BREAK and CTRL+C.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV21140@%%@4@%%@AB@%2.1.1.4 Selecting from Menus with the Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21141@%%@4@%This section discusses how to make selections from menus with the keyboard.%@EH@% The effects of the selections are discussed in Section 2.1.3%@BO: 23f2f@%, "Using Menu Selections," below.%@NL@% %@NL@% %@CR:MCV21142@%%@4@%The menu bar at the top of the screen has eleven titles: File, View, Search,%@EH@% Run, Watch, Options, Language, Calls, Help, Trace, and Go. The first nine titles are menus, and the last two are commands. The Trace and Go titles are provided primarily for mouse users.%@NL@% %@NL@% %@CR:MCV21143@%%@4@%The four steps for opening a menu and making a selection are described%@EH@% below.%@NL@% %@NL@% %@CR:MCV21144@% 1. To open a menu, press ALT and the mnemonic (the first letter) of the%@NL@% menu title. This can be accomplished either by pressing ALT first,%@NL@% releasing the key, and pressing the letter; or you can hold down ALT%@NL@% and then press the letter. For example, press ALT+S to open the Search%@NL@% menu. The menu title is highlighted, and a menu box listing the%@NL@% selections pops up below the title.%@NL@% %@NL@% The mnemonic is a single letter that represents the selection. In color%@NL@% displays, this letter is in red; in black-and-white displays, it is in%@NL@% bold. In most cases, but not all, the letter is simply the first letter%@NL@% of the name of the selection. You can type an uppercase or a lowercase%@NL@% letter for the same selection.%@NL@% %@NL@% 2. There are two ways to make a selection from an open menu:%@NL@% %@NL@% a. Press the DOWN ARROW key on the numeric keypad to move down the%@NL@% menu. The highlight will follow your movement. When the item you%@NL@% want is highlighted, press ENTER to execute the command.%@NL@% You can also press the UP ARROW key to move up the menu. If you%@NL@% move off the top or bottom of the menu, the highlight wraps around%@NL@% to the other end of the menu.%@NL@% %@NL@% b. Press the key corresponding to the menu-selection mnemonic.%@NL@% %@NL@% 3. After a selection is made from the menu, one of three things will%@NL@% happen:%@NL@% %@NL@% a. For most menu selections, the choice is executed immediately.%@NL@% %@NL@% b. The items on the View, Options, and Language menus have small%@NL@% double arrows next to them if the option is on, or no arrows if%@NL@% the option is off. Choosing the item toggles the option. The%@NL@% status of the arrows will be reversed the next time an option is%@NL@% chosen.%@NL@% %@NL@% c. Some items require a response. In this case, there is another step%@NL@% in the menu-selection process.%@NL@% %@NL@% 4. If the item you select requires a response, a dialog box opens when you%@NL@% select a menu item. Type your response to the prompt in the box and%@NL@% press ENTER. For example, the Find dialog box asks you to enter a%@NL@% regular expression (see Appendix A%@BO: d21a7@% for a complete explanation of%@NL@% regular expressions).%@NL@% %@NL@% If your response is valid, the command will be executed. If you enter%@NL@% an invalid response, a message box will appear, telling you the problem%@NL@% and asking you to press a key. Press any key to make the message box%@NL@% disappear.%@NL@% %@NL@% %@CR:MCV21145@%%@4@%At any point during the process of selecting a menu item, you can press%@EH@% ESCAPE to cancel the menu. While a menu is open, you can press the LEFT ARROW or RIGHT ARROW key to move from one menu to an adjacent menu, or to one of the command titles on the menu bar. Pressing ENTER without entering any characters in response to a message box will also cancel the menu.%@NL@% %@NL@% %@NL@% %@CR:MCV21200@%%@3@%%@AB@%2.1.2 Executing Window Commands with the Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21201@%%@4@%The CodeView debugger is designed to work with the Microsoft Mouse (it also%@EH@% works with some compatible pointing devices). By moving the mouse on a flat surface, you can move the mouse pointer in a corresponding direction on the screen. The following terms refer to the way you select items or execute commands with the mouse.%@NL@% %@NL@% %@CR:MCV21202@%%@NL@% %@AB@%Term Definition %@AE@%%@NL@% %@NL@% Point Move the mouse until the mouse pointer rests on%@NL@% the item you want to select.%@NL@% %@NL@% Click Quickly press and release a mouse button while%@NL@% pointing at an item you want to select.%@NL@% %@NL@% Drag Press a mouse button while on a selected item,%@NL@% then hold the button down while moving the%@NL@% mouse. The item moves in the direction of the%@NL@% mouse movement. When the item you are moving is%@NL@% where you want it, release the button; the item%@NL@% will stay at that place.%@NL@% %@NL@% %@NL@% %@CR:MCV21203@%%@4@%The CodeView debugger uses two mouse buttons. The terms "click Right,"%@EH@% "click Left," "click both," and "click either" are sometimes used to designate which buttons to use. When dragging, either button can be used.%@NL@% %@NL@% %@CR:MCV21210@%%@4@%%@AB@%2.1.2.1 Changing the Screen with the Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21211@%%@4@%You can change various aspects of the screen display by pointing to one of%@EH@% the following elements and then either clicking or dragging.%@NL@% %@CR:MCV21212@%%@NL@% %@TH: 44 3054 2 28 48 @%%@AB@%Item Action %@AE@%%@NL@%%@NL@%Single line separating Drag the separator line up to increase the size%@NL@%display and dialog of the dialog window while decreasing the size%@NL@%windows of the display window, or drag the line down to%@NL@% increase the size of the display window while%@NL@% decreasing the size of the dialog window. You%@NL@% can eliminate either window completely by%@NL@% dragging the line all the way up or down%@NL@% (providing the cursor is not in the window you%@NL@% want to eliminate).%@NL@%%@NL@%UP ARROW or DOWN ARROW Point and click Left on one of the four arrows%@NL@%on the scroll bar on the scroll bars to scroll up or down. If you%@NL@% are in the display window, source code scrolls%@NL@% up or down. If you are in the dialog window, the%@NL@% buffer containing dialog commands entered during%@NL@% the session scrolls up or down.%@NL@%%@NL@% Click Left to scroll up or down just one line at%@NL@% a time. Press Left and hold it down in order to%@NL@% scroll continuously. Continuous scrolling is%@NL@% easier to use when you want to scroll more than%@NL@% a couple of lines. The scrolling stops as soon%@NL@% as you release the mouse button.%@NL@%%@NL@%Scroll bar elevator Each scroll bar has an "elevator," which is a%@NL@% highlighted rectangle on the bar that can be%@NL@% moved up or down with the mouse. In the display%@NL@% window, the elevator indicates your relative%@NL@% position in the source file; if you are in mixed%@NL@% or assembly mode, the elevator indicates your%@NL@% position in the executable file relative to the%@NL@% instructions that correspond to the source file.%@NL@% You can move quickly through the source file by%@NL@% dragging the display window elevator up or down.%@NL@%%@NL@% In the dialog window, the position of the%@NL@% elevator does not have any significance.%@NL@%%@NL@% To move up one page (either in the display or%@NL@% dialog window), click the scroll bar anywhere%@NL@% above the elevator. To move down a page, click%@NL@% the scroll bar anywhere below the elevator.%@NL@%%@TE: 44 3054 2 28 48 @% %@NL@% %@CR:MCV21220@%%@4@%%@AB@%2.1.2.2 Controlling Program Execution with the Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21221@%%@4@%By clicking the following mouse items, you can set and clear breakpoints,%@EH@% trace through your program, execute to a breakpoint, or change flag bits.%@NL@% %@CR:MCV21222@% %@TH: 80 4887 2 28 48 @%%@AB@%Item Action%@AE@%Source line or Point and click on a source line in source modeinstruction or on an instruction in assembly mode to take one of the following actions: %@AB@%Button Result%@AE@% Click Left If the line under the mouse cursor does not have a breakpoint, one is set there. If the line already has a breakpoint, the breakpoint is removed. Lines with breakpoints are shown in high-intensity text. Click Right A temporary breakpoint is set on the line, and the CodeView debugger executes until it reaches the line (or until it reaches a previously set breakpoint or the end of the program if either is encountered before the temporary breakpoint). If you click on a line that does not correspond to code (for example, a declaration or comment), the CodeView debugger will sound a warning and ignore the command."Trace" on menu bar Point and click to trace the next instruction. The kind of trace is determined by which button is clicked: %@AB@%Button Result%@AE@% Click Left The Trace command is executed. The CodeView debugger executes the next source line in source mode or the next instruction in assembly mode. If the source line or instruction contains a call to a routine or interrupt, the debugger starts tracing through the call (it enters the call and is ready to execute the first source line or instruction). This command will not trace into DOS function calls. Click Right The Program Step command is executed. The debugger executes the next source line in source mode, or the next instruction in assembly mode. If the source line or instruction contains a call to a routine or interrupt, the CodeView debugger steps over the entire call (it executes the call to the return) and is ready to execute the line or instruction after the call. These two commands are different only if the current location is the start of a procedure, an interrupt, or a call."Go" on menu bar Point and click either button to execute to the next breakpoint, or to the end of the program if no breakpoints are encountered.Flag in register window Point to a flag name and click either button to reverse the flag. If the flag bit is set, it will be cleared; if the flag bit is cleared, it will be set. The flag name is changed on the screen to match the new status. If you are using color mode, the color of the flag mnemonic will also change. This command can only be used when the register window is open. Use the command with caution since changing flag bits can change program execution at the lowest level.%@TE: 80 4887 2 28 48 @% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% You can usually interrupt program execution by pressing either CTRL+BREAK%@NL@% or CTRL+C. See the note in Section 2.1.1.3%@BO: 1e85f@%, "Controlling Program%@NL@% Execution with Keyboard Commands," for more information.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV21230@%%@4@%%@AB@%2.1.2.3 Selecting from Menus with the Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21231@%%@4@%This section discusses how to make selections from menus with the mouse. The%@EH@% effect of each selection is discussed in Section 2.1.3%@BO: 23f2f@%, "Using Menu Selections."%@NL@% %@NL@% %@CR:MCV21232@%%@4@%The menu bar at the top of the screen has eleven titles: File, View, Search,%@EH@% Run, Watch, Options, Language, Calls, Help, Trace, and Go. The first nine are menus, and the last two are commands that you can execute by clicking with the mouse. The five steps for opening a menu and making a selection are described below:%@NL@% %@NL@% %@CR:MCV21233@% 1. To open a menu, point to the title of the menu you want to select.%@NL@% %@NL@% 2. With the mouse pointer on the title, press and hold down either mouse%@NL@% button. The selected title is highlighted and a menu box with a list of%@NL@% selections pops up below the title.%@NL@% %@NL@% 3. Press and drag the mouse toward you. The highlight follows the mouse%@NL@% movement. You can move the highlight up or down in the menu box.%@NL@% %@NL@% If you move off the box, the highlight will disappear. However, as long%@NL@% as you do not release the button, you can move the pointer back onto%@NL@% the menu to make the highlight reappear.%@NL@% %@NL@% 4. When the selection you want is highlighted, release the mouse button.%@NL@% %@NL@% When you release the button, the menu selection is executed. One of%@NL@% three things will happen:%@NL@% %@NL@% a. For most menu selections, the choice is executed immediately.%@NL@% %@NL@% b. The items on the View, Options, and Language menus have small%@NL@% double arrows next to them if the option is on, or no arrows if%@NL@% the option is off. Choosing the item toggles the option. The%@NL@% status of the arrows on a chosen item will appear reversed the%@NL@% next time you open the menu.%@NL@% %@NL@% c. Some items require a response. In this case, there is another step%@NL@% in the menu-selection process.%@NL@% %@NL@% 5. If the item you select requires a response, a dialog box with a prompt%@NL@% appears. Type your response and press ENTER or a mouse button. For%@NL@% example, if you select Find, the prompt will ask you to enter a regular%@NL@% expression (see Section 2.1.3.3%@BO: 25bfd@%, "The Search Menu," or Appendix A%@BO: d21a7@% for%@NL@% an explanation of regular expressions).%@NL@% %@NL@% If your response is valid, the command will be executed. If you enter%@NL@% an invalid response in the dialog box, a message box will appear%@NL@% telling you the problem and asking you to press a key. Press any key or%@NL@% click a mouse button to make the message box disappear.%@NL@% %@NL@% Also, if you press ENTER without entering any characters, the message%@NL@% box will disappear.%@NL@% %@NL@% %@CR:MCV21234@%%@4@%There are several shortcuts you can take when selecting menu items with the%@EH@% mouse. If you change your mind and decide not to select an item from a menu, just move off the menu and release the mouse button──the menu will disappear. You can move from one menu to another by dragging the pointer directly from the current menu to the title of the new menu.%@NL@% %@NL@% %@NL@% %@CR:MCV21300@%%@3@%%@AB@%2.1.3 Using Menu Selections%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21301@%%@4@%This section describes the selections on each of the CodeView menus. These%@EH@% selections can be made with the keyboard, as described in Section 2.1.1%@BO: 1c85a@%, or with the mouse, as described in Section 2.1.2.%@BO: 20854@%%@NL@% %@NL@% %@CR:MCV21302@%%@4@%Note that although the Trace and Go commands appear on the menu bar, they%@EH@% are not menus. These titles are provided primarily for mouse users.%@NL@% %@NL@% %@CR:MCV21310@%%@4@%%@AB@%2.1.3.1 The File Menu%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21311@%%@4@%The File menu includes selections for working on the current source or%@EH@% program file. The File menu is shown in Figure 2.2%@FN@% Figure 2.2 is found on page 46 of the printed version.%@EF@%, and the selections are explained below.%@NL@% %@CR:MCV21312@%%@NL@% %@TH: 59 3605 2 28 48 @%%@AB@%Selection Action%@AE@%Open Opens a new file. When you make this selection, a dialog box appears asking for the name of the new file you want to open. Type the name of a source file, an include file, or any other text file. The text of the new file replaces the current contents of the display window (if you are in assembly mode, the CodeView debugger will switch to source mode). When you finish viewing the file, you can reopen the original file. The last location and breakpoints will still be marked when you return. You may not need to open a new file to see source files for a different module of your program. The CodeView debugger automatically switches to the source file of a module when program execution enters that module. Although switching source files is never necessary, it may be desirable if you want to set breakpoints or execute to a line in a module not currently being executed. Note that if the debugger cannot find the source file when it switches modules, a dialog box appears asking for a file specification for the source file. You can either enter a new file specification if the file is in another directory, or press ENTER if no source file exists. If you press ENTER, the module can only be debugged in assembly mode.DOS Shell Exits to a DOS shell. This where you can execute DOS commands or executable files. To return to the CodeView debugger, type %@AS@%exit%@AE@% at the DOS command prompt. The CodeView screen reappears with the same status it had when you left it. The Shell Escape command works by saving the current processes in memory and then executing a second copy of %@AB@%C%@AE@% OMMAND.COM. This requires more than 200K of free memory, since the debugger, COMMAND.COM, symbol tables, and the debugged program must all be saved in memory. If you do not have enough memory to execute the Shell Escape command, an error message appears. Even if you have enough memory to execute the command, you may not have enough memory left to execute large programs from the shell. The Shell Escape command does not work under certain conditions. See Section 11.7%@BO: 7b01d@% for additional information.Exit Terminates the debugger and returns to DOS.%@TE: 59 3605 2 28 48 @% %@CR:MCV21320@%%@4@%%@AB@%2.1.3.2 The View Menu%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21321@%%@4@%The View menu includes selections for switching between source and assembly%@EH@% modes, and for switching between the debugging screen and the output screen. The corresponding function keys for menu selection are shown on the right side of the menu where appropriate. The View menu is shown in Figure 2.3%@FN@% Figure 2.3 is found on page 48 of the printed version.%@EF@%, and the selections are explained below.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The terms "source mode" and "assembly mode" apply to Microsoft Macro%@NL@% Assembler programs as well as to high-level-language programs. Source%@NL@% mode used with assembler programs shows the source code as originally%@NL@% written, including comments and directives. Assembly mode displays%@NL@% unassembled machine code, without symbolic information.%@NL@% %@NL@% The use of one mode or another affects Trace and Program Step commands,%@NL@% as explained in Chapter 5%@BO: 3d63b@%, "Executing Code."%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV21322@%%@4@%At all times exactly one of the following selections will have a small%@EH@% double arrow to the left of the name: Source, Mixed, and Assembly. This arrow indicates which of the three display modes is in use. If you select a mode when you are already in that mode, the selection will be ignored. The Registers selection may or may not have a double arrow to the left, depending on whether or not the register window is being displayed.%@AB@%%@NL@% %@CR:MCV21323@%%@NL@% %@AB@%Selection Action %@AE@%%@EH@%%@NL@% %@NL@% Source Changes to source mode (showing source lines%@NL@% only).%@NL@% %@NL@% Mixed Changes to mixed mode (showing both unassembled%@NL@% machine code and source lines).%@NL@% %@NL@% Assembly Changes to assembly mode (showing only%@NL@% unassembled machine code).%@NL@% %@NL@% Registers Selecting this option will toggle the register%@NL@% window on and off. You can also turn the%@NL@% register on and off by pressing F2.%@NL@% %@NL@% Output Selecting this option will display the output%@NL@% screen. The entire CodeView display will%@NL@% temporarily disappear, but come back as soon as%@NL@% you press any key. The Output command can also%@NL@% be selected with F4.%@NL@% %@NL@% %@NL@% %@CR:MCV21330@%%@4@%%@AB@%2.1.3.3 The Search Menu%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21331@%%@4@%The Search menu includes selections for searching through text files for%@EH@% text strings and searching executable code for labels. The Search menu is shown in Figure 2.4%@FN@% Figure 2.4 is found on page 49 of the printed version.%@EF@%, and the selections are explained below.%@NL@% %@CR:MCV21332@%%@NL@% %@TH: 86 5324 2 28 48 @%%@AB@%Selection Action %@AE@%Find Searches the current source file or other text file for a specified regular expression. (This selection can also be made without pulling down a menu by pressing CTRL+F.) When you make this selection, a dialog box opens asking you to enter a regular expression. Type the expression you want to search for and press ENTER. The CodeView debugger starts at the current or most recent cursor position in the display window and searches for the expression. If your entry is found, the cursor moves to the first source line containing the expression. If you are in assembly mode, the debugger automatically switches to source mode when the expression is found. If the entry is not found, a message box opens, telling you the problem and asking you to press a key (you can also click a mouse button) to continue. Regular expressions are a method of specifying variable text strings. This method is similar to the DOS method of using wild cards in file names. Regular expressions are explained in detail in Appendix A of this manual. You can use the Search selections without understanding regular expressions. Since text strings are the simplest form of regular expressions, you can simply enter a string of characters as the expression you want to find. For example, you could enter %@AS@%count%@AE@% if you wanted to search for the word "count." The following characters have a special meaning in regular expressions: backslash (%@AB@%\%@AE@%), asterisk (%@AB@%*%@AE@%), left bracket (%@AB@%[%@AE@%), period (%@AB@%.%@AE@%), dollar sign (%@AB@%$%@AE@%), and caret (%@AB@%^%@AE@%). In order to find strings containing these characters, you must precede the characters with a backslash; this cancels their special meanings. For example, the periods in FORTRAN relational and logical operators must be preceded by back-slashes. You would use %@AS@%%@AE@%%@AS@%\.EQ%@AE@%%@AS@% %@AE@%%@AS@%%@AE@% to find the%@AS@%.EQ%@AE@% operator. With C, you would use %@AS@%%@AE@%%@AS@%\*ptr%@AE@%%@AS@% %@AE@%%@AS@%%@AE@% to find%@AE@% %@AS@%%@AE@%%@AS@%*ptr%@AE@%; with BASIC, you would use %@AS@%%@AE@%%@AS@%NAME\$%@AE@% to find%@AE@% %@AS@%%@AE@%%@AS@%NAME$%@AE@%. The Case Sense selection from the Options menu has no effect on searching for regular expressions.Next Searches for the next match of the current regular expression. This selection is meaningful only after you have used the Search command to specify the current regular expression. If the CodeView debugger searches to the end of the file without finding another match for the expression, it wraps around and starts searching at the beginning of the file.Previous Searches for the previous match of the current regular expression. This selection is meaningful only after you have used the Search command to specify the current regular expression. If the debugger searches to the beginning of the file without finding another match for the expression, it wraps around and starts searching at the end of the file.Label Searches the executable code for an assembly-language label. If the label is found, the cursor moves to the instruction containing the label. If you start the search in source mode, the debugger will switch to assembly mode to show a label in a library routine or an assembly-language module.%@TE: 86 5324 2 28 48 @% %@NL@% %@CR:MCV21340@%%@4@%%@AB@%2.1.3.4 The Run Menu%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21341@%%@4@%The Run menu includes selections for running your program. The Run menu is%@EH@% shown in Figure 2.5%@FN@% Figure 2.5 is found on page 51 of the printed version.%@EF@%, and the selections are explained below.%@NL@% %@CR:MCV21342@% %@TH: 33 1676 2 28 48 @%%@AB@%Selection Action%@AE@%Start Starts the program from the beginning and runs it. Any previously set breakpoints or watch statements will still be in effect. The CodeView debugger will run your program from the beginning to the first breakpoint, or to the end of the program if no breakpoint is encountered. This has the same effect as selecting Restart (see the next selection), then entering the Go command.Restart Restarts the current program, but does not begin executing it. You can debug the program again from the beginning. Any previously set breakpoints or watch statements will still be in effect.Execute Executes from the current instruction. This is the same as the Execute dialog command (%@AB@%E%@AE@%). To stop execution, press any key or a mouse button.Clear Breakpoints Clears all breakpoints. This selection may be convenient after selecting Restart if you don't want to use previously set breakpoints. Note that watch statements are not cleared by this command.%@TE: 33 1676 2 28 48 @% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Although the Start and Restart selections retain breakpoints along with%@NL@% pass count and arguments, any instructions entered with the Assemble%@NL@% command will be overwritten by the original program.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV21350@%%@4@%%@AB@%2.1.3.5 The Watch Menu%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21351@%%@4@%The Watch menu includes selections for managing the watch window. Selections%@EH@% on this menu are also available with dialog commands. The Watch menu is shown in Figure 2.6%@FN@% Figure 2.6 is found on page 52 of the printed version.%@EF@%, and the selections are explained below.%@NL@% %@CR:MCV21352@%%@NL@% %@TH: 81 5051 2 28 49 @%%@AB@%Selection Action%@AE@%Add Watch Adds a watch-expression statement to the watch window. (This selection can also be made directly, by pressing CTRL+W.) A dialog window opens, asking for the source-level expression (which may be simply a variable) whose value you want to see displayed in the watch window. Type the expression and press ENTER or a mouse button. The statement appears in the watch window in normal text. You cannot specify a memory range to be displayed with the Add Watch selection as with the Watch dialog command. You can specify the format in which the value will be displayed. Type the expression, followed by a comma and a CodeView format specifier. If you do not give a format specifier, the CodeView debugger displays the value in a default format. See Chapter 6%@BO: 43f5c@%, "Examining Data and Expressions," for more information about format specifiers and the default format. See Section 8.2%@BO: 5ceb8@%, "Setting Watch-Expression and Watch-Memory Statements," for more information about the Watch command.Watchpoint Adds a watchpoint statement to the window. A dialog window opens, asking for the source-level expression whose value you want to test. The watchpoint statement appears in the watch window in high-intensity text when you enter the expression. A watchpoint is a conditional breakpoint that causes execution to stop when the expression becomes nonzero (true). See Section 8.3%@BO: 5ebff@%, "Setting Watchpoints," for more information.Tracepoint Adds a tracepoint statement to the watch window. A dialog window opens, asking for the source-level expression or memory range whose value you want to test. The tracepoint statement appears in the watch window in high-intensity text when you enter the expression. A tracepoint is a conditional breakpoint that causes execution to stop when the value of a given expression changes. You cannot specify a memory range to be tested with the Tracepoint selection as you can with the Tracepoint dialog command. When setting a tracepoint expression, you can specify the format in which the value will be displayed. After the expression type a comma and a format specifier. If you do not give a format specifier, the CodeView debugger displays the value in a default format. See Chapter 6%@BO: 43f5c@%, "Examining Data and Expressions," for more information about format specifiers and default. See Section 8.4%@BO: 6059c@%, "Setting Tracepoints," for more information about tracepoints.Delete Watch Deletes a statement from the watch window. (This selection can also be made directly, by pressing CTRL+U.) A dialog window opens, showing the current watch statements. If you are using a mouse, move the pointer to the statement you want to delete and click either button. If you are using the keyboard, press the UP ARROW or DOWN ARROW key to move the highlight to the statement you want to delete, then press ENTER.Delete All Watch Deletes all statements in the watch window. All watch, watchpoint, and tracepoint statements are deleted, the watch window disappears, and the display window is redrawn to take advantage of the freed space on screen.%@TE: 81 5051 2 28 49 @% %@NL@% %@CR:MCV21360@%%@4@%%@AB@%2.1.3.6 The Options Menu%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21361@%%@4@%The Options menu allows you to set options that affect various aspects of%@EH@% the behavior of the CodeView debugger. The Options menu is shown in Figure 2.7%@FN@% Figure 2.7 is found on page 54 of the printed version.%@EF@%, and the selections are explained below.%@NL@% %@NL@% %@CR:MCV21362@%%@4@%Selections on the Options menu have small double arrows to the left of the%@EH@% selection name when the option is on. The status of the option (and the presence of the double arrows) is reversed each time you select the option. By default, the Flip/Swap and Bytes Coded options are on and the 386 option is off when you start the CodeView debugger. Depending on which language your main program is in, the debugger will automatically turn Case Sense on (if your program is in C) or off (if your program is in another language) when you start debugging.%@AB@%%@NL@% %@NL@% %@CR:MCV21363@%%@4@%The selections from the Options menu are discussed below.%@EH@%%@NL@% %@CR:MCV21364@%%@NL@% %@TH: 80 4684 2 28 58 @%%@AB@%Selection Action%@AE@%Flip/Swap When on (the default), screen swapping or screen flipping (whichever the debugger was started with) is active; when off, swapping or flipping is disabled. Turning off swapping or flipping makes the screen scroll more smoothly. You will not see the program flip or swap each time you execute part of the program. This option has no effect if neither swapping nor flipping was selected during start-up. ─────────────────────────────────────────────── %@AI@%WARNING%@AE@% Any time your program writes to the screen, make sure flipping or swapping is on. If swapping and flipping are off, your program writes the output at the location of the cursor. The CodeView debugger detects the screen has changed and redraws the screen, thus destroying the program output. An error message is also displayed: %@AS@%Flip/Swap%@AE@% %@AS@%option off - application output lost%@AE@%. ───────────────────────────────────────────────Bytes Coded When on (the default), the instructions, instruction addresses, and the bytes for each instruction are shown; when off, only the instructions are shown. This option affects only assembly mode. The following display shows the appearance of sample code when the option is off: The following display shows the appearance of the same code when the option is on: 27: name = gets(namebuf);<R> LEA AX,Word Ptr [namebuf]<R> PUSH AX<R> CALL _gets (03E1)<R> ADD SP,02<R> MOV Word Ptr [name],AX The following display shows the appearance of the same code when the option is on: 27: name = gets(namebuf); 32AF:003E 8D46DE LEA AX,Word Ptr [namebuf] 32AF:0041 50 PUSH AX 32AF:0042 E89C03 CALL _gets (03E1) 32AF:0045 83C402 ADD SP,02 32AF:0048 8946DA MOV Word Ptr [name],AXCase Sense When the selection is turned on, the CodeView debugger assumes that symbol names are case sensitive (each lowercase letter is different from the corresponding uppercase letter); when off, symbol names are not case sensitive. This option is on by default for C programs and off by default for FORTRAN, BASIC, and assembly programs. You will probably want to leave the option in its default setting.386 (DOS Only) When on, the register window will display the registers in the wider, 386 format. Furthermore, this option will enable you to assemble and execute instructions that reference 32-bit registers. If the 386 option is not on, any data stored in the high-order word of a 32-bit register will be lost. To use this option, you should have a 386 processor running in 386 mode. If you do not have a 386 processor, the debugger will respond with the message, %@AS@%CPU is not an 80386%@AE@%, and leave the option turned off.%@TE: 80 4684 2 28 58 @% %@NL@% %@CR:MCV21370@%%@4@%%@AB@%2.1.3.7 The Language Menu%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21371@%%@4@%The Language menu allows you to either select the expression evaluator or%@EH@% instruct the CodeView debugger to select it for you automatically. The Language menu is shown in Figure 2.8%@FN@% Figure 2.8 is found on page 56 of the printed version.%@EF@%, and the selections are explained below.%@NL@% %@NL@% %@CR:MCV21372@%%@4@%As with the Options menu, the selection on is marked by double arrows.%@EH@% Unlike the Options menu, however, exactly one item (and no more) on the Language menu is selected at any given time.%@AB@%%@NL@% %@NL@% %@CR:MCV21373@%%@4@%The Auto selection causes the debugger to select automatically the%@EH@% expression evaluator each time a new source file is loaded. The debugger will examine the extension of the source file in order to determine which expression evaluator to select. The Auto selection will use the C expression evaluator if the current source file does not have a .BAS, .F, .FOR, or .PAS extension.%@NL@% %@NL@% %@CR:MCV21374@%%@4@%If you change to a source module with an .ASM extension, Auto will cause the%@EH@% debugger to select the C expression evaluator, but not all of the C defaults will be used; system radix will be hexadecimal, case sensitivity will be turned off, and the register window will be displayed.%@NL@% %@NL@% %@CR:MCV21375@%%@4@%When a language expression evaluator is selected, the debugger uses that%@EH@% evaluator, regardless of what kind of program is being debugged.%@NL@% %@NL@% %@CR:MCV21380@%%@4@%%@AB@%2.1.3.8 The Calls Menu%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21381@%%@4@%The Calls menu is different from other menus in that its contents and size%@EH@% change depending on the status of your program. The Calls menu is shown in Figure 2.9%@FN@% Figure 2.9 is found on page 57 of the printed version.%@EF@%.%@NL@% %@NL@% %@CR:MCV21382@%%@4@%The mnemonic for each item in the Calls menu is a number. Type the number%@EH@% displayed immediately to the left of a routine in order to select it. You can also use the UP ARROW or DOWN ARROW key to move to your selection, and then press ENTER. You can use the mouse to select from the Calls menu as well.%@NL@% %@NL@% %@CR:MCV21383@%%@4@%The effect of making a selection from the Calls menu is to view a routine.%@EH@% The cursor will go to the line at which the selected routine was last executing. For example, selecting %@AS@%main%@AE@% in the example above will cause CodeView to display %@AS@%main%@AE@%, at the point at which %@AS@%main%@AE@% made a call to %@AS@%calc%@AE@% (the function immediately above it). Note that selecting a routine from the Calls menu does not (by itself) affect program execution. It simply provides a convenient way to view previously called routines.%@NL@% %@NL@% %@CR:MCV21384@%%@4@%It is not required that one of the routines be selected. The Calls menu is%@EH@% useful for viewing the list of previously called routines.%@NL@% %@NL@% %@CR:MCV21385@%%@4@%The Calls menu shows the current routine and the trail of routines from%@EH@% which it was called. The current routine is always at the top. The routine from which the current routine was called is directly below. Other active routines are shown in the reverse order in which they were called. With C and FORTRAN programs, the bottom routine should always be %@AB@%main%@AE@%. (The only time %@AB@%main%@AE@% will not be the bottom routine is when you are tracing through the standard library's start-up or termination routines.)%@NL@% %@NL@% %@CR:MCV21386@%%@4@%The current value of each argument, if any, is shown in parentheses%@EH@% following the routine. The menu expands to accommodate the arguments of the widest routine. Arguments are shown in the current radix (the default is decimal). If there are more active routines than will fit on the screen, or if the routine arguments are too wide, the display will expand to both the left and right. The Stack Trace dialog command (%@AB@%K%@AE@%) also shows all the routines and arguments.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% If you are using the CodeView debugger to debug assembly-language%@NL@% programs, routines will be shown in the Calls menu only if they use one%@NL@% of the Microsoft calling conventions. These calling conventions are%@NL@% explained in the Microsoft Mixed-Language Programming Guide.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV21390@%%@4@%%@AB@%2.1.3.9 The Help Menu%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21391@%%@4@%The Help menu lists the major topics in the on-line Help. For Help, open the%@EH@% Help menu and select the topic you want to view.%@NL@% %@NL@% %@CR:MCV21392@%%@4@%Each topic may have any number of subtopics. You must go to the major topic%@EH@% first. Information on how to move around within the help system is provided in the next section.%@NL@% %@NL@% %@CR:MCV21393@%%@4@%The bottom selection on the Help menu is the About command. When you make%@EH@% this selection, the debugger displays a small box at the center of the screen that gives the time, the name of the product, and the version number.%@NL@% %@NL@% %@NL@% %@CR:MCV21400@%%@3@%%@AB@%2.1.4 Using On-Line Help%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV21401@%%@4@%The CodeView on-line Help system uses tree-structured menus to give you%@EH@% quick access to help screens on a variety of subjects. Help uses a combination of menu access and sequentially linked screens, as explained below.%@NL@% %@NL@% %@CR:MCV21402@%%@4@%The Help file is called CV.HLP. It must be present in the current directory%@EH@% or in one of the directories specified with the DOS PATH command. If the Help file is not found, the CodeView debugger will still operate, but you will not be able to use Help. An error message will appear if you try to use a Help command.%@NL@% %@NL@% %@CR:MCV21403@%%@4@%When you request help, either by pressing F1, by using the %@AB@%H%@AE@% dialog command,%@EH@% or by selecting the Help menu, the first help screen appears. You can select Next and Previous buttons to page through the screens. The screens are arranged in a circular fashion, so that selecting Next on the last screen gets you to the first screen. Select the Cancel button to return to the CodeView screen. Pressing the PGDN, PGUP, and ESC keys achieves the same results as selecting Next, Previous, and Cancel, respectively, with the mouse.%@NL@% %@NL@% %@CR:MCV21404@%%@4@%You can enter Help at a particular topic by selecting the topic from the%@EH@% Help menu. Once in Help, use Next and Previous to page to other screens.%@NL@% %@NL@% %@NL@% %@CR:MCV22000@%%@2@%%@AB@%2.2 Using Sequential Mode%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV22001@%%@4@%Sequential mode is required if you have neither an IBM Personal Computer nor%@EH@% a closely compatible computer. In sequential mode, the CodeView debugger works much like its forerunner, the Microsoft Symbolic Debug Utility (SYMDEB) and the DOS DEBUG utility. Sequential mode is also useful when you are using redirected CodeView input and output.%@NL@% %@NL@% %@CR:MCV22002@%%@4@%In sequential mode, the CodeView debugger's input and output always move%@EH@% down the screen from the current location. When the screen is full, the old output scrolls off the top of the screen to make room for new output appearing at the bottom. You can never return to examine previous commands once they scroll off, but in many cases, you can reenter the command to put the same information on the screen again.%@NL@% %@NL@% %@CR:MCV22003@%%@4@%Most window commands cannot be used in sequential mode. However, the%@EH@% following function keys, which are used as commands in window mode, are also available in sequential mode.%@NL@% %@CR:MCV22004@%%@NL@% %@TH: 60 3138 2 28 48 @%%@AB@%Command Action%@AE@%F1 Displays a command-syntax summary.F2 Displays the registers. This is equivalent to the Register (%@AB@%R%@AE@%) dialog command.F3 Toggles between source, mixed, and assembly modes. Pressing this key will rotate the mode between source, mixed, and assembly. You can achieve the same effect by using the Set Assembly (%@AB@%S-%@AE@%), Set Mixed (%@AB@%S&%@AE@%), and Set Source (%@AB@%S+%@AE@%) dialog commands.F4 Switches to the output screen, which shows the output of your program. Press any key to return to the CodeView debugging screen. This is equivalent to the Screen Exchange (%@AB@%\%@AE@%) dialog command.F5 Executes from the current instruction until a breakpoint or the end of the program is encountered. This is equivalent to the Go dialog command (%@AB@%G%@AE@%) with no argument.F8 Executes the next source line in source mode, or the next instruction in assembly mode. If the source line or instruction contains a function, procedure, or interrupt call, the CodeView debugger executes the first source line or instruction of the call and is ready to execute the next source line or instruction within the call. This is equivalent to the Trace (%@AB@%T%@AE@%) dialog command.F9 Sets or clears a breakpoint at the current program location. If the current program location has no breakpoint, one is set. If the current location has a breakpoint, it is removed. This is equivalent to the Breakpoint Set (%@AB@%BP%@AE@%) dialog command with no argument.F10 Executes the next source line in source mode or the next instruction in assembly mode. If the source line or instruction contains a function, procedure, or interrupt call, the call is executed to the end, and the CodeView debugger is ready to execute the line or instruction after the call. This is equivalent to the Program Step (%@AB@%P%@AE@%) dialog command.%@TE: 60 3138 2 28 48 @% %@NL@% %@CR:MCV22005@%%@4@%The CodeView Watch (%@AB@%W%@AE@%), Watchpoint (%@AB@%WP%@AE@%), and Tracepoint (%@AB@%TP%@AE@%) commands work in sequential mode, but since there is no watch window, the watch statements are not shown. You must use the Watch List command (%@AB@%W%@AE@%) to examine watch statements and watch values. See Chapter 8%@BO: 5c045@% for information on watch statement commands.%@NL@% %@NL@% %@CR:MCV22006@%%@4@%All the CodeView commands that affect program operation (such as Trace, Go,%@EH@% and Breakpoint Set) are available in sequential mode. Any debugging operation done in window mode can also be done in sequential mode.%@NL@% %@NL@% %@NL@% %@CR:MCV30000@%%@1@%%@AB@%Chapter 3 Using Dialog Commands%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV30001@%%@4@%CodeView dialog commands can be used in sequential mode or from the dialog%@EH@% window. In sequential mode, they are the primary method of entering commands. In window mode, dialog commands are used to enter commands that require arguments or do not have corresponding window commands.%@NL@% %@NL@% %@CR:MCV30002@%%@4@%Many window commands have duplicate dialog commands. Generally, the window%@EH@% version of a command is more convenient, but the dialog version is more powerful. For example, to set a breakpoint on a source line in window mode, put the cursor on the source line and press F9, or point to the line and click the left mouse button. The dialog version of the Breakpoint command (%@AB@%BP%@AE@%) requires more keystrokes, but it allows you to specify an address, a pass count, and a string of commands to be taken whenever the breakpoint is encountered.%@NL@% %@NL@% %@CR:MCV30003@%%@4@%The rest of this chapter explains how to enter dialog commands and how to%@EH@% select text on the screen for use with commands.%@NL@% %@NL@% %@NL@% %@CR:MCV31000@%%@2@%%@AB@%3.1 Entering Commands and Arguments%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV31001@%%@4@%Dialog commands are entered at the CodeView prompt(%@AS@%>%@AE@%). Type the command and%@EH@% arguments and press ENTER.%@NL@% %@NL@% %@CR:MCV31002@%%@4@%In window mode, you can enter commands whether or not the cursor is at the%@EH@% CodeView prompt. If the cursor is not in the dialog window, it moves to the dialog window as soon as you type text.%@NL@% %@NL@% %@NL@% %@CR:MCV31100@%%@3@%%@AB@%3.1.1 Using Special Keys%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV31101@%%@4@%When entering dialog commands or viewing output from commands, you can use%@EH@% the following special keys:%@NL@% %@CR:MCV31102@%%@NL@% %@TH: 25 1636 2 28 48 @%%@AB@%Key Action%@AE@%CTRL+C Stops the current output or cancels the current command line. For example, if you are watching a long display from a Dump command, you can press CTRL+C to interrupt the output and return to the CodeView prompt. If you make a mistake while entering a command, you can press CTRL+C to cancel the command without executing it. A new prompt appears, and you can reenter the command.CTRL+S Pauses during the output of a command. You can press any key to continue output. For example, if you are watching a long display from a Dump command, you can press CTRL+S when a part of the display appears that you want to examine more closely. Then press any key when you are ready for the output to continue scrolling.BACKSPACE Deletes the previous character on the command line and moves the cursor back one space. For example, if you make an error while typing a command, you can use the BACKSPACE key to delete the characters back to the error──then retype the remainder of the command.%@AB@%%@TE: 25 1636 2 28 48 @% %@NL@% %@CR:MCV31200@%%@3@%%@AB@%3.1.2 Using the Command Buffer%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV31201@%%@4@%In window mode, the CodeView debugger has a command buffer where the last%@EH@% 2-4 screens of commands and command output are stored. The command buffer is not available in sequential mode.%@NL@% %@NL@% %@CR:MCV31202@%%@4@%When the cursor is in the dialog window, you can scroll up or down to view%@EH@% the commands you have entered earlier in the session. The commands for moving the cursor and scrolling through the buffer are explained in sections 2.1.1.1%@BO: 1cb3e@% and 2.1.2.1%@BO: 20e91@%.%@NL@% %@NL@% %@CR:MCV31203@%%@4@%Scrolling through the buffer is particularly useful for viewing the output%@EH@% from commands, such as Dump or Examine Symbols, whose output may scroll off the top of the dialog window.%@NL@% %@NL@% %@CR:MCV31204@%%@4@%If you have scrolled through the dialog buffer to look at previous commands%@EH@% and output, you can still enter new commands. When you type a command, the cursor moves to the end of the command buffer and the text appears on a new line.%@NL@% %@NL@% %@CR:MCV31205@%%@4@%When you start the debugger, the buffer is empty except for the copyright%@EH@% message. As you enter commands during the session, the buffer is gradually filled from the bottom to the top. If you have not filled the entire buffer and you press HOME to go to the top of the buffer, you will not see the first commands of the session. Instead you will see blank lines, since there is nothing at the top of the buffer.%@NL@% %@NL@% %@NL@% %@CR:MCV32000@%%@2@%%@AB@%3.2 Format for CodeView Commands and Arguments%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV32001@%%@4@%The CodeView command format is similar to the format of the earlier%@EH@% Microsoft debuggers, SYMDEB and DEBUG. However, some features, particularly operators and expressions, are different. The general format for CodeView commands is shown below:%@NL@% %@NL@% %@AI@%command%@AE@% «%@AI@%arguments%@AE@%» «;%@AI@%command2%@AE@%»%@NL@% %@NL@% %@CR:MCV32002@%%@4@%The %@AI@%command%@AE@% is a one-, two-, or three-character command name, and %@AI@%arguments%@AE@%%@EH@% are expressions that represent values or addresses to be used by the command. The %@AI@%command%@AE@% is not case sensitive; any combination of uppercase and lowercase letters can be used. However, %@AI@%arguments%@AE@% consisting of source-level expressions may or may not be case sensitive. (For example, C expressions are normally case sensitive; FORTRAN expressions are not. Case sensitivity can be affected by the language selected for expression evaluation.) Usually, the first %@AI@%argument%@AE@% can be placed immediately after %@AI@%command%@AE@% with no space separating the two fields.%@NL@% %@NL@% %@CR:MCV32003@%%@4@%The number of arguments required or allowed with each command varies. If a%@EH@% command takes two or more arguments, you must separate the arguments with spaces. A semicolon (%@AB@%;%@AE@%) can be used as a command separator if you want to specify more than one command on a line.%@NL@% %@NL@% %@CR:MCV32004@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% DB 100 200 %@AI@%;* Example 1%@AE@%%@NL@% %@NL@% >U Label1 %@AI@%;* Example 2, C variable as argument%@AE@%%@NL@% %@NL@% >U SUM %@AI@%;* Example 3, FORTRAN variable as argument%@AE@%%@NL@% %@NL@% >U SUM; DB %@AI@%;* Example 4, multiple commands%@AE@%%@NL@% %@NL@% %@CR:MCV32005@%%@4@%In Example 1, %@AS@%DB%@AE@% is the first command (for the Dump Bytes command). The%@EH@% arguments to the command are %@AS@%100%@AE@% and %@AS@%200%@AE@%. The second command on this line is the Comment command (%@AS@%*%@AE@%). A semicolon is used to separate the two commands. The Comment command is used throughout the rest of the manual to number examples.%@NL@% %@NL@% %@CR:MCV32006@%%@4@%In Example 2, %@AS@%U%@AE@% is the first command (for the Unassemble command), and the%@EH@% C-language variable %@AS@%Label1%@AE@% is a command argument.%@NL@% %@NL@% %@CR:MCV32007@%%@4@%In Example 3, %@AS@%U%@AE@% is again the first command (for the Unassemble command), and%@EH@% the FORTRAN variable %@AS@%SUM%@AE@% is a command argument.%@NL@% %@NL@% %@CR:MCV32008@%%@4@%Example 4 consists of three commands, separated by semicolons. The first is%@EH@% the Unassemble command ( %@AS@%U%@AE@%) with the FORTRAN variable %@AS@%SUM%@AE@% as an argument. The second is the Dump Bytes command (%@AS@%DB%@AE@%) with no arguments. The third is the Comment command (%@AS@%*%@AE@%).%@NL@% %@NL@% %@NL@% %@CR:MCV33000@%%@2@%%@AB@%3.3 Selecting Text for Use with Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV33001@%%@4@%If you run CodeView in window mode, you can select text on the screen and%@EH@% use this same text as a command. This technique is useful for reusing a dialog command that is not among the last 20. Any text that appears in any window can be selected.%@NL@% %@NL@% %@CR:MCV33002@%%@4@%To select and use text onscreen, follow these steps:%@EH@%%@NL@% %@NL@% %@CR:MCV33003@% 1. Select text with either the mouse or keyboard.%@NL@% %@NL@% To select text with the mouse, move the mouse cursor to the beginning%@NL@% of the desired text, hold the left mouse button down and drag the mouse%@NL@% to the left. When you have dragged the mouse to the end of the desired%@NL@% text, release the button.%@NL@% %@NL@% To select text with the keyboard, move the cursor to the beginning of%@NL@% the desired text, hold the SHIFT key down, and move the cursor to the%@NL@% right. When the cursor is at the end of the desired text, release the%@NL@% SHIFT key and press ENTER.%@NL@% %@NL@% 2. To use the selected text, press INS.%@NL@% %@NL@% 3. Edit the command if desired, and press ENTER to execute.%@NL@% %@NL@% %@NL@% %@CR:MCV40000@%%@1@%%@AB@%Chapter 4 CodeView Expressions%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV40001@%%@4@%CodeView command arguments are expressions that can include symbols,%@EH@% constant numbers, operators, and registers. Arguments can be simple machine-level expressions that directly specify an address or range in memory, or they can be source-level expressions that correspond to operators and symbols used in Microsoft C, FORTRAN, BASIC, or the Macro Assembler. For each high-level language (C, FORTRAN, and BASIC), CodeView has an expression evaluator that computes the value of source-level expressions.%@NL@% %@NL@% %@CR:MCV40002@%%@4@%Each of the three expression evaluators has a different set of operators and%@EH@% rules of precedence. However, the basic syntax for registers, addresses, and line numbers is the same regardless of the language. You can always change the expression evaluator. If you specify a language other than the one used in the source file, the expression evaluator will still recognize your program symbols──if possible. (C and FORTRAN, however, will not accept BASIC type tags.) If you are debugging an assembly routine called from BASIC or FORTRAN, you may want to choose the language of the main program rather than C, the default for assembly programs.%@NL@% %@NL@% %@CR:MCV40003@%%@4@%If the Auto option is on, the debugger examines the file extension of each%@EH@% new source file you trace through. Both C and assembly modules cause the debugger to select C as the expression evaluator.%@NL@% %@NL@% %@CR:MCV40004@%%@4@%This chapter first deals with the expressions specific to each language.%@EH@% Line-number expressions are presented next; they work the same way regardless of the language. Then, register and address expressions are described. Generally, these do not have to be mastered unless you are doing assembly-level debugging. Finally, the chapter describes how to switch the expression evaluator.%@NL@% %@NL@% %@NL@% %@CR:MCV41000@%%@2@%%@AB@%4.1 C Expressions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV41001@%%@4@%The C expression evaluator uses a subset of the most commonly used C%@EH@% operators. It also supports the colon operator (%@AB@%:%@AE@%), which is described in Section 4.6.2%@BO: 3a308@%, "Addresses," and the three memory operators (%@AB@%BY%@AE@%, %@AB@%WO%@AE@%, and %@AB@%DW%@AE@%), which are discussed in Section 4.7.%@BO: 3b6ea@% The memory operators are primarily useful for debugging assembly source code. The CodeView C expression operators are listed in Table 4.1 in order of precedence. The superscripts a, b, and c refer to explanatory footnotes.%@NL@% %@NL@% %@CR:MCV4T100@%%@4@%%@AB@%Table 4.1 CodeView C Expression Operators%@AE@%%@EH@%%@NL@% %@TH: 25 1414 1 16 60 @%%@AB@%Precedence Operators%@AE@%(Highest)1 %@AB@%( ) [ ] -> .%@AE@%2 %@AB@%! ~ -%@AE@%%@FN@%The minus sign with precedence 2 is the %@AI@%unary minus%@AE@% indicating the sign ofa number; the minus sign with precedence 4 is a %@AI@%binary minus%@AE@% indicatingsubtraction.%@EF@% (%@AI@%type%@AE@%) %@AB@%++ -- %@AE@%%@AB@%*%@AE@%%@FN@%The asterisk with precedence 2 is the pointer operator; the asterisk withprecedence 3 is the multiplication operator.%@EF@% %@AB@%&%@AE@%%@FN@%The ampersand with precedence 2 is the address-of operator. The ampersandas a bitwise %@AB@%AND%@AE@% operator is not supported by the CodeViewdebugger.%@EF@% %@AB@%sizeof%@AE@%3 %@AB@%*%@AE@%%@FN@%The asterisk with precedence 2 is the pointer operator; the asterisk withprecedence 3 is the multiplication operator.%@EF@% %@AB@%/ % :%@AE@%4 %@AB@%+ -%@AE@%%@FN@%The minus sign with precedence 2 is the %@AI@%unary minus%@AE@% indicating the sign ofa number; the minus sign with precedence 4 is a %@AI@%binary minus%@AE@% indicatingsubtraction.%@EF@%5 %@AB@%< > <= >=%@AE@%6 %@AB@%== !=%@AE@%7 %@AB@%&&%@AE@%8 %@AB@%||%@AE@%9 %@AB@%= += -= *= /= %=%@AE@%10 %@AB@%BY WO DW%@AE@%(Lowest)%@TE: 25 1414 1 16 60 @% %@NL@% %@CR:MCV41002@%%@4@%See the %@AI@%Microsoft C Compiler Language Reference%@AE@% for a description of how C%@EH@% operators can be combined with identifiers and constants to form expressions. With the C expression evaluator, the period (%@AB@%.%@AE@%) has its normal use as a member selection operator, but it also has an extended use as a specifier of local variables in parent functions. The syntax is shown below:%@NL@% %@NL@% %@AI@%function%@AE@%.%@AI@%variable%@AE@%%@NL@% %@NL@% %@CR:MCV41003@%%@4@%The %@AI@%function%@AE@% must be a high-level-language function, and the %@AI@%variable%@AE@% must%@EH@% be a local variable within the specified function. The %@AI@%variable%@AE@% cannot be a register variable. For example, you can use the expression %@AS@%main.argc%@AE@% to refer to the local variable %@AS@%argc%@AE@% when you are in a function that has been called by %@AS@%main%@AE@%.%@NL@% %@NL@% %@CR:MCV41004@%%@4@%The %@AI@%type%@AE@% operator (used in type casting) can be any of the predefined C%@EH@% types. The CodeView debugger limits casts of pointer types to one level of indirection. For example, %@AS@%(char *)sym%@AE@% is accepted, but %@AS@%(char **)sym%@AE@% is not.%@NL@% %@NL@% %@CR:MCV41005@%%@4@%When a C expression is used as an argument with a command that takes%@EH@% multiple arguments, the expression should not have any internal spaces. For example, %@AS@%count+6%@AE@% is allowed, but %@AS@%count + 6%@AE@% may be interpreted as three separate arguments. Some commands (such as the Display Expression command) do permit spaces in expressions.%@NL@% %@NL@% %@NL@% %@CR:MCV41100@%%@3@%%@AB@%4.1.1 C Symbols%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV41101@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AI@%name%@AE@%%@NL@% %@NL@% %@CR:MCV41102@%%@4@%A symbol is a name that represents a register, a segment address, an offset%@EH@% address, or a full 32-bit address. At the C source level, a symbol is a variable name or the name of a function. Symbols (also called identifiers) follow the naming rules of the C compiler. Although CodeView command letters are not case sensitive, symbols given as arguments are case sensitive (unless you have turned off case sensitivity with the Case Sense selection from the Options menu).%@NL@% %@NL@% %@CR:MCV41103@%%@4@%In assembly-language output or in output from the Examine Symbols command,%@EH@% the CodeView debugger displays some symbol names in the object-code format produced by the Microsoft C Compiler. This format includes a leading underscore. For example, the function %@AS@%main%@AE@% is displayed as %@AS@%_main.%@AE@% Only global labels (such as procedure names) are shown in this format. You do not need to include the underscore when specifying such a symbol in CodeView commands. Labels within library routines are sometimes displayed with a double underscore %@AS@%(__chkstk)%@AE@%. You must use two leading underscores when accessing these labels with CodeView commands.%@NL@% %@NL@% %@NL@% %@CR:MCV41200@%%@3@%%@AB@%4.1.2 C Constants%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV41201@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AI@%digits%@AE@% Default radix%@NL@% %@AB@%0%@AE@%%@AI@%digits%@AE@% Octal radix%@NL@% %@AB@%0x%@AE@%%@AI@%digits%@AE@% Hexadecimal radix%@NL@% %@AB@%0n%@AE@%%@AI@%digits%@AE@% Decimal radix%@NL@% %@NL@% %@CR:MCV41202@%%@4@%Numbers used in CodeView commands represent integer constants. They are made%@EH@% up of octal, hexadecimal, or decimal digits, and are entered in the current input radix. The C-language format for entering numbers of different radixes can be used to override the current input radix.%@NL@% %@NL@% %@CR:MCV41203@%%@4@%The default radix for the C expression evaluator is decimal. However, you%@EH@% can use the Radix command (%@AB@%N%@AE@%) to specify an octal or hexadecimal radix, as explained in Section 11.3%@BO: 77bd5@%, "Radix Command."%@NL@% %@NL@% %@CR:MCV41204@%%@4@%If the current radix is 16 (hexadecimal) or 8 (octal), you can enter decimal%@EH@% numbers in the special CodeView format %@AB@%0n%@AE@%%@AI@%digits%@AE@%. For example, you would enter 21 decimal as %@AS@%0n21%@AE@%.%@NL@% %@NL@% %@CR:MCV41205@%%@4@%With radix 16, it is possible to enter a value or argument that could be%@EH@% interpreted either as a symbol or as a hexadecimal number. The CodeView debugger resolves the ambiguity by searching first for a symbol (identifier) with that name. If no symbol is found, the debugger interprets the value as a hexadecimal number. If you want to enter a number that overrides an existing symbol, use the hexadecimal format (%@AB@%0x%@AE@%%@AI@%digits%@AE@%).%@NL@% %@NL@% %@CR:MCV41206@%%@4@%For example, if you enter %@AS@%abc%@AE@% as an argument when the program contains a%@EH@% variable or function named %@AS@%abc%@AE@%, the CodeView debugger interprets the argument as the symbol. If you want to enter %@AS@%abc%@AE@% as a number, enter it as%@AE@% %@AS@%0xabc%@AE@%.%@NL@% %@NL@% %@CR:MCV41207@%%@4@%Table 4.2 shows how a sample number (63 decimal) would be represented in%@EH@% each radix.%@NL@% %@NL@% %@CR:MCV4T200@%%@4@%%@AB@%Table 4.2 C Radix Examples%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%Input Radix Octal Decimal Hexadecimal%@AE@%%@NL@% %@NL@% 8 %@AS@%77 0n63 0x3F %@AE@%%@NL@% %@NL@% 10 %@AS@%077 63 0x3F %@AE@%%@NL@% %@NL@% 16 %@AS@%077 0n63 3F%@AE@%%@NL@% %@NL@% %@NL@% %@CR:MCV41300@%%@3@%%@AB@%4.1.3 C Strings%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV41301@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%"%@AE@%%@AI@%null-terminated-string%@AE@%%@AB@%"%@AE@%%@NL@% %@NL@% %@CR:MCV41302@%%@4@%Strings can be specified as expressions in the C format. You can use C%@EH@% escape characters within strings. For example, double quotation marks within a string are specified with the escape character %@AS@%\"%@AE@%.%@NL@% %@NL@% %@CR:MCV41303@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% EA message "This \"string\" is okay."%@NL@% %@NL@% %@CR:MCV41304@%%@4@%The example uses the Enter ASCII command (%@AB@%EA%@AE@%) to enter the given string into%@EH@% memory starting at the address of the variable %@AS@%message.%@AE@%%@NL@% %@NL@% %@NL@% %@CR:MCV42000@%%@2@%%@AB@%4.2 FORTRAN Expressions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV42001@%%@4@%The FORTRAN expression evaluator uses a subset of the most commonly used%@EH@% FORTRAN operators. It also supports two additional operators, the period (%@AB@%.%@AE@%) and the colon (%@AB@%:%@AE@%). A number of FORTRAN intrinsic functions, which are listed in Section 4.2.4%@BO: 34369@%, are also supported. FORTRAN function calls are permitted, but statement function names and COMMON block names are not. (Note that these limitations only apply to the arguments of CodeView commands. They do not apply to the source program, which can contain any valid FORTRAN expression.)%@NL@% %@NL@% %@CR:MCV42002@%%@4@%The CodeView FORTRAN operators are listed in Table 4.3 in order of%@EH@% precedence.%@NL@% %@NL@% %@CR:MCV4T300@%%@4@%%@AB@%Table 4.3 CodeView FORTRAN Operators%@AE@%%@EH@%%@NL@% %@TH: 27 514 2 16 60 @%%@AB@%Precedence Operators%@AE@%(Highest)1 %@AB@%()%@AE@%2 %@AB@%. :%@AE@%3 Unary %@AB@%+ -%@AE@%4 %@AB@%* /%@AE@%5 Binary %@AB@%+ -%@AE@%6 %@AB@%.LT. .LE. .EQ. .NE. .GT. .GE.%@AE@%7 %@AB@%.NOT.%@AE@%8 %@AB@%.AND.%@AE@%9 %@AB@%.OR.%@AE@%10 %@AB@%.EQV. .NEQV.%@AE@%11 %@AB@%=%@AE@%(Lowest)%@TE: 27 514 2 16 60 @% %@NL@% %@CR:MCV42003@%%@4@%The FORTRAN expression evaluator does not support the character%@EH@% concatenation operator (%@AB@%//%@AE@%) or the exponentiation operator (%@AB@%**%@AE@%). Relational operators are not supported for string variables or constants.%@NL@% %@NL@% %@CR:MCV42004@%%@4@%The order and precedence with which the CodeView debugger evaluates FORTRAN%@EH@% expressions are the same as in the Microsoft FORTRAN language. See Chapter 1%@BO: 9668@%, "Elements of FORTRAN" of the %@AI@%Microsoft FORTRAN Reference%@AE@% for a description of how FORTRAN operators can be combined with symbols and constants to form expressions.%@NL@% %@NL@% %@CR:MCV42005@%%@4@%The colon operator (%@AB@%:%@AE@%) may be used when specifying a memory address. It acts%@EH@% as a %@AI@%segment%@AE@%%@AB@%:%@AE@%%@AI@%offset%@AE@% separator, as described in Section 4.6.2%@BO: 3a308@%, "Addresses."%@NL@% %@NL@% %@CR:MCV42006@%%@4@%In the CodeView debugger, the period (%@AB@%.%@AE@%) has an extended use as a specifier%@EH@% of local variables in parent routines. The syntax is shown below:%@NL@% %@NL@% %@AI@%routine%@AE@%.%@AI@%variable%@AE@%%@NL@% %@NL@% %@CR:MCV42007@%%@4@%The %@AI@%routine%@AE@% must be a high-level-language routine and the %@AI@%variable%@AE@% must be a%@EH@% local variable within the specified routine. For example, you can use the expression %@AS@%main.X%@AE@% to refer to the local variable %@AS@%X%@AE@% in the procedure %@AS@%main%@AE@% if you are in a routine called by %@AS@%main%@AE@%. Note that in this example, %@AS@%main%@AE@% refers to the main routine of a FORTRAN or C program. It does not appear in FORTRAN source code.%@NL@% %@NL@% %@NL@% %@CR:MCV42100@%%@3@%%@AB@%4.2.1 FORTRAN Symbols%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV42101@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AI@%name%@AE@%%@NL@% %@NL@% %@CR:MCV42102@%%@4@%A symbol is a name that represents a register, a segment address, an offset%@EH@% address, or a full 32-bit address. At the FORTRAN source level, a symbol is simply a variable name or the name of a routine; you do not necessarily need to know what kind of address it represents. When given as arguments, symbols are never case sensitive with the FORTRAN expression evaluator. If you have turned on case sensitivity with the Case Sense selection from the Options menu, it is turned off automatically when a symbol is used.%@NL@% %@NL@% %@CR:MCV42103@%%@4@%In assembly-language output or in output from the Examine Symbols command,%@EH@% the CodeView debugger displays some symbol names in the object-code format produced by the Microsoft FORTRAN Optimizing Compiler. This format includes a leading underscore. For example, the main routine in your program is displayed as %@AS@%_main%@AE@%. Only global labels (such as procedure names) are shown in this format. You do not need to include the underscore when specifying such a symbol in CodeView commands. Labels within library routines are sometimes displayed with a double underscore %@AS@%(__chkstk)%@AE@%. You must use leading underscores when accessing these labels with CodeView commands.%@NL@% %@NL@% %@NL@% %@CR:MCV42200@%%@3@%%@AB@%4.2.2 FORTRAN Constants%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV42201@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AI@%digits%@AE@% Default radix%@NL@% %@AI@%radix#digits%@AE@% Specified radix%@NL@% %@AI@%#digits%@AE@% Hexadecimal radix%@NL@% %@NL@% %@CR:MCV42202@%%@4@%Numbers used in CodeView commands represent integer constants. These%@EH@% constants are entered in the current input radix (base). When you are using the FORTRAN expression evaluator, the debugger will recognize any explicitly specified radix between 2 and 36 inclusive, as in %@AS@%20#2G.%@AE@% The FORTRAN radix specifiers can be used to override the current radix. Note that a hexadecimal number may be entered in two ways. For example, 3F hex could be entered as either %@AS@%#3F%@AE@% or %@AS@%16#3F%@AE@%. In this manual, the number sign alone is used to indicate hexadecimal numbers.%@NL@% %@NL@% %@CR:MCV42203@%%@4@%The default radix for the FORTRAN version of the CodeView debugger is%@EH@% decimal. However, you can use the Radix command (%@AB@%N%@AE@%) to specify an octal or hexadecimal radix, as explained in Section 11.3%@BO: 77bd5@%, "Radix Command."%@NL@% %@NL@% %@CR:MCV42204@%%@4@%With radix 16, it is possible to enter a value or argument that could be%@EH@% interpreted either as an identifier or as a hexadecimal number. The CodeView debugger resolves the ambiguity by searching first for a symbol (identifier) with that name. If no symbol is found, the debugger interprets the value as a hexadecimal number. If you want to enter a number that overrides an existing symbol, use the hexadecimal format (%@AS@%#%@AE@%%@AI@%digits%@AE@%).%@NL@% %@NL@% %@CR:MCV42205@%%@4@%For example, if you enter %@AS@%ABC%@AE@% as an argument when the program contains a%@EH@% variable or function named %@AS@%ABC%@AE@%, the CodeView debugger interprets the argument as the symbol. If you want to enter %@AS@%ABC%@AE@% as a number, enter it as %@AS@%#ABC.%@AE@%%@NL@% %@NL@% %@CR:MCV42206@%%@4@%Table 4.4 shows how a sample number (63 decimal) would be represented in the%@EH@% octal, decimal, and hexadecimal radixes.%@NL@% %@NL@% %@CR:MCV4T400@%%@4@%%@AB@%Table 4.4 FORTRAN Radix Examples%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%Input Radix Octal Decimal Hexadecimal%@AE@%%@NL@% %@NL@% 8 %@AS@%77 10#63 #3F %@AE@%%@NL@% %@NL@% 10 %@AS@%8#77 63 #3F %@AE@%%@NL@% %@NL@% 16 %@AS@%8#77 10#63 3F %@AE@%%@NL@% %@NL@% %@NL@% %@CR:MCV42300@%%@3@%%@AB@%4.2.3 FORTRAN Strings%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV42301@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%'%@AE@%%@AI@%string%@AE@%%@AB@%'%@AE@%%@NL@% %@NL@% %@CR:MCV42302@%%@4@%Strings can be specified as character expressions in the FORTRAN format.%@EH@% Single quotation marks within a string must be specified by two single quotation marks.%@NL@% %@NL@% %@CR:MCV42303@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% EA MESSAGE 'This ''string'' is okay. '%@NL@% %@NL@% %@CR:MCV42304@%%@4@%The example above uses the Enter ASCII command (%@AB@%EA%@AE@%) to enter the given%@EH@% string into memory, starting at the address of the variable %@AS@%MESSAGE%@AE@%. Notice that the string includes embedded single quotation marks and trailing blanks.%@NL@% %@NL@% %@NL@% %@CR:MCV42400@%%@3@%%@AB@%4.2.4 FORTRAN Intrinsic Functions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV42401@%%@4@%When entering a FORTRAN expression, you may use a limited number of FORTRAN%@EH@% intrinsic functions. The primary use of these functions is to convert a FORTRAN variable or value from one type to another for purposes of calculation. The intrinsic functions recognized by the expression evaluator of the CodeView debugger are listed in Table 4.5. See Chapter 5%@BO: 3d63b@%, "Intrinsic Functions and Additional Procedures" of the %@AI@%Microsoft FORTRAN Reference%@AE@% for a complete description of the FORTRAN intrinsic functions.%@NL@% %@NL@% %@CR:MCV4T500@%%@4@%%@AB@%Table 4.5 FORTRAN Intrinsic Functions Supported by the CodeView Debugger%@AE@%%@EH@% %@TH: 51 2760 3 23 17 26 10 @%%@AB@% Argument Function%@AE@%%@AB@%Name Definition Type Type%@AE@%%@AB@%CHAR(%@AE@%%@AI@%int%@AE@%%@AB@%)%@AE@% Data-type int char%@FN@%The abbreviations used for the different data types in this table are listedin Chapter 5, "Intrinsic Functions and Additional Procedures" of the%@AI@%Microsoft FORTRAN Reference%@AE@%.%@EF@% conversion%@AB@%CMPLX(%@AE@%%@AI@%genA%@AE@%«,%@AI@%genB%@AE@%») Data-type int, real, or cmp cmp8 conversion%@AB@%DBLE(%@AE@%%@AI@%gen%@AE@%%@AB@%)%@AE@% Data-type int, real, or cmp dbl conversion%@AB@%DCMPLX(%@AE@%%@AI@%genA%@AE@%«,%@AI@%genB%@AE@%») Data-type int, real, or cmp cmp16 conversion%@AB@%DIMAG(%@AE@%%@AI@%cmp16%@AE@%%@AB@%)%@AE@% Imaginary cmp16 dbl part of cmp16 number%@AB@%DREAL(%@AE@%%@AI@%cmp16%@AE@%%@AB@%)%@AE@% Data-type cmp16 dbl conversion%@AB@%ICHAR(%@AE@%%@AI@%char%@AE@%%@AB@%)%@AE@% Data-type char int conversion%@AB@%IMAG(%@AE@%%@AI@%cmp%@AE@%%@AB@%)%@AE@% Imaginary cmp real%@FN@%If argument is %@AB@%COMPLEX*8%@AE@%, function is %@AB@%REAL*4%@AE@%. If argument is %@AB@%COMPLEX*16%@AE@%,function is %@AB@%DOUBLE PRECISION%@AE@%%@EF@% part of cmp number%@AB@%INT(%@AE@%%@AI@%gen%@AE@%%@AB@%)%@AE@% Data-type int, real, or cmp int conversion%@AB@%INT1(%@AE@%%@AI@%gen%@AE@%%@AB@%)%@AE@% Data-type int, real, or cmp int1 conversion%@AB@%INT4(%@AE@%%@AI@%gen%@AE@%%@AB@%)%@AE@% Data-type int, real, or cmp int4 conversion%@AB@%INTC(%@AE@%%@AI@%gen%@AE@%%@AB@%)%@AE@% Data-type int, real, or cmp %@AB@%INTEGER%@AE@%[%@AB@%C%@AE@%] conversion%@AB@%LOCFAR(%@AE@%%@AI@%gen%@AE@%%@AB@%)%@AE@% Segmented int, real, or cmp int4 address%@AB@%LOCNEAR%@AE@%(%@AI@%gen%@AE@%%@AB@%)%@AE@% Unsegmented int, real, or cmp int2 address%@AB@%REAL(%@AE@%%@AI@%gen%@AE@%%@AB@%)%@AE@% Data-type int, real, or cmp real4 conversion%@TE: 51 2760 3 23 17 26 10 @% %@NL@% %@CR:MCV43000@%%@2@%%@AB@%4.3 BASIC Expressions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV43001@%%@4@%The BASIC expression evaluator uses a subset of the most commonly used BASIC%@EH@% operators. It also supports one important BASIC command──the %@AB@%LET%@AE@% command──and one operator in addition to the BASIC operators──the colon (%@AB@%:%@AE@%). The CodeView BASIC operators are listed in Table 4.6 in order of precedence.%@NL@% %@NL@% %@CR:MCV4T700@%%@4@%%@AB@%Table 4.6 CodeView BASIC Operators%@AE@%%@EH@%%@NL@% %@TH: 31 573 2 16 60 @%%@AB@%Precedence Operators%@AE@%(Highest)1 %@AB@%()%@AE@%2 %@AB@%. :%@AE@%3 %@AB@%* /%@AE@%4 %@AB@%\ MOD%@AE@%5 %@AB@%+ -%@AE@%6 %@AB@%= <> < > <= >=%@AE@%7 %@AB@%NOT%@AE@%8 %@AB@%AND%@AE@%9 %@AB@%OR%@AE@%10 %@AB@%XOR%@AE@%11 %@AB@%EQV%@AE@%12 %@AB@%IMP%@AE@%13 %@AB@%LET%@AE@% %@AI@%variable%@AE@% %@AB@%=%@AE@%(Lowest)%@TE: 31 573 2 16 60 @% %@NL@% %@CR:MCV43002@%%@4@%The BASIC expression evaluator does not support the exponentiation operator%@EH@% (%@AB@%^%@AE@%). Nor does it support string assignment, the string concatenation operator (%@AB@%+%@AE@%), or any of the relational operators (%@AB@%=%@AE@%,%@AB@%<%@AE@%,%@AB@%>%@AE@%,etc.), when used with strings. However, arrays, records, and user-defined types are all supported.%@AS@%%@NL@% %@NL@% %@CR:MCV43003@%%@4@%The order and precedence with which the CodeView debugger evaluates BASIC%@EH@% expressions are the same as in the Microsoft BASIC language. See your BASIC documentation for a description of how BASIC operators can be combined with symbols and constants to form expressions.%@NL@% %@NL@% %@CR:MCV43004@%%@4@%The assignment operator %@AB@%LET%@AE@% is supported for numerical operations only. When%@EH@% you use %@AB@%LET%@AE@% in a BASIC expression, the return value will not be useful. However, an assignment will take place whenever the expression is evaluated. This gives you a convenient way of manipulating data. For example, after the expression %@AS@%LET A = 5%@AE@% is evaluated, the variable %@AS@%A%@AE@% will contain the value 5. You must use the keyword %@AB@%LET%@AE@% to specify assignment; otherwise, the BASIC expression evaluator will interpret the equal sign (%@AB@%=%@AE@%) as a test for equality.%@NL@% %@NL@% %@CR:MCV43005@%%@4@%The colon operator (%@AB@%:%@AE@%) may be used to specify a memory address. It acts as a%@EH@% %@AI@%segment%@AE@%%@AS@%:%@AE@%%@AI@%offset%@AE@% separator, as described in Section 4.6.2%@BO: 3a308@%, "Addresses."%@NL@% %@NL@% %@CR:MCV43006@%%@4@%In the CodeView debugger, the period (.) has an extended use as a specifier%@EH@% of local variables in parent routines. The syntax is shown below:%@NL@% %@NL@% routine.variable%@NL@% %@NL@% %@CR:MCV43007@%%@4@%The %@AS@%routine%@AE@% must be a high-level-language routine and the %@AS@%variable%@AE@% must be a%@EH@% local variable within the routine.%@NL@% %@NL@% %@CR:MCV43008@%%@4@%When a BASIC expression is used as an argument with a command that takes%@EH@% multiple arguments, the expression should not have any internal spaces. For example, %@AS@%COUNT+6%@AE@% is allowed, but %@AS@%COUNT%@AE@%%@AS@%+ 6%@AE@% may be interpreted as three arguments. Some commands (such as the Display Expression command) only take one argument; these commands do permit spaces in expressions.%@NL@% %@NL@% %@NL@% %@CR:MCV43100@%%@3@%%@AB@%4.3.1 BASIC Symbols%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV43101@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AI@%name%@AE@%%@NL@% %@NL@% %@CR:MCV43102@%%@4@%A symbol is a name that represents a register, a segment address, an offset%@EH@% address, or a full 32-bit address. At the BASIC source level, a symbol is simply a variable name or the name of a routine; you do not necessarily need to know what kind of address it represents. With the BASIC expression evaluator, symbols follow the naming rules of the BASIC compiler. In particular, all the type specifiers used in BASIC (%@AB@%$%@AE@%, %@AB@%%%@AE@%, %@AB@%&%@AE@%, %@AB@%!%@AE@%, and %@AB@%#%@AE@%) are accepted by the BASIC expression evaluator. Symbols are never case sensitive to BASIC, whether the Case Sense option is on or not.%@AS@%%@NL@% %@NL@% %@NL@% %@CR:MCV43200@%%@3@%%@AB@%4.3.2 BASIC Constants%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV43201@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AI@%fixed-point-string%@AE@%«%@AS@%#%@AE@%|%@AS@%!%@AE@%» Single or double, fixed-point format %@AI@%floating-point-string%@AE@%«%@AS@%#%@AE@%| %@AS@%!%@AE@%» Single or double, floating-point format %@AI@%digits%@AE@% Integer, default radix %@AB@%&O%@AE@%%@AI@%digits%@AE@% Octal radix %@AB@%&%@AE@%%@AI@%digits%@AE@% Alternative octal radix %@AB@%&H%@AE@%%@AI@%digits%@AE@% Hexadecimal radix %@NL@% %@CR:MCV43202@%%@4@%With the BASIC expression evaluator, numbers can be entered as integer,%@EH@% long, single-precision, or double-precision data objects. Constants are formed according to the rules of the Microsoft BASIC Compiler. A single- or double-precision constant must be entered in decimal radix, regardless of the current system radix. To enter a single or double, use the Microsoft BASIC rules for forming fixed and floating point strings.%@NL@% %@NL@% %@CR:MCV43203@%%@4@%Integer constants are entered in the system radix and are made up of octal,%@EH@% decimal, or hexadecimal digits. You may override the system radix by using the octal, or hexadecimal prefix. In addition, you can use the %@AB@%&%@AE@% suffix on any integer constant to indicate that the integer is to be stored as a long (four-byte) integer, rather than as a short (two-byte) integer. To enter integers in the decimal format, the system radix must be 10, and you use the default radix. There is no way to enter decimal integers when the system radix is other than 10, unless you switch to another expression evaluator.%@NL@% %@NL@% %@CR:MCV43204@%%@4@%The default radix for the BASIC expression evaluator is decimal. However,%@EH@% you can use the Radix command (%@AB@%N%@AE@%) to specify an octal or hexadecimal radix, as explained in Section 11.3%@BO: 77bd5@%, "Radix Command." With radix 16, it is possible to enter a value or argument that could be interpreted either as an identifier or as a hexadecimal number. The CodeView debugger resolves the ambiguity by searching first for a symbol (identifier) with that name. If no symbol is found, the debugger interprets the value as a hexadecimal number. If you want to enter a number that overrides an existing symbol, use the hexadecimal format (%@AB@%&H%@AE@%%@AI@%digits%@AE@%).%@NL@% %@NL@% %@CR:MCV43205@%%@4@%For example, if you enter %@AS@%ABC%@AE@% as an argument when the program contains a%@EH@% variable or function named %@AS@%ABC%@AE@%, the CodeView debugger interprets the argument as the symbol. If you want to enter %@AS@%ABC%@AE@% as a number, enter it as %@AS@%&HABC%@AE@%.%@NL@% %@NL@% %@CR:MCV43206@%%@4@%Table 4.7 shows how a sample number (63 decimal) would be represented in the%@EH@% octal, decimal, and hexadecimal radixes.%@NL@% %@NL@% %@CR:MCV4T800@%%@4@%%@AB@%Table 4.7 BASIC Radix Examples%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%Input Radix Octal Decimal Hexadecimal%@AE@%%@NL@% %@NL@% 8 %@AS@%77 - &H3F %@AE@%%@NL@% %@NL@% 10 %@AS@%&O77 63 &H3F %@AE@%%@NL@% %@NL@% 16 %@AS@%&O77 - 3F %@AE@%%@NL@% %@NL@% %@NL@% %@CR:MCV43300@%%@3@%%@AB@%4.3.3 BASIC Strings%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV43301@%%@4@%The BASIC expression evaluator does not allow you to input strings while%@EH@% debugging. However, it does recognize both fixed and variable-length string variables, as defined by the BASIC compiler. (This includes arrays and records of strings.) Expressions that refer to strings will probably be quite simple, because string operators (concatenation and relational operators) are not supported by the BASIC expression evaluator.%@NL@% %@NL@% %@CR:MCV43302@%%@4@%By using the Enter Address command, you can enter a string literal at a%@EH@% given address. To use this technique effectively, however, you will need to understand how BASIC handles string variables. For more information, see Chapter 6%@BO: 43f5c@%, "Examining Data and Expressions."%@NL@% %@NL@% %@NL@% %@CR:MCV43400@%%@3@%%@AB@%4.3.4 BASIC Intrinsic Functions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV43401@%%@4@%When entering a BASIC expression, you may use a limited number of BASIC%@EH@% intrinsic functions. The primary use of these functions is to convert a BASIC variable or value from one type to another for purposes of calculation. The intrinsic functions recognized by the expression evaluator of the CodeView debugger are listed in Table 4.8. See your BASIC compiler manual for a complete description of the BASIC intrinsic functions.%@NL@% %@NL@% %@CR:MCV4T900@%%@4@%%@AB@%Table 4.8 BASIC Intrinsic Functions Supported by the CodeView Debugger%@AE@%%@EH@%%@NL@% %@TH: 38 2180 3 24 27 27 18 @%%@AB@% Argument Function%@AE@%%@AB@%Name Definition Type Type%@AE@%%@AB@%ASC%@AE@%%@FN@%Except where noted, each of the functions in this table takes exactly oneargument of the type indicated in the third column%@EF@% ASCII value of first string integer character%@AB@%CDBL%@AE@% Data-type conversion numerical expression double%@AB@%CINT%@AE@% Conversion, with numerical expression integer rounding%@AB@%CSGN%@AE@% Data-type conversion numerical expression single%@AB@%CVI%@AE@% Data-type conversion two-byte string integer%@AB@%CVL%@AE@% Data-type conversion four-byte string long%@AB@%CVS%@AE@% Data-type conversion four-byte string short%@AB@%CVD%@AE@% Data-type conversion eight-byte string double%@AB@%FIX%@AE@% Conversion, with numerical expression integer truncation%@AB@%INT%@AE@% Conversion, with numerical expression integer truncation%@AB@%LBOUND(%@AE@%%@AI@%arr%@AE@%%@AB@%«,%@AE@%%@AI@%dim%@AE@%%@AB@%»)%@AE@% Lowest index of array array, dimension integer%@AB@%UBOUND(%@AE@%%@AI@%arr%@AE@%%@AB@%«,%@AE@%%@AI@%dim%@AE@%%@AB@%»)%@AE@% Highest index of array array, dimension integer%@AB@%VAL%@AE@% Numerical value of string integer, long, string single, or double%@AB@%VARPTR%@AE@% Offset of variable variable name integer%@AB@%VARSEG%@AE@% Segment of variable variable name integer%@TE: 38 2180 3 24 27 27 18 @% %@NL@% %@CR:MCV44000@%%@2@%%@AB@%4.4 Assembly Expressions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV44001@%%@4@%The /ZI option, available with Version 5.0 and later of the Microsoft Macro%@EH@% Assembler, provides variable size information for the CodeView debugger. This makes for correct evaluation of expressions derived from assembly code (except with arrays, which are discussed later in this section). If you have an earlier version of the Macro Assembler, you will need to use C type casts to get correct evaluation.%@NL@% %@NL@% %@CR:MCV44002@%%@4@%When a program assembles or when the Auto switch is on, source files with an%@EH@% .ASM extension will cause CodeView to select the C expression evaluator. How-ever, the following options will be set differently from the C default options:%@NL@% %@NL@% %@CR:MCV44003@% ■ System radix is hexadecimal (not decimal).%@NL@% %@NL@% ■ Register window is on.%@NL@% %@NL@% ■ Case sense is off.%@NL@% %@NL@% %@CR:MCV44004@%%@4@%The C expression evaluator supports the memory operators described in%@EH@% Section 4.7%@BO: 3b6ea@%, and generally is the appropriate expression evaluator with which to debug assembly because of its flexibility.%@NL@% %@NL@% %@CR:MCV44005@%%@4@%However, you cannot always use the C expression evaluator to specify an%@EH@% expression exactly as it would appear in assembly code. The list below describes the principal differences between assembler syntax and syntax used with the C expression evaluator.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The examples below present expressions, not CodeView commands. You can%@NL@% see the results of these expressions by using them as operands for the%@NL@% Display Expression command (%@AB@%?%@AE@%), described in Chapter 6%@BO: 43f5c@%, "Examining Data%@NL@% and Expressions."%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV44006@%%@4@%In the following list, examples of assembly source code are shown in the%@EH@% left-hand column. Corresponding CodeView expressions (with the C expression evaluator) are shown in the right-hand column.%@NL@% %@NL@% %@CR:MCV44007@% 1. Register indirection.%@NL@% %@NL@% The C expression evaluator does not extend the use of brackets to%@NL@% registers. To refer to the byte, word, or double word pointed to by a%@NL@% register, use the %@AB@%BY%@AE@%, %@AB@%WO%@AE@%, or %@AB@%DW%@AE@% operator.%@NL@% %@NL@% %@AS@%BYTE PTR [bx] BY bx%@AE@%%@NL@% %@AS@%WORD PTR [bp] WO bp%@AE@%%@NL@% %@AS@%DWORD PTR [bp] DW bp%@AE@%%@NL@% %@NL@% 2. Register indirection with displacement.%@NL@% %@NL@% To perform based, indexed, or based-index indirection with a%@NL@% displacement, use either the %@AB@%BY%@AE@%, %@AB@%WO%@AE@%, or %@AB@%DW%@AE@% operator along with addition%@NL@% in a complex expression:%@NL@% %@NL@% %@AS@%BYTE PTR [di+6] BY di+6%@AE@%%@NL@% %@AS@%BYTE PTR [si][bp+6] BY si+bp+6%@AE@%%@NL@% %@AS@%WORD PTR [bx][si] WO bx+si%@AE@%%@NL@% %@NL@% 3. Taking the address of a variable.%@NL@% %@NL@% Use the ampersand (%@AB@%&%@AE@%) to get the address of a variable with the C%@NL@% expression evaluator.%@NL@% %@NL@% %@AS@%OFFSET var &var%@AE@%%@NL@% %@NL@% 4. The %@AB@%PTR%@AE@% operator.%@NL@% %@NL@% With the CodeView debugger, C type casts perform the same function as%@NL@% the assembler %@AB@%PTR%@AE@% operator.%@NL@% %@NL@% %@AS@%BYTE PTR var (char) var%@AE@%%@NL@% %@AS@%WORD PTR var (int) var%@AE@%%@NL@% %@AS@%DWORD PTR var (long) var%@AE@%%@NL@% %@NL@% 5. Accessing array elements.%@NL@% %@NL@% Accessing arrays declared in assembly code is problematic because the%@NL@% Macro Assembler emits no type information to indicate which variables%@NL@% are arrays. Therefore the CodeView debugger treats an array name like%@NL@% any other variable.%@NL@% %@NL@% In C, an array name is equated with the address of the first element.%@NL@% Therefore, if you prefix an array with the address operator (%@AB@%&%@AE@%), the C%@NL@% expression evaluator gives correct results for array operations.%@NL@% %@NL@% %@AS@%string[12] (&string)[12]%@AE@%%@NL@% %@AS@%warray[bx+di] (&warray)(bx+di)/2%@AE@%%@NL@% %@AS@%darray[4] (&darray)[1]%@AE@%%@NL@% %@NL@% %@CR:MCV44008@%%@4@%In the second and third examples above, notice that the indexes used%@EH@% in the assembly source-code expressions differ from the indexes used in the CodeView expressions. This difference is necessary because C arrays are automatically scaled according to the size of elements. In assembly, the program must do the scaling.%@NL@% %@NL@% %@NL@% %@CR:MCV45000@%%@2@%%@AB@%4.5 Line Numbers%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV45001@%%@4@%Line numbers are useful for source-level debugging. They correspond to the%@EH@% lines in source-code files (BASIC, C, FORTRAN, or Macro Assembler). In source mode, you see a program displayed with each line numbered sequentially. The CodeView debugger allows you to use these same numbers to access parts of a program.%@NL@% %@NL@% %@CR:MCV45002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% .«%@AI@%filename%@AE@%:»%@AI@%linenumber%@AE@%%@NL@% %@NL@% %@CR:MCV45003@%%@4@%The address corresponding to a source-line number can be specified as %@EH@% %@AI@%linenumber%@AE@% prefixed with a period (%@AB@%.%@AE@%). The CodeView debugger assumes that the source line is in the current source file, unless you specify the optional %@AI@%filename%@AE@% followed by a colon and the line number.%@NL@% %@NL@% %@CR:MCV45004@%%@4@%The CodeView debugger displays an error message if %@AI@%filename%@AE@% does not exist,%@EH@% or if no source line exists for the specified number.%@NL@% %@NL@% %@CR:MCV45005@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >V .100%@NL@% %@NL@% %@CR:MCV45006@%%@4@%The example above uses the View command (%@AB@%V%@AE@%) to display code starting at the%@EH@% source line %@AS@%100%@AE@%. Since no file is indicated, the current source file is assumed.%@NL@% %@NL@% >V .SAMPLE.FOR:10%@NL@% %@NL@% >V .EXAMPLE.BAS:22%@NL@% %@NL@% >V .DEMO.C:301%@NL@% %@NL@% %@CR:MCV45007@%%@4@%The examples above use %@AB@%V%@AE@% to display source code starting at line %@AS@%10%@AE@% of%@EH@% %@AS@%SAMPLE.FOR%@AE@%, line %@AS@%22%@AE@% of %@AS@%EXAMPLE.BAS%@AE@%, and line %@AS@%301%@AE@% of %@AS@%DEMO.C%@AE@%, respectively.%@AS@%%@NL@% %@NL@% %@NL@% %@CR:MCV46000@%%@2@%%@AB@%4.6 Registers and Addresses%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV46001@%%@4@%This section presents alternative ways to refer to objects in memory,%@EH@% including values stored in the processor's registers. Addresses are basic to each of the expression evaluators. A data symbol represents an address in a data segment; a procedure name represents an address in a code segment. All of the syntax in this section can be considered as an extension to the BASIC, C, or FORTRAN expression evaluator.%@NL@% %@NL@% %@NL@% %@CR:MCV46100@%%@3@%%@AB@%4.6.1 Registers%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV46101@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% «@»%@AI@%register%@AE@%%@NL@% %@NL@% %@CR:MCV46102@%%@4@%You can specify a register name if you want to use the current value stored%@EH@% in the register. Registers are rarely needed in source-level debugging, but they are used frequently for assembly-language debugging.%@NL@% %@NL@% %@CR:MCV46103@%%@4@%When you specify an identifier, the CodeView debugger first checks the%@EH@% symbol table for a symbol with that name. If the debugger does not find a symbol, it checks to see if the identifier is a valid register name. If you want the identifier to be considered a register, regardless of any name in the symbol table, use the "at" sign (%@AB@%@%@AE@%) as a prefix to the register name. For example, if your program has a symbol called %@AS@%AX%@AE@%, you could specify %@AS@%@AX%@AE@% to refer to the AX register. You can avoid this problem entirely by making sure that identifier names in your program do not conflict with register names.%@NL@% %@NL@% %@CR:MCV46104@%%@4@%The register names known to the CodeView debugger are shown in Table 4.9.%@EH@% Note that the 32-bit registers are available only if the 386 option is on and if the computer is a 386 machine running in 386 mode.%@NL@% %@NL@% %@CR:MCV4TB00@%%@4@%%@AB@%Table 4.9 Registers%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%Type Names%@AE@%%@NL@% %@NL@% 8-bit high byte AH BH CH DH%@NL@% %@NL@% 8-bit low byte AL BL CL DL%@NL@% %@NL@% 16-bit general purpose AX BX CX DX%@NL@% %@NL@% 16-bit segment CS DS SS ES%@NL@% %@NL@% 16-bit pointer SP BP IP%@NL@% %@NL@% 16-bit index SI DI%@NL@% %@NL@% 32-bit general purpose EAX EBX ECX EDX%@NL@% %@NL@% 32-bit pointer ESP EBP%@NL@% %@NL@% 32-bit index ESI EDI%@NL@% %@NL@% %@NL@% %@CR:MCV46200@%%@3@%%@AB@%4.6.2 Addresses%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV46201@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% «%@AI@%segment%@AE@%:»%@AI@%offset%@AE@%%@NL@% %@NL@% %@CR:MCV46202@%%@4@%Addresses can be specified in the CodeView debugger through the use of the%@EH@% colon operator as a %@AI@%segment%@AE@%%@AB@%:%@AE@%%@AI@%offset%@AE@% connector. Both the %@AI@%segment%@AE@% and the %@AI@%offset%@AE@% are made up of expressions.%@NL@% %@NL@% %@CR:MCV46203@%%@4@%A full address has a %@AI@%segment%@AE@% and an %@AI@%offset%@AE@%, separated by a colon. A partial%@EH@% address has just an %@AI@%offset%@AE@%; a default segment is assumed. The default segment varies, depending on the command with which the address is used. Commands that refer to data (Dump, Enter, Watch, and Tracepoint) use the contents of the DS register. Commands that refer to code (Assemble, Breakpoint Set, Go, Unassemble, and View) use the contents of the CS register.%@NL@% %@NL@% %@CR:MCV46204@%%@4@%Full addresses are seldom necessary in source-level debugging. Occasionally%@EH@% they may be convenient for referring to addresses outside the program, such as BIOS (basic input/output system) or DOS addresses.%@NL@% %@NL@% %@CR:MCV46205@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >DB 100%@NL@% %@NL@% %@CR:MCV46206@%%@4@%In the example above, the Dump Bytes command (%@AB@%DB%@AE@%) is used to dump memory%@EH@% starting at offset address %@AS@%100%@AE@%. Since no segment is given, the data segment (the default for Dump commands) is assumed.%@NL@% %@NL@% >DB ARRAY(COUNT) %@AI@%;* FORTRAN/BASIC example%@AE@%%@NL@% %@NL@% %@CR:MCV46207@%%@4@%In the example above, the Dump Bytes command is used to dump memory starting%@EH@% at the address of the variable %@AS@%ARRAY(COUNT)%@AE@%. In C, a similar variable might be denoted as %@AS@%array[count]%@AE@%.%@NL@% %@NL@% >DB label+10%@NL@% %@NL@% %@CR:MCV46208@%%@4@%In the example above, the Dump Bytes command is used to dump memory starting%@EH@% at a point 10 bytes beyond the symbol %@AS@%label%@AE@%.%@NL@% %@NL@% >DB ES:200%@NL@% %@NL@% %@CR:MCV46209@%%@4@%In the example above, the Dump Bytes command is used to dump memory at the%@EH@% address having the segment value stored in ES and the offset address %@AS@%200%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCV46300@%%@3@%%@AB@%4.6.3 Address Ranges%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV46301@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AI@%startaddress%@AE@% %@AI@%endaddress%@AE@%%@NL@% %@AI@%startaddress%@AE@% %@AB@%L%@AE@% %@AI@%count%@AE@%%@NL@% %@NL@% %@CR:MCV46302@%%@4@%A "range" is a pair of memory addresses that bound a sequence of contiguous%@EH@% memory locations.%@NL@% %@NL@% %@CR:MCV46303@%%@4@%You can specify a range in two ways. One way is to give the start and end%@EH@% points. In this case, the range covers %@AI@%startaddress%@AE@% to %@AI@%endaddress%@AE@%, inclusively. If a command takes a range, but if you do not supply a second address, the CodeView debugger usually assumes the default range. Each command has its own default range. (The most common default range is 128 bytes.)%@NL@% %@NL@% %@CR:MCV46304@%%@4@%You can also specify a range by giving its starting point and the number of%@EH@% objects you want included in the range. This type of range is called an object range. In specifying an object range, %@AI@%startaddress%@AE@% is the address of the first object in the list, %@AB@%L%@AE@% indicates that this is an object range rather than an ordinary range, and %@AI@%count%@AE@% specifies the number of objects in the range.%@NL@% %@NL@% %@CR:MCV46305@%%@4@%The size of the objects is the size taken by the command. For example, the%@EH@% Dump Bytes command (%@AB@%DB%@AE@%) has byte objects, the Dump Words command (%@AB@%DW%@AE@%) has words, the Unassemble command (%@AB@%U%@AE@%) has instructions, and so on.%@NL@% %@NL@% %@CR:MCV46306@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >DB buffer%@NL@% %@NL@% %@CR:MCV46307@%%@4@%The example above dumps a range of memory starting at the symbol %@AS@%buffer%@AE@%.%@EH@% Since the end of the range is not given, the default size (128 bytes for the Dump Bytes command) is assumed.%@NL@% %@NL@% >DB buffer buffer+20%@NL@% %@NL@% %@CR:MCV46308@%%@4@%The example above dumps a range of memory starting at %@AS@%buffer%@AE@% and ending at%@EH@% %@AS@%buffer+20%@AE@% (the point 20 bytes beyond %@AS@%buffer%@AE@%).%@NL@% %@NL@% >DB buffer L 20%@NL@% %@NL@% %@CR:MCV46309@%%@4@%The example above uses an object range to dump the same range as in the%@EH@% previous example. The %@AS@%L%@AE@% indicates that the range is an object range, and %@AS@%20%@AE@% is the number of objects in the range. Each object has a size of 1 byte, since that is the command size.%@NL@% %@NL@% >U funcname-30 funcname%@NL@% %@NL@% %@CR:MCV4630A@%%@4@%The example above uses the Unassemble command (%@AS@%U%@AE@%) to list the%@EH@% assembly-language statements starting 30 instructions before %@AS@%funcname%@AE@% and continuing to %@AS@%funcname%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCV47000@%%@2@%%@AB@%4.7 Memory Operators%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV47001@%%@4@%Memory operators return the content of specific locations in memory. They%@EH@% are unary operators that work in the same way regardless of the language selected and return the result of a direct memory operation. They are chiefly of interest to programmers who debug in assembly mode, and are not necessary for high-level debugging.%@NL@% %@NL@% %@CR:MCV47002@%%@4@%All of the operators listed in this section are part of the CodeView C%@EH@% expression evaluator and should not be confused with CodeView commands. As opera-tors, they can only build expressions, which in turn are used as arguments in commands.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The memory operators discussed in this section are only available with%@NL@% the C expression evaluator and have the lowest precedence of any C%@NL@% operators.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV47100@%%@3@%%@AB@%4.7.1 Accessing Bytes (BY)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV47101@%%@4@%You can access the byte at an address by using the %@AB@%BY%@AE@% operator. This%@EH@% operator is useful for simulating the %@AB@%BYTE PTR%@AE@% operation of the Microsoft Macro Assembler. It is useful for watching the byte pointed to by a particular register.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The examples that follow in this section make use of the Display%@NL@% Expression (%@AB@%?%@AE@%) Command, which is described in Section 6.1.%@BO: 44676@% The %@AB@%x%@AE@% format%@NL@% specifier causes the debugger to produce output in hexadecimal.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV47102@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%BY%@AE@% %@AI@%address%@AE@%%@NL@% %@NL@% %@CR:MCV47103@%%@4@%The result is a short integer that contains the value of the first byte%@EH@% stored at %@AI@%address%@AE@%.%@NL@% %@NL@% %@CR:MCV47104@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >? BY sum%@NL@% %@AS@%101%@NL@% %@NL@% %@CR:MCV47105@%%@4@%The example above returns the first byte at the address of %@AS@%sum.%@AE@%%@EH@%%@NL@% %@NL@% >? BY bp+6%@NL@% %@AS@%42%@NL@% %@NL@% %@CR:MCV47106@%%@4@%This example returns the byte pointed to by the BP register, with a%@EH@% displacement of 6.%@NL@% %@NL@% %@NL@% %@CR:MCV47200@%%@3@%%@AB@%4.7.2 Accessing Words (WO)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV47201@%%@4@%You can access the word at an address by using the %@AB@%WO%@AE@% operator. This%@EH@% operator is useful for simulating the %@AB@%WORD PTR%@AE@% operation of the assembler. It is particularly useful for watching the word pointed to by a particular register, such as the stack pointer.%@NL@% %@NL@% %@CR:MCV47202@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%WO%@AE@% %@AI@%address%@AE@%%@NL@% %@NL@% %@CR:MCV47203@%%@4@%The result is a short integer that contains the value of the first two bytes%@EH@% stored at %@AI@%address%@AE@%.%@NL@% %@NL@% %@CR:MCV47204@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >? WO sum%@NL@% %@AS@%>13120%@NL@% %@NL@% %@CR:MCV47205@%%@4@%The example above returns the first word at the address of %@AS@%sum.%@AE@%%@EH@%%@NL@% %@NL@% >? WO sp,x%@NL@% %@AS@%>2F38%@NL@% %@NL@% %@CR:MCV47206@%%@4@%This example returns the word pointed to by the stack pointer; the word%@EH@% therefore represents the last word pushed (the "top" of the stack).%@NL@% %@NL@% %@NL@% %@CR:MCV47300@%%@3@%%@AB@%4.7.3 Accessing Double Words (DW)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV47301@%%@4@%You can access the word at an address by using the %@AB@%DW%@AE@% operator. This%@EH@% operator is useful for simulating the %@AB@%DWORD PTR%@AE@% operation of the Microsoft Macro Assembler. It is particularly useful for watching the word pointed to by a particular register.%@NL@% %@NL@% %@CR:MCV47302@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%DW%@AE@% %@AI@%address%@AE@%%@NL@% %@NL@% %@CR:MCV47303@%%@4@%The result is a long integer that contains the value of the first four bytes%@EH@% stored at %@AI@%address%@AE@%.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Be careful not to confuse the %@AB@%DW%@AE@% operator with the %@AB@%DW%@AE@% comm and. The%@NL@% operator is only useful for building expressions; it occurs within a%@NL@% CodeView command line, but never at the beginning. The second use of %@AB@%DW%@AE@%%@NL@% mentioned above, the Dump Words Command, occurs only at the beginning of%@NL@% a CodeView command line. It displays an entire range of memory (in words,%@NL@% not double words) rather than returning a single result.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV47304@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >? DW sum%@NL@% %@AS@%>132120365%@NL@% %@NL@% %@CR:MCV47305@%%@4@%The example above returns the first double word at the address of %@AS@%sum%@AE@%.%@EH@%%@NL@% %@NL@% >? DW si,x%@NL@% %@AS@%>3F880000%@NL@% %@NL@% %@CR:MCV47306@%%@4@%This example returns the double word pointed to by the SI register.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCV48000@%%@2@%%@AB@%4.8 Switching Expression Evaluators%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV48001@%%@4@%The CodeView debugger allows you to specify a particular expression%@EH@% evaluator: BASIC, C, or FORTRAN. You may want to specify the expression evaluator if you are debugging a source module that does not use the standard extension of the source language (such as .C for C, .BAS for BASIC, etc.), or if you want to use a feature of a different language. For example, you might be debugging a C program and want to evaluate a string of binary digits. The FORTRAN expression evaluator accepts base 2, so you might want to switch temporarily to the FORTRAN expression evaluator.%@NL@% %@NL@% %@CR:MCV48002@%%@4@%It is normally not necessary to specify the evaluator, even if you are%@EH@% debugging a mixed-language program; the Auto selection changes the expression evaluator for you.%@NL@% %@NL@% %@CR:MCV48003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV48004@%%@4@%To switch expression evaluators with the mouse, open the Language menu and%@EH@% click the appropriate language selection.%@NL@% %@NL@% %@CR:MCV48005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV48006@%%@4@%To switch expression evaluators with a keyboard command, press ALT+L to open%@EH@% up the Language menu, use the direction keys (or mnemonic letter) to move to the appropriate language, then press RETURN.%@NL@% %@NL@% %@CR:MCV48007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV48008@%%@4@%To switch expression evaluators using a dialog command, enter a command line%@EH@% with the syntax%@NL@% %@NL@% %@AB@%USE%@AE@% «%@AI@%language%@AE@%»%@NL@% %@NL@% %@CR:MCV48009@%%@4@%where %@AI@%language%@AE@% is C, FORTRAN, BASIC, or Auto. The command is not case%@EH@% sensitive, and you can enter the language name in any combination of uppercase and lowercase letters. Entered on a line by itself, %@AB@%USE%@AE@% displays the name of the current expression evaluator. The %@AB@%USE%@AE@% command always displays the name of the current expression evaluator or the new expression evaluator (if specified).%@NL@% %@NL@% %@CR:MCV4800A@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >USE fortran%@NL@% %@AS@%FORTRAN%@NL@% %@NL@% %@CR:MCV4800B@%%@4@%The example above switches to the FORTRAN expression evaluator.%@EH@%%@NL@% %@NL@% >USE%@NL@% %@AS@%BASIC%@NL@% %@NL@% %@CR:MCV4800C@%%@4@%The example above displays the name of the current expression evaluator,%@EH@% which in this case happens to be BASIC.%@NL@% %@NL@% %@NL@% %@CR:MCV50000@%%@1@%%@AB@%Chapter 5 Executing Code%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV50001@%%@4@%Several commands execute code within a program. Among the differences%@EH@% between the commands is the size of step executed by each. The commands and their step sizes are listed below.%@NL@% %@NL@% %@CR:MCV50002@% ■ Trace (%@AB@%T%@AE@%)%@NL@% %@NL@% Executes the current source line in source mode, or the current%@NL@% instruction in assembly mode; traces into routines, procedures, or%@NL@% interrupts%@NL@% %@NL@% ■ Program Step (%@AB@%P%@AE@%)%@NL@% %@NL@% Executes the current source line in source mode, or the current%@NL@% instruction in assembly mode; steps over routines, procedures, or%@NL@% interrupts%@NL@% %@NL@% ■ Go (%@AB@%G%@AE@%)%@NL@% %@NL@% Executes the current program%@NL@% %@NL@% ■ Execute (%@AB@%E%@AE@%)%@NL@% %@NL@% Executes the current program in slow motion%@NL@% %@NL@% ■ Restart (%@AB@%L%@AE@%)%@NL@% %@NL@% Restarts the current program%@NL@% %@NL@% %@NL@% %@CR:MCV51000@%%@2@%%@AB@%5.1 Window and Sequential Mode Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV51001@%%@4@%In window mode, the screen is updated to reflect changes that occur when you%@EH@% execute a Trace, Program Step, or Go command. The highlight marking the current location is moved to the new instruction in the display window. When appropriate, values are changed in the register and watch windows.%@NL@% %@NL@% %@CR:MCV51002@%%@4@%In sequential mode, the current source line or instruction is displayed%@EH@% after each Trace, Program Step, or Go command. The format of the display depends on the display mode. The three display modes in sequential mode (source, assembly, and mixed) are discussed in Chapter 9%@BO: 6542b@%, "Examining Code."%@NL@% %@NL@% %@CR:MCV51003@%%@4@%If the display mode is source (%@AB@%S+%@AE@%) in sequential mode, the current source%@EH@% line is shown. If the display mode is assembly (%@AB@%S-%@AE@%), the status of the registers and the flags and the new instruction are shown in the format of the Register command (see Chapter 6%@BO: 43f5c@%, "Examining Data and Expressions"). If the display mode is mixed (%@AB@%S&%@AE@%), then the registers, the new source line, and the new instruction are all shown.%@NL@% %@NL@% %@CR:MCV51004@%%@4@%The commands that execute code are explained in Sections 5.2%@BO: 3e3a8@%-5.6.%@EH@%%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% If you are executing a section of code with the Go or Program Step%@NL@% command, you can usually interrupt program execution by pressing%@NL@% CTRL+BREAK or CTRL+C. This can terminate endless loops, or it can%@NL@% interrupt loops that are delayed by the Watchpoint or Tracepoint command%@NL@% (see Chapter 8%@BO: 5c045@%, "Managing Watch Statements").%@NL@% %@NL@% CTRL+BREAK or CTRL+C may not work if your program has a special use for%@NL@% either of these key combinations. If you have an IBM Personal Computer AT%@NL@% (or a compatible computer), you can use the SYSTEM-REQUEST key to%@NL@% interrupt execution regardless of your program's use of CTRL+BREAK and%@NL@% CTRL+C.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV52000@%%@2@%%@AB@%5.2 Trace Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV52001@%%@4@%The Trace command executes the current source line in source mode, or the%@EH@% current instruction in assembly mode. The current source line or instruction is the one pointed to by the CS and IP registers. In window mode, the current instruction is shown in reverse video or in a contrasting color.%@NL@% %@NL@% %@CR:MCV52002@%%@4@%In source mode, if the current source line contains a call, the CodeView%@EH@% debugger executes the first source line of the called routine. In this mode, the debugger will only trace into functions and routines that have source code. For example, if the current line contains a call to an intrinsic function or a standard C library function, the debugger will simply execute the function if you are in source mode, since the source code for Microsoft standard libraries is not available.%@NL@% %@NL@% %@CR:MCV52003@%%@4@%If you are in assembly or mixed mode, the debugger will trace into the%@EH@% function. In this mode, if the current instruction is %@AB@%CALL%@AE@%, %@AB@%INT%@AE@% or %@AB@%REP%@AE@%, the debugger executes the first instruction of the procedure, interrupt, or repeated string sequence.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% When you debug Microsoft Macro Assembler programs in source mode, the%@NL@% paragraph above still applies. The debugger will not trace into an %@AB@%INT%@AE@% or%@NL@% %@AB@%REP%@AE@% sequence when you are in source mode.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV52004@%%@4@%Use the Trace command i execute calls without tracing into them, you should%@EH@% use the Program Step command (%@AB@%P%@AE@%) instead. Both commands execute DOS function calls without tracing into them. There is no direct way to trace into DOS function calls. However, you can trace through BIOS calls in assembly or mixed mode.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The Trace command (%@AB@%T%@AE@%) uses the hardware trace mode of the 8086 family of%@NL@% processors. Consequently, you can also trace instructions stored in ROM%@NL@% (read-only memory). However, the Program Step command (%@AB@%P%@AE@%) will not work%@NL@% in ROM.Using the Program Step command has the same effect as using the%@NL@% Gocommand (%@AB@%G%@AE@%).%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV52005@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV52006@%%@4@%To execute the Trace command with the mouse, point to Trace on the menu bar%@EH@% and click Left.%@NL@% %@NL@% %@CR:MCV52007@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV52008@%%@4@%To execute the Trace command with a keyboard command, press F8. This works%@EH@% in both window and sequential modes.%@NL@% %@NL@% %@CR:MCV52009@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV5200A@%%@4@%To execute the Trace command using a dialog command, enter a command line%@EH@% with the following syntax:%@NL@% %@NL@% %@AB@%T%@AE@% «%@AI@%count%@AE@%»%@NL@% %@NL@% %@CR:MCV5200B@%%@4@%If the optional %@AI@%count%@AE@% is specified, the command executes %@AI@%count%@AE@% times before%@EH@% stopping.%@NL@% %@NL@% %@CR:MCV5200C@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV5200D@%%@4@%The following example shows the Trace command in sequential mode. (In window%@EH@% mode, there would be no output from the commands, but the display would be updated to show changes caused by the command.)%@NL@% %@NL@% S+ %@AI@%;* FORTRAN example%@AE@%%@NL@% source%@NL@% >.%@NL@% 9: CALL INPUT (DATA,N,INPFMT)%@NL@% >T 3%@NL@% 34: OPEN (1,FILE='EXAMPLE.DAT',STATUS='OLD')%@NL@% 35: DO 100 I=1,N%@NL@% 36: READ (1,'(BN,I10)',END=999) DATA(I)%@NL@% %@NL@% >%@NL@% %@NL@% %@CR:MCV5200E@%%@4@%The FORTRAN example above sets the display mode to source, and then uses the%@EH@% Source Line command to display the current source line. (See Chapter 9%@BO: 6542b@%, "Examining Code," for a further explanation of the Set Source and Source Line commands.) Note that the current source line calls the subroutine %@AS@%INPUT%@AE@%. The Trace command is then used to execute the next three source lines. These lines will be the first three lines of the subroutine %@AS@%INPUT%@AE@%.%@NL@% %@NL@% %@CR:MCV5200F@%%@4@%Debugging C and BASIC source code is very similar. If you execute the Trace%@EH@% command when the current source line contains a C function call or a BASIC subprogram call, the debugger will execute the first line of the called routine.%@NL@% %@NL@% S-%@NL@% assembly%@NL@% >T%@NL@% AX=0058 BX=3050 CX=000B DX=3FB0 SP=304C BP=3056 SI=00CC DI=40E0%@NL@% DS=49B7 ES=49B7 SS=49B7 CS=3FB0 IP=0013 NV UP EI PL NZ AC PONC%@NL@% 3FB0:0013 50 PUSH AX%@NL@% >%@NL@% %@NL@% %@CR:MCV5200G@%%@4@%The example above sets the display mode to assembly and traces the current%@EH@% instruction. (This example and the next example are the same as the examples of the Program Step command in Section 5.3.%@BO: 3fb26@%) The Trace and Program Step commands behave differently only when the current instruction is a %@AB@%CALL%@AE@%, %@AB@%INT%@AE@%, or %@AB@%REP%@AE@% instruction.%@NL@% %@NL@% S&%@NL@% mixed%@NL@% >T%@NL@% AX=0000 BX=319C CX=0028 DX=0000 SP=304C BP=3056 SI=00CC DI=40E0%@NL@% DS=49B7 ES=49B7 SS=49B7 CS=3FB0 IP=003C NV UP EI PL NZ NA PONC%@NL@% 8: IF (N.LT.1 .OR. N.GT.1000) GO TO 100%@NL@% 3FB0:003C 833ECE2101 CMP Word Ptr [21CE],+01 DS:21CE=0028%@NL@% >%@NL@% %@NL@% %@CR:MCV5200H@%%@4@%The example above sets the display mode to mixed and traces the current%@EH@% instruction.%@NL@% %@NL@% %@NL@% %@CR:MCV53000@%%@2@%%@AB@%5.3 Program Step Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV53001@%%@4@%The Program Step command executes the current source line in source mode, or%@EH@% the current instruction in assembly mode. The current source line or instruction is the one pointed to by the CS and IP registers. In window mode, the current instruction is shown in reverse video or in a contrasting color.%@NL@% %@NL@% %@CR:MCV53002@%%@4@%In source mode, if the current source line contains a call, the CodeView%@EH@% debugger executes the entire routine and is ready to execute the line after the call. In assembly mode, if the current instruction is %@AB@%CALL%@AE@%, %@AB@%INT%@AE@%, or %@AB@%REP%@AE@%, the debugger executes the entire procedure, interrupt, or repeated string sequence. Use the Program Step command if you want to execute over routine, function, procedure, and interrupt calls. If you want to trace into calls, you should use the Trace command (%@AB@%T%@AE@%) instead. Both commands execute DOS function calls without tracing into them. There is no direct way to trace into DOS function calls.%@NL@% %@NL@% %@CR:MCV53003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV53004@%%@4@%To execute the Program Step command with the mouse, point to Trace on the%@EH@% menu bar and click Right.%@NL@% %@NL@% %@CR:MCV53005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV53006@%%@4@%To execute the Program Step command with a keyboard command, press F10. This%@EH@% works in both window and sequential modes.%@NL@% %@NL@% %@CR:MCV53007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV53008@%%@4@%To execute the Program Step command with a dialog command, enter a command%@EH@% line with the following syntax:%@NL@% %@NL@% %@AB@%P%@AE@% «%@AI@%count%@AE@%»%@NL@% %@NL@% %@CR:MCV53009@%%@4@%If the optional %@AI@%count%@AE@% is specified, the command executes %@AI@%count%@AE@% times before%@EH@% stopping.%@NL@% %@NL@% %@CR:MCV5300A@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV5300B@%%@4@%This example shows the Program Step command in sequential mode. In window%@EH@% mode, there would be no output from the commands, but the display would be updated to show changes.%@NL@% %@NL@% S+ %@AI@%;* FORTRAN/BASIC example%@AE@%%@NL@% source%@NL@% >.%@NL@% 9: CALL INPUT (DATA,N,INPFMT)%@NL@% >P 3%@NL@% 10: CALL BUBBLE (DATA,N)%@NL@% 11: CALL STATS (DATA,N)%@NL@% 12: END%@NL@% >%@NL@% %@NL@% %@CR:MCV5300C@%%@4@%The example above (in FORTRAN or BASIC) sets the display mode to source, and%@EH@% then uses the Source Line command to display the current source line. (See Chapter 9%@BO: 6542b@%, "Examining Code," for an explanation of the Set Source and Source Line commands.) Notice that the current source line calls the subprogram %@AS@%INPUT%@AE@%. The Program Step command is then used to execute the next three source lines. The first program step executes the entire subprogram %@AS@%INPUT%@AE@%. The next two steps execute the subprograms %@AS@%BUBBLE%@AE@% and %@AS@%STATS%@AE@% in their entirety.%@NL@% %@NL@% %@CR:MCV5300D@%%@4@%The same program, written in C, would behave exactly the same way with the%@EH@% Program Step command. The Program Step command will not trace into a C function call.%@NL@% %@NL@% S-%@NL@% assembly%@NL@% >P%@NL@% AX=0058 BX=3050 CX=000B DX=3FB0 SP=304C BP=3056 SI=00CC DI=40E0%@NL@% DS=49B7 ES=49B7 SS=49B7 CS=3FB0 IP=0013 NV UP EI PL NZ AC PONC%@NL@% 3FB0:0013 50 PUSH AX%@NL@% >%@NL@% %@NL@% %@CR:MCV5300E@%%@4@%The example above sets the display mode to assembly and steps through the%@EH@% current instruction. (This example and the next example are the same as the examples of the Trace command in Section 5.2.%@BO: 3e3a8@%) The Trace and Program Step commands behave differently only when the current instruction is a %@AB@%CALL%@AE@%, %@AB@%INT%@AE@%, or %@AB@%REP%@AE@% instruction.%@NL@% %@NL@% S&%@NL@% mixed%@NL@% >P%@NL@% AX=0000 BX=319C CX=0028 DX=0000 SP=304C BP=3056 SI=00CC DI=40E0%@NL@% DS=49B7 ES=49B7 SS=49B7 CS=3FB0 IP=003C NV UP EI PL NZ NA PONC%@NL@% 8: IF (N.LT.1 .OR. N.GT.1000) GO TO 100%@NL@% 3FB0:003C 833ECE2101 CMP Word Ptr [21CE],+01 DS:21CE=0028%@NL@% >%@NL@% %@NL@% %@CR:MCV5300F@%%@4@%The example above sets the display mode to mixed and steps through the%@EH@% current instruction.%@NL@% %@NL@% %@NL@% %@CR:MCV54000@%%@2@%%@AB@%5.4 Go Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV54001@%%@4@%The Go command starts execution at the current address. There are two%@EH@% variations of the Go command──Go and Goto. The Go variation simply starts execution and continues to the end of the program or until a breakpoint set earlier with the Breakpoint Set (%@AB@%BP%@AE@%), Watchpoint (%@AB@%WP%@AE@%), or Tracepoint (%@AB@%TP%@AE@%) command is encountered. The other variation is a Goto command, in which a destination is given with the command.%@NL@% %@NL@% %@CR:MCV54002@%%@4@%If a destination address is given but never encountered (for example, if the%@EH@% destination is on a program branch that is never taken), the CodeView debugger executes to the end of the program.%@NL@% %@NL@% %@CR:MCV54003@%%@4@%If you enter the Go command and the debugger does not encounter a%@EH@% breakpoint, the entire program is executed and the following message is displayed:%@NL@% %@NL@% %@AS@%Program terminated normally (%@AE@%%@AI@%number%@AE@%%@AS@%)%@AE@%%@NL@% %@NL@% %@CR:MCV54004@%%@4@%The %@AI@%number%@AE@% in parentheses is the value returned by the program (sometimes%@EH@% called the exit or "errorlevel" code).%@NL@% %@NL@% %@CR:MCV54005@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV54006@%%@4@%To execute the Go command with no destination, point to Go on the menu bar%@EH@% and press either button.%@NL@% %@NL@% %@CR:MCV54007@%%@4@%To execute the Goto variation of the Go command, point to the source line or%@EH@% instruction you wish to go to, then press the right button. The highlight marking the current location will move to the source line or instruction you pointed to (unless a breakpoint is encountered first). The CodeView debugger will sound a warning and take no action if you try to go to a comment line or other source line that does not correspond to code.%@NL@% %@NL@% %@CR:MCV54008@%%@4@%If the line you wish to go to is in another module, you can use the Load%@EH@% command from the Files menu to load the source file for the other module. Then point to the destination line and press the right button.%@NL@% %@NL@% %@CR:MCV54009@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV5400A@%%@4@%To use a keyboard command to execute the Go command with no destination,%@EH@% press F5. This works in both window and sequential modes.%@NL@% %@NL@% %@CR:MCV5400B@%%@4@%To execute the Goto variation of the Go command, point to the source line or%@EH@% instruction you wish to go to then press the right button. The highlight marking the current location will move to the source line or instruction to which you wish to go. If the cursor is in the dialog window, first press F6 to move the cursor to the display window. When the cursor is at the appropriate line in the display window, press F7. The highlight marking the current location will move to the source line or instruction you pointed to (unless a breakpoint is encountered first). If you try to go to a comment line or to another source line that does not correspond to code, the CodeView debugger will sound a warning and take no action.%@NL@% %@NL@% %@CR:MCV5400C@%%@4@%If the line you wish to go to is in another module, you can use the Load%@EH@% command from the Files menu to load the source file for the other module. Then move the cursor to the destination line and press F7.%@NL@% %@NL@% %@CR:MCV5400D@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV5400E@%%@4@%To execute the Go command with a dialog command, enter a command line with%@EH@% the following syntax:%@NL@% %@NL@% %@AB@%G%@AE@% «%@AI@%breakaddress%@AE@%»%@NL@% %@NL@% %@CR:MCV5400F@%%@4@%If the command is given with no argument, execution continues until a%@EH@% breakpoint or the end of the program is encountered.%@NL@% %@NL@% %@CR:MCV5400G@%%@4@%The Goto form of the command can be given by specifying %@AI@%breakaddress%@AE@%. The%@EH@% %@AI@%breakaddress%@AE@% can be given as a symbol, a line number, or an address in the %@AI@%segment%@AE@%%@AB@%:%@AE@%%@AI@%offset%@AE@% format. If the offset address is given without a segment, the address in the CS register is used as the default segment. If %@AI@%breakaddress%@AE@% is given as a line number, but the corresponding source line is a comment, declaration, or blank line, the following message appears:%@NL@% %@NL@% %@AS@%No code at this line number%@AE@%%@NL@% %@NL@% %@CR:MCV5400H@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV5400I@%%@4@%The following examples show the Go command in sequential mode. In window%@EH@% mode there would be no output from the commands, but the display would be updated to show changes caused by the command.%@NL@% %@NL@% >G%@NL@% %@NL@% Program terminated normally (0)%@NL@% >%@NL@% %@NL@% %@CR:MCV5400J@%%@4@%The example above passes control to the instruction pointed to by the%@EH@% current values of the CS and IP registers. No breakpoint is encountered, so that the CodeView debugger executes to the end of the program, where it prints a termination message and the exit code returned by the program ( %@AS@%0%@AE@% in the example).%@NL@% %@NL@% S+ %@AI@%;* FORTRAN/BASIC example (source mode)%@AE@%%@NL@% source%@NL@% >G BUBBLE%@NL@% 17: A = B + C%@NL@% >%@NL@% %@NL@% %@CR:MCV5400K@%%@4@%In the example above, the display mode is first set to source %@AS@%(S+)%@AE@%. (See%@EH@% Chapter 9%@BO: 6542b@%, "Examining Code," for information on setting the display mode.) When the Go command is entered, the CodeView debugger starts program execution at the current address and continues until it reaches the start of the subprogram %@AS@%BUBBLE%@AE@%.%@NL@% %@NL@% S& %@AI@%;* C example (mixed mode)%@AE@%%@NL@% mixed%@NL@% >G .22%@NL@% AX=02F4 BX=0002 CX=00A8 DX=0000 SP=3036 BP=3042 SI=0070 DI=40E0%@NL@% DS=49B7 ES=49B7 SS=49B7 CS=3FB0 IP=0141 NV UP EI PL NZ NAPO NC%@NL@% 22: x[i] = x[j];%@NL@% 3FB0:0141 8B7608 MOV SI,Word Ptr [BP+08] SS:304A=0070%@NL@% >%@NL@% %@NL@% %@CR:MCV5400L@%%@4@%The example above passes execution control to the program at the current%@EH@% address and executes to the address of source line %@AS@%22%@AE@%. If the address with the breakpoint is never encountered (for example, if the program has less than 22 lines, or if the breakpoint is on a program branch that is never taken), the CodeView debugger executes to the end of the program.%@NL@% %@NL@% S-%@NL@% assembly%@NL@% >G #2A8%@NL@% AX=0049 BX=0049 CX=028F DX=0000 SP=12F2 BP=12F6 SI=04BA DI=1344%@NL@% DS=5DAF ES=5DAF SS=5DAF CS=58BB IP=02A8 NV UP EI PL NZ NA PENC%@NL@% 58BB:02A8 98 CBW%@NL@% >%@NL@% %@NL@% %@CR:MCV5400M@%%@4@%The example above executes to the hexadecimal address CS:2A8. Since no%@EH@% segment address is given, the CS register is assumed.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Mixed and source mode can be used equally well with all three languages.%@NL@% The examples alternate languages in this chapter simply to be accessible%@NL@% to more users.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV55000@%%@2@%%@AB@%5.5 Execute Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV55001@%%@4@%The Execute command is similar to the Go command with no arguments except%@EH@% that it executes in slow motion (several source lines per second). Execution starts at the current address and continues to the end of the program or until a breakpoint, tracepoint, or watchpoint is reached. You can also stop automatic program execution by pressing any key or a mouse button.%@NL@% %@NL@% %@CR:MCV55002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV55003@%%@4@%To execute code in slow motion with the mouse, point to Run on the menu bar,%@EH@% press a mouse button and drag the highlight down to the Execute selection, and then release the button.%@NL@% %@NL@% %@CR:MCV55004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV55005@%%@4@%To execute code in slow motion with a keyboard command, press ALT+R to open%@EH@% the Run menu, and then press ALT+E to select Execute.%@NL@% %@NL@% %@CR:MCV55006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV55007@%%@4@%To execute code in slow motion with a dialog command, enter a command line%@EH@% with the following syntax:%@NL@% %@NL@% %@AB@%E%@AE@%%@NL@% %@NL@% %@CR:MCV55008@%%@4@%You cannot set a destination for the Execute command as you can for the Go%@EH@% command.%@NL@% %@NL@% %@CR:MCV55009@%%@4@%In sequential mode, the output from the Execute command depends on the%@EH@% display mode (source, assembly, or mixed). In assembly or mixed mode, the command executes one instruction at a time. The command displays the current status of the registers and the instruction. In mixed mode, it will also show a source line if there is one at the instruction. In source mode, the command executes one source line at a time, displaying the lines as it executes them.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The Execute command has the same command letter (%@AB@%E%@AE@%)as the Enter command.%@NL@% If the command has at least one argument, it is interpreted as Enter; if%@NL@% not, it is interpreted as Execute.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV56000@%%@2@%%@AB@%5.6 Restart Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV56001@%%@4@%The Restart command restarts the current program. The program is ready to be%@EH@% executed just as if you had restarted the CodeView debugger. Program variables are reinitialized, but any existing breakpoints or watch statements are retained. The pass count for all breakpoints is reset to 1. Any program arguments are also retained, though they can be changed with the dialog version of the command.%@NL@% %@NL@% %@CR:MCV56002@%%@4@%The Restart command can only be used to restart the current program. If you%@EH@% wish to load a new program, you must exit and restart the CodeView debugger with the new program name.%@NL@% %@NL@% %@CR:MCV56003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV56004@%%@4@%To restart the program with the mouse, point to Run on the menu bar, press a%@EH@% mouse button and drag the highlight down to the Restart or Start selection, and then release the button. The program will be restarted. If the Restart selection is chosen, the program will be ready to start executing from the beginning (but not actually running). If the Start selection is chosen, the program starts executing from the beginning and continues until a breakpoint or the end of the program is encountered.%@NL@% %@NL@% %@CR:MCV56005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV56006@%%@4@%To restart the program with a keyboard command, press ALT+R to open the Run%@EH@% menu, and then press either ALT+R to select Restart or ALT+S to select Start. The program will be restarted. If the Restart selection is chosen, the program will be ready to start executing from the beginning (but not actually running). If the Start selection is chosen, the program starts executing from the beginning and continues until a breakpoint or the end of the program is encountered.%@NL@% %@NL@% %@CR:MCV56007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV56008@%%@4@%To restart the program with a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%L%@AE@% «%@AI@%arguments%@AE@%»%@NL@% %@NL@% %@CR:MCV56009@%%@4@%When you restart using the dialog version of the command, the program will%@EH@% be ready to start executing from the beginning. If you want to restart with new program arguments, you can give optional %@AI@%arguments%@AE@%. You cannot specify new arguments with the mouse or keyboard version of the command.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The command letter %@AB@%L%@AE@% is a mnemonic for Load, but the command should not%@NL@% be confused with the Load selection from the File menu, since that%@NL@% selection only loads a source file without restarting the program.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV5600A@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% L%@NL@% >%@NL@% %@NL@% %@CR:MCV5600B@%%@4@%The example above starts the current executable file, retaining any%@EH@% breakpoints, watchpoints, tracepoints, and arguments.%@NL@% %@NL@% L 6%@NL@% >%@NL@% %@NL@% %@CR:MCV5600C@%%@4@%The example above restarts the current executable file, but with %@AS@%6%@AE@% as the%@EH@% new program argument.%@NL@% %@NL@% %@NL@% %@CR:MCV60000@%%@1@%%@AB@%Chapter 6 Examining Data and Expressions%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV60001@%%@4@%The CodeView debugger provides several commands for examining different%@EH@% kinds of data such as expressions, symbols, memory, and registers. The data-evaluation commands discussed in this chapter are summarized below.%@NL@% %@NL@% %@CR:MCV60002@%%@AB@%Command Action%@AE@%%@NL@% %@NL@% Display Expression (%@AB@%?%@AE@%) Evaluates and displays locals, the value of%@NL@% symbols, or expressions%@NL@% %@NL@% Graphic Display (%@AB@%??%@AE@%) Displays local variables and complete data%@NL@% structures in a scrollable dialog box and traces%@NL@% pointer, structure, and array references%@NL@% %@NL@% Examine Symbol (%@AB@%X?%@AE@%) Displays the addresses of symbols%@NL@% %@NL@% Dump (%@AB@%D%@AE@%) Displays sections of memory containing data%@NL@% (with variations for examining different kinds%@NL@% of data)%@NL@% %@NL@% Compare Memory (%@AB@%C%@AE@%) Compares two blocks of memory, byte by byte%@NL@% %@NL@% Search Memory (%@AB@%S%@AE@%) Scans memory for specified byte values%@NL@% %@NL@% Port Input (%@AB@%I%@AE@%) Reads a byte from a hardware port%@NL@% %@NL@% Register (%@AB@%R%@AE@%) Shows the current value of each register and%@NL@% each flag (and optionally changes them)%@NL@% %@NL@% 8087 (%@AB@%7%@AE@%) Shows the current value in the 8087 or 80287%@NL@% register%@NL@% %@NL@% %@NL@% %@CR:MCV61000@%%@2@%%@AB@%6.1 Display Expression Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV61001@%%@4@%The Display Expression command displays the value of a CodeView expression.%@EH@%%@NL@% %@NL@% %@CR:MCV61002@%%@4@%Each of the expression evaluators (C, FORTRAN, and BASIC) accepts a%@EH@% different set of symbols, operators, functions, and constants, as explained in Chapter 4%@BO: 2faf9@%, "CodeView Expressions." The resulting expressions can contain the intrinsic functions listed for the FORTRAN and BASIC expression evaluators. They may also contain functions that are part of the executable file. The simplest form of expression is a symbol representing a single variable or routine.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% FORTRAN subroutines and BASIC subprograms do not return values as%@NL@% functions do. They can be used in expressions, and may be useful for%@NL@% observing side effects. However, the value returned by the expression%@NL@% will be meaningless.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV61003@%%@4@%In addition to displaying values, the Display Expression command can also%@EH@% set values as a side effect. For example, with the C expression evaluator you can increment the variable %@AS@%n%@AE@% by using the expression %@AS@%++n%@AE@% with the Display Expression command. With the FORTRAN expression evaluator you would use %@AS@%N=N+1%@AE@%, and with the BASIC expression evaluator you would use %@AS@%LET N=N+1%@AE@%. After being incremented, the new value will be displayed.%@NL@% %@NL@% %@CR:MCV61004@%%@4@%You can specify the format in which the values of expressions are displayed%@EH@% by the Display Expression command. Type a comma after the expression, followed by a CodeView format specifier. The format specifiers used in the CodeView debugger are a subset of those used by the C %@AB@%printf%@AE@% function. They are listed in Table 6.1.%@NL@% %@NL@% %@CR:MCV6T100@%%@4@%%@AB@%Table 6.1 CodeView Format Specifiers%@AE@%%@EH@%%@NL@% %@TH: 31 2189 3 13 35 14 14 @%%@AB@% Output Sample Sample%@AE@%%@AB@%Character Format Expression Output%@AE@%%@AB@%d%@AE@% Signed decimal integer %@AS@%? 40000,d 40000%@AE@%%@AB@%i%@AE@% Signed decimal integer %@AS@%? 40000,i 40000%@AE@%%@AB@%u%@AE@%%@FN@%FORTRAN and BASIC have no unsigned data types. Using an unsigned formatspecifier has no effect on the output of positive numbers, but causesnegative numbers to be output as positive values.%@EF@% Unsigned decimal integer %@AS@%? 40000,u 40000%@AE@%%@AB@%o%@AE@% Unsigned octal integer %@AS@%? 40000,o 116100%@AE@%%@AB@%x%@AE@% or %@AB@%X%@AE@% Hexadecimal integer %@AS@%? 40000,x 9c40%@AE@%%@AB@%f%@AE@% Signed value in floating-point %@AS@%? 3./2.,f 1.500000%@AE@% decimal format with six decimal places%@AB@%e%@AE@% or %@AB@%E%@AE@%%@FN@%The "E" is uppercse if the type is %@AB@%E%@AE@% or %@AB@%G%@AE@%; and lowercase if the type is %@AB@%e%@AE@% or%@AB@%g%@AE@%.%@EF@% Signed value in scientific- %@AS@%? 3./2.,e 1.500000e+000%@AE@% notation format with up to six decimal places (trailing zeros and decimal point are truncated)%@AB@%g%@AE@% or %@AB@%G%@AE@%%@FN@%The "G" is uppercase if the type is %@AB@%E%@AE@% or %@AB@%G%@AE@%; and lowercase if the type is %@AB@%e%@AE@% or%@AB@%g%@AE@%.%@EF@% Signed value with floating-point %@AS@%? 3./2.,g 1.5%@AE@% decimal format (%@AB@%f%@AE@%) or scientific- notation format (%@AB@%g%@AE@% or %@AB@%G%@AE@%), whichever is more compact%@AB@%c%@AE@% Single character %@AS@%? 65,c A%@AE@%%@AB@%s%@AE@%%@FN@%The %@AB@%s%@AE@% string format is used only with the C expression evaluator; it printscharacters up to the first null.%@EF@% Characters printed up to the %@AS@%? "String",s String%@AE@% first null character%@TE: 31 2189 3 13 35 14 14 @% %@NL@% %@CR:MCV61005@%%@4@%If no format specifier is given, single- and double-precision real numbers%@EH@% are displayed as if the format specifier had been given as %@AB@%g%@AE@%. (If you are familiar with the C language, you should note that the %@AB@%n%@AE@% and %@AB@%p%@AE@% format specifiers and the %@AB@%F%@AE@% and %@AB@%H%@AE@% prefixes are not supported by the CodeView debugger, even though they are supported by the C %@AB@%printf%@AE@% function.)%@NL@% %@NL@% %@CR:MCV61006@%%@4@%The prefix %@AB@%h%@AE@% can be used with the integer format specifiers (%@AB@%d%@AE@%, %@AB@%o%@AE@%, %@AB@%u%@AE@%, %@AB@%x%@AE@%, and%@EH@% %@AB@%X%@AE@%) to specify a two-byte integer. The prefix %@AB@%l%@AE@% can be used with the same types to specify a four-byte integer. For example, the command %@AS@%?100000,ld%@AE@% produces the output %@AS@%100000%@AE@%. However, the command %@AS@%?100000,hd%@AE@% evaluates only the low-order two bytes, producing the output %@AS@%-31072%@AE@%.%@NL@% %@NL@% %@CR:MCV61007@%%@4@%You can specify individual members of a C structure or BASIC user-defined%@EH@% type, or display the entire structure. Each member of a structure or BASIC user-defined type is displayed, within the limits of the dialog box. (See Section 6.2%@BO: 48adf@%, "The Graphic Display Command," for information on how to see all the fields of a large structure.)%@NL@% %@NL@% %@CR:MCV61008@%%@4@%The Display Expression command does not work for programs assembled with%@EH@% Microsoft Macro Assembler Versions 4.0 and earlier because the assembler does not write information to the object file about the type size of each variable. Use the Dump command instead.%@NL@% %@NL@% %@CR:MCV61009@%%@4@%When calling a FORTRAN subroutine that uses alternate returns, the value of%@EH@% the return labels in the actual parameter list must be 0. For example, the subroutine call %@AS@%CALL PROCESS (I,*10,J,*20,*30)%@AE@% must be called from the debugger as%@AS@%?PROCESS(IARG1,0,IARG2,0,0)%@AE@%. Using other values as return labels will cause the error %@AS@%Type%@AE@%%@AS@%clash in function argument%@AE@% or %@AS@%Unknown symbol%@AE@%.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Do not use a %@AI@%type specifier when evaluating strings in FORTRAN or%@AE@% %@AI@%BASIC.%@AE@%%@NL@% %@AI@%Simply leave off the type specifier, and the expression evaluator%@AE@% %@AI@%will%@AE@%%@NL@% %@AI@%display the string correctly. The%@AE@% %@AI@%s%@AE@%%@AI@% type%@AE@% %@AI@%specifier assumes the C language%@AE@%%@NL@% string format, with which other languages conflict; if you use %@AI@%s%@AE@%, then%@NL@% the debugger will simply display characters at the given address until a%@NL@% null is encountered.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV6100A@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6100B@%%@4@%The Display Expression command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV6100C@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6100D@%%@4@%The Display Expression command cannot be executed by using a keyboard%@EH@% command.%@NL@% %@NL@% %@CR:MCV6100E@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6100F@%%@4@%To display the value of an expression using a dialog command, enter a%@EH@% command line with the following syntax:%@NL@% %@NL@% %@AB@%?%@AE@% %@AI@%expression%@AE@%[[%@AB@%,%@AE@%%@AI@%format%@AE@%]]%@NL@% %@NL@% %@CR:MCV6100G@%%@4@%The %@AI@%expression%@AE@% is any valid CodeView expression, and the optional %@AI@%format%@AE@% is%@EH@% a CodeView format specifier.%@NL@% %@NL@% %@CR:MCV6100H@%%@4@%The remainder of this section first gives examples that are relevant to all%@EH@% languages and then gives examples specific to C, FORTRAN, and BASIC.%@NL@% %@NL@% %@CR:MCV6100I@%%@4@%If you are debugging code written with the assembler, you will use the C%@EH@% expression evaluator by default. See Section 4.4%@BO: 37e4e@% for guidelines on how to use the C expression evaluator with assembly code.%@NL@% %@NL@% %@CR:MCV6100J@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >? amount%@NL@% 500%@NL@% >? amount,x%@NL@% 1f4%@NL@% >? amount,o%@NL@% 764%@NL@% >%@NL@% %@NL@% %@CR:MCV6100K@%%@4@%The example above displays the value stored in the variable %@AS@%amount%@AE@%, an%@EH@% integer. This value is first displayed in the system radix (in this case, decimal), then in hexadecimal, and then in octal.%@NL@% %@NL@% ? mystruct%@NL@% {c1=123, c2={a=1, b=2}, c3=0x1000:2d34}%@NL@% %@NL@% %@CR:MCV6100L@%%@4@%The example above shows how the CodeView debugger displays a C structure or%@EH@% BASIC user-defined type. Note that nested structures are displayed within an extra set of braces.%@NL@% %@NL@% >? 92,x%@NL@% 5c%@NL@% >? 109*(35+2),o%@NL@% 7701%@NL@% >? 118,c%@NL@% v%@NL@% >%@NL@% %@NL@% %@CR:MCV6100M@%%@4@%The example above shows how the CodeView debugger can be used as a%@EH@% calculator. You can convert between radixes, calculate the value of constant expressions, or check ASCII equivalences.%@NL@% %@NL@% >? chance,f%@NL@% 0.083333%@NL@% >? chance,e%@NL@% 8. 333333e-002%@NL@% >? chance,E%@NL@% 8.333333E-002%@NL@% %@NL@% %@CR:MCV6100N@%%@4@%The example above shows a double-precision real number, %@AS@%chance%@AE@%, displayed in%@EH@% three formats. The %@AB@%f%@AE@% format always displays six digits of precision. The %@AB@%e%@AE@% format uses scientific notation. Note that the %@AB@%E%@AE@% format yields essentially the same display as %@AB@%e%@AE@% does.%@NL@% %@NL@% %@CR:MCV6100O@%%@4@%The rest of the examples in this section are specific to particular%@EH@% languages.%@NL@% %@NL@% %@CR:MCV6100P@%%@4@%%@AB@%C Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6100Q@%%@4@%The following examples assume that a C source file is being debugged and it%@EH@% contains the following declarations:%@NL@% %@NL@% char *text = "Here is a string."%@NL@% int amount;%@NL@% struct {%@NL@% char name[20];%@NL@% int id;%@NL@% long class;%@NL@% } student, *pstudent;%@NL@% %@NL@% int square(int);%@NL@% %@NL@% %@CR:MCV6100R@%%@4@%Assume also that the program has been executed where the above variables%@EH@% have been assigned values, and that the C expression evaluator is in use.%@NL@% %@NL@% >? text, X%@NL@% 13f3%@NL@% >DA 0x13F3%@NL@% 3D83:13F0 Here is a string.%@NL@% >? text,s%@NL@% Here is a string.%@NL@% >%@NL@% %@NL@% %@CR:MCV6100S@%%@4@%The example above shows how to examine strings. One method is to evaluate%@EH@% the variable that points to the string, and then dump the values at that address (the Dump commands are explained in Section 6.4%@BO: 4e3b9@%). A more direct method is to use the %@AB@%s%@AE@% type specifier.%@NL@% %@NL@% >? student.id%@NL@% 19643%@NL@% >? pstudent->id%@NL@% 19643%@NL@% >%@NL@% %@NL@% %@CR:MCV6100T@%%@4@%The example above illustrates how to display the values of members of a%@EH@% structure. The same syntax applies to unions.%@NL@% %@NL@% >? amount%@NL@% 500%@NL@% >? ++amount%@NL@% 501%@NL@% >? amount=600%@NL@% 600%@NL@% >%@NL@% %@NL@% %@CR:MCV6100U@%%@4@%The example above shows how the Display Expression command can be used with%@EH@% the C expression evaluator to change the values of variables.%@NL@% %@NL@% >? square(9)%@NL@% 81%@NL@% >%@NL@% %@NL@% %@CR:MCV6100V@%%@4@%The example above shows how functions can be evaluated in expressions. The%@EH@% CodeView debugger executes the function %@AS@%square%@AE@% with an argument of %@AS@%9%@AE@%, and displays the value returned by the function. Note that you can use symbols as well as constants as function arguments. However, you can only display function values after you have executed into the function %@AS@%main%@AE@%.%@NL@% %@NL@% %@CR:MCV6100W@%%@4@%The C expression evaluator also supports type casts. The equivalent of a%@EH@% type cast in another language is a type-conversion function.%@NL@% %@NL@% %@CR:MCV6100X@%%@4@%%@AB@%FORTRAN Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6100Y@%%@4@%The examples below assume that the FORTRAN source file contains the%@EH@% following variable declarations, in which %@AS@%SQUARE%@AE@% is a function:%@NL@% %@NL@% INTEGER*2 SQUARE%@NL@% INTEGER*2 AMOUNT%@NL@% CHARACTER*16 STR%@NL@% STR = 'Here is a string'%@NL@% %@NL@% %@CR:MCV6100Z@%%@4@%Assume also that the program has executed to the point where these variables%@EH@% have been assigned values, and that the FORTRAN expression evaluator has been selected.%@NL@% %@NL@% >? STR%@NL@% 'Here is a string'%@AS@%%@NL@% %@NL@% %@CR:MCV6100a@%%@4@%The example above shows how to examine strings with the FORTRAN expression%@EH@% evaluator. The %@AB@%s%@AE@% format specifier is not required.%@NL@% %@NL@% ? AMOUNT%@NL@% 500%@NL@% >? AMOUNT=AMOUNT+1%@NL@% 501%@NL@% >? AMOUNT=600%@NL@% 600%@NL@% >? AMOUNT%@NL@% 600%@NL@% >%@AS@%%@NL@% %@NL@% %@CR:MCV6100b@%%@4@%The example above shows how the Display Expression command can be used to%@EH@% change values with the FORTRAN expression evaluator.%@NL@% %@NL@% ? SQUARE(9)%@NL@% 81%@NL@% >%@NL@% %@NL@% %@CR:MCV6100c@%%@4@%The example above shows how functions can be evaluated in expressions. The%@EH@% CodeView debugger executes the function %@AS@%SQUARE%@AE@% with an argument of %@AS@%9%@AE@%, and displays the value returned by the function. You can only display the values of functions after you have executed into the main program level.%@NL@% %@NL@% %@CR:MCV6100d@%%@4@%%@AB@%BASIC Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6100e@%%@4@%These examples assume the BASIC source file contains the following%@EH@% statements:%@NL@% %@NL@% amount% = 500%@NL@% str$ = "Here is a string"%@NL@% %@NL@% %@CR:MCV6100f@%%@4@%Assume also that the program has been executed up to these statements and%@EH@% that the BASIC expression evaluator is in use.%@NL@% %@NL@% >? str$%@NL@% Here is a %@AS@%string%@NL@% %@NL@% %@CR:MCV6100g@%%@4@%The first example above shows how to examine strings with the BASIC%@EH@% expression evaluator. The %@AB@%s%@AE@% format specifier should not be used.%@NL@% %@NL@% ? ASC(str$)%@NL@% 72%@AS@%%@NL@% %@NL@% %@CR:MCV6100h@%%@4@%The second example demonstrates one of the BASIC intrinsic functions%@EH@% supported by the CodeView debugger, %@AB@%ASC%@AE@%, which returns the ASCII value of the first character in a string.%@NL@% %@NL@% >? amount%%@NL@% 500%@NL@% >? LET amount%=amount%+1%@NL@% 501%@NL@% >? LET amount%=600%@NL@% 600%@NL@% >? amount%%@NL@% 600%@NL@% >%@NL@% %@NL@% %@CR:MCV6100i@%%@4@%The example above shows how the Display Expression command can be used to%@EH@% change values with the BASIC expression evaluator. With BASIC, the %@AB@%LET%@AE@% command can only be applied to numeric data, not strings.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The BASIC expression evaluator cannot evaluate functions defined in the%@NL@% program, as the C and FORTRAN expression evaluators can.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV6100j@%%@4@%%@AB@%Assembly Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6100k@%%@4@%By default, the C expression evaluator is used for debugging assembly%@EH@% modules. However, some C expressions are particularly helpful for debugging assembly code. Some typical examples are presented below.%@NL@% %@NL@% >? BY bx%@NL@% 12%@NL@% >%@NL@% %@NL@% %@CR:MCV6100l@%%@4@%The example above displays the first byte at the location pointed to by BX,%@EH@% and is equivalent to the assembly expression %@AS@%BYTE PTR%@AE@%%@AS@%[bx]%@AE@%.%@NL@% %@NL@% >? WO bp+8%@NL@% 9359%@NL@% >%@NL@% %@NL@% %@CR:MCV6100m@%%@4@%The example above displays the first word at the location pointed to by%@EH@% %@AS@%[bp+8]%@AE@%.%@NL@% %@NL@% >? DW si+12%@NL@% Y12555324%@NL@% >%@NL@% %@NL@% %@CR:MCV6100n@%%@4@%The example above displays the first double word at the location pointed to%@EH@% by %@AS@%[si+12]%@AE@%.%@NL@% %@NL@% >? (char) var%@NL@% 5%@NL@% >? (int) var%@NL@% 1005%@NL@% >%@NL@% %@NL@% %@CR:MCV6100o@%%@4@%The last two examples use type casts, which are similar to the assembler %@AB@%PTR%@AE@%%@EH@% operator. The expression %@AS@%(char) var%@AE@% displays the byte at the address of %@AS@%var%@AE@%, in signed format. The expression %@AS@%(int) var%@AE@% displays the word at the same address, also in signed format. You can alter either of these commands to display results in unsigned format simply by using the %@AB@%u%@AE@% format specifier.%@NL@% %@NL@% >? (char) var,u%@NL@% %@NL@% >? (int) var,u%@NL@% %@NL@% %@NL@% %@CR:MCV62000@%%@2@%%@AB@%6.2 The Graphic Display Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV62001@%%@4@%The Graphic Display command (%@AB@%??%@AE@%) is similar to the Examine Symbols command.%@EH@% The Graphic Display command shows the value of any symbol you specify. However, the Graphic Display command is the more efficient means for viewing a multiple-field object such as a structure or a linked list of data.%@NL@% %@NL@% %@CR:MCV62002@%%@4@%The Graphic Display command lets you browse through related data. For%@EH@% example, both C and BASIC let you define structures inside of other structures. (In BASIC, structures are called "user-defined types.") The Graphic Display command lets you quickly move up and down through layers of structures. The command also works with C pointer variables; with a single mouse click or a few keystrokes, you see the entire structure that a pointer addresses. When you examine a list of structures linked through pointers, the Graphic Display command lets you quickly move back and forth through the list.%@NL@% %@NL@% %@CR:MCV62003@%%@4@%To resume debugging, you must remove the Graphic Display dialog box.%@EH@% Pressing ESC terminates the dialog box.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Throughout the rest of this section, the term "structure" is used to%@NL@% refer to any of the following: a C structure, Pascal record, or BASIC%@NL@% user-defined type.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV62004@%%@4@%This section discusses how to invoke the Graphic Display command and how to%@EH@% browse through data once the Graphic Display dialog box appears. Regardless of how you invoke the command, the same rules apply for browsing through the data.%@NL@% %@NL@% %@NL@% %@CR:MCV62100@%%@3@%%@AB@%6.2.1 Invoking the Graphic Display Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV62101@%%@4@%The Graphic Display command is useful for evaluating a structure or pointer,%@EH@% although you can legally use the command with any variable. To use this command to display the contents of a variable, enter the following:%@NL@% %@NL@% %@AB@%??%@AE@%%@AI@%symbol,%@AE@% %@AB@%c%@AE@%%@NL@% %@NL@% %@CR:MCV62102@%%@4@%In the syntax display above, %@AI@%symbol%@AE@% is the name of any recognized variable,%@EH@% the second field is either blank or contains the character c.%@NL@% %@NL@% %@CR:MCV62103@%%@4@%The second field may contain the character %@AS@%c%@AE@%. This character is a C %@AB@%printf%@AE@%%@EH@% format specifier that causes CodeView to display each byte of a character array in its ASCII form, rather than display its numerical value.%@NL@% %@NL@% %@CR:MCV62104@%%@4@%As shown in the Figure 6.1%@FN@% Figure 6.1 is found on page 108 of the printed version.%@EF@% below, structures are represented as three dots%@EH@% enclosed in braces: {...}. Pointers are represented in the standard %@AI@%segment%@AE@%%@AB@%:%@AE@%%@AI@%offset%@AE@% format. The Graphic Display dialog box also displays a title; the title is the name of the variable or member currently displayed.%@NL@% %@NL@% %@CR:MCV62105@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% ?? graduate, c%@NL@% %@NL@% %@CR:MCV62106@%%@4@%The example above displays the members of a structure, as shown in Figure%@EH@% 6.1%@FN@% Figure 6.1 is found on page 108 of the printed version.%@EF@%.%@NL@% %@NL@% %@CR:MCV62107@%%@4@%As is the case with the display of local variables, nested structures are%@EH@% represented as three dots enclosed in braces, and pointers are represented in the standard%@AI@%segment%@AE@%:%@AI@%offset%@AE@% format. Section 6.2.2%@BO: 49b89@%, "Changing the Display," explains how to select nested structures and pointers for display.%@NL@% %@NL@% ?? Kount%@AB@%%@NL@% %@NL@% %@CR:MCV62108@%%@4@%Since %@AS@%Kount%@AE@% is neither a structure nor an array, CodeView responds by%@EH@% displaying a single field as shown in Figure 6.2%@FN@% Figure 6.2 is found on page 109 of the printed version.%@EF@%.%@NL@% %@NL@% %@CR:MCV62109@%%@4@%To close the Graphic display dialog box and continue debugging, click left%@EH@% outside the dialog box or press ESC.%@NL@% %@NL@% %@NL@% %@CR:MCV62200@%%@3@%%@AB@%6.2.2 Changing the Display%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV62201@%%@4@%Once the Graphic Display dialog box appears, you change what information is%@EH@% displayed by selecting an individual variable, member, or array element. (However, the command displays array elements only when the current module is a C module.) Making such a selection changes the subject matter of the dialog box; for example, selecting a nested structure moves you one level deeper within the structure. You can use either the mouse or the keyboard to select an item.%@NL@% %@NL@% %@CR:MCV62202@%%@4@%%@AB@%Changing the Display with the Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV62203@%%@4@%To select an item with the mouse, simply click the left mouse button on the%@EH@% line where the item appears.%@NL@% %@NL@% %@CR:MCV62204@%%@4@%CodeView allows you to move backward through displays as well as forward.%@EH@% After you select an item and move to a new display, CodeView remembers the previous state of the dialog box. To move back to the previous display, click the backward arrow just below the dialog box title, or click the right mouse button.%@NL@% %@NL@% %@CR:MCV62205@%%@4@%To close the dialog box and continue debugging, click the left mouse button%@EH@% while outside the dialog box.%@NL@% %@NL@% %@CR:MCV62206@%%@4@%%@AB@%Changing the Display with the Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV62207@%%@4@%To select an item with the keyboard, move the cursor to the desired item and%@EH@% press ENTER.%@NL@% %@NL@% %@CR:MCV62208@%%@4@%CodeView allows you to move backward through displays as well as forward.%@EH@% After you select an item and move to a new display, CodeView remembers the previous state of the dialog box. To move back to the previous display, press BACKSPACE.%@NL@% %@NL@% %@CR:MCV62209@%%@4@%To close the dialog box and continue debugging, press ESC.%@EH@%%@NL@% %@NL@% %@CR:MCV6220A@%%@4@%%@AB@%Effect of Selecting an Item%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6220B@%%@4@%Depending on the item you select, CodeView executes a specific action:%@EH@%%@NL@% %@NL@% %@CR:MCV6220C@%%@AB@%Item Action%@AE@%%@NL@% %@NL@% Nested structure The structure is "expanded"; the nested%@NL@% structure becomes the new subject of the dialog%@NL@% box. The dialog box displays each member of the%@NL@% nested structure.%@NL@% %@NL@% Pointer The pointer is "dereferenced"; in other words,%@NL@% CodeView locates the data that the pointer%@NL@% addresses. This data becomes the new subject of%@NL@% the dialog box.%@NL@% %@NL@% The pointer's type determines how the debugger%@NL@% displays the dereferenced data. The debugger%@NL@% uses this type information even if the pointer%@NL@% does not currently address any meaningful data.%@NL@% If the pointer addresses a structure, CodeView%@NL@% displays each element.%@NL@% %@NL@% Other items CodeView takes no action.%@NL@% %@NL@% %@CR:MCV6220D@%%@4@%No matter how many times you change the display, and no matter what the%@EH@% previous display looked like, all the rules above apply. You can repeat these operations any number of times. For example, given a sufficiently complex structure, you can move down several levels of nested structures, then follow a pointer reference to another variable.%@NL@% %@NL@% %@NL@% %@CR:MCV63000@%%@2@%%@AB@%6.3 Examine Symbols Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV63001@%%@4@%The Examine Symbols command displays the names and addresses and the names%@EH@% of modules defined within a program. You can specify the group you want to examine by module, procedure, or name.%@NL@% %@NL@% %@CR:MCV63002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV63003@%%@4@%The Examine Symbols command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV63004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV63005@%%@4@%The Examine Symbols command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCV63006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV63007@%%@4@%To view the addresses of symbols with a dialog command, enter a command line%@EH@% in one of the following formats:%@NL@% %@NL@% %@AB@%XL%@AE@%%@NL@% %@AB@%X*%@AE@%%@NL@% %@AB@%X%@AE@%%@NL@% %@AB@%X?%@AE@% «%@AI@%module%@AE@%%@AB@%!%@AE@%» «%@AI@%routine%@AE@%%@AB@%.%@AE@%» «%@AI@%symbol%@AE@%» «%@AB@%*%@AE@%»%@NL@% %@NL@% %@CR:MCV63008@%%@4@%in which %@AI@%routine%@AE@% is in a program unit, such as a C function or a BASIC%@EH@% subprogram, capable of having its own local variables.%@NL@% %@NL@% %@CR:MCV63009@%%@4@%The syntax combinations are listed in more detail below.%@EH@%%@NL@% %@CR:MCV6300A@%%@NL@% %@TH: 38 2297 2 28 48 @%%@AB@%Syntax Display%@AE@%%@AB@%X?%@AE@%%@AI@%module%@AE@%%@AB@%!%@AE@%%@AI@%routine%@AE@%%@AB@%.%@AE@%%@AI@%symbol%@AE@% The specified %@AI@%symbol%@AE@% in the specified %@AI@%routine%@AE@% in the specified %@AI@%module%@AE@%.%@AB@%X?%@AE@%%@AI@%module%@AE@%%@AB@%!%@AE@%%@AI@%routine%@AE@%%@AB@%.*%@AE@% All symbols in the specified %@AI@%routine%@AE@% in the specified %@AI@%module%@AE@%.%@AB@%X?%@AE@%%@AI@%module%@AE@%%@AB@%!%@AE@%%@AI@%symbol%@AE@% The specified %@AI@%symbol%@AE@% in the specified %@AI@%module%@AE@% (symbols within routines are not found).%@AB@%X?%@AE@%%@AI@%module%@AE@%%@AB@%!*%@AE@% All symbols in the specified %@AI@%module%@AE@%.%@AB@%X?%@AE@%%@AI@%routine%@AE@%%@AB@%.%@AE@%%@AI@%symbol%@AE@% The specified %@AI@%symbol%@AE@% in the specified %@AI@%routine%@AE@% (looks for %@AI@%routine%@AE@% first in the current module, and then in other modules from first to last).%@AB@%X?%@AE@%%@AI@%routine%@AE@%%@AB@%.*%@AE@% All symbols in the specified %@AI@%routine%@AE@% (looks for %@AI@%routine%@AE@% first in the current module, and then in other modules from first to last).%@AB@%X?%@AE@%%@AI@%symbol%@AE@% Looks for the specified %@AI@%symbol%@AE@% in this order: 1. In the current routine. 2. In the current module. 3. In other modules, from first to last.%@AB@%X?*%@AE@% All symbols in the current routine.%@AB@%XL%@AE@% All local variables of the currently executing routine. This variation of the command uses a special format as explained below.%@AB@%X*%@AE@% All module names (file extensions are added to these names).%@AB@%X%@AE@% All symbolic names in the program, including all modules and symbols.%@TE: 38 2297 2 28 48 @% %@NL@% %@CR:MCV6300B@%%@4@%When you debug an assembly module, you cannot use the %@AI@%routine%@AE@% field; you%@EH@% must use the %@AI@%module%@AE@% field. Therefore, the only versions of this command that work with assembly modules are the following:%@NL@% %@NL@% %@AB@%X?%@AE@%%@AI@%module%@AE@%%@AB@%!*%@AE@%%@NL@% %@AB@%X?%@AE@%%@AI@%module%@AE@%%@AB@%!%@AE@%%@AI@%symbol%@AE@%%@NL@% %@NL@% XL is a special variation of the Examine Symbol command. It lists local variables for the currently executing routine and provides more information than other variations of the command.%@NL@% %@NL@% %@CR:MCV6300C@%%@4@%Whereas most forms of the command display the address, type, and name of%@EH@% each symbol, the %@AB@%XL%@AE@% variation displays the value of each local variable as well. The value of a local variable is displayed in the same format that the Display Expression command would use, assuming no type specifier.%@NL@% %@NL@% %@CR:MCV6300D@%%@4@%The following example shows the use of the %@AB@%XL%@AE@% command when the currently%@EH@% executing routine has many local variables.%@NL@% %@NL@% >XL%@NL@% [BP+0004] int argc = 1%@NL@% [BP+0006] char * * argv = 0x2f:0x1510%@NL@% [BP-0002] int i = 20%@NL@% SI register int k = 7%@NL@% [BP-0078] struct cat item0 = {item1=0, item2=0, dog=0x2f:0x1476}%@NL@% [BP-0070] struct cow moo = {c1=11, c2=22, c3=36, c4=16}%@NL@% [BP-0008] char * wiz = 0x2f:0x1514%@NL@% [BP-0080] int duck = 0%@NL@% DI register int j = 83%@NL@% %@NL@% %@CR:MCV6300E@%%@4@%In the example above, variables %@AS@%i%@AE@% and %@AS@%j%@AE@% are register variables assigned to%@EH@% the registers %@AS@%SI%@AE@% and %@AS@%DI%@AE@%, respectively. The other variables are located on the stack; %@AS@%XL%@AE@% shows the displacement of each variable from the %@AS@%BP%@AE@% register, which holds the value of the stack pointer (SP) at the time of entry into the procedure.%@NL@% %@NL@% %@CR:MCV6300F@%%@4@%If you have a parameter that is declared as a register in a C program, it%@EH@% will appear twice: on the stack (as an offset from BP) and in the SI or DI register.%@NL@% %@NL@% %@CR:MCV6300G@%%@4@%Note that if you program in assembly, local variables are not recognized by%@EH@% CodeView unless you use the %@AB@%PROC%@AE@% and %@AB@%LOCALS%@AE@% directives provided with MASM Version 5.1 and later.%@NL@% %@NL@% %@CR:MCV6300H@%%@4@%The rest of this section shows examples using the other variations of the%@EH@% Examine Symbols command.%@NL@% %@NL@% %@CR:MCV6300I@%%@4@%%@AB@%C Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6300J@%%@4@%For the following examples, assume that the program being examined is called%@EH@% %@AS@%pi.exe%@AE@%, and that it consists of two modules: %@AS@%pi.c%@AE@% and %@AS@%math.c%@AE@%. The %@AS@%pi.c%@AE@% module is a skeleton consisting only of the %@AS@%main%@AE@% function, whereas the %@AS@%math.c%@AE@% module has several functions. Assume that the current function is %@AB@%div%@AE@% within the %@AS@%math%@AE@% module.%@NL@% %@NL@% >X* %@AI@%;*Example 1%@AE@%%@NL@% PI.OBJ%@NL@% MATH.OBJ%@NL@% chkstk.asm%@NL@% crt0.asm%@NL@% .%@NL@% .%@NL@% .%@NL@% C:\LIB\SLIBC.LIB(xtoa.asm)%@NL@% >%@NL@% %@NL@% %@CR:MCV6300K@%%@4@%Example 1 lists the two user-created modules of the program, as well as the%@EH@% library modules used in the program.%@NL@% %@NL@% >X?* %@AI@%;*Example 2%@AE@%%@NL@% DI int b%@NL@% [BP-0006] int quotient%@NL@% SI int i%@NL@% [BP-0002] int remainder%@NL@% [BP+0004] int divisor%@NL@% >%@NL@% %@NL@% %@CR:MCV6300L@%%@4@%Example 2 lists the symbols in the current function (%@AB@%div%@AE@%). Local variables%@EH@% are shown as being stored either in a register (%@AS@%b%@AE@% in register %@AS@%DI%@AE@%) or at a memory location specified as an offset from a register (%@AS@%divisor%@AE@% at location %@AS@%[BP+0004]%@AE@%).%@NL@% %@NL@% >X?pi!* %@AI@%;* Example 3%@AE@%%@NL@% 3D37:19B2 int _scratch0 3D37:0A10 char _p[]%@NL@% 3D37:2954 int _scratch1 3D37:19B4 char _t[]%@NL@% 3D37:2956 int _scratch2 3D37:19B0 int _q%@NL@% 3A79:0010 int _main() 3A79:0010 int main()%@NL@% 3D37:19B2 int scratch0%@NL@% 3D37:0A10 char p[]%@NL@% 3D37:2954 int scratch1%@NL@% 3D37:19B4 char t[]%@NL@% 3D37:2956 int scratch2%@NL@% 3D37:19B0 int q%@NL@% >%@NL@% %@NL@% %@CR:MCV6300M@%%@4@%Example 3 shows all the symbols in the %@AS@%pi.c%@AE@% module.%@EH@%%@NL@% %@NL@% >X?math!div.* %@AI@%;*Example 4%@AE@%%@NL@% 3A79:0264 int div()%@NL@% DI int b%@NL@% [BP-0006] int quotient%@NL@% SI int i%@NL@% [BP-0002] int remainder%@NL@% [BP+0004] int divisor%@NL@% >%@NL@% %@NL@% %@CR:MCV6300N@%%@4@%Example 4 shows the symbols in the %@AS@%div%@AE@% function in module %@AS@%math.c%@AE@%. You%@EH@% wouldn't need to specify the module if %@AS@%math.c%@AE@% were the current module, but you would if the current module were %@AS@%pi.c%@AE@%.%@NL@% %@NL@% %@CR:MCV6300O@%%@4@%Variables local to a function are indented under that function.%@EH@%%@NL@% %@NL@% >X?math!arctan.s %@AI@%;* Example 5%@AE@%%@AE@%%@NL@% 3A79:00FA int arc%@AS@%tan()%@AE@%%@NL@% [BP+0004] int s%@NL@% >%@NL@% %@NL@% %@CR:MCV6300P@%%@4@%Example 5 shows one specific variable (%@AS@%s%@AE@%) within the %@AS@%arctan%@AE@% function.%@EH@%%@NL@% %@NL@% %@CR:MCV6300Q@%%@4@%%@AB@%FORTRAN Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6300R@%%@4@%For the following examples, assume that the program being examined is called%@EH@% %@AS@%FRUST.EXE%@AE@%, and it consists of four modules: %@AS@%FRUST.FOR%@AE@%, %@AS@%FRUST1.FOR%@AE@%, %@AS@%FRUST2.FOR%@AE@%, and %@AS@%FRUST3.FOR%@AE@%. Assume that the current routine is %@AS@%main%@AE@% within the %@AS@%FRUST.FOR%@AE@% module.%@NL@% %@NL@% >X*%@NL@% FRUST.OBJ%@NL@% FRUST1.OBJ%@NL@% FRUST2.OBJ%@NL@% FRUST3.OBJ%@NL@% fixups.asm%@NL@% crt0.asm%@NL@% .%@NL@% .%@NL@% .%@NL@% txtmode.asm%@NL@% _creat.asm%@NL@% %@NL@% %@CR:MCV6300S@%%@4@%The example above lists the four modules called by the program. The library%@EH@% files called by the program are also listed.%@NL@% %@NL@% >X?T%@NL@% 520D:0DE4 REAL*4 T%@NL@% %@NL@% %@CR:MCV6300T@%%@4@%The example above shows the address of the variable %@AS@%T%@AE@% in the current module.%@EH@%%@NL@% %@NL@% >X?FRUST3!MULTPI.*%@NL@% 4B28:0005 INTEGER*4 MULTPI()%@NL@% [BP+000A] V%@NL@% [BP+0006] X%@NL@% [BP-0004] INTEGER*4 MULTPI%@NL@% %@NL@% %@CR:MCV6300U@%%@4@%The example above lists the symbols in the function %@AS@%MULTPI%@AE@%, located in%@EH@% module %@AS@%FRUST3%@AE@%. Variables local to the function are indented under the function. You wouldn't need to specify the module if %@AS@%FRUST3%@AE@% were the current module.%@NL@% %@NL@% >X?FRUST2!SAREA.*%@NL@% 4B15:000E void SAREA()%@NL@% [BP+0012] R1%@NL@% [BP+000E] R2%@NL@% [BP+000A] H%@NL@% [BP+0006] T%@NL@% 520D:0DEC REAL*4 S12%@NL@% 520D:0DE8 REAL*4 U%@NL@% %@NL@% %@CR:MCV6300V@%%@4@%The example above shows all the symbols in the routine %@AS@%SAREA%@AE@% in the module%@EH@% %@AS@%FRUST2%@AE@%. Because %@AS@%SAREA%@AE@% is a subroutine instead of a function, the word %@AS@%void%@AE@% appears where function return-value types are shown.%@NL@% %@NL@% %@CR:MCV6300W@%%@4@%%@AB@%BASIC Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV6300X@%%@4@%For the following examples, assume that the program being examined is called%@EH@% %@AS@%PROG.EXE%@AE@%, and it consists of the following modules: %@AS@%PROG.BAS%@AE@% and %@AS@%SORT.BAS%@AE@%. Assume that the current routine is the main program (which, unlike subprograms, has no name in a BASIC program) and the module %@AS@%SORT.BAS%@AE@% contains two subprograms, %@AS@%SORT%@AE@% and %@AS@%SWITCH%@AE@%.%@NL@% %@NL@% >X*%@NL@% PROG.OBJ%@NL@% SORT.OBJ%@NL@% ftmdata.asm%@NL@% crt0.asm%@NL@% crt0dat.asm%@NL@% .%@NL@% .%@NL@% .%@NL@% xtoa.asm%@NL@% %@NL@% %@CR:MCV6300Y@%%@4@%The example above lists the two modules of the program, including %@AS@%PROG.OBJ%@AE@%,%@EH@% which is the main module. The BASIC library files called by the program are also listed.%@NL@% %@NL@% >X?*%@NL@% 5825:17BE integer A%[array]%@NL@% 5825:1780 single HOURS!%@NL@% 5825:1784 integer I%%@NL@% %@NL@% %@CR:MCV6300Z@%%@4@%The example above lists the symbols in the current routine, which happens to%@EH@% be the main program. Although the main program has no label and therefore will not show up in a stack trace, it is still an independent routine and has its own local variables. In BASIC, local variables are not put on the stack unless they are subprogram parameters.%@NL@% %@NL@% >X?*SORT!*%@NL@% 572F:0033 integer SORT()%@NL@% 572F:00E1 integer SWITCH()%@NL@% %@NL@% %@CR:MCV6300a@%%@4@%The example above lists the routines in the module %@AS@%SORT.OBJ%@AE@%. This form of%@EH@% the Display Symbols command lists routines only, not variables. Note that %@AS@%SORT()%@AE@% and %@AS@%SWITCH()%@AE@% are given with the addresses of the two subprograms by that name.%@NL@% %@NL@% >X?SORT!SWITCH.*%@NL@% [BP+0008] integer B%%@NL@% [BP+0006] integer C%%@NL@% 5824:1798 integer TEMP%%@NL@% %@NL@% %@CR:MCV6300b@%%@4@%The example above shows all the symbols in the routine %@AS@%SWITCH%@AE@%, which is in%@EH@% the %@AS@%SORT.OBJ%@AE@% module. Each represents an integer. However, %@AS@%B%%@AE@% and %@AS@%C%%@AE@% represent subprogram parameters that were passed on the stack, whereas%@NL@% %@NL@% %@CR:MCV6300c@%%@4@%%@AS@%TEMP%%@AE@% is a true subprogram variable. Therefore, %@AS@%TEMP%%@AE@% has an absolute%@EH@% address in memory, whereas %@AS@%B%%@AE@% and %@AS@%C%%@AE@% are addressed relative to the stack.%@AE@% %@AS@%(%@AE@%%@AS@%BP%@AE@% points to the value of the stack at the time the routine %@AS@%SWITCH%@AE@% was called.)%@NL@% %@NL@% %@NL@% %@CR:MCV64000@%%@2@%%@AB@%6.4 Dump Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64001@%%@4@%The CodeView debugger has several commands for dumping data from memory to%@EH@% the screen (or other output device). The Dump commands are listed below.%@NL@% %@NL@% %@CR:MCV64002@% %@AB@%Command Command Name%@AE@%%@NL@% %@NL@% %@AB@%D%@AE@% Dump (size is the default type)%@NL@% %@NL@% %@AB@%DB%@AE@% Dump Bytes%@NL@% %@NL@% %@AB@%DA%@AE@% Dump ASCII%@NL@% %@NL@% %@AB@%DI%@AE@% Dump Integers%@NL@% %@NL@% %@AB@%DU%@AE@% Dump Unsigned Integers%@NL@% %@NL@% %@AB@%DW%@AE@% Dump Words%@NL@% %@NL@% %@AB@%DD%@AE@% Dump Double Words%@NL@% %@NL@% %@AB@%DS%@AE@% Dump Short Reals%@NL@% %@NL@% %@AB@%DL%@AE@% Dump Long Reals%@NL@% %@NL@% %@AB@%DT%@AE@% Dump 10-Byte Reals%@NL@% %@NL@% %@CR:MCV64003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64004@%%@4@%The Dump commands cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV64005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64006@%%@4@%The Dump commands cannot be executed with keyboard commands.%@EH@%%@NL@% %@NL@% %@CR:MCV64007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64008@%%@4@%To execute a Dump command with a dialog command, enter a command line with%@EH@% the following syntax:%@NL@% %@NL@% %@AB@%D%@AE@%«%@AI@%type%@AE@%» «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64009@%%@4@%The %@AI@%type%@AE@% is a one-letter specifier that indicates the type of the data to be%@EH@% dumped. The Dump commands expect either a starting %@AI@%address%@AE@% or a %@AI@%range%@AE@% of memory. If the starting %@AI@%address%@AE@% is given, the commands assume a default range (usually%@NL@% %@NL@% %@CR:MCV6400A@%%@4@%determined by the size of the dialog window) starting at %@AI@%address%@AE@%. If %@AI@%range%@AE@%%@EH@% is given, the commands dump from the start to the end of %@AI@%range%@AE@%. The maximum size of %@AI@%range%@AE@% is 32K.%@NL@% %@NL@% %@CR:MCV6400B@%%@4@%If neither %@AI@%address%@AE@% nor %@AI@%range%@AE@% is given, the commands assume the current dump%@EH@% address as the start of the range and the default size associated with the size of the object as the length of the range. The Dump Real commands have a default range size of one real number. The other Dump commands have a default size determined by the size of the dialog window (if you are in window mode), or a default size of 128 bytes otherwise.%@NL@% %@NL@% %@CR:MCV6400C@%%@4@%The current dump address is the byte following the last byte specified in%@EH@% the previous Dump command. If no Dump command has been used during the session, the dump address is the start of the data segment (DS). For example, if you enter the Dump Words command with no argument as the first command of a session, the CodeView debugger displays the first 64 words (128 bytes) of data declared in the data segment. If you repeat the same command, the debugger displays the next 64 words following the ones dumped by the first command.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% If the value in memory cannot be evaluated as a real number, the Dump%@NL@% commands that display real numbers (Dump Short Reals, Dump Long Reals, or%@NL@% Dump 10-Byte Reals) will display a number containing one of the following%@NL@% character sequences: %@AS@%#NAN%@AE@%, %@AS@%#INF%@AE@%, or %@AS@%#IND%@AE@%. NAN (not a number) indicates%@NL@% that the data cannot be evaluated as a real number. INF (infinity)%@NL@% indicates that the data evaluates to infinity. IND (indefinite) indicates%@NL@% that the data evaluates to an indefinite number.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV6400D@%%@4@%Sections 6.4.1%@BO: 4f43b@%-6.4.10 discuss the variations of the Dump commands in order%@EH@% of the size of data they display.%@NL@% %@NL@% %@NL@% %@CR:MCV64100@%%@3@%%@AB@%6.4.1 Dump%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64101@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%D%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64102@%%@4@%The Dump command displays the contents of memory at the specified %@AI@%address%@AE@% or%@EH@% in the specified %@AI@%range%@AE@% of addresses. The command dumps data in the format of the default type. The default type is the last type specified with a Dump, Enter, Watch Memory, or Tracepoint Memory command. If none of these commands has been entered during the session, the default type is bytes.%@NL@% %@NL@% %@CR:MCV64103@%%@4@%The Dump command displays one or more lines, depending on the address or%@EH@% range specified. Each line displays the address of the first item displayed. The Dump command must be separated by at least one space from any %@AI@%address%@AE@% or %@AI@%range%@AE@% value. For example, to dump memory starting at symbol %@AS@%a%@AE@%, use the command %@AS@%D a%@AE@%, not %@AS@%Da%@AE@%. The second syntax would be interpreted as the Dump ASCII command.%@NL@% %@NL@% %@NL@% %@CR:MCV64200@%%@3@%%@AB@%6.4.2 Dump Bytes%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64201@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%DB%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64202@%%@4@%The Dump Bytes command displays the hexadecimal and ASCII values of the%@EH@% bytes at the specified %@AI@%address%@AE@% or in the specified %@AI@%range%@AE@% of addresses. The command displays one or more lines, depending on the address or range supplied.%@NL@% %@NL@% %@CR:MCV64203@%%@4@%Each line displays the address of the first byte in the line, followed by up%@EH@% to 16 hexadecimal byte values. The byte values are immediately followed by the corresponding ASCII values. The hexadecimal values are separated by spaces, except the eighth and ninth values, which are separated by a dash (-). ASCII values are printed without separation. Unprintable ASCII values (less than 32 or greater than 126) are displayed as dots. No more than 16 hexadecimal values are displayed in a line. The command displays values and characters until the end of the %@AI@%range%@AE@% or, if no %@AI@%range%@AE@% is given, until the first 128 bytes have been displayed.%@NL@% %@NL@% %@CR:MCV64204@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >DB 0 36%@NL@% 3D5E:0000 53 6F 6D 65 20 6C 65 74-74 65 72 73 20 61 6E 64 Someletters and%@NL@% 3D5E:0010 20 6E 75 6D 62 65 72 73-3A 00 10 EA 89 FC FF EF numbers:.......%@NL@% 3D5E:0020 00 F0 00 CA E4 - .....%@NL@% >%@NL@% %@NL@% %@CR:MCV64205@%%@4@%The example above displays the byte values from %@AS@%DS:0%@AE@% to %@AS@%DS:36%@AE@% (36 decimal is%@EH@% equivalent to 24 hexadecimal). The data segment is assumed if no segment is given. ASCII characters are shown on the right.%@NL@% %@NL@% %@NL@% %@CR:MCV64300@%%@3@%%@AB@%6.4.3 Dump ASCII%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64301@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%DA%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64302@%%@4@%The Dump ASCII command displays the ASCII characters at a specified %@AI@%address%@AE@%%@EH@% or in a specified %@AI@%range%@AE@% of addresses. The command displays one or more lines of characters, depending on the %@AI@%address%@AE@% or %@AI@%range%@AE@% specified.%@NL@% %@NL@% %@CR:MCV64303@%%@4@%If no ending address is specified, the command dumps either 128 bytes or all%@EH@% bytes preceding the first null byte, whichever comes first. Up to 64 characters per line are displayed. Unprintable characters, such as carriage returns and line feeds, are displayed as dots. ASCII characters less than 32 and greater than 126 in number are unprintable.%@NL@% %@NL@% %@CR:MCV64304@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >DA 0%@NL@% 3D7C:0000 Some letters and numbers:%@NL@% >%@NL@% %@NL@% %@CR:MCV64305@%%@4@%The example above displays the ASCII values of the bytes starting at %@AS@%DS:0%@AE@%.%@EH@% Since no ending address is given, values are displayed up to the first null byte.%@NL@% %@NL@% >DA 0 36%@NL@% 3D7C:0000 Some letters and numbers:...........%@NL@% >%@NL@% %@NL@% %@CR:MCV64306@%%@4@%In the example above, an ending address is given, so that the characters%@EH@% from %@AS@%DS:0%@AE@% to %@AS@%DS:36%@AE@% (24 hexadecimal) are shown. Unprintable characters are shown as dots.%@NL@% %@NL@% %@NL@% %@CR:MCV64400@%%@3@%%@AB@%6.4.4 Dump Integers%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64401@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%DI%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64402@%%@4@%The Dump Integers command displays the signed decimal values of the words%@EH@% (two-byte values) starting at %@AI@%address%@AE@% or in the specified %@AI@%range%@AE@% of addresses. The command displays one or more lines, depending on the address or range specified. Each line displays the address of the first integer in the line, followed by up to eight signed decimal words. The values are separated by spaces. The command displays values until the end of the %@AI@%range%@AE@% or until the first 64 two-byte integers have been displayed, whichever comes first.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% In this manual an integer is considered a two-byte value since the%@NL@% CodeView debugger assumes that integer size. Note that a default FORTRAN%@NL@% integer is a four-byte value.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV64403@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >DI 0 36%@NL@% 3D5E:0000 28499 25965 27680 29797 25972 29554 24864 25710%@NL@% 3D5E:0010 28192 28021 25954 29554 58 -5616 -887 -4097%@NL@% 3D5E:0020 -4096 -13824 2532%@NL@% >%@NL@% %@NL@% %@CR:MCV64404@%%@4@%The example above displays the byte values from %@AS@%DS:0%@AE@% to %@AS@%DS:36%@AE@% (24%@EH@% hexadecimal). Compare the signed decimal numbers at the end of this dump with the same values shown as unsigned integers in Section 6.4.5%@BO: 50cc7@% below.%@NL@% %@NL@% %@NL@% %@CR:MCV64500@%%@3@%%@AB@%6.4.5 Dump Unsigned Integers%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64501@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%DU%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64502@%%@4@%The Dump Unsigned Integers command displays the unsigned decimal values of%@EH@% the words (two-byte values) starting at %@AI@%address%@AE@% or in the specified %@AI@%range%@AE@% of addresses. The command displays one or more lines, depending on the address or range specified. Each line displays the address of the first unsigned integer in the line, followed by up to eight decimal words. The values are separated by spaces. The command displays values until the end of the %@AI@%range%@AE@% or until the first 64 unsigned integers have been displayed, whichever comes first.%@NL@% %@NL@% %@CR:MCV64503@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >DU 0 36%@NL@% 3D5E:0000 28499 25965 27680 29797 25972 29554 24864 25710%@NL@% 3D5E:0010 28192 28021 25954 29554 58 59920 64649 61439%@NL@% 3D5E:0020 61440 51712 2532%@NL@% >%@NL@% %@NL@% %@CR:MCV64504@%%@4@%The example above displays the byte values from %@AS@%DS:0%@AE@% to %@AS@%DS:36%@AE@% (24%@EH@% hexadecimal). Compare the unsigned decimal numbers at the end of this dump with the same values shown as signed integers in Section 6.4.4%@BO: 505cb@% above.%@NL@% %@NL@% %@NL@% %@CR:MCV64600@%%@3@%%@AB@%6.4.6 Dump Words%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64601@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%DW%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64602@%%@4@%The Dump Words command displays the hexadecimal values of the words%@EH@% (two-byte values) starting at %@AI@%address%@AE@% or in the specified %@AI@%range%@AE@% of addresses. The command displays one or more lines, depending on the address or range specified. Each line displays the address of the first word in the line, followed by up to eight hexadecimal words. The hexadecimal values are separated by spaces. The command displays values until the end of the %@AI@%range%@AE@% or until the first 64 words have been displayed, whichever comes first.%@NL@% %@NL@% %@CR:MCV64603@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >DW 0 36%@NL@% 3D5E:0000 6F53 656D 6C20 7465 6574 7372 6120 646E%@NL@% 3D5E:0010 6E20 6D75 6562 7372 003A EA10 FC89 EFFF%@NL@% 3D5E:0020 F000 CA00 09E4%@NL@% >%@NL@% %@NL@% %@CR:MCV64604@%%@4@%The example above displays the word values from %@AS@%DS:0%@AE@% to %@AS@%DS:36%@AE@% (24%@EH@% hexadecimal). No more than eight values per line are displayed.%@NL@% %@NL@% %@NL@% %@CR:MCV64700@%%@3@%%@AB@%6.4.7 Dump Double Words%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64701@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%DD%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64702@%%@4@%The Dump Double Words command displays the hexadecimal values of the double%@EH@% words (four-byte values) starting at %@AI@%address%@AE@% or in the specified %@AI@%range%@AE@% of addresses.%@NL@% %@NL@% %@CR:MCV64703@%%@4@%The command displays one or more lines, depending on the address or range%@EH@% specified. Each line displays the address of the first double word in the line, followed by up to four hexadecimal double-word values. The words of each double word are separated by a colon. The values are separated by spaces. The command displays values until the end of the %@AI@%range%@AE@% or until the first 32 double words have been displayed, whichever comes first.%@NL@% %@NL@% %@CR:MCV64704@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >DD 0 36%@NL@% 3D5E:0000 656D:6F53 7465:6C20 7372:6574 646E:6120%@NL@% 3D5E:0010 6D75:6E20 7372:6562 EA10:003A EFFF:FC89%@NL@% 3D5E:0020 CA00:F000 6F73:09E4%@NL@% >%@NL@% %@NL@% %@CR:MCV64705@%%@4@%The example above displays the double-word values from %@AS@%DS:0%@AE@% to %@AS@%DS:36%@AE@% (24%@EH@% hexadecimal). No more than four double-word values per line are displayed.%@NL@% %@NL@% %@NL@% %@CR:MCV64800@%%@3@%%@AB@%6.4.8 Dump Short Reals%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64801@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%DS%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64802@%%@4@%The Dump Short Reals command displays the hexadecimal and decimal values of%@EH@% the short (four-byte) floating-point numbers at %@AI@%address%@AE@% or in the specified %@AI@%range%@AE@% of addresses.%@NL@% %@NL@% %@CR:MCV64803@%%@4@%The command displays one or more lines, depending on the address or range%@EH@% specified. Each line displays the address of the floating-point number in the first column. Next, the hexadecimal values of the bytes in the number are shown, followed by the decimal value of the number. The hexadecimal values are separated by spaces.%@NL@% %@NL@% %@CR:MCV64804@%%@4@%The decimal value has the following form:%@EH@%%@NL@% %@NL@% «-»%@AI@%digit%@AE@%.%@AI@%digits%@AE@%%@AB@%E%@AE@%{+ | -}%@AI@%exponent%@AE@%%@NL@% %@NL@% %@CR:MCV64805@%%@4@%If the number is negative, it will have a minus sign; positive numbers have%@EH@% no sign. The first digit of the number is followed by a decimal point. Six decimal places are shown following the decimal point. The letter E follows the decimal digits and marks the start of a three-digit signed %@AI@%exponent%@AE@%.%@NL@% %@NL@% %@CR:MCV64806@%%@4@%The command displays at least one value. If a %@AI@%range%@AE@% is specified, all values%@EH@% in the range are displayed.%@NL@% %@NL@% %@CR:MCV64807@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >DS SPI%@NL@% 5E68:0100 DB 0F 49 40 3.141593E+000%@NL@% >%@NL@% %@NL@% %@CR:MCV64808@%%@4@%The example above displays the short-real floating-point number at the%@EH@% address of the variable %@AS@%SPI%@AE@%. Only one value is displayed per line.%@NL@% %@NL@% %@NL@% %@CR:MCV64900@%%@3@%%@AB@%6.4.9 Dump Long Reals%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64901@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%DL%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64902@%%@4@%The Dump Long Reals command displays the hexadecimal and decimal values of%@EH@% the long (eight-byte) floating-point numbers at the specified %@AI@%address%@AE@% or in the specified %@AI@%range%@AE@% of addresses.%@NL@% %@NL@% %@CR:MCV64903@%%@4@%The command displays one or more lines, depending on the address or range%@EH@% specified. Each line displays the address of the floating-point number in the first column. Next, the hexadecimal values of the bytes in the number are shown, followed by the decimal value of the number. The hexadecimal values are separated by spaces.%@NL@% %@NL@% %@CR:MCV64904@%%@4@%The decimal value has the following form:%@EH@%%@NL@% %@NL@% «-»%@AI@%digit.digits%@AE@%%@AB@%E%@AE@%{+ | -}%@AI@%exponent%@AE@%%@NL@% %@NL@% %@CR:MCV64905@%%@4@%If the number is negative, it will have a minus sign; positive numbers have%@EH@% no sign. The first digit of the number is followed by a decimal point. Six decimal places are shown following the decimal point. The letter E follows the decimal digits and marks the start of a three-digit signed %@AI@%exponent%@AE@%.%@NL@% %@NL@% %@CR:MCV64906@%%@4@%The command displays at least one value. If a %@AI@%range%@AE@% is specified, all values%@EH@% in the range are displayed.%@NL@% %@NL@% %@CR:MCV64907@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >DL LPI%@NL@% 5E68:0200 11 2D 44 54 FB 21 09 40 3.141593E+000%@NL@% >%@NL@% %@NL@% %@CR:MCV64908@%%@4@%The example above displays the long-real floating-point number at the%@EH@% address of the variable %@AS@%LPI%@AE@%. Only one value per line is displayed.%@NL@% %@NL@% %@NL@% %@CR:MCV64A00@%%@3@%%@AB@%6.4.10 Dump 10-Byte Reals%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV64A01@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%DT%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV64A02@%%@4@%The Dump 10-Byte Reals command displays the hexadecimal and decimal values%@EH@% of the 10-byte floating-point numbers at the specified %@AI@%address%@AE@% or in the specified %@AI@%range%@AE@% of addresses.%@NL@% %@NL@% %@CR:MCV64A03@%%@4@%The command displays one or more lines, depending on the address or range%@EH@% specified. Each line displays the address of the floating-point number in the first column. Next, the hexadecimal values of the bytes in the number are shown, followed by the decimal value of the number. The hexadecimal values are separated by spaces.%@NL@% %@NL@% %@CR:MCV64A04@%%@4@%The decimal value has the following form:%@EH@%%@NL@% %@NL@% «-»%@AI@%digit%@AE@%.%@AI@%digits%@AE@%%@AB@%E%@AE@%{+ | -}%@AI@%exponent%@AE@%%@NL@% %@NL@% %@CR:MCV64A05@%%@4@%If the number is negative, it will have a minus sign; positive numbers have%@EH@% no sign. The first digit of the number is followed by a decimal point. Six decimal places are shown following the decimal point. The letter E follows the decimal digits and marks the start of a three-digit signed %@AI@%exponent%@AE@%.%@NL@% %@NL@% %@CR:MCV64A06@%%@4@%The command displays at least one value. If a %@AI@%range%@AE@% is specified, all values%@EH@% in the range are displayed.%@NL@% %@NL@% %@CR:MCV64A07@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >DT TPI%@NL@% 5E68:0300 DE 87 68 21 A2 DA 0F C9 00 40 3.141593E+000%@NL@% >%@NL@% %@NL@% %@CR:MCV64A08@%%@4@%The example above displays the 10-byte floating-point number at the address%@EH@% of the variable %@AS@%TPI%@AE@%. Only one number per line is displayed.%@NL@% %@NL@% %@NL@% %@CR:MCV65000@%%@2@%%@AB@%6.5 Compare Memory Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV65001@%%@4@%The Compare Memory command provides a convenient way for comparing two%@EH@% blocks of memory, specified by absolute addresses. This command is primarily of interest to programmers using assembly mode; however, it can be useful to anyone who wants to compare two large areas of data, such as arrays.%@NL@% %@NL@% %@CR:MCV65002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV65003@%%@4@%The Compare Memory command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV65004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV65005@%%@4@%The Compare Memory command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCV65006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV65007@%%@4@%To compare two blocks of memory, enter a command line with the following%@EH@% syntax:%@NL@% %@NL@% %@AB@%C%@AE@% %@AI@%range%@AE@% %@AI@%address%@AE@%%@NL@% %@NL@% %@CR:MCV65008@%%@4@%The bytes in the memory locations specified by %@AI@%range%@AE@% are compared with the%@EH@% corresponding bytes in the memory locations beginning at %@AI@%address%@AE@%. If one or more pairs of corresponding bytes do not match, each pair of mismatched bytes is displayed.%@NL@% %@NL@% %@CR:MCV65009@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >C 100 01FF 300 %@AI@%;* hexadecimal radix assumed%@AE@%%@NL@% 39BB:0102 0A 00 39BB:0302%@NL@% 39BB:0108 0A 01 39BB:0308%@NL@% >%@NL@% %@NL@% %@CR:MCV6500A@%%@4@%The first example (in which hexadecimal is assumed to be the default radix)%@EH@% compares the block of memory from 100 to 1FF with the block of memory from 300 to 3FF. It indicates that the third and ninth bytes differ in the two areas of memory.%@NL@% %@NL@% >C arr1(1) L 100 arr2(1) %@AI@%;* BASIC/FORTRAN notation used%@AE@%%@NL@% >%@NL@% %@NL@% %@CR:MCV6500B@%%@4@%The second example compares the 100 bytes starting at the address of%@EH@% %@AS@%arr1(1)%@AE@%, with the 100 bytes starting at address of %@AS@%arr2(1)%@AE@%. The CodeView debugger produces no output in response, so this indicates that the first 100 bytes of each array are identical. (In C language, this example would be entered as %@AS@%Carr1[0] L 100 arr2[0]%@AE@%.)%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% You can enter the Compare Memory command using any radix you like;%@NL@% however, any output will still be in hexadecimal format.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV66000@%%@2@%%@AB@%6.6 Search Memory Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV66001@%%@4@%The Search Memory command (not to be confused with the Search command%@EH@% discussed in Section 11.5%@BO: 78f11@%) scans a specified area of memory, looking for specific byte values. It is primarily of interest to programmers using assembly mode and to users testing for the presence of specific values within a range of data.%@NL@% %@NL@% %@CR:MCV66002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV66003@%%@4@%The Search Memory command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV66004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV66005@%%@4@%The Search Memory command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCV66006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV66007@%%@4@%To search a block of memory, enter the Search Memory command with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%S%@AE@% %@AI@%range%@AE@% %@AI@%list%@AE@%%@NL@% %@NL@% %@CR:MCV66008@%%@4@%The debugger will search the specified %@AI@%range%@AE@% of memory locations for the%@EH@% byte values specified in the %@AI@%list%@AE@%. If bytes with the specified values are found, the debugger displays the addresses of each occurrence of bytes in the list.%@NL@% %@NL@% %@CR:MCV66009@%%@4@%The %@AI@%list%@AE@% can have any number of bytes. Each byte value must be separated by%@EH@% a space or comma, unless the list is an ASCII string. If the list contains more than one byte, the Search Memory command looks for a series of bytes that precisely match the order and value of bytes in %@AI@%list%@AE@%. If found, the beginning address of each such series is displayed.%@NL@% %@NL@% %@CR:MCV6600A@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >S buffer L 1500 "error"%@NL@% 2BBA:0404%@NL@% 2BBA:05E3%@NL@% 2BBA:0604%@NL@% >%@NL@% %@NL@% %@CR:MCV6600B@%%@4@%The first example displays the address of each memory location containing%@EH@% the string %@AS@%error%@AE@%. The command searches the first 1500 bytes at the address specified by %@AS@%buffer%@AE@%. The string was found at the three addresses displayed by the CodeView debugger.%@NL@% %@NL@% >S DS:100 200 0A %@AI@%;* hexadecimal radix assumed%@AE@%%@NL@% 3CBA:0132%@NL@% 3CBA:01C2%@NL@% >%@NL@% %@NL@% %@CR:MCV6600C@%%@4@%The second example displays the address of each memory location that%@EH@% contains the byte value 0A in the range DS:0100 to DS:0200 (hexadecimal). The value was found at two addresses.%@NL@% %@NL@% %@NL@% %@CR:MCV67000@%%@2@%%@AB@%6.7 Port Input Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV67001@%%@4@%The Port Input command reads and displays a byte from a specified hardware%@EH@% port. It is primarily of interest to assembly-language programmers writing hardware-specific programs.%@NL@% %@NL@% %@CR:MCV67002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV67003@%%@4@%The Port Input command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV67004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV67005@%%@4@%The Port Input command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCV67006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV67007@%%@4@%The Port Input command is executed with the following syntax:%@EH@%%@NL@% %@NL@% %@AB@%I%@AE@% %@AI@%port%@AE@%%@NL@% %@NL@% %@CR:MCV67008@%%@4@%The byte is read and displayed from the specified %@AI@%port%@AE@%, which can be any%@EH@% 16-bit address.%@NL@% %@NL@% %@CR:MCV67009@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >I 2f8 %@AI@%;* hexadecimal radix assumed%@NL@% E8%@NL@% >%@NL@% %@NL@% %@CR:MCV6700A@%%@4@%The preceding example reads input port, number %@AS@%2F8%@AE@%, and displays the result,%@EH@% %@AS@%E8%@AE@%. You may enter the port address using any radix you want, but the result will always be displayed in current radix.%@NL@% %@NL@% %@CR:MCV6700B@%%@4@%The Port Input command is often used in conjunction with the Port Output%@EH@% command, which is described in Section 10.5.%@BO: 75046@%%@NL@% %@NL@% %@NL@% %@CR:MCV68000@%%@2@%%@AB@%6.8 Register Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV68001@%%@4@%The Register command has two functions. It displays the contents of the%@EH@% central processing unit (CPU) registers. It can also change the values of the registers. The display features of the Register command are explained here. The modification features of the command are explained in Chapter 10%@BO: 6c3f1@%, "Modifying Code or Data."%@NL@% %@NL@% %@CR:MCV68002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV68003@%%@4@%To display the registers with the mouse, point to View on the menu bar,%@EH@% press a mouse button and drag the highlight down to the Registers selection, then release the button. The register window will appear on the right side of the screen. If the register window is already on the screen, the same command removes it.%@NL@% %@NL@% %@CR:MCV68004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV68005@%%@4@%To display the registers using a keyboard command in window mode, press F2.%@EH@% The register window will appear on the right side of the screen. If the register window is already on the screen, the same command will remove it.%@NL@% %@NL@% %@CR:MCV68006@%%@4@%In sequential mode, the F2 key will display the current status of the%@EH@% registers. (This produces the same effect as entering the Register dialog command with no argument.)%@NL@% %@NL@% %@CR:MCV68007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV68008@%%@4@%To display the registers in the dialog window (or sequentially in sequential%@EH@% mode), enter a command line with the following syntax:%@NL@% %@NL@% %@AB@%R%@AE@%%@NL@% %@NL@% %@CR:MCV68009@%%@4@%The current values of all registers and flags are displayed. The instruction%@EH@% at the address pointed to by the current CS and IP register values is also shown. (The Register command can also be given with arguments, but only when used to modify registers, as explained in Chapter 10%@BO: 6c3f1@%, "Modifying Code or Data.")%@NL@% %@NL@% %@CR:MCV6800A@%%@4@%If the display mode is source (%@AB@%S+%@AE@%) or mixed (%@AB@%S&%@AE@%) (see Section 9.1%@BO: 6576d@%, "Set%@EH@% Mode Command," for more information), the current source line is also displayed by the Register command. If an operand of the instruction contains memory expressions or immediate data, the CodeView debugger will evaluate operands and show the value to the right of the instruction. This value is referred to as the "effective address," and is also displayed at the bottom of the register window. If the CS and IP registers are currently at a breakpoint location, the register display will indicate the breakpoint number.%@NL@% %@NL@% %@CR:MCV6800B@%%@4@%In sequential mode, the Trace (%@AB@%T%@AE@%), Program Step (%@AB@%P%@AE@%), and Go (%@AB@%G%@AE@%) commands%@EH@% show registers in the same format as the Register command.%@NL@% %@NL@% %@CR:MCV6800C@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >S&%@NL@% mixed%@NL@% >R%@NL@% AX=0005 BX=299E CX=0000 DX=0000 SP=3800 BP=380E SI=0070 DI=40D1%@NL@% DS=5067 ES=5067 SS=5067 CS=4684 IP=014F NV UP EI PL NZ NA PO NC%@NL@% 35: VARIAN = (N*SUMXSQ-SUMX**2)/(N-1)%@NL@% 4684:014F 8B5E06 MOV BX,Word Ptr [BP+06] ;BR1 SS:3814=299E%@NL@% >%@NL@% %@NL@% %@CR:MCV6800D@%%@4@%The example above displays all register and flag values, as well as the%@EH@% instruction at the address pointed to by the CS and IP registers. Because the mode has been set to mixed (%@AB@%S&%@AE@%), the current source line is also shown. The example is from a FORTRAN program, but applies equally well to BASIC and C programs.%@NL@% %@NL@% >S-%@NL@% assembly%@NL@% >R%@NL@% AX=0005 BX=299E CX=0000 DX=0000 SP=3800 BP=380E SI=0070 DI=40D1%@NL@% DS=5067 ES=5067 SS=5067 CS=4684 IP=014F NV UP EI PL NZ NA PO NC%@NL@% 4684:014F 8B5E06 MOV BX,Word Ptr [BP+06] ;BR1 SS:3814=299E%@NL@% >%@NL@% %@NL@% %@CR:MCV6800E@%%@4@%In the example above, the display mode is set to assembly (%@AB@%S-%@AE@%), so no source%@EH@% line is shown. Note the breakpoint number at the right of the last line indicating that the current address is at Breakpoint 1.%@NL@% %@NL@% %@NL@% %@CR:MCV69000@%%@2@%%@AB@%6.9 8087 Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV69001@%%@4@%The 8087 command dumps the contents of the 8087 registers. If you do not%@EH@% have an 8087, 80287, or 80387 coprocessor chip on your system, this command will dump the contents of the pseudoregisters created by the compiler's emulator routines. This command is useful only if you have an 8087, 80287, or 80387 chip installed or if your executable file includes math routines from a Microsoft 8087-emulator library.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% This section does not attempt to explain how the registers of the Intel%@NL@% 8087 and 80287 processors are organized or how they work. In order to%@NL@% interpret the command output, you must learn about the chip from an Intel%@NL@% reference manual or other book on the subject. Since the Microsoft%@NL@% emulator routines mimic the behavior of the 8087 coprocessor, these%@NL@% references will apply to emulator routines as well as to the chips%@NL@% themselves.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV69002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV69003@%%@4@%The 8087 command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV69004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV69005@%%@4@%The 8087 command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCV69006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV69007@%%@4@%To display the status of the 8087 or 80287 chip (or floating-point emulator%@EH@% routines) with a dialog command, enter a command line with the following syntax:%@NL@% %@NL@% %@AB@%7%@AE@%%@NL@% %@NL@% %@CR:MCV69008@%%@4@%The current status of the chip is displayed when you enter the command. In%@EH@% window mode, the output is to the dialog window. If you do not have an 8087 or 80287 chip and are not linking to an emulator library, the debugger will report the error message %@AS@%Floating point not %@AE@%%@AS@%loaded%@AE@%. CodeView reports this message each time you give the %@AB@%7%@AE@% command, unless a floating-point instruction has been executed.%@NL@% %@NL@% %@CR:MCV69009@%%@4@%The following example shows a display for a machine that actually has an%@EH@% 8087 or 80287 chip. The example at the end of this section shows the same display for a machine using an emulator library instead of an actual math coprocessor.%@NL@% %@NL@% %@CR:MCV6900A@%%@4@%%@AB@%8087 Example%@AE@%%@EH@%%@NL@% %@NL@% >7%@NL@% cControl 037F (Projective closure, Round nearest, 64-bit precision)%@NL@% iem=0 pm=1 um=1 om=1 zm=1 dm=1 im=1%@NL@% cStatus 6004 cond=1000 top=4 pe=0 ue=0 oe=0 ze=1 de=0 ie=0%@NL@% Tag A1FF instruction=59380 operand=59360 opcode=D9EE%@NL@% Stack Exp Mantissa Value%@NL@% cST(3) special 7FFF 8000000000000000 = + Infinity%@NL@% cST(2) special 7FFF 0101010101010101 = + Not a Number%@NL@% cST(1) valid 4000 C90FDAA22168C235 = +3.141592265110390E+000%@NL@% cST(0) zero 0000 0000000000000000 = +0.000000000000000E+000%@NL@% >%@NL@% %@NL@% %@CR:MCV6900B@%%@4@%In the example above, the first line of the dump shows the current closure%@EH@% method, rounding method, and the precision. The number %@AS@%037F%@AE@% is the hexadecimal value in the control register. The rest of the line interprets the bits of the number. The closure method can be either projective (as in the example) or affine. The rounding method can be either rounding to the nearest even number (as in the example), rounding down, rounding up, or using the chop method of rounding (truncating toward zero). The precision may be 64 bits (as in the example), 53 bits, or 24 bits.%@NL@% %@NL@% %@CR:MCV6900C@%%@4@%The second line of the display indicates whether each exception mask bit is%@EH@% set or cleared. The masks are interrupt-enable mask (%@AS@%iem%@AE@%), precision mask (%@AS@%pm%@AE@%), underflow mask (%@AS@%um%@AE@%), overflow mask (%@AS@%om%@AE@%), zero-divide mask (%@AS@%zm%@AE@%), denormalized-operand mask (%@AS@%dm%@AE@%), and invalid-operation mask (%@AS@%im%@AE@%).%@NL@% %@NL@% %@CR:MCV6900D@%%@4@%The third line of the display shows the hexadecimal value of the status%@EH@% register ( %@AS@%6004%@AE@% in the example), and then interprets the bits of the register. The condition code (%@AS@%cond%@AE@%) in the example is the binary number %@AS@%1000%@AE@%. The top of the stack (%@AS@%top%@AE@%) is register 4 (shown in decimal). The other bits shown are precision exception (%@AS@%pe%@AE@%), underflow exception (%@AS@%ue%@AE@%), overflow exception (%@AS@%oe%@AE@%), zero-divide exception (%@AS@%ze%@AE@%), denormalized-operand exception (%@AS@%de%@AE@%), and invalid-operation exception (%@AS@%ie%@AE@%).%@NL@% %@NL@% %@CR:MCV6900E@%%@4@%The fourth line of the display first shows the 20-bit hexadecimal address%@EH@% value of the tag register (%@AS@%A1FF%@AE@% in the example). It then gives the hexadecimal offsets of the instruction (%@AS@%59380%@AE@%), the operand (%@AS@%59360%@AE@%), and the operation code, or opcode, (%@AS@%D9EE%@AE@%).%@NL@% %@NL@% %@CR:MCV6900F@%%@4@%The fifth line is a heading for the subsequent lines that contain the%@EH@% contents of each 8087 or 80287 stack register. The registers in the example contain four types of numbers that may be held in these registers. Starting from the bottom, register 0 contains zero. Register 1 contains a valid real number. Its exponent (in hexadecimal) is %@AS@%4000%@AE@% and its mantissa is%@AE@% %@AS@%C90FDAA22168C235%@AE@%. The number is shown in scientific notation in the rightmost column. Register 2 contains a value that cannot be interpreted as a number, and register 3 contains infinity.%@NL@% %@NL@% %@CR:MCV6900G@%%@4@%The %@AS@%c%@AE@% that precedes %@AS@%Control%@AE@%, %@AS@%Status%@AE@%, and each of the %@AS@%ST%@AE@% listings indicates%@EH@% that an actual math-coprocessor chip is in use. If emulator routines were in use instead of a chip, each %@AS@%c%@AE@% prefix would be replaced by %@AS@%e%@AE@%, as in the next example.%@NL@% %@NL@% %@CR:MCV6900H@%%@4@%%@AB@%Floating-Point Emulator Example%@AE@%%@EH@%%@NL@% %@NL@% >7%@NL@% eControl 037F (Projective closure, Round nearest, 64-bit precision)%@NL@% iem=0 pm=1 um=1 om=1 zm=1 dm=1 im=1%@NL@% eStatus 6004 cond=1000 top=4 pe=0 ue=0 oe=0 ze=1 de=0 ie=0%@NL@% Tag A1FF instruction=59380 operand=59360 opcode=D9EE%@NL@% Stack Exp Mantissa Value%@NL@% eST(3) special 7FFF 8000000000000000 = + Infinity%@NL@% eST(2) special 7FFF 0101010101010101 = + Not a Number%@NL@% eST(1) valid 4000 C90FDAA22168C235 = +3.141592265110390E+000%@NL@% eST(0) zero 0000 0000000000000000 = +0.000000000000000E+000%@NL@% >%@NL@% %@NL@% %@CR:MCV6900I@%%@4@%Note the %@AS@%e%@AE@% at the beginning of the first, third, sixth, seventh, eighth, and%@EH@% ninth lines. Aside from this replacement of the %@AS@%c%@AE@% prefix by %@AS@%e%@AE@%, the emulator display is the same as the corresponding display for an 8087 chip.%@NL@% %@NL@% %@NL@% %@CR:MCV70000@%%@1@%%@AB@%Chapter 7 Managing Breakpoints%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV70001@%%@4@%The CodeView debugger enables you to control program execution by setting%@EH@% breakpoints. A breakpoint is an address that stops program execution each time the address is encountered. By setting breakpoints at key addresses in your program, you can "freeze" program execution and examine the status of memory or expressions at that point.%@NL@% %@NL@% %@CR:MCV70002@%%@4@%The commands listed below control breakpoints:%@EH@%%@NL@% %@NL@% %@CR:MCV70003@%%@AB@%Command Action%@AE@%%@NL@% %@NL@% Breakpoint Set (%@AB@%BP%@AE@%) Sets a breakpoint and, optionally, a pass count%@NL@% and break commands%@NL@% %@NL@% Breakpoint Clear (%@AB@%BC%@AE@%) Clears one or more breakpoints%@NL@% %@NL@% Breakpoint Disable (%@AB@%BD%@AE@%) Disables one or more breakpoints%@NL@% %@NL@% Breakpoint Enable (%@AB@%BE%@AE@%) Enables one or more breakpoints%@NL@% %@NL@% Breakpoint List (%@AB@%BL%@AE@%) Lists all breakpoints%@NL@% %@NL@% %@CR:MCV70004@%%@4@%In addition to these commands, the Watchpoint (%@AB@%WP%@AE@%) and Tracepoint (%@AB@%TP%@AE@%)%@EH@% commands can be used to set conditional breakpoints (see Chapter 8%@BO: 5c045@%, "Managing Watch Statements," for information on these two commands).%@NL@% %@NL@% %@NL@% %@CR:MCV71000@%%@2@%%@AB@%7.1 Breakpoint Set Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV71001@%%@4@%The Breakpoint Set command (%@AB@%BP%@AE@%) creates a breakpoint at a specified address.%@EH@% Any time a breakpoint is encountered during program execution, the program halts and waits for a new command.%@NL@% %@NL@% %@CR:MCV71002@%%@4@%The CodeView debugger allows up to 20 breakpoints (0 through 19). Each new%@EH@% breakpoint is assigned to the next available number. Breakpoints remain in memory until you delete them or until you quit the debugger. They are not canceled when you restart the program. Because breakpoints are not automatically canceled, you are able to set up a complicated series of breakpoints, then execute through the program several times without resetting.%@NL@% %@NL@% %@CR:MCV71003@%%@4@%If you try to set a breakpoint at a comment line or other source line that%@EH@% does not correspond to code, the CodeView debugger displays the following message:%@NL@% %@NL@% %@AS@%No code at this line number%@AE@%%@NL@% %@NL@% %@CR:MCV71004@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV71005@%%@4@%To set a breakpoint with the mouse, point to the source line or instruction%@EH@% where you want to set the breakpoint and then click the left button. The line will be displayed in high-intensity text and will remain so until you remove or disable the breakpoint.%@NL@% %@NL@% %@CR:MCV71006@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV71007@%%@4@%To set a breakpoint with a keyboard command in window mode, move the cursor%@EH@% to the source line or instruction where you want to set a breakpoint. You may have to press F6 to move the cursor to the display window. When the cursor is on the appropriate source line, press F9. The line will be displayed in high-intensity text and will remain so until you remove or disable the breakpoint.%@NL@% %@NL@% %@CR:MCV71008@%%@4@%In sequential mode, the F9 key can be used to set a breakpoint at the%@EH@% current location. You must use the dialog version of the command to set a breakpoint at any other location.%@NL@% %@NL@% %@CR:MCV71009@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV7100A@%%@4@%To set a breakpoint using a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%BP%@AE@% «%@AI@%address%@AE@% «%@AI@%passcount%@AE@%» «%@AB@%"%@AE@%%@AI@%commands%@AE@%%@AB@%"%@AE@%»»%@NL@% %@NL@% %@CR:MCV7100B@%%@4@%If no %@AI@%address%@AE@% is given, a breakpoint is created on the current source line%@EH@% in source mode or on the current instruction in assembly mode. You can specify the %@AI@%address%@AE@% in the %@AI@%segment%@AE@%%@AB@%:%@AE@%%@AI@%offset%@AE@% format or as a source line, a routine name, or a label. If you give an offset address, the code segment is assumed.%@NL@% %@NL@% %@CR:MCV7100C@%%@4@%The dialog version of the command is more powerful than the mouse or%@EH@% keyboard version in that it allows you to give a %@AI@%passcount%@AE@% and a string of %@AI@%commands%@AE@%.%@NL@% %@NL@% %@CR:MCV7100D@%%@4@%The %@AI@%passcount%@AE@% specifies the first time the breakpoint is to be taken. For%@EH@% example, if the pass count is 5, the breakpoint will be ignored the first four times it is encountered, and taken the fifth time. Thereafter, the breakpoint is always taken.%@NL@% %@NL@% %@CR:MCV7100E@%%@4@%The %@AI@%commands%@AE@% are a list of dialog commands enclosed in quotation marks (%@AB@%" "%@AE@%)%@EH@% and separated by semicolons (%@AB@%;%@AE@%). For example, if you specify the commands as %@AS@%"? code;T"%@AE@%, the CodeView debugger will automatically display the value of the variable %@AS@%code%@AE@% and then execute the Trace command each time the breakpoint is encountered. The Trace and Display Expression commands are described in Chapter 5%@BO: 3d63b@%, "Executing Code," and Chapter 6%@BO: 43f5c@%, "Examining Data and Expressions," respectively.%@NL@% %@NL@% %@CR:MCV7100F@%%@4@%In window mode, a breakpoint entered with a dialog command has exactly the%@EH@% same effect as one created with a window command. The source line or instruction corresponding to the breakpoint location is shown in high-intensity text.%@NL@% %@NL@% %@CR:MCV7100G@%%@4@%In sequential mode, information about the current instruction will be%@EH@% displayed each time you execute to a breakpoint. The register values, the current instruction, and the source line may be shown, depending on the display mode. See Chapter 9%@BO: 6542b@%, "Examining Code," for more information about display modes.%@NL@% %@NL@% %@CR:MCV7100H@%%@4@%When a breakpoint address is shown in the assembly-language format, the%@EH@% breakpoint number will be shown as a comment to the right of the instruction. This comment appears even if the breakpoint is disabled (but not if it is deleted).%@NL@% %@NL@% %@CR:MCV7100I@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >BP .19 10%@NL@% >%@NL@% %@NL@% %@CR:MCV7100J@%%@4@%The example above creates a breakpoint at line 19 of the current source file%@EH@% (or if there is no executable statement at line 19, at the first executable statement after line 19). The breakpoint is passed over nine times before being taken on the tenth pass.%@NL@% %@NL@% >BP STATS 10 "?COUNTER = COUNTER + 1;G"%@NL@% >%@NL@% %@NL@% %@CR:MCV7100K@%%@4@%The example above creates a breakpoint at the address of the routine %@AS@%STATS%@AE@%.%@EH@% The breakpoint is passed over nine times before being taken on the 10th pass. Each time execution stops for the breakpoint, the quoted commands are executed. The Display Expression command increments %@AS@%COUNTER%@AE@%, then the Go command restarts execution. If %@AS@%COUNTER%@AE@% is set to 0 when the breakpoint is set, this has the effect of counting the number of times the breakpoint is taken.%@NL@% %@NL@% >S- %@AI@%;* FORTRAN example - uses FORTRAN hexadecimal notation%@AE@%%@NL@% assembly%@NL@% >BP #0A94%@NL@% >G%@NL@% AX=0006 BX=304A CX=000B DX=465D SP=3050 BP=3050 SI=00BB DI=40D1%@NL@% DS=5064 ES=5064 SS=5064 CS=46A2 IP=0A94 NV UP EI PL NZ NA PENC%@NL@% 46A2:0A94 7205 JB __chkstk+13 (0A9B) ;BR1%@NL@% >%@NL@% %@NL@% %@CR:MCV7100L@%%@4@%The example above first sets the mode to assembly and then creates a%@EH@% breakpoint at the hexadecimal (offset) address %@AS@%#0A94%@AE@% in the default (CS) segment. (The same address would be specified as %@AS@%0x0A94%@AE@% with the C expression evaluator, and as %@AS@%&H0A9%@AE@% with the BASIC expression evaluator.) The Go command (%@AB@%G%@AE@%) is then used to execute to the breakpoint. Note that in the output to the Go command, the breakpoint number is shown as an assembly-language comment (%@AS@%;BR1%@AE@%) to the right of the current instruction. The Go command displays this output only in sequential mode; in window mode no assembly-language information appears.%@NL@% %@NL@% %@NL@% %@CR:MCV72000@%%@2@%%@AB@%7.2 Breakpoint Clear Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV72001@%%@4@%The Breakpoint Clear command (%@AB@%BC%@AE@%) permanently removes one or more previously%@EH@% set breakpoints.%@NL@% %@NL@% %@CR:MCV72002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV72003@%%@4@%To clear a single breakpoint with the mouse, point to the breakpoint line or%@EH@% instruction you want to clear. Breakpoint lines are shown in high-intensity text. Press the left mouse button. The line will be shown in normal text to indicate that the breakpoint has been removed.%@NL@% %@NL@% %@CR:MCV72004@%%@4@%To remove all breakpoints with the mouse, point to Run on the menu bar,%@EH@% press a mouse button and drag the highlight down to the Clear Breakpoints selection, then release the button.%@NL@% %@NL@% %@CR:MCV72005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV72006@%%@4@%To clear a single breakpoint with a keyboard command, move the cursor to the%@EH@% breakpoint line or instruction you want to clear. Breakpoint lines are shown in high-intensity text. Press F9. The line will be shown in normal text to indicate that the breakpoint has been removed.%@NL@% %@NL@% %@CR:MCV72007@%%@4@%To remove all breakpoints using a keyboard command, press ALT+R to open the%@EH@% Run menu, and then press ALT+C to select Clear Breakpoints.%@NL@% %@NL@% %@CR:MCV72008@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV72009@%%@4@%To clear breakpoints using a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%BC%@AE@% %@AI@%list%@AE@%%@NL@% %@AB@%BC *%@NL@% %@NL@% %@CR:MCV7200A@%%@4@%If %@AI@%list%@AE@% is specified, the command removes the breakpoints named in the list.%@EH@% The %@AI@%list%@AE@% can be any combination of integer values from 0 to 19. You can use the Breakpoint List command (%@AB@%BL%@AE@%) if you need to see the numbers for each existing breakpoint. If an asterisk (%@AB@%*%@AE@%) is given as the argument, all breakpoints are removed.%@NL@% %@NL@% %@CR:MCV7200B@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >BC 0 4 8%@NL@% >%@NL@% %@NL@% %@CR:MCV7200C@%%@4@%The example above removes breakpoints 0, 4, and 8.%@EH@%%@NL@% %@NL@% >BC *%@NL@% >%@NL@% %@NL@% %@CR:MCV7200D@%%@4@%The example above removes all breakpoints.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCV73000@%%@2@%%@AB@%7.3 Breakpoint Disable Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV73001@%%@4@%The Breakpoint Disable command (%@AB@%BD%@AE@%) temporarily disables one or more%@EH@% existing breakpoints. The breakpoints are not deleted. They can be restored at any time using the Breakpoint Enable command (%@AB@%BE%@AE@%).%@NL@% %@NL@% %@CR:MCV73002@%%@4@%When a breakpoint is disabled in window mode, it is shown in the display%@EH@% window with normal text; when enabled, it is shown in high-intensity text.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% All disabled breakpoints are automatically enabled whenever you restart%@NL@% the program being debugged. The program can be restarted with the Start%@NL@% or Restart selection from the Run menu, or with the Restart dialog%@NL@% command%@AI@%(%@AE@%%@AI@%L%@AE@%%@AI@%). See%@AE@% Chapter 5%@BO: 3d63b@%, "Executing Code."%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV73003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV73004@%%@4@%The Breakpoint Disable command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV73005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV73006@%%@4@%The Breakpoint Disable command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCV73007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV73008@%%@4@%To disable breakpoints with a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%BD%@AE@% %@AI@%list%@AE@%%@NL@% %@AB@%BD *%@NL@% %@NL@% %@CR:MCV73009@%%@4@%If %@AI@%list%@AE@% is specified, the command disables the breakpoints named in the%@EH@% list. The %@AI@%list%@AE@% can be any combination of integer values from 0 to 19. Use the Breakpoint List command (%@AB@%BL%@AE@%) if you need to see the numbers for each existing breakpoint. If an asterisk (%@AB@%*%@AE@%) is given as the argument, all breakpoints are disabled.%@NL@% %@NL@% %@CR:MCV7300A@%%@4@%The window commands for setting and clearing breakpoints can also be used to%@EH@% enable or clear disabled breakpoints.%@NL@% %@NL@% %@CR:MCV7300B@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >BD 0 4 8%@NL@% >%@NL@% %@NL@% %@CR:MCV7300C@%%@4@%The example above disables breakpoints 0, 4, and 8.%@EH@%%@NL@% %@NL@% >BD *%@NL@% >%@NL@% %@NL@% %@CR:MCV7300D@%%@4@%The example above disables all breakpoints.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCV74000@%%@2@%%@AB@%7.4 Breakpoint Enable Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV74001@%%@4@%The Breakpoint Enable command (%@AB@%BE%@AE@%) enables breakpoints that have been%@EH@% temporarily disabled with the Breakpoint Disable command.%@NL@% %@NL@% %@CR:MCV74002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV74003@%%@4@%To enable a disabled breakpoint with the mouse, point to the source line or%@EH@% instruction of the breakpoint, and click Left. The line will be displayed in high-intensity text, and will remain so until you remove or disable the breakpoint. This is the same as creating a new breakpoint at that location.%@NL@% %@NL@% %@CR:MCV74004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV74005@%%@4@%To enable a disabled breakpoint using a keyboard command, move the cursor to%@EH@% the source line or instruction of the breakpoint, and press F9. The line is displayed in high-intensity text and remains so until you remove or disable the breakpoint. This is the same as creating a new breakpoint at that location.%@NL@% %@NL@% %@CR:MCV74006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV74007@%%@4@%To enable breakpoints using a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%BE%@AE@% %@AI@%list%@AE@%%@NL@% %@AB@%BE *%@NL@% %@NL@% %@CR:MCV74008@%%@4@%If %@AI@%list%@AE@% is specified, the command enables the breakpoints named in the list.%@EH@% The %@AI@%list%@AE@% can be any combination of integer values from 0 to 19. Use the Breakpoint List command (%@AB@%BL%@AE@%) if you need to see the numbers for each existing breakpoint. If an asterisk (%@AB@%*%@AE@%) is given as the argument, all breakpoints are enabled. The CodeView debugger ignores all or part of the command if you try to enable a breakpoint that is not disabled.%@NL@% %@NL@% %@CR:MCV74009@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >BE 0 4 8%@NL@% >%@NL@% %@NL@% %@CR:MCV7400A@%%@4@%The example above enables breakpoints 0, 4, and 8.%@EH@%%@NL@% %@NL@% >BE*%@NL@% >%@NL@% %@NL@% %@CR:MCV7400B@%%@4@%The example above enables all disabled breakpoints.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCV75000@%%@2@%%@AB@%7.5 Breakpoint List Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV75001@%%@4@%The Breakpoint List command (%@AB@%BL%@AE@%) lists current information about all%@EH@% breakpoints.%@NL@% %@NL@% %@CR:MCV75002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV75003@%%@4@%The Breakpoint List command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV75004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV75005@%%@4@%The Breakpoint List command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCV75006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV75007@%%@4@%To list breakpoints with a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%BL%@AE@%%@NL@% %@NL@% %@CR:MCV75008@%%@4@%The command displays the breakpoint number, the enabled status (%@AS@%e%@AE@% for%@EH@% "enabled," %@AS@%d%@AE@% for "disabled"), the address, the routine, and the line number.%@NL@% %@NL@% %@CR:MCV75009@%%@4@%If the breakpoint does not fall on a line number, an offset is shown from%@EH@% the nearest previous line number. The pass count and break commands are shown if they have been set. If no breakpoints are currently defined, nothing is displayed.%@NL@% %@NL@% %@CR:MCV7500A@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >BL%@NL@% 0 e 56C4:0105 _ARCTAN:10%@NL@% 1 d 56C4:011E _ARCTAN:19 (pass = 10) "T;T"%@NL@% 2 e 56C4:00FD _ARCTAN:9+6%@NL@% >%@NL@% %@NL@% %@CR:MCV7500B@%%@4@%In the example above, breakpoint 0 is enabled at address %@AS@%56C4:0105%@AE@%. This%@EH@% address is in routine %@AS@%ARCTAN%@AE@% and is at line %@AS@%10%@AE@% of the current source file. No pass count or break commands have been set.%@NL@% %@NL@% %@CR:MCV7500C@%%@4@%Breakpoint 1 is currently disabled, as indicated by the %@AS@%d%@AE@% after the%@EH@% breakpoint number. It also has a pass count of 10, meaning that the breakpoint will not be taken until the 10th time it is encountered. The command string at the end of the line indicates that each time the breakpoint is taken, the Trace command will automatically be executed twice.%@NL@% %@NL@% %@CR:MCV7500D@%%@4@%The line number for breakpoint 2 has an offset. The address is six bytes%@EH@% beyond the address for line 9 in the current source file. Therefore, the breakpoint was probably set in assembly mode, since it would be difficult to set a breakpoint anywhere except on a source line in source mode.%@NL@% %@NL@% %@NL@% %@CR:MCV80000@%%@1@%%@AB@%Chapter 8 Managing Watch Statements%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV80001@%%@4@%Watch Statement commands are among the Microsoft CodeView debugger's most%@EH@% powerful features. They enable you to set, delete, and list watch statements. Watch statements describe expressions or areas of memory to watch. Some watch statements specify conditional breakpoints, which depend upon the value of the expression or memory area.%@NL@% %@NL@% %@CR:MCV80002@%%@4@%Syntax for each CodeView command is always the same, regardless of the%@EH@% expression evaluator; however, the method for specifying an %@AI@%argument%@AE@% may vary with the language. Therefore, each example in this chapter is repeated with C, FORTRAN, and BASIC arguments. The sample screens throughout the text that present these examples feature BASIC. At the end of this chapter are C and FORTRAN sample screens that incorporate all the previous examples (except for Watch Delete and Watch List).%@NL@% %@NL@% %@NL@% %@CR:MCV81000@%%@2@%%@AB@%8.1 Watch Statement Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV81001@%%@4@%The Watch Statement commands are summarized below:%@EH@%%@NL@% %@NL@% %@CR:MCV81002@%%@AB@%Command Action%@AE@%%@NL@% %@NL@% Watch (%@AB@%W%@AE@%) Sets an expression or range of memory to be%@NL@% watched%@NL@% %@NL@% Watchpoint (%@AB@%WP%@AE@%) Sets a conditional breakpoint that will be taken%@NL@% when the expression becomes nonzero (true)%@NL@% %@NL@% Tracepoint (%@AB@%TP%@AE@%) Sets a conditional breakpoint that will be taken%@NL@% when a given expression or range of memory%@NL@% changes%@NL@% %@NL@% Watch Delete (%@AB@%Y%@AE@%) Deletes one or more watch statements%@NL@% %@NL@% Watch List (%@AB@%W%@AE@%) Lists current watch statements%@NL@% %@NL@% %@CR:MCV81003@%%@4@%Watch statements, like breakpoints, remain in memory until you specifically%@EH@% remove them or quit the CodeView debugger. They are not canceled when you restart the program being debugged. Therefore, you can set a complicated series of watch statements once and then execute through the program several times without resetting.%@NL@% %@NL@% %@CR:MCV81004@%%@4@%In window mode, Watch Statement commands can be entered either in the dialog%@EH@% window or with menu selections. Current watch statements are shown in a watch window that appears between the menu bar and the source window.%@NL@% %@NL@% %@CR:MCV81005@%%@4@%In sequential mode, the Watch, Tracepoint, and Watchpoint commands can be%@EH@% used, but since there is no watch window, you cannot see the watch statements and their values. You must use the Watch List command to examine the current watch statements.%@NL@% %@NL@% %@CR:MCV81006@%%@4@%To set a watch statement containing a local variable, you must be in the%@EH@% function where the variable is defined. If the current line is not in the function, the CodeView debugger displays the message %@AS@%UNKNOWN SYMBOL%@AE@%. When you exit from a function containing a local variable referenced in a watch statement, the value of the statement is displayed as %@AS@%UNKNOWN%@AE@% %@AS@%SYMBOL%@AE@%. When you reenter the function, the local variable will again have a value. With the C and FORTRAN expression evaluators, you can avoid this limitation by using the period operator to specify both the function and the variable. For example, enter %@AS@%main.x%@AE@% instead of just %@AS@%x%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCV82000@%%@2@%%@AB@%8.2 Setting Watch-Expression and Watch-Memory Statements%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV82001@%%@4@%The Watch command is used to set a watch statement that specifies an%@EH@% expression (watch-expression statement) or a range of addresses in memory (watch-memory statement). The value or values specified by this watch statement are shown in the watch window. The watch window is updated to show new values each time the value of the watch statement changes during program execution. Since the watch window does not exist in sequential mode, you must use the Watch List command to examine the values of watch statements.%@NL@% %@NL@% %@CR:MCV82002@%%@4@%When setting a watch expression, you can specify the format in which the%@EH@% value will be displayed. Type the expression followed by a comma and a format specifier. If you do not give a format specifier, the CodeView debugger displays the value in a default format. See Section 6.1%@BO: 44676@%, "Display Expression Command," for more information about type specifiers and the default format.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% If your program directly accesses absolute addresses used by IBM or%@NL@% IBM-compatible computers, you may sometimes get unexpected results with%@NL@% the Display Expression and Dump commands. However, the Watch command will%@NL@% usually show the correct values. This problem can arise if the CodeView%@NL@% debugger and your program begin to use the same memory location.%@NL@% The problem often occurs when a program reads data directly from the%@NL@% screen buffer of the display adapter. If you have an array called %@AS@%screen%@AE@%%@NL@% that is initialized to the starting address of the screen buffer, the%@NL@% command %@AS@%DB screen L 16%@AE@% will display data from the CodeView display rather%@NL@% than from the display of the program you are debugging. The command %@AS@%WB%@AE@%%@NL@% %@AS@%screen L 16%@AE@% will display data from the program's display (provided screen%@NL@% swapping or screen flipping was specified at start-up). The Watch command%@NL@% behaves differently from the Dump command because watch-statement values%@NL@% are updated during program execution, and any values read from the screen%@NL@% buffer will be taken from the output screen rather than from the%@NL@% debugging screen.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV82003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV82004@%%@4@%To set a watch-expression statement using the mouse, point to Watch on the%@EH@% menu bar, press a mouse button and drag the highlight down to the Add Watch selection, and then release the button. A dialog box appears, asking for the expression to be watched. Type the expression and press the ENTER key or a mouse button.%@NL@% %@NL@% %@CR:MCV82005@%%@4@%You cannot use the mouse version of the command to specify a range of memory%@EH@% to be watched, as you can with the dialog version.%@NL@% %@NL@% %@CR:MCV82006@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV82007@%%@4@%To set a watch-expression statement with a keyboard command, press ALT+W to%@EH@% open the Watch menu, and then type %@AB@%A%@AE@% (uppercase or lowercase) to select Add Watch. You can also select the Add Watch command directly by pressing CONTROL+W. A dialog box appears, asking for the expression to be watched. Type the expression and press the ENTER key.%@NL@% %@NL@% %@CR:MCV82008@%%@4@%You cannot use the keyboard version of the command to specify a range of%@EH@% memory to be watched, as you can with the dialog version.%@NL@% %@NL@% %@CR:MCV82009@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV8200A@%%@4@%To set a watch-expression statement with a dialog command, enter a command%@EH@% line with the following syntax:%@NL@% %@NL@% %@AB@%W?%@AE@% %@AI@%expression%@AE@%«%@AB@%,%@AE@%%@AI@%format%@AE@%»%@NL@% %@NL@% %@CR:MCV8200B@%%@4@%To set a watch-memory command with a dialog command, enter a command line%@EH@% with the following syntax:%@NL@% %@NL@% %@AB@%W%@AE@%«%@AI@%type%@AE@%» %@AI@%range%@AE@%%@NL@% %@NL@% %@CR:MCV8200C@%%@4@%An %@AI@%expression%@AE@% used with the Watch command can be either a simple variable or%@EH@% a complex expression using several variables and operators. The expression should be no longer than the width of the watch window. The characters permitted for %@AI@%format%@AE@% correspond to format arguments used in a C %@AB@%printf%@AE@% function call. See Section 6.1%@BO: 44676@%, "Display Expression Command," for more information on format arguments.%@NL@% %@NL@% %@CR:MCV8200D@%%@4@%When watching a memory location, %@AI@%type%@AE@% is a one-letter size specifier from%@EH@% the following list:%@NL@% %@NL@% %@CR:MCV8200E@%%@AB@%Specifier Size%@AE@% %@NL@% %@NL@% None Default type%@NL@% %@NL@% %@AB@%B%@AE@% Byte%@NL@% %@NL@% %@AB@%A%@AE@% ASCII%@NL@% %@NL@% %@AB@%I%@AE@% Integer (signed decimal word)%@NL@% %@NL@% %@AB@%U%@AE@% Unsigned (unsigned decimal word)%@NL@% %@NL@% %@AB@%WP%@AE@% Word%@NL@% %@NL@% %@AB@%D%@AE@% Double word%@NL@% %@NL@% %@AB@%S%@AE@% Short real%@NL@% %@NL@% %@AB@%L%@AE@% Long real%@NL@% %@NL@% %@AB@%T%@AE@% 10-byte real%@NL@% %@NL@% %@CR:MCV8200F@%%@4@%If no type size is specified, the default type used is the last type used by%@EH@% a Dump, Enter, Watch Memory, or Tracepoint Memory command. If none of these commands has been used during the session, the default type is byte.%@NL@% %@NL@% %@CR:MCV8200G@%%@4@%The data will be displayed in a format similar to that used by the Dump%@EH@% commands (see Section 6.1%@BO: 44676@%, "Display Expression Command," for more information on format arguments). The %@AI@%range%@AE@% can be any length, but only one line of data will be displayed in the watch window. If you do not specify an ending address for the range, the default range is one object.%@NL@% %@NL@% %@CR:MCV8200H@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV8200I@%%@4@%The following three examples display watch statements in the watch window.%@EH@%%@NL@% %@NL@% W? n%@NL@% %@NL@% %@CR:MCV8200J@%%@4@%The example above displays the current value of the variable %@AS@%n%@AE@%.%@EH@%%@NL@% %@NL@% W? higher * 100%@NL@% %@NL@% %@CR:MCV8200K@%%@4@%The example above displays the value of the expression %@AS@%higher%@AE@%%@AS@%* 100%@AE@%.%@EH@%%@NL@% %@NL@% WL chance%@NL@% %@NL@% %@CR:MCV8200L@%%@4@%The example above displays the value of %@AS@%chance%@AE@%, a double-precision%@EH@% floating-point variable. Exactly how %@AS@%chance%@AE@% is stored in memory is shown first. (The command %@AS@%W? chance%@AE@% would display the value of %@AS@%chance%@AE@% but not any actual bytes of memory.)%@NL@% %@NL@% %@CR:MCV8200M@%%@4@%These commands, entered while debugging a BASIC program, produce the watch%@EH@% window in Figure 8.1%@FN@% Figure 8.1 is found on page 145 of the printed version.%@EF@%. Corresponding C and FORTRAN examples are included with other commands in language-specific sections at the end of the chapter.%@AB@%%@NL@% %@NL@% %@NL@% %@CR:MCV83000@%%@2@%%@AB@%8.3 Setting Watchpoints%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV83001@%%@4@%The Watchpoint command is used to set a conditional breakpoint called a%@EH@% watchpoint. A watchpoint breaks program execution when the expression described by its watch statement becomes true. You can think of watchpoints as "break when" points, since the break occurs when the specified expression becomes true (nonzero).%@NL@% %@NL@% %@CR:MCV83002@%%@4@%A watch statement created by the Watchpoint command describes the expression%@EH@% that will be watched and compared to 0. The statement remains in memory until you delete it or quit the CodeView debugger. Any valid CodeView expression can be used as the watchpoint expression as long as the expression is not wider than the watch window.%@NL@% %@NL@% %@CR:MCV83003@%%@4@%In window mode, watchpoint statements and their values are displayed in%@EH@% high-intensity text in the watch window. In sequential mode, there is no watch window, so the values of watchpoint statements can only be displayed with the Watch List command (see Section 8.6%@BO: 63917@% "Listing Watchpoints and Tracepoints," for more information).%@NL@% %@NL@% %@CR:MCV83004@%%@4@%Although watchpoints can be any valid CodeView expression, the command works%@EH@% best with expressions that use the relational operators (such as %@AB@%<%@AE@% and %@AB@%>%@AE@% for C and BASIC, or %@AB@%.LT.%@AE@% and %@AB@%.GT.%@AE@% for FORTRAN). Relational expressions always evaluate to false (zero) or true (nonzero). Care must be taken with other kinds of expressions when they are used as watchpoints, because the watchpoints will break execution whenever they do not equal precisely zero. For example, your program might use a loop variable I, which ranges from 1 to 100. If you entered %@AS@%I%@AE@% as a watchpoint, then it would always suspend program execution, since %@AS@%I%@AE@% is never equal to 0. However, the relational expression %@AS@%I>90%@AE@% (or %@AS@%I.GT.90%@AE@%) would not suspend program execution until %@AS@%I%@AE@% exceeded 90.%@NL@% %@NL@% %@CR:MCV83005@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV83006@%%@4@%To set a watchpoint statement with the mouse, point to Watch on the menu%@EH@% bar, press a mouse button and drag the highlight down to the Watchpoint selection, and then release the button. A dialog box appears, asking for the expression to be watched. Type the expression and press the ENTER key or a mouse button.%@NL@% %@NL@% %@CR:MCV83007@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV83008@%%@4@%To execute the Watchpoint command with a keyboard command, press ALT+W to%@EH@% open the Watch menu, and then press ALT+W to select Watchpoint. A dialog box appears, asking for the expression to be watched. Type the expression and press the ENTER key.%@NL@% %@NL@% %@CR:MCV83009@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV8300A@%%@4@%To set a watchpoint using a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%WP?%@AE@% %@AI@%expression%@AE@%«%@AB@%,%@AE@%%@AI@%format%@AE@%»%@NL@% %@NL@% %@CR:MCV8300B@%%@4@%The %@AI@%expression%@AE@% can be any valid CodeView expression (usually a relational%@EH@% expression). You can enter a format specifier, but there is little reason to do so, since the expression value is normally either 1 or 0.%@NL@% %@NL@% %@CR:MCV8300C@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV8300D@%%@4@%The following dialog commands display two watch statements (watchpoints) in%@EH@% the watch window:%@NL@% %@NL@% WP? higher > chance %@AI@%;* BASIC/C%@AE@%%@NL@% WP? higher .gt. chance %@AI@%;* FORTRAN example%@AE@%%@NL@% %@NL@% %@CR:MCV8300E@%%@4@%The examples above instruct the CodeView debugger to break execution when%@EH@% the variable %@AS@%higher%@AE@% is greater than the variable %@AS@%chance%@AE@%. (Note that BASIC and C happen to use the same syntax in this case, but FORTRAN uses its own.) After setting this watchpoint, you could use the Go command to execute until the condition becomes true.%@NL@% %@NL@% WP? n=7 or n=11 %@AI@%;* BASIC example%@AE@%%@NL@% WP? n==7 || n==11 %@AI@%;* C example%@AE@%%@NL@% WP? n.eq.7 .or. n.eq.11 %@AI@%;* FORTRAN example%@AE@%%@NL@% %@NL@% %@CR:MCV8300F@%%@4@%The examples above instruct the CodeView debugger to break execution when%@EH@% the variable %@AS@%n%@AE@% is equal to 7 or 11.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% BASIC and C will each display a numerical result in response to a Boolean%@NL@% expression (0 being equivalent to false, nonzero to true). However, the%@NL@% corresponding FORTRAN condition will be displayed with either .TRUE. or%@NL@% .FALSE. in the watch window.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV8300G@%%@4@%These commands, entered while debugging a BASIC program, produce the watch%@EH@% window shown in Figure 8.2%@FN@% Figure 8.2 is found on page 148 of the printed version.%@EF@%. Corresponding C and FORTRAN examples are included with other commands, at the end of the chapter.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Setting watchpoints significantly slows execution of the program being%@NL@% debugged. The CodeView debugger checks if the expression is true each%@NL@% time a source line is executed in source mode, or each time an%@NL@% instruction is executed in assembly mode. Be careful when setting%@NL@% watchpoints near large or nested loops. A loop that executes almost%@NL@% instantly when run from MS-DOS can take many minutes if executed from%@NL@% within the debugger with several watchpoints set.%@NL@% %@NL@% Tracepoints do not slow CodeView execution as much as watchpoints, so you%@NL@% should use tracepoints when possible. For example, although you can set a%@NL@% watchpoint on a Boolean variable (%@AS@%WP? moving%@AE@%), a trace-point on the same%@NL@% variable (%@AS@%TP?moving%@AE@%) has essentially the same effect and does not slow%@NL@% execution as much.%@NL@% %@NL@% If you enter a seemingly endless loop, press CONTROL+BREAK or CONTROL+C%@NL@% to exit. You will soon learn the size of loop you can safely execute when%@NL@% watchpoints are set.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV84000@%%@2@%%@AB@%8.4 Setting Tracepoints%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV84001@%%@4@%The Tracepoint command is used to set a conditional breakpoint called a%@EH@% tracepoint. A tracepoint breaks program execution when the value of a specified expression or range of memory changes.%@NL@% %@NL@% %@CR:MCV84002@%%@4@%The watch statement created by the Tracepoint command describes the%@EH@% expression or memory range to be watched and tested for change. The statement remains in memory until you delete it or quit the CodeView debugger.%@NL@% %@NL@% %@CR:MCV84003@%%@4@%In window mode, tracepoint statements and their values are shown in%@EH@% high-intensity text in the watch window. In sequential mode, there is no watch window, so the values of tracepoint statements can only be displayed with the Watch List command (see Section 8.5%@BO: 62b98@%, "Listing Watchpoints and Tracepoints," for more information).%@NL@% %@NL@% %@CR:MCV84004@%%@4@%An expression used with the Tracepoint command must evaluate to an "lvalue."%@EH@% In other words, the expression must refer to an area of memory rather than a constant. Furthermore, the area of memory must be not more than 128 bytes in size. For example, %@AS@%i==10%@AE@% (which is similar to %@AS@%I.EQ.10%@AE@% in FORTRAN and %@AS@%I=10%@AE@% in BASIC) would be invalid because it is either 1 (true) or 0 (false) rather than a value stored in memory. The expression %@AS@%sym1+sym2%@AE@% is invalid because it is the calculated sum of the value of two memory locations. The expression %@AS@%buffer%@AE@% would be invalid if %@AS@%buffer%@AE@% is an array of 130 bytes, but valid if the array is 120 bytes. (However, using array names this way is not valid with BASIC modules because BASIC uses array descriptors.) Note that if %@AS@%buffer%@AE@% is declared as an array of 64 bytes, then the Tracepoint command given with the expression %@AS@%buffer%@AE@% checks all 64 bytes of the array. The same command given with the C expression %@AS@%buffer[32]%@AE@%, or %@AS@%BUFFER(33)%@AE@% in FORTRAN or BASIC, means that only one byte (the 33rd) will be checked. (Note that C and FORTRAN index the same element differently.)%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The following is relevant only to C programs.%@NL@% %@NL@% Register variables are not considered values. Therefore, if %@AS@%i%@AE@% is declared%@NL@% as %@AS@%register int i%@AE@%, the command %@AS@%TP?%@AE@%%@AS@%i%@AE@% is invalid. However, you can still%@NL@% check for changes in the value of %@AS@%i%@AE@%. Use the Examine Symbols command to%@NL@% learn which register contains the value of %@AS@%i%@AE@% .%@NL@% %@NL@% Then learn the value of %@AS@%i%@AE@%. Finally, set up a watchpoint to test the%@NL@% value. For example, use the following sequence of commands:%@NL@% %@NL@% >X? i%@NL@% 3A79:0264 int div()%@NL@% SI int i%@NL@% >?i%@NL@% 10%@NL@% >WP? @SI%@AI@%!=10%@AE@%%@NL@% >%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV84005@%%@4@%When setting a tracepoint expression, you can specify the format in which%@EH@% the value will be displayed. Type the expression followed by a comma and a type specifier. If you do not give a type specifier, the CodeView debugger displays the value in a default format. See Section 6.1%@BO: 44676@%,"Display Expression Command," for more information about type specifiers and the default format.%@NL@% %@NL@% %@CR:MCV84006@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV84007@%%@4@%To set a tracepoint-expression statement with the mouse, point to Watch on%@EH@% the menu bar, press a mouse button and drag the highlight down to the Tracepoint selection, and then release the button. A dialog box appears, asking for the expression to be watched. Type the expression, and press the ENTER key or a mouse button.%@NL@% %@NL@% %@CR:MCV84008@%%@4@%You cannot specify a range of memory to be watched with the mouse version of%@EH@% the command, as you can with the dialog version.%@NL@% %@NL@% %@CR:MCV84009@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV8400A@%%@4@%To set a tracepoint-expression statement with a keyboard command, press%@EH@% ALT+W to open the Watch menu, and then press ALT+T to select Tracepoint. A dialog box appears, asking for the expression to be watched. Type the expression and press the ENTER key.%@NL@% %@NL@% %@CR:MCV8400B@%%@4@%You cannot use the keyboard version of the command to specify a range of%@EH@% memory to be watched, as you can with the dialog version.%@NL@% %@NL@% %@CR:MCV8400C@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV8400D@%%@4@%To set a tracepoint with a dialog command, enter a command line with one of%@EH@% the following forms of syntax:%@NL@% %@NL@% %@AB@%TP?%@AE@% %@AI@%expression%@AE@%,«%@AI@%format%@AE@%»%@NL@% %@AB@%TP%@AE@%«%@AI@%type%@AE@%» %@AI@%range%@AE@%%@NL@% %@NL@% %@CR:MCV8400E@%%@4@%The first syntax line above sets a tracepoint expression; the second line%@EH@% sets a tracepoint memory.%@NL@% %@NL@% %@CR:MCV8400F@%%@4@%An %@AI@%expression%@AE@% used with the Tracepoint command can be either a simple%@EH@% variable or a complex expression using several variables and operators. The expression should not be longer than the width of the watch window. You can specify %@AI@%format%@AE@% using a C %@AB@%printf%@AE@% type specifier if you do not want the value to be displayed in the default format (decimal for integers or floating point for real numbers). See Section 6.1%@BO: 44676@%, "Display Expression Command," for more information on format arguments.%@NL@% %@NL@% %@CR:MCV8400G@%%@4@%In the memory-tracepoint form, %@AI@%range%@AE@% must be a valid address range and %@AI@%type%@AE@%%@EH@% must be a one-letter memory-size specifier. If you specify only the start of the range, the CodeView debugger displays one object as the default.%@NL@% %@NL@% %@CR:MCV8400H@%%@4@%Although no more than one line of data will be displayed in the watch%@EH@% window, the range to be checked for change can be any size up to 128 bytes.%@NL@% %@NL@% %@CR:MCV8400I@%%@4@%The data will be displayed in the format used by the Dump commands (see%@EH@% Section 6.1%@BO: 44676@%, "Display Expression Command," for more information on format arguments). The valid memory-size specifiers are listed below:%@NL@% %@NL@% %@CR:MCV8400J@%%@AB@%Specifier Size%@AE@% %@NL@% %@NL@% None Default type%@NL@% %@NL@% %@AB@%B%@AE@% Byte%@NL@% %@NL@% %@AB@%A%@AE@% ASCII%@NL@% %@NL@% %@AB@%I%@AE@% Integer (signed decimal word)%@NL@% %@NL@% %@AB@%U%@AE@% Unsigned (unsigned decimal word)%@NL@% %@NL@% %@AB@%WP%@AE@% Word%@NL@% %@NL@% %@AB@%D%@AE@% Double word%@NL@% %@NL@% %@AB@%S%@AE@% Short real%@NL@% %@NL@% %@AB@%L%@AE@% Long real%@NL@% %@NL@% %@AB@%T%@AE@% 10-byte real%@NL@% %@NL@% %@CR:MCV8400K@%%@4@%The default type used if no type size is specified is the last type used by%@EH@% a Dump, Enter, Watch Memory, or Tracepoint Memory command. If none of these commands has been used during the session, the default type is byte.%@NL@% %@NL@% %@CR:MCV8400L@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV8400M@%%@4@%The two dialog commands below display watch statements (tracepoints) in the%@EH@% watch window.%@NL@% %@NL@% TP? sum%@NL@% %@NL@% %@CR:MCV8400N@%%@4@%The example above instructs the CodeView debugger to suspend program%@EH@% execution whenever the value of the variable %@AS@%sum%@AE@% changes.%@NL@% %@NL@% TPB n%@NL@% %@NL@% %@CR:MCV8400O@%%@4@%The example above instructs the CodeView debugger to suspend program%@EH@% execution whenever the first byte at the address of %@AS@%n%@AE@% changes; the address of this byte and its contents are displayed. The value of %@AS@%n%@AE@% may change because of a change in the %@AI@%second%@AE@% byte at the address of %@AS@%n%@AE@%; but that change (by itself) would have no effect on this tracepoint.%@NL@% %@NL@% %@CR:MCV8400P@%%@4@%These commands, entered while debugging a BASIC program, produce the watch%@EH@% window in Figure 8.3%@FN@% Figure 8.3 is found on page 152 of the printed version.%@EF@%. Corresponding C and FORTRAN examples are included, with other commands, at the end of the chapter.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Setting tracepoints significantly slows execution of the program being%@NL@% debugged. The CodeView debugger has to check to see if the expression or%@NL@% memory range has changed each time a source line is executed in source%@NL@% mode or each time an instruction is executed in assembly mode. However,%@NL@% tracepoints do not slow execution as much as do watchpoints.%@NL@% %@NL@% Be careful when setting tracepoints near large or nested loops. A loop%@NL@% that executes almost instantly when run from the MS-DOS operating system%@NL@% can take many minutes if executed from within the debugger with several%@NL@% tracepoints set. If you enter a seemingly endless loop, press%@NL@% CONTROL+BREAK or CONTROL+C to exit. Often you can tell how far you went%@NL@% in the loop by the value of the tracepoint when you exited.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV85000@%%@2@%%@AB@%8.5 Deleting Watch Statements%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV85001@%%@4@%The Watch Delete command enables you to delete watch statements that were%@EH@% set previously with the Watch, Watchpoint, or Tracepoint command.%@NL@% %@NL@% %@CR:MCV85002@%%@4@%When you delete a watch statement in window mode, the statement disappears%@EH@% and the watch window closes around it. For example, if there are three watch statements in the window and you delete statement 1, the window is redrawn with one less line. Statement 0 remains unchanged, but statement 2 becomes statement 1. If there is only one statement, the window disappears.%@NL@% %@NL@% %@CR:MCV85003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV85004@%%@4@%To delete a watch statement with the mouse, point to Watch on the menu bar,%@EH@% press a mouse button and drag the highlight down to the Delete Watch selection, and then release the button. A dialog box appears, containing all the watch statements. Point to the statement you want to delete and press the ENTER key or a mouse button. The dialog box disappears, and the watch window is redrawn without the watch statement.%@NL@% %@NL@% %@CR:MCV85005@%%@4@%You can also delete all the statements in the watch window at once, simply%@EH@% by selecting the Delete All selection.%@NL@% %@NL@% %@CR:MCV85006@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV85007@%%@4@%To execute the Delete Watch command with a keyboard command, press ALT+W to%@EH@% open the Watch menu, and then type %@AB@%D%@AE@% (uppercase or lowercase) to select Delete Watch. You can also select the Delete Watch command directly by pressing CONTROL+U. A dialog box appears, containing all the watch statements. Use the UP and DOWN keys to move the cursor to the statement you want to delete, and then press the ENTER key. The dialog box disappears, and the watch window is redrawn without the watch statement.%@NL@% %@NL@% %@CR:MCV85008@%%@4@%You can also delete all the statements in the watch window at once, simply%@EH@% by selecting the Delete All selection. Do this by pressing %@AB@%L%@AE@% (upppercase or lowercase) after the Watch menu is open.%@NL@% %@NL@% %@CR:MCV85009@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV8500A@%%@4@%To delete watch statements with a dialog command, enter a command line with%@EH@% the following syntax:%@NL@% %@NL@% %@AB@%Y%@AE@% %@AI@%number%@AE@%%@NL@% %@NL@% %@CR:MCV8500B@%%@4@%When you set a watch statement, it is automatically assigned a number%@EH@% (starting with 0). In window mode, the number appears to the left of the watch statement in the watch window. In sequential mode, you can use the Watch List (%@AB@%W%@AE@%) command to view the numbers of current watch statements.%@NL@% %@NL@% %@CR:MCV8500C@%%@4@%You can delete existing watch statements by specifying the %@AI@%number%@AE@% of the%@EH@% statement you want to delete with the Delete Watch command. (The %@AB@%Y%@AE@% is a mnemonic for "yank.")%@NL@% %@NL@% %@CR:MCV8500D@%%@4@%You can use the asterisk (%@AB@%*%@AE@%) to represent all watch statements.%@EH@%%@NL@% %@NL@% %@CR:MCV8500E@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >Y 2%@NL@% >%@NL@% %@NL@% %@CR:MCV8500F@%%@4@%The command above deletes watch statement 2.%@EH@%%@NL@% %@NL@% >Y *%@NL@% >%@NL@% %@NL@% %@CR:MCV8500G@%%@4@%The command above deletes all watch statements and closes the watch window.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCV86000@%%@2@%%@AB@%8.6 Listing Watchpoints and Tracepoints%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV86001@%%@4@%The Watch List command lists all previously set watchpoints and tracepoints%@EH@% with their assigned numbers and their current values.%@NL@% %@NL@% %@CR:MCV86002@%%@4@%This command is the only way to examine current watch statements in%@EH@% sequential mode. The command has little use in window mode, since watch statements are already visible in the watch window as shown in Figure 8.4%@FN@% Figure 8.4 is found on page 154 of the printed version.%@EF@%.%@NL@% %@NL@% %@CR:MCV86003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV86004@%%@4@%The Watch List command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV86005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV86006@%%@4@%The Watch List command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCV86007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV86008@%%@4@%To list watch statements with a dialog command, enter a command line with%@EH@% the following syntax:%@NL@% %@NL@% >W%@NL@% %@NL@% %@CR:MCV86009@%%@4@%The display is the same as the display that appears in the watch window in%@EH@% window mode shown in Figure 8.5%@FN@% Figure 8.5 is found on page 155 of the printed version.%@EF@%.%@NL@% %@NL@% %@CR:MCV8600A@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >W%@NL@% 0) code,c : I%@NL@% 1) (float)letters/words,f : 4.777778%@NL@% 2) 3F65:0B20 20 20 43 4F 55 4E 54 COUNT%@NL@% 3) lines==11 : 0%@NL@% >%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The command letter for the Watch List command is the same as the command%@NL@% letter for the memory version of the Watch command when no memory size is%@NL@% given. The difference between the commands is that the Watch List command%@NL@% never takes an argument. The Watch command always requires at least one%@NL@% argument.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCV87000@%%@2@%%@AB@%8.7 C Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV87001@%%@4@%The seven examples shown previously in a BASIC screen would be entered in a%@EH@% C debugging session as follows:%@NL@% %@NL@% %@CR:MCV87002@%%@4@%The first three items in the watch window are simple watch statements. They%@EH@% display values but never cause execution to break.%@AB@%%@NL@% %@NL@% %@CR:MCV87003@%%@4@%The next two items are watchpoints; they cause execution to break whenever%@EH@% they evaluate to true (nonzero). The fourth item will break execution whenever %@AS@%higher%@AE@% is greater than %@AS@%chance%@AE@%, and the fifth item will break execution whenever %@AS@%n%@AE@% is equal to 7 or 11.%@NL@% %@NL@% %@CR:MCV87004@%%@4@%The last two items are tracepoints, which cause execution to break whenever%@EH@% any bytes change within a specified area of memory. The sixth item breaks execution whenever the value of %@AS@%sum%@AE@% changes; the seventh item breaks execution whenever there is a change in the first byte at the address of %@AS@%n%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCV88000@%%@2@%%@AB@%8.8 FORTRAN Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV88001@%%@4@%The seven examples shown previously in a BASIC screen would be entered in a%@EH@% FORTRAN debugging session as follows:%@NL@% %@NL@% %@CR:MCV88002@%%@4@%The first three items in the watch window are simple watch statements. They%@EH@% display values but never cause execution to break. %@AB@%%@NL@% %@NL@% %@CR:MCV88003@%%@4@%The next two items are watchpoints; they cause execution to break whenever%@EH@% they evaluate to true (nonzero). The fourth item will break execution whenever %@AS@%higher%@AE@% is greater than %@AS@%chance%@AE@%, and the fifth item will break execution whenever %@AS@%n is equal to %@AE@%%@AS@%7 or 11%@AE@%.%@AS@%%@NL@% %@NL@% %@CR:MCV88004@%%@4@%The last two items are tracepoints, which cause execution to break whenever%@EH@% any bytes change within a specified area of memory. The sixth item breaks execution whenever the value of %@AS@%sum%@AE@% changes; the seventh item breaks execution whenever there is a change in the first byte at the address of %@AS@%n%@AE@% .%@NL@% %@NL@% %@NL@% %@CR:MCV89000@%%@2@%%@AB@%8.9 Assembly Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV89001@%%@4@%By default, assembly source modules are debugged with the C expression%@EH@% evaluator. Therefore, refer to the C examples for appropriate syntax for entering watch expressions.%@NL@% %@NL@% %@CR:MCV89002@%%@4@%In addition, certain C expressions tend to be more useful for debugging%@EH@% assembly modules. The following examples show some typical cases used with watch and tracepoint commands.%@NL@% %@NL@% %@CR:MCV89003@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >WW sp L 8%@NL@% >WW bp L 8%@NL@% >W? wo bp+4,d%@NL@% >W? by bp-2,d%@NL@% >TPW arr L 5%@NL@% >%@NL@% %@NL@% %@CR:MCV89004@%%@4@%The first two examples watch a range of memory. The watch command %@AS@%WW sp L 8%@AE@%%@EH@% is particularly useful because it will cause the debugger to watch the stack dynamically; the debugger will continually display the first eight words on the top of the stack as items are pushed and popped. The expression %@AS@%WW bp L%@AE@% %@AS@%8%@AE@% is similar; it causes the debugger to watch the first eight words in memory pointed to by %@AB@%BP%@AE@% (the framepointer).%@NL@% %@NL@% %@CR:MCV89005@%%@4@%The third example, %@AS@%W? wo bp+4,d%@AE@%, is useful if you are using the stack to%@EH@% pass parameters. In this case, the position on the stack four bytes above %@AB@%BP%@AE@% holds one of three integer parameters. The %@AB@%WO%@AE@% operator returns the same value as the assembler expression %@AS@%WORD PTR [bp+4]%@AE@%; the result is displayed in decimal.%@NL@% %@NL@% %@CR:MCV89006@%%@4@%You must use the expression %@AS@%bp+4%@AE@% in order to watch this parameter; you%@EH@% cannot specify a parameter by name. The assembler does not emit symbolic information for parameters. The fourth command, %@AS@%W? by%@AE@%%@AS@%bp-2,d%@AE@%, is similar to the third, but watches a local variable instead of watching a parameter. The operator %@AB@%BY%@AE@% returns the same value as the assembler expression %@AS@%BYTE PTR%@AE@% %@AS@%[bp-2]%@AE@%.%@NL@% %@NL@% %@CR:MCV89007@%%@4@%The final example sets a tracepoint on a range of memory, which corresponds%@EH@% to the first five words of the array %@AS@%arr%@AE@%. Range arguments for tracepoint and watch expressions are particularly useful for large data structures, such as arrays.%@NL@% %@NL@% %@CR:MCV89008@%%@4@%The five examples above produce the screen shown in Figure 8.6%@FN@% Figure 8.6 is found on page 157 of the printed version.%@EF@% when entered%@EH@% in a CodeView debugging session.%@NL@% %@NL@% %@NL@% %@CR:MCV90000@%%@1@%%@AB@%Chapter 9 Examining Code%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV90001@%%@4@%Several CodeView commands allow you to examine program code or data related%@EH@% to code. The following commands are discussed in this chapter:%@NL@% %@NL@% %@CR:MCV90002@%%@AB@%Command Action%@AE@%%@NL@% %@NL@% Set Mode (%@AB@%S%@AE@%) Sets format for code displays%@NL@% %@NL@% Unassemble (%@AB@%U%@AE@%) Displays assembly instructions%@NL@% %@NL@% View (%@AB@%V%@AE@%) Displays source lines%@NL@% %@NL@% Current Location (%@AB@%.%@AE@%) Displays the current location line%@NL@% %@NL@% Stack Trace (%@AB@%K%@AE@%) Displays routines or procedures%@NL@% %@NL@% %@NL@% %@CR:MCV91000@%%@2@%%@AB@%9.1 Set Mode Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV91001@%%@4@%The Set Mode command sets the mode in which code is displayed. The two basic%@EH@% display modes are source mode in which the program is displayed as source lines, and assembly mode in which the program is displayed as assembly-language instructions. These two modes can be combined in mixed mode in which the program is displayed with both source lines and assembly-language instructions.%@NL@% %@NL@% %@CR:MCV91002@%%@4@%In sequential mode, there are three display modes: source, assembly, and%@EH@% mixed. These modes affect the output of commands that display code (Register, Trace, Program Step, Go, Execute, and Unassemble).%@NL@% %@NL@% %@CR:MCV91003@%%@4@%In window mode, these same display modes are available, but affect what kind%@EH@% of code appears in the display window.%@NL@% %@NL@% %@CR:MCV91004@%%@4@%Source and mixed modes are only available if the executable file contains%@EH@% symbols in the CodeView format. Programs that do not contain symbolic information (including all .COM files) are displayed in assembly mode.%@NL@% %@NL@% %@CR:MCV91005@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV91006@%%@4@%To set the display mode with the mouse, point to View on the menu bar, press%@EH@% a mouse button and drag the highlight to either the Source selection for source mode, the Mixed selection for mixed mode, or the Assembly selection for assembly mode. Then release the button.%@NL@% %@NL@% %@CR:MCV91007@%%@4@%You can further control the display of assembly-language instructions by%@EH@% making selections from the Options menu. See Section 2.1.3.6%@BO: 2918d@% for more information.%@NL@% %@NL@% %@CR:MCV91008@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV91009@%%@4@%To change the display mode with a keyboard command, press F3. This will%@EH@% rotate the mode to the next setting; you may need to press F3 twice to get the desired mode. This command works in either window or sequential mode. In sequential mode, the word %@AS@%source%@AE@%, %@AS@%mixed%@AE@%, or %@AS@%assembly%@AE@% is displayed to indicate the new mode.%@NL@% %@NL@% %@CR:MCV9100A@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV9100B@%%@4@%To set the display mode from the dialog window, enter a command line with%@EH@% the following syntax:%@NL@% %@NL@% %@AB@%S%@AE@%«%@AB@%+ | - | &%@AE@%»%@NL@% %@NL@% %@CR:MCV9100C@%%@4@%If the plus sign is specified (%@AB@%S+%@AE@%), source mode is selected, and the word%@EH@% %@AS@%source%@AE@% is displayed.%@NL@% %@NL@% %@CR:MCV9100D@%%@4@%If the minus sign is specified (%@AB@%S-%@AE@%), assembly mode is selected, and the word%@EH@% %@AS@%assembly%@AE@% is displayed. In window mode, the display will include any assembly options, except the Mixed Source option, previously toggled on from the Options menu. The Mixed Source option is always turned off by the %@AB@%S-%@AE@% command.%@NL@% %@NL@% %@CR:MCV9100E@%%@4@%If the ampersand is specified (%@AB@%S&%@AE@%), mixed mode is selected, and the word%@EH@% %@AS@%mixed%@AE@% is displayed. In window mode, the display will include any assembly options previously toggled on from the Options menu. In addition, the Mixed Source option will be turned on by the %@AB@%S&%@AE@% command.%@NL@% %@NL@% %@CR:MCV9100F@%%@4@%If no argument is specified (%@AB@%S%@AE@%), the current mode (%@AS@%source%@AE@%, %@AS@%assembly%@AE@%, or%@EH@% %@AS@%mixed%@AE@%) is displayed.%@NL@% %@NL@% %@CR:MCV9100G@%%@4@%The Unassemble command in sequential mode is an exception in that it%@EH@% displays mixed, source, and assembly with both the source (%@AB@%S+%@AE@%) and mixed (%@AB@%S&%@AE@%) modes.%@NL@% %@NL@% %@CR:MCV9100H@%%@4@%When you enter the dialog version of the Set Mode command, the CodeView%@EH@% outputs the name of the new display mode: %@AS@%source%@AE@%, %@AS@%assembly%@AE@%, or %@AS@%mixed%@AE@%.%@NL@% %@NL@% %@CR:MCV9100I@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >S+%@NL@% source%@NL@% >S-%@NL@% assembly%@NL@% >S&%@NL@% mixed%@NL@% >%@NL@% %@NL@% %@CR:MCV9100J@%%@4@%The examples above show the source mode being changed to %@AS@%source%@AE@%, %@AS@%assembly%@AE@%,%@EH@% and %@AS@%mixed%@AE@%. In window mode, the commands change the format of the display window. In sequential mode, the commands change the output from the commands that display code (Register, Trace, Program Step, Go, Execute, and Unassemble). See the sections below on individual commands for examples of how they are affected by the display mode.%@NL@% %@NL@% %@NL@% %@CR:MCV92000@%%@2@%%@AB@%9.2 Unassemble Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV92001@%%@4@%The Unassemble command displays the assembly-language instructions of the%@EH@% program being debugged. It is most useful in sequential mode, where it is the only method of examining a sequence of assembly-language instructions. In window mode, it can be used to display a specific portion of assembly-language code in the display window.%@NL@% %@NL@% %@CR:MCV92002@%%@4@%Occasionally, code similar to the following will be displayed:%@EH@%%@NL@% %@NL@% FE30 ??? Byte Ptr [BX + SI]%@NL@% %@NL@% %@CR:MCV92003@%%@4@%If you attempt to unassemble data, the CodeView debugger may display%@EH@% meaningless instructions.%@NL@% %@NL@% %@CR:MCV92004@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV92005@%%@4@%The Unassemble command has no direct mouse equivalent, but you can view%@EH@% unassembled code at any time by changing the mode to assembly or mixed (see Section 9.1%@BO: 6576d@%, "Set Mode Command," for more information).%@NL@% %@NL@% %@CR:MCV92006@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV92007@%%@4@%The Unassemble command has no direct keyboard equivalent, but you can view%@EH@% unassembled code at any time by changing the mode to assembly or mixed (see Section 9.1%@BO: 6576d@%, "Set Mode Command," for more information).%@NL@% %@NL@% %@CR:MCV92008@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV92009@%%@4@%To display unassembled code using a dialog command, enter a command line%@EH@% with the following syntax:%@NL@% %@NL@% %@AB@%U%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%»%@NL@% %@NL@% %@CR:MCV9200A@%%@4@%The effect of the command varies depending on whether you are in sequential%@EH@% or window mode.%@NL@% %@NL@% %@CR:MCV9200B@%%@4@%In sequential mode, if you do not specify %@AI@%address%@AE@% or %@AI@%range%@AE@%, the disassembled%@EH@% code begins at the current unassemble address and shows the next eight lines of instructions. The unassemble address is the address of the instruction after the last instruction displayed by the previous Unassemble command. If the Unassemble command has not been used during the session, the unassemble address is the current instruction.%@NL@% %@NL@% %@CR:MCV9200C@%%@4@%If you specify an %@AI@%address%@AE@%, the disassembly starts at that address and shows%@EH@% the next eight lines of instructions. If you specify a %@AI@%range%@AE@%, the instructions within the range will be displayed.%@NL@% %@NL@% %@CR:MCV9200D@%%@4@%The sequential mode format of the display depends on the current display%@EH@% mode (see Section 9.1%@BO: 6576d@%, "Set Mode Command," for more information). If the mode is source (%@AB@%S+%@AE@%) or mixed (%@AB@%S&%@AE@%), the CodeView debugger displays source lines mixed with unassembled instructions. One source line is shown for each corresponding group of assembly-language instructions. If the display mode is assembly, only assembly-language instructions are shown.%@NL@% %@NL@% %@CR:MCV9200E@%%@4@%In window mode, the Unassemble command changes the mode of the display%@EH@% window to assembly. The display format will reflect any options previously set from the Options menu. There is no output to the dialog window. If %@AI@%address%@AE@% is given, the instructions in the display window will begin at the specified address. If %@AI@%range%@AE@% is given, only the starting address will be used. If no argument is given, the debugger scrolls down and displays the next screen of assembly-language instructions.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The 80286 protected-mode mnemonics (also available with the 80386) cannot%@NL@% be displayed with the Unassemble command.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV9200F@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >S&%@NL@% mixed%@NL@% >U 0x11%@NL@% 49D0:0011 35068E XOR AX,__sqrtjmptab+8cd4 (8E06)%@NL@% 49D0:0014 189A2300 SBB Byte Ptr [BP+SI+0023],BL%@NL@% 49D0:0018 FC CLD%@NL@% 49D0:0019 49 DEC CX%@NL@% 49D0:001A CD351ED418 INT 35 ;FSTP DWord Ptr [__fpinit+ee (18D4)]%@NL@% 49D0:001F CD3D INT 3D ;FWAIT%@NL@% 7: A = 0.0%@NL@% 49D0:0021 CD35EE INT 35 ;FLDZ%@NL@% %@NL@% %@CR:MCV9200G@%%@4@%The sequential mode example above sets the mode to mixed and unassembles%@EH@% eight lines of machine code, plus whatever source lines are encountered within those lines. The display would be the same if the mode were source.%@NL@% %@NL@% %@CR:MCV9200H@%%@4@%The example is taken from a FORTRAN debugging session, but produces results%@EH@% similar to what would be produced using the same commands with a C or BASIC program.%@NL@% %@NL@% >S-%@NL@% assembly%@NL@% >U 0x11%@NL@% 49D0:0011 35068E XOR AX,__sqrtjmptab+8cd4 (8E06)%@NL@% 49D0:0014 189A2300 SBB Byte Ptr [BP+SI+0023],BL%@NL@% 49D0:0018 FC CLD%@NL@% 49D0:0019 49 DEC CX%@NL@% 49D0:001A CD351ED418 INT 35 ;FSTP DWord Ptr [__fpinit+ee (18D4)]%@AE@%%@NL@% 49D0:001F CD3D INT 3D ;FWAIT%@NL@% 49D0:0021 CD35EE INT 35 ;FLDZ%@NL@% >%@NL@% %@NL@% %@CR:MCV9200I@%%@4@%The sequential mode example above sets the mode to assembly and repeats the%@EH@% same command.%@NL@% %@NL@% %@NL@% %@CR:MCV93000@%%@2@%%@AB@%9.3 View Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV93001@%%@4@%The View command displays the lines of a text file (usually a source module%@EH@% or include file). It is most useful in sequential mode where it is the only method of examining a sequence of source lines. In window mode the View command can be used to page through the source file or to load a new source file.%@NL@% %@NL@% %@CR:MCV93002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV93003@%%@4@%To load a new source file with the button, point to File on the menu bar,%@EH@% press a mouse button and drag the highlight to the Load selection, then release the button. A dialog box appears, asking for the name of the file you wish to load. Type the name of the file, and press ENTER or a mouse button. The new file appears in the display window.%@NL@% %@NL@% %@CR:MCV93004@%%@4@%The paging capabilities of the View command have no direct mouse equivalent,%@EH@% but you can move about in the source file by pointing to the up or down arrows on the scroll bars and then clicking different mouse buttons. See Section 2.1.2.2%@BO: 21bc1@%, "Controlling Program Execution with the Mouse," for more information.%@NL@% %@NL@% %@CR:MCV93005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV93006@%%@4@%To load a new source file with a keyboard command, press ALT+F to open the%@EH@% File menu, then press L to select Load. A dialog box appears, asking for the name of the file you wish to load. Type the name of the file, and press ENTER. The new file appears in the display window.%@NL@% %@NL@% %@CR:MCV93007@%%@4@%The paging capabilities of the View command have no direct keyboard%@EH@% equivalent, but you can move about in the source file by first putting the cursor in the display window with the F6 key, then pressing the PGUP, PGDN, HOME, END,%@NL@% %@NL@% %@CR:MCV93008@%%@4@%UP ARROW, and DOWN ARROW keys. See Section 2.1.1.3%@BO: 1e85f@%, "Controlling Program%@EH@% Execution with Keyboard Commands," for more information.%@NL@% %@NL@% %@CR:MCV93009@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV9300A@%%@4@%To display source lines using a dialog command, enter a command line with%@EH@% the following syntax:%@NL@% %@NL@% %@AB@%V%@AE@% «%@AI@%expression%@AE@%»%@NL@% %@NL@% %@CR:MCV9300B@%%@4@%Since addresses for the View command are often specified as a line number%@EH@% (with an optional source file), a more specific syntax for the command would be as follows:%@NL@% %@NL@% %@AB@%V%@AE@% «%@AB@%.%@AE@%«%@AI@%filename%@AE@%:»%@AI@%linenumber%@AE@%»%@NL@% %@NL@% %@CR:MCV9300C@%%@4@%The effect of the command varies, depending on whether you are in sequential%@EH@% or window mode.%@NL@% %@NL@% %@CR:MCV9300D@%%@4@%In sequential mode, the View command displays eight source lines. The%@EH@% starting source line is one of the following:%@NL@% %@NL@% %@CR:MCV9300E@% ■ The current source line if no argument is given.%@NL@% %@NL@% ■ The specified %@AI@%linenumber%@AE@%. If %@AI@%filename%@AE@% is given, the specified file is%@NL@% loaded, and the %@AI@%linenumber%@AE@% refers to lines in it.%@NL@% %@NL@% ■ The address that %@AI@%expression%@AE@% evaluates to. For example, %@AI@%expression%@AE@% could%@NL@% be a procedure name or an address in the %@AI@%segment%@AE@%%@AB@%:%@AE@%%@AI@%offset%@AE@% format. The%@NL@% code segment is assumed if no segment is given.%@NL@% %@NL@% %@CR:MCV9300F@%%@4@%In sequential mode, the View command is not affected by the current display%@EH@% mode (source, assembly, or mixed); source lines are displayed without regard to mode.%@NL@% %@NL@% %@CR:MCV9300G@%%@4@%In window mode, if you enter the View command while the display mode is%@EH@% assembly, the CodeView debugger will automatically switch back to source mode. If you give %@AI@%linenumber%@AE@% or %@AI@%expression%@AE@%, the display window will be redrawn so that the source line corresponding to the given %@AI@%address%@AE@% will appear at the top of the source window. If you specify a %@AI@%filename%@AE@% with a %@AI@%linenumber%@AE@%, the specified file will be loaded.%@NL@% %@NL@% %@CR:MCV9300H@%%@4@%If you enter the View command with no arguments, the display will scroll%@EH@% down one line short of a page; that is, the source line that was at the bottom of the window will be at the top.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The View command with no argument is similar to pressing the PGDN key or%@NL@% clicking Right on the down arrow with the mouse. The difference is that%@NL@% pressing the PGDN key enables you to scroll down one more line.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV9300I@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >V BUBBLE %@AI@%;* Example 1, FORTRAN source code%@AE@%%@NL@% 51: IF (N .LE. 1) GOTO 101%@NL@% 52: DO 201 I = 1,N-1%@NL@% 53: DO 301 J = I + 1,N%@NL@% 54: IF (X(I) .LE. X(J)) GOTO 301%@NL@% 55: TEMP = X(I)%@NL@% 56: X(I) = X(J)%@NL@% 57: X(J) = TEMP%@NL@% 58: 301 CONTINUE%@NL@% %@NL@% %@CR:MCV9300J@%%@4@%Example 1 (shown in sequential mode) displays eight source lines, beginning%@EH@% at routine %@AS@%BUBBLE%@AE@%.%@NL@% %@NL@% >V .math.c:30 %@AI@%;* Example 2, C source code%@AE@%%@NL@% 30: register int j;%@NL@% 31:%@NL@% 32: for (j = q; j >= 0; j--)%@NL@% 33: if (t[j] + p[j] > 9) {%@NL@% 34: p[j] += t[j] - 10;%@NL@% 35: p[j-1] += 1;%@NL@% 36: } else%@NL@% 37: p[j] += t[j];%@NL@% >%@NL@% %@NL@% %@CR:MCV9300K@%%@4@%Example 2 loads the source file %@AS@%math.c%@AE@% and displays eight source lines%@EH@% starting at line %@AS@%30%@AE@%.%@NL@% %@NL@% %@CR:MCV9300L@%%@4@%All forms of the View command are supported with all languages that work%@EH@% with the CodeView debugger.%@NL@% %@NL@% %@NL@% %@CR:MCV94000@%%@2@%%@AB@%9.4 Current Location Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV94001@%%@4@%The Current Location command displays the source line or assembly-language%@EH@% instruction corresponding to the current program location.%@NL@% %@NL@% %@CR:MCV94002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV94003@%%@4@%The Current Location command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCV94004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV94005@%%@4@%The Current Location command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCV94006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV94007@%%@4@%To display the current location line using a dialog command, enter a command%@EH@% line with the following syntax (a period only):%@NL@% %@NL@% %@AB@%.%@AE@%%@NL@% %@NL@% %@CR:MCV94008@%%@4@%In sequential mode, the command displays the current source line. The line%@EH@% is displayed regardless of whether the current debugging mode is source or assembly. If the program being debugged has no symbolic information, the command will be ignored.%@NL@% %@NL@% %@CR:MCV94009@%%@4@%In window mode, the command puts the current program location (marked with%@EH@% reverse video or a contrasting color) in the center of the display window. The display mode (source or assembly) will not be affected. This command is useful if you have scrolled through the source code or assembly-language instructions so that the current location line is no longer visible.%@NL@% %@NL@% %@CR:MCV9400A@%%@4@%For example, if you are in window mode and have executed the program being%@EH@% debugged to somewhere near the start of the program, but you have scrolled the display to a point near the end, the Current Location command returns the display to the current program location.%@NL@% %@NL@% %@CR:MCV9400B@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >.%@NL@% MINDAT = 1.0E6%@NL@% >%@NL@% %@NL@% %@CR:MCV9400C@%%@4@%The example above illustrates how to display the current source line in%@EH@% sequential mode. The same command in window mode would not produce any output, but it could change the text that is shown in the display window.%@NL@% %@NL@% %@NL@% %@CR:MCV95000@%%@2@%%@AB@%9.5 Stack Trace Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV95001@%%@4@%The Stack Trace command allows you to display routines that have been called%@EH@% during program execution (see note below). The first line of the display shows the name of the current routine. The succeeding lines (if any) list any other routines that were called to reach the current address. The dialog version of the Stack Trace command also displays the source lines where each routine was called.%@NL@% %@NL@% %@CR:MCV95002@%%@4@%For each routine, the values of any arguments are shown in parentheses after%@EH@% the routine name. Values are shown in the current radix (the default is decimal).%@NL@% %@NL@% %@CR:MCV95003@%%@4@%The term "stack trace" is used because as each routine is called, its%@EH@% address and arguments are stored on (pushed onto) the program stack. Therefore, tracing through the stack shows the currently active routines. With C and FORTRAN programs, the %@AB@%main%@AE@% routine will always be at the bottom of the stack. With BASIC programs, the main program is not listed on the stack because BASIC programs have no standard label (such as %@AB@%main%@AE@%) corresponding to the first line of a program. Only routines called by the main program will be displayed. In assembly-language programs, the bottom routine displayed in the stack trace is %@AB@%astart%@AE@% instead of %@AB@%main%@AE@%.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% This discussion uses the term "routines," which is a general term for%@NL@% functions (C, FORTRAN, Pascal), subroutines (FORTRAN), procedures%@NL@% (Pascal), and subprograms and function procedures (BASIC)──each of which%@NL@% uses the stack to transfer control to an independent program unit. In%@NL@% assembly mode, the term "procedure" may be more accurate. %@AB@%GOSUB%@AE@% and %@AB@%DEF%@AE@%%@NL@% %@AB@%FN%@AE@% routines in BASIC will not work with the Stack Trace command, since%@NL@% they do not follow the same convention for setting up the stack.%@NL@% If you are using the CodeView debugger to debug assembly-language%@NL@% programs, the Stack Trace command will work only if procedures were%@NL@% called with the calling convention used by Microsoft languages. This%@NL@% calling convention is explained in the Microsoft Mixed-Language%@NL@% Programming Guide.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCV95004@%%@4@%The Stack Trace command does not work reliably until you execute at least to%@EH@% the beginning of the main procedure. The main procedure sets up the frame pointer (%@AB@%BP%@AE@%), which CodeView uses to locate parameters, local variables, and return addresses. If your main module is written in assembly, you must execute at least to the beginning of the first procedure called. Furthermore, your procedures must follow the standard Microsoft calling conventions.%@NL@% %@NL@% %@CR:MCV95005@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV95006@%%@4@%To view a stack trace with the mouse, point to Calls on the menu bar and%@EH@% press a mouse button. The Calls menu will appear, showing the current routine at the top and other routines below it in the reverse order in which they were called; for example, the first routine called (which is always %@AB@%main%@AE@% in a C or FORTRAN program) will be at the bottom. The values of any routine arguments will be shown in parentheses following the routines.%@NL@% %@NL@% %@CR:MCV95007@%%@4@%If you want to view one of the routines that was previously called, select%@EH@% the routine by dragging down the highlight to the routine you wish to see, then releasing the mouse button. (You can also select a routine by clicking a selection once the menu is open.) The effect of selecting a routine in the Calls menu is to cause the debugger to display that routine. The cursor will be on the last statement executed in the routine.%@NL@% %@NL@% %@CR:MCV95008@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV95009@%%@4@%To view a stack trace with a keyboard command, press ALT+C to open the Calls%@EH@% menu. The menu will show the current routine at the top and other routines below it in the reverse order in which they were called; for example, the first routine called will be at the bottom. The values of any routine arguments will be shown in parentheses following the routine.%@NL@% %@NL@% %@CR:MCV9500A@%%@4@%If you want to view one of the routines that was previously called, select%@EH@% the routine by moving the cursor with the arrow keys and then pressing ENTER, or by typing the number or letter to the left of the routine. The effect of selecting a routine in the Calls menu is to cause the debugger to display that routine. The cursor will be on the last statement that was executed in the routine.%@NL@% %@NL@% %@CR:MCV9500B@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCV9500C@%%@4@%To display a stack trace with a dialog command, enter a command line with%@EH@% the following syntax:%@NL@% %@NL@% %@AB@%K%@AE@%%@NL@% %@NL@% %@CR:MCV9500D@%%@4@%The output from the Stack Trace dialog command lists the routines in the%@EH@% reverse order in which they were called. The arguments to each routine are shown in parentheses. Finally, the line number from which the routine was called is shown.%@NL@% %@NL@% %@CR:MCV9500E@%%@4@%You can enter the line number as an argument to the View or Unassemble%@EH@% command if you want to view code at the point where the routine was called.%@NL@% %@NL@% %@CR:MCV9500F@%%@4@%In window mode, the output from the Stack Trace dialog command appears in%@EH@% the dialog window.%@NL@% %@NL@% %@CR:MCV9500G@%%@4@%%@AB@%FORTRAN Example%@AE@%%@EH@%%@NL@% %@NL@% >K%@NL@% ANALYZE(67,0), line 94%@NL@% COUNTWORDS(0,512), line 73%@NL@% MAIN(2,5098), line 42%@NL@% >%@NL@% %@NL@% %@CR:MCV9500H@%%@4@%In the example above, the first line of output indicates that the current%@EH@% routine is %@AS@%ANALYZE%@AE@%. Its first argument currently has a decimal value of %@AS@%67%@AE@%, and its second argument, a value of %@AS@%0%@AE@%. The current location in this routine is %@AS@%line 94%@AE@%.%@NL@% %@NL@% %@CR:MCV9500I@%%@4@%The second line indicates that %@AS@%ANALYZE%@AE@% was called by %@AS@%COUNTWORDS%@AE@%, and that%@EH@% its arguments have the values %@AS@%0%@AE@% and %@AS@%512%@AE@%. Routine %@AS@%ANALYZE%@AE@% was called from %@AS@%line 73%@AE@% of routine %@AS@%COUNTWORDS%@AE@%.%@NL@% %@NL@% %@CR:MCV9500J@%%@4@%Likewise, %@AS@%COUNTWORDS%@AE@% was called from %@AS@%line 42%@AE@% of %@AS@%MAIN%@AE@%, and its arguments%@EH@% have the values %@AS@%2%@AE@% and %@AS@%5098%@AE@%.%@NL@% %@NL@% %@CR:MCV9500K@%%@4@%If the radix had been set to 16 or 8 using the Radix (%@AB@%N%@AE@%) command, the%@EH@% arguments would be shown in that radix. For example, the last line would be shown as %@AS@%MAIN( 2%@AE@%,%@AS@%13ea )%@AE@% in hexadecimal or %@AS@%MAIN( 2%@AE@%,%@AS@%11752 )%@AE@% in octal.%@NL@% %@NL@% %@CR:MCV9500L@%%@4@%%@AB@%C Example%@AE@%%@EH@%%@NL@% %@NL@% >K%@NL@% analyze(67,0), line 94%@NL@% countwords(0,512), line 73%@NL@% main(2,5098)%@NL@% >%@NL@% %@NL@% %@CR:MCV9500M@%%@4@%As with the FORTRAN example, the example above shows the routines on the%@EH@% stack in the reverse order in which they were called. Since %@AS@%analyze%@AE@% is on the top, it has been called most recently; in other words, it is the current routine.%@NL@% %@NL@% %@CR:MCV9500N@%%@4@%Each routine is shown with the arguments it was passed, along with the last%@EH@% source line that it had been executing. Note that %@AS@%main%@AE@% is shown with the command line arguments %@AS@%argc%@AE@% (which is equal to 2) and %@AS@%argv%@AE@% (which is a pointer equal to 5,098 decimal). Since the language is C, %@AS@%main%@AE@% will always be on the bottom of the stack.%@NL@% %@NL@% %@CR:MCV9500O@%%@4@%%@AB@%BASIC Example%@AE@%%@EH@%%@NL@% %@NL@% >K%@NL@% ROLL#(19122:6040)%@NL@% MAKE#(19122:6040)%@NL@% CALC(19122:5982, 19122:5990)%@NL@% >%@NL@% %@NL@% %@CR:MCV9500P@%%@4@%As with the FORTRAN example, the example above shows the routines on the%@EH@% stack in the reverse order in which they were called. Since %@AS@%ROLL#%@AE@% is on the top, it has been called most recently; in other words, it is the current routine.%@NL@% %@NL@% %@CR:MCV9500Q@%%@4@%Each routine is displayed along with the arguments by which it was passed.%@EH@% In BASIC, arguments passed to routines are always addresses.%@NL@% %@NL@% %@CR:MCV9500R@%%@4@%This example shows some features peculiar to BASIC. First of all, there is%@EH@% no %@AS@%MAIN%@AE@% displayed because the BASIC compiler does not produce any such symbol. Furthermore, each routine will have a type tag if it is a function; the tag indicates what the function returns. %@AS@%ROLL#%@AE@% and %@AS@%MAKE#%@AE@% are both functions returning a double-precision floating point. A function that returned a short integer would have a %@AB@%%%@AE@% type tag. %@AS@%CALC%@AE@% has no type tag since it is a sub-program, and therefore does not return a value of any type.%@NL@% %@NL@% %@NL@% %@CR:MCVA0000@%%@1@%%@AB@%Chapter 10 Modifying Code or Data%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVA0001@%%@4@%The CodeView debugger provides the following commands for modifying code or%@EH@% data in memory:%@NL@% %@NL@% %@CR:MCVA0002@%%@AB@%Command Action%@AE@%%@NL@% %@NL@% Assemble (%@AB@%A%@AE@%) Modifies code%@NL@% %@NL@% Enter (%@AB@%E%@AE@%) Modifies memory, usually data%@NL@% %@NL@% Register (%@AB@%R%@AE@%) Modifies registers and flags%@NL@% %@NL@% Fill Memory (%@AB@%F%@AE@%) Fills a block of memory%@NL@% %@NL@% Move Memory (%@AB@%M%@AE@%) Copies one block of memory to another%@NL@% %@NL@% Port Output (%@AB@%O%@AE@%) Outputs a byte to a hardware port%@NL@% %@NL@% %@CR:MCVA0003@%%@4@%These commands change code temporarily. You can use the alterations for%@EH@% testing in the CodeView debugger, but you cannot save them or permanently change the program. To make permanent changes, you must modify the source code and recompile.%@NL@% %@NL@% %@NL@% %@CR:MCVA1000@%%@2@%%@AB@%10.1 Assemble Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA1001@%%@4@%The Assemble command assembles 8086-family (8086, 8087, 8088, 80186, 80286,%@EH@% 80287, and 80286 and 80386 unprotected) instruction mnemonics and places the resulting instruction code into memory at a specified address. The only 8086-family mnemonics that cannot be assembled are 80286 protected-mode mnemonics. In addition, the debugger will also assemble 80286 instructions that utilize the expanded 386 registers.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The effects of the Assemble command are temporary. Any instructions that%@NL@% you assemble are lost as soon as you exit the program.%@NL@% %@NL@% The instructions you assemble are also lost when you restart the program%@NL@% with the Start or Restart command because the original code is reloaded%@NL@% on top of memory you may have altered.%@NL@% %@NL@% To test the results of an Assemble command, you may need to manipulate%@NL@% the %@AB@%IP%@AE@% register (and possibly the %@AB@%CS%@AE@% register) to the starting address%@NL@% of the instructions you have assembled. If you do this, you must use the%@NL@% Current Line command (%@AB@%.%@AE@%) to reset the debugger's internal variables so%@NL@% that it will trace properly.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVA1002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA1003@%%@4@%The Assemble command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCVA1004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA1005@%%@4@%The Assemble command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCVA1006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA1007@%%@4@%To assemble code using a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%A%@AE@% «%@AI@%address%@AE@%»%@NL@% %@NL@% %@CR:MCVA1008@%%@4@%If %@AI@%address%@AE@% is specified, the assembly starts at that address; otherwise the%@EH@% current assembly address is assumed.%@NL@% %@NL@% %@CR:MCVA1009@%%@4@%The assembly address is normally the current address (the address pointed to%@EH@% by the CS and IP registers). However, when you use the Assemble command, the assembly address is set to the address immediately following the last assembled instruction. When you enter any command that executes code (Trace, Program Step, Go, or Execute), the assembly address is reset to the current address.%@NL@% %@NL@% %@CR:MCVA100A@%%@4@%When you type the Assemble command, the assembly address is displayed. The%@EH@% CodeView debugger then waits for you to enter a new instruction in the standard 8086-family instruction-mnemonic form. You can enter instructions in uppercase, lowercase, or both.%@NL@% %@NL@% %@CR:MCVA100B@%%@4@%To assemble a new instruction, type the desired mnemonic and press ENTER.%@EH@% The CodeView debugger assembles the instruction into memory and displays the next available address. Continue entering new instructions until you have assembled all the instructions you want. To conclude assembly and return to the CodeView prompt, press ENTER only.%@NL@% %@NL@% %@CR:MCVA100C@%%@4@%If an instruction you enter contains a syntax error, the debugger displays%@EH@% the message %@AS@%^ Syntax error%@AE@%, redisplays the current assembly address, and waits for you to enter a correct instruction. The caret symbol in the message will point to the first character the CodeView debugger could not interpret.%@NL@% %@NL@% %@CR:MCVA100D@%%@4@%The following eight principles govern entry of instruction mnemonics:%@EH@%%@NL@% %@NL@% %@CR:MCVA100E@% 1. The far-return mnemonic is %@AB@%RETF%@AE@%.%@NL@% %@NL@% 2. String mnemonics must explicitly state the string size. For example,%@NL@% %@AB@%MOVSW%@AE@% must be used to move word strings, and %@AB@%MOVSB%@AE@% must be used to move%@NL@% byte strings.%@NL@% %@NL@% 3. The CodeView debugger automatically assembles short, near, or far jumps%@NL@% and calls, depending on byte displacement to the destination address.%@NL@% These may be overridden with the %@AB@%NEAR%@AE@% or %@AB@%FAR%@AE@% prefix, as shown in the%@NL@% following examples:%@NL@% %@NL@% %@AS@%JMP 0x502%@AE@%%@NL@% %@AS@%JMP NEAR 0x505%@AE@%%@NL@% %@AS@%JMP FAR 0x50A%@AE@%%@NL@% %@NL@% The %@AB@%NEAR%@AE@% prefix can be abbreviated to %@AB@%NE%@AE@%, but the %@AB@%FAR%@AE@% prefix cannot be%@NL@% abbreviated. The examples above use the C notation for hexadecimal%@NL@% numbers. If the FORTRAN option were selected, you would enter the%@NL@% operands as %@AS@%#502%@AE@%, %@AS@%#505%@AE@%, and %@AS@%#50A%@AE@%; if the BASIC option were selected,%@NL@% you would enter them as %@AS@%&H502%@AE@% , %@AS@%&H505%@AE@%, and %@AS@%&H50A%@AE@%.%@NL@% %@NL@% 4. The CodeView debugger cannot determine whether some operands refer to a%@NL@% word memory location or to a byte memory location. In these cases, the%@NL@% data type must be explicitly stated with the prefix %@AB@%WORD%@AE@%%@AB@%PTR%@AE@% or %@AB@%BYTE%@AE@%%@NL@% %@AB@%PTR%@AE@%. Acceptable abbreviations are %@AB@%WO%@AE@% and %@AB@%BY%@AE@%. Examples are shown below:%@NL@% %@NL@% %@AS@%MOV WORD PTR [BP],1%@AE@%%@NL@% %@AS@%MOV BYTE PTR [SI-1],symbol%@AE@%%@NL@% %@AS@%MOV WO PTR [BP],1%@AE@%%@NL@% %@AS@%MOV BY PTR [SI-1],symbol%@AE@%%@NL@% %@NL@% 5. The CodeView debugger cannot determine whether an operand refers to a%@NL@% memory location or to an immediate operand. The debugger uses the%@NL@% convention that operands enclosed in square brackets refer to memory.%@NL@% Two examples are shown below:%@NL@% %@NL@% %@AS@%MOV AX,#21%@AE@%%@NL@% %@AS@%MOV AX,[#21]%@AE@%%@NL@% %@NL@% The first statement moves %@AS@%21%@AE@% hexadecimal into %@AS@%AX%@AE@%. The second statement%@NL@% moves the data at offset %@AS@%21%@AE@% hexadecimal into %@AS@%AX%@AE@%. Both statements use%@NL@% the FORTRAN notation for the hexadecimal number 21. If the C option%@NL@% were selected, this number would be represented as %@AS@%0x21%@AE@%, and if the%@NL@% BASIC option were selected, the number would be represented as %@AS@%&H21%@AE@%.%@NL@% %@NL@% 6. The CodeView debugger supports all forms of indirect register%@NL@% instructions, as shown in the following examples:%@NL@% %@NL@% %@AS@%ADD BX,[BP+2].[SI-1]%@AE@%%@NL@% %@AS@%POP [BP+DI]%@AE@%%@NL@% %@AS@%PUSH [SI]%@AE@%%@NL@% %@NL@% 7. All instruction-name synonyms are supported. If you assemble%@NL@% instructions and then examine them with the Unassemble command (%@AB@%U%@AE@%), the%@NL@% CodeView debugger may show synonymous instructions, rather than the%@NL@% ones you assembled, as shown in the following examples:%@NL@% %@NL@% %@AS@%LOOPZ &H100%@AE@%%@NL@% %@AS@%LOOPE &H100%@AE@%%@NL@% %@AS@%JA &H200%@AE@%%@NL@% %@AS@%JNBE &H200%@AE@%%@NL@% %@NL@% The examples above use the BASIC hexadecimal notation. Instead of using%@NL@% the %@AS@%&H%@AE@% prefix, you would use %@AS@%0x%@AE@% with the C option selected, and %@AS@%#%@AE@% with%@NL@% the FORTRAN option selected.%@NL@% %@NL@% 8. Do not assemble and execute 8087 or 80287 instructions if your system%@NL@% is not equipped with one of these math coprocessor chips. If you try to%@NL@% execute the %@AB@%WAIT%@AE@% instruction without the appropriate chip, for example,%@NL@% your system will crash.%@NL@% %@NL@% %@CR:MCVA100F@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >U #40 L 1%@NL@% 39B0:0040 89C3 MOV BX,AX%@NL@% >A #40%@NL@% 39B?0:0040 MOV CX,AX%@NL@% 39B0:0042%@NL@% >U #40 L 1%@NL@% 39B0:0040 89C1 MOV CX,AX%@NL@% >%@AS@%%@NL@% %@NL@% %@CR:MCVA100G@%%@4@%The example above (in FORTRAN notation) modifies the instruction at address%@EH@% %@AS@%40%@AE@% hexadecimal so that it moves data into the %@AS@%CX%@AE@% register instead of the %@AS@%BX%@AE@% register (%@AS@%40%@AE@% hexadecimal is notated as %@AS@%0x40%@AE@% in C, and as %@AS@%&H40%@AE@% in BASIC). The Unassemble command (%@AB@%U%@AE@%) is used to show the instruction before and after the assembly.%@NL@% %@NL@% %@CR:MCVA100H@%%@4@%You can modify a portion of code for testing, as in the example, but you%@EH@% cannot save the modified program. You must modify your source code and recompile.%@NL@% %@NL@% %@NL@% %@CR:MCVA2000@%%@2@%%@AB@%10.2 Enter Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2001@%%@4@%The CodeView debugger has several commands for entering data to memory. You%@EH@% can use these commands to modify either code or data, though code can usually be modified more easily with the Assemble command (%@AB@%A%@AE@%). The Enter commands are listed below:%@NL@% %@NL@% %@CR:MCVA2002@%%@AB@%Command Command Name%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%E%@AE@% Enter (size is the default type)%@NL@% %@NL@% %@AB@%EB%@AE@% Enter Bytes%@NL@% %@NL@% %@AB@%EA%@AE@% Enter ASCII%@NL@% %@NL@% %@AB@%EI%@AE@% Enter Integers%@NL@% %@NL@% %@AB@%EU%@AE@% Enter Unsigned Integers%@NL@% %@NL@% %@AB@%EW%@AE@% Enter Words%@NL@% %@NL@% %@AB@%ED%@AE@% Enter Double Words%@NL@% %@NL@% %@AB@%ES%@AE@% Enter Short Reals%@NL@% %@NL@% %@AB@%EL%@AE@% Enter Long Reals%@NL@% %@NL@% %@AB@%ET%@AE@% Enter 10-Byte Reals%@NL@% %@NL@% %@CR:MCVA2003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2004@%%@4@%The Enter commands cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCVA2005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2006@%%@4@%The Enter commands cannot be executed with keyboard commands.%@EH@%%@NL@% %@NL@% %@CR:MCVA2007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2008@%%@4@%To enter data (or code) to memory with a dialog command, enter a command%@EH@% line with the following syntax:%@NL@% %@NL@% %@AB@%E%@AE@%«%@AI@%type%@AE@%» %@AI@%address%@AE@% «%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2009@%%@4@%The %@AI@%type%@AE@% is a one-letter specifier that indicates the type of the data to be%@EH@% entered. The %@AI@%address%@AE@% indicates where the data will be entered. If no segment is given in the address, the data segment (DS) is assumed.%@NL@% %@NL@% %@CR:MCVA200A@%%@4@%The %@AI@%list%@AE@% can consist of one or more expressions that evaluate to data of the%@EH@% size specified by %@AI@%type%@AE@% (the expressions in the list are separated by spaces). This data will be entered to memory at %@AI@%address%@AE@%. If one of the values in the list is invalid, an error message will be displayed. The values preceding the error are entered; values at and following the error are not entered.%@NL@% %@NL@% %@CR:MCVA200B@%%@4@%The expressions in the list are evaluated in the current radix, regardless%@EH@% of the size and type of data being entered. For example, if the radix is 10 and you give the value 10 in a list with the Enter Words command, the decimal value 10 will be entered even though word values are normally entered in hexadecimal. This means that the Enter Words, Enter Integers, and Enter Unsigned Integers commands are identical when used with the list method since two-byte data are being entered for each command.%@NL@% %@NL@% %@CR:MCVA200C@%%@4@%If %@AI@%list%@AE@% is not given, the CodeView debugger will prompt for values to be%@EH@% entered to memory. Values entered in response to prompts are accepted in hexadecimal for the Enter Bytes, Enter ASCII, Enter Words, and Enter Double Words commands. The Enter Integers command accepts signed decimal integers, while the Enter Unsigned Integers command accepts unsigned decimal integers. The Enter Short Reals, Enter Long Reals, and Enter 10-Byte Reals commands accept decimal floating-point values.%@NL@% %@NL@% %@CR:MCVA200D@%%@4@%With the prompting method of data entry, the CodeView debugger prompts for a%@EH@% new value at %@AI@%address%@AE@% by displaying the address and its current value. As explained below, you can then replace the value, skip to the next value, return to a previous value, or exit the command.%@NL@% %@NL@% %@CR:MCVA200E@% 1. To replace the value, type the new value after the current value.%@NL@% %@NL@% 2. To skip to the next value, press the SPACEBAR. Once you have skipped to%@NL@% the next value, you can change its value or skip to the following%@NL@% value. If you pass the end of the display, the CodeView debugger%@NL@% displays a new address to start a new display line.%@NL@% %@NL@% 3. To return to the preceding value, type a backslash (%@AB@%\%@AE@%). When you return%@NL@% to the preceding value, the debugger starts a new display line with the%@NL@% address and value.%@NL@% %@NL@% 4. To stop entering values and return to the CodeView prompt, press ENTER.%@NL@% You can exit the command at any time.%@NL@% %@NL@% %@CR:MCVA200F@%%@4@%Sections 10.2.1%@BO: 707ab@%-10.2.10 discuss the Enter commands in order of the size of%@EH@% data they accept.%@NL@% %@NL@% %@CR:MCVA200G@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >EW PLACE 16 32%@NL@% %@NL@% %@CR:MCVA200H@%%@4@%The example above shows how to enter two word-sized values at the %@AS@%PLACE%@AE@%%@EH@% address.%@NL@% %@NL@% >EW PLACE%@NL@% %@NL@% 3DA5:0B20 00F3.%@AH@% %@AE@%%@NL@% %@NL@% %@CR:MCVA200I@%%@4@%The example above illustrates the prompting method of entering data. When%@EH@% you supply the address where you want to enter data but supply no data, the CodeView debugger displays the current value of the address and waits for you to enter a new value. The reverse-video space (%@AH@% %@AE@%) in this example and the examples below represents the CodeView cursor. You change the value %@AS@%F3%@AE@% to the new value 16 (10 hexadecimal) by typing %@AS@%10%@AE@% (without pressing ENTER yet). The value must be typed in hexadecimal for the Enter Words command, as shown below:%@NL@% %@NL@% >EW PLACE%@NL@% %@NL@% 3DA5:0B20 00F3.10%@AH@% %@AE@%%@NL@% %@NL@% %@CR:MCVA200J@%%@4@%You can then skip to the next value by pressing the SPACEBAR. The CodeView%@EH@% debugger responds by displaying the next value, as shown below:%@NL@% %@NL@% >EW PLACE%@NL@% %@NL@% 3DA5:0B20 00F3.10 4F20.%@AH@% %@AE@%%@AS@%%@NL@% %@NL@% %@CR:MCVA200K@%%@4@%You can then type another hexadecimal value, such as %@AS@%30%@AE@%:%@EH@%%@NL@% %@NL@% >EW PLACE%@NL@% %@NL@% 3DA5:0B20 00F3.10 4F20.30%@AH@% %@AE@%%@AS@%%@NL@% %@NL@% %@CR:MCVA200L@%%@4@%To move to the next value, press the SPACEBAR.%@EH@%%@NL@% %@NL@% >EW PLACE%@NL@% %@NL@% 3DA5:0B20 00F3.10 4F20.30 3DC1.%@AH@% %@AE@%%@AS@%%@NL@% %@NL@% %@CR:MCVA200M@%%@4@%Assume you realize that the last value entered, %@AS@%30%@AE@%, is incorrect. You really%@EH@% wanted to enter %@AS@%20%@AE@%. You could return to the previous value by typing a backslash. The CodeView debugger starts a new line, starting with the previous value. Note that the backslash is not echoed on the screen:%@NL@% %@NL@% >EW PLACE%@NL@% %@NL@% 3DA5:0B20 00F3.10 4F20.30 3DC1.%@NL@% 3DA5:0B22 0030.%@AH@% %@AE@%%@AS@%%@NL@% %@NL@% %@CR:MCVA200N@%%@4@%Type the correct value, %@AS@%20%@AE@%:%@EH@%%@NL@% %@NL@% >EW PLACE%@NL@% %@NL@% 3DA5:0B20 00F3.10 4F20.30 3DC1.%@NL@% 3DA5:0B22 0030.20%@AH@% %@AE@%%@AS@%%@NL@% %@NL@% %@CR:MCVA200O@%%@4@%If this is the last value you want to enter, press ENTER to stop. The%@EH@% CodeView prompt reappears, as shown below:%@NL@% %@NL@% >EW PLACE%@NL@% %@NL@% 3DA5:0B20 00F3.10 4F20.30 3DC1.%@NL@% 3DA5:0B22 0030.20%@NL@% >%@AH@% %@AE@%%@AS@%%@NL@% %@NL@% %@NL@% %@CR:MCVA2100@%%@3@%%@AB@%10.2.1 Enter Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2101@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%E%@AE@% %@AI@%address%@AE@%«%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2102@%%@4@%The Enter command enters one or more values into memory at the specified%@EH@% %@AI@%address%@AE@%. The data are entered in the format of the default type, which is the last type specified with a Dump, Enter, Watch Memory, or Tracepoint Memory command. If none of these commands has been entered during the session, the default type is bytes.%@NL@% %@NL@% %@CR:MCVA2103@%%@4@%Use this command with caution when entering values in the list format;%@EH@% values will be truncated if you enter a word-sized value when the default type is actually bytes. If you are not sure of the current default type, specify the size in the command.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The Execute command and the Enter command have the same command letter%@NL@% (%@AB@%E%@AE@%). The difference is that the Execute command never takes an argument;%@NL@% the Enter command always requires at least one argument.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVA2200@%%@3@%%@AB@%10.2.2 Enter Bytes Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2201@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%EB%@AE@% %@AI@%address%@AE@%«%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2202@%%@4@%The Enter Bytes command enters one or more byte values into memory at%@EH@% %@AI@%address%@AE@%. The optional %@AI@%list%@AE@% can be entered as a list of expressions separated by spaces. The expressions are evaluated and entered in the current radix. If %@AI@%list%@AE@% is not given, the CodeView debugger prompts for new values that must be entered in hexadecimal.%@NL@% %@NL@% %@CR:MCVA2203@%%@4@%The Enter Bytes command can also be used to enter strings, as described in%@EH@% Section 10.2.3%@BO: 7124c@%, "Enter ASCII Command."%@NL@% %@NL@% %@CR:MCVA2204@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >EB 256 10 20 30%@NL@% >%@NL@% %@NL@% %@CR:MCVA2205@%%@4@%If the current radix is 10, the above example replaces the three bytes at%@EH@% DS:256, DS:257, and DS:258 with the decimal values %@AS@%10%@AE@%, %@AS@%20%@AE@%, and %@AS@%30%@AE@%. (These three bytes correspond to the hexadecimal addresses DS:0100, DS:0101, and DS:0102.)%@NL@% %@NL@% >EB 256%@NL@% %@NL@% 3DA5:0100 130F.A%@NL@% >%@AS@%%@NL@% %@NL@% %@CR:MCVA2206@%%@4@%The example above replaces the byte at DS:256 (DS:0100 hexadecimal) with 10%@EH@% (0A hexadecimal).%@NL@% %@NL@% %@NL@% %@CR:MCVA2300@%%@3@%%@AB@%10.2.3 Enter ASCII Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2301@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%EA%@AE@% %@AI@%address%@AE@%«%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2302@%%@4@%The Enter ASCII command works in the same way as the Enter Bytes command%@EH@% (%@AB@%EB%@AE@%) described in Section 10.2.2%@BO: 70cc7@% above. The %@AI@%list%@AE@% version of this command can be used to enter a string expression.%@NL@% %@NL@% %@CR:MCVA2303@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >EA message "File cannot be found"%@NL@% >%@NL@% %@NL@% %@CR:MCVA2304@%%@4@%In the example above, the string %@AS@%File cannot be found%@AE@% is entered starting at%@EH@% the symbolic address %@AS@%message%@AE@%. (Note that the double quotation marks are CodeView string delimiters.)%@NL@% %@NL@% %@CR:MCVA2305@%%@4@%You can also use the Enter Bytes command to enter a string expression, or%@EH@% you can enter nonstring values using the Enter ASCII command.%@NL@% %@NL@% %@NL@% %@CR:MCVA2400@%%@3@%%@AB@%10.2.4 Enter Integers Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2401@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%EI%@AE@% %@AI@%address%@AE@%«%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2402@%%@4@%The Enter Integers command enters one or more word values into memory at%@EH@% %@AI@%address%@AE@% using the signed-integers format. With the CodeView debugger, a signed integer can be any decimal integer between -32,768 and 32,767.%@NL@% %@NL@% %@CR:MCVA2403@%%@4@%The optional %@AI@%list%@AE@% can be entered as a list of expressions separated by%@EH@% spaces. The expressions are entered and evaluated in the current radix. If %@AI@%list%@AE@% is not given, the CodeView debugger prompts for new values that must be entered in decimal.%@NL@% %@NL@% %@CR:MCVA2404@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >EI 256 -10 10 -20%@NL@% >%@NL@% %@NL@% %@CR:MCVA2405@%%@4@%If the current radix is 10, the example above replaces the three integers at%@EH@% DS:256, DS:258, and DS:260 with the decimal values %@AS@%-10%@AE@%, 10, and %@AS@%-20%@AE@%. (The three addresses correspond to the three hexadecimal addresses DS:0100, DS:0102, and DS:0104.)%@NL@% %@NL@% >EI 256%@NL@% %@NL@% 3DA5:0100 130F.-10%@NL@% >%@NL@% %@NL@% %@CR:MCVA2406@%%@4@%The example above replaces the integer at DS:256 (hexadecimal address%@EH@% DS:0100) with %@AS@%-10%@AE@%.%@AS@%%@NL@% %@NL@% %@NL@% %@CR:MCVA2500@%%@3@%%@AB@%10.2.5 Enter Unsigned Integers Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2501@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%EU%@AE@% %@AI@%address%@AE@%«%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2502@%%@4@%The Enter Unsigned Integers command enters one or more word values into%@EH@% memory at %@AI@%address%@AE@% using the unsigned-integers format. With the CodeView debugger, an unsigned integer can be any decimal integer between 0 and 65,535. The optional %@AI@%list%@AE@% can be entered as a list of expressions separated by spaces. The expressions are entered and evaluated in the current radix. If %@AI@%list%@AE@% is not given, the CodeView debugger prompts for new values that must be entered in decimal.%@NL@% %@NL@% %@CR:MCVA2503@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >EU 256 10 20 30%@NL@% >%@NL@% %@NL@% %@CR:MCVA2504@%%@4@%If the current radix is 10, the example above replaces the three unsigned%@EH@% integers at DS:256, DS:258, and DS:260 with the decimal values %@AS@%10%@AE@%, %@AS@%20%@AE@%, and %@AS@%30%@AE@%. (These addresses correspond to the hexadecimal addresses DS:0100, DS:0102, and DS:0104.)%@NL@% %@NL@% >EU 256%@NL@% %@NL@% 3DA5:0100 130F.10%@NL@% >%@NL@% %@NL@% %@CR:MCVA2505@%%@4@%The example above replaces the integer at DS:256 (DS:0100 hexadecimal) with%@EH@% %@AS@%10%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVA2600@%%@3@%%@AB@%10.2.6 Enter Words Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2601@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%EW%@AE@% %@AI@%address%@AE@%«%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2602@%%@4@%The Enter Words command enters one or more word values into memory at%@EH@% %@AI@%address%@AE@%.%@NL@% %@NL@% %@CR:MCVA2603@%%@4@%The optional %@AI@%list%@AE@% can be entered as a list of expressions separated by%@EH@% spaces. The expressions are entered and evaluated in the current radix. If %@AI@%list%@AE@% is not given, CodeView prompts for new values that must be entered in hexadecimal.%@NL@% %@NL@% %@CR:MCVA2604@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >EW 256 10 20 30%@NL@% >%@NL@% %@NL@% %@CR:MCVA2605@%%@4@%If the current radix is 10, the example above replaces the three words at%@EH@% DS:256, DS:258, and DS:260 with the decimal values %@AS@%10%@AE@%, %@AS@%20%@AE@%, and %@AS@%30%@AE@%. (These addresses correspond to the hexadecimal addresses DS:0100, DS:0102, and DS:0104.)%@NL@% %@NL@% >EW 256%@NL@% %@NL@% 3DA5:0100 130F.A%@NL@% >%@NL@% %@NL@% %@CR:MCVA2606@%%@4@%The example above replaces the integer at DS:256 (DS:0100 hexadecimal) with%@EH@% 10 (0A hexadecimal).%@NL@% %@NL@% %@NL@% %@CR:MCVA2700@%%@3@%%@AB@%10.2.7 Enter Double Words Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2701@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ED%@AE@% %@AI@%address%@AE@%«%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2702@%%@4@%The Enter Double Words command enters one or more double-word values into%@EH@% memory at %@AI@%address%@AE@%. Double words are displayed and entered in the address%@NL@% %@NL@% %@CR:MCVA2703@%%@4@%format %@AI@%segment%@AE@%%@AB@%:%@AE@%%@AI@%offset%@AE@%──that is, two words separated by a colon (%@AB@%:%@AE@%). If the%@EH@% colon is omitted and only one word entered, only the offset portion of the address will be changed.%@NL@% %@NL@% %@CR:MCVA2704@%%@4@%The optional %@AI@%list%@AE@% can be entered as a list of expressions separated by%@EH@% spaces. The expressions are entered and evaluated in the current radix. If %@AI@%list%@AE@% is not given, CodeView prompts for new values that must be entered in hexadecimal.%@NL@% %@NL@% %@CR:MCVA2705@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >ED 256 8700:12008%@NL@% >%@NL@% %@NL@% %@CR:MCVA2706@%%@4@%If the current radix is 10, the example above replaces the double words at%@EH@% DS:256 (DS:0100 hexadecimal) with the decimal address %@AS@%8700:12008%@AE@% (hexadecimal address 21FC:2EE8).%@NL@% %@NL@% >ED 256%@NL@% %@NL@% 3DA5:0100 21FC:2EE8.2EE9%@NL@% >%@NL@% %@NL@% %@CR:MCVA2707@%%@4@%The example above replaces the offset portion of the double word at DS:256%@EH@% (DS:0100 hexadecimal) with %@AS@%2EE9%@AE@% hexadecimal. Since the segment portion of the address is not provided, the existing segment (%@AS@%21FC%@AE@% hexadecimal) is unchanged.%@NL@% %@NL@% %@NL@% %@CR:MCVA2800@%%@3@%%@AB@%10.2.8 Enter Short Reals Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2801@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ES%@AE@% %@AI@%address%@AE@%«%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2802@%%@4@%The Enter Short Reals command enters one or more short-real values into%@EH@% memory at %@AI@%address%@AE@%.%@NL@% %@NL@% %@CR:MCVA2803@%%@4@%The optional %@AI@%list%@AE@% can be entered as a list of real numbers separated by%@EH@% spaces. The numbers must be entered in decimal, regardless of the current radix. If %@AI@%list%@AE@% is not given, the CodeView debugger prompts for new values that must be entered in decimal. Short-real numbers can be entered either in floating-point format or in scientific-notation format.%@NL@% %@NL@% %@CR:MCVA2804@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >ES 256 23.479 1/4 -1.65E+4 235%@NL@% >%@NL@% %@NL@% %@CR:MCVA2805@%%@4@%The example above replaces the four numbers at DS:256, DS:260, DS:264, and%@EH@% DS:268 with the real numbers %@AS@%23.479%@AE@%, %@AS@%0.25%@AE@%, %@AS@%-1650.0%@AE@%, and %@AS@%235.0%@AE@%. (These addresses correspond to the hexadecimal addresses DS:0100, DS:0104, DS:0108, and DS:0112.)%@NL@% %@NL@% >ES PI%@NL@% 3DA5:0064 42 79 74 65 7.215589E+022 3.141593%@NL@% >%@NL@% %@NL@% %@CR:MCVA2806@%%@4@%The example above replaces the number at the symbolic address %@AS@%PI%@AE@% with%@EH@% %@AS@%3.141593%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVA2900@%%@3@%%@AB@%10.2.9 Enter Long Reals Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2901@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%EL%@AE@% %@AI@%address%@AE@%«%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2902@%%@4@%The Enter Long Reals command enters one or more long-real values into memory%@EH@% at %@AI@%address%@AE@%.%@NL@% %@NL@% %@CR:MCVA2903@%%@4@%The optional %@AI@%list%@AE@% can be entered as a list of real numbers separated by%@EH@% spaces. The numbers must be entered in decimal, regardless of the current radix. If %@AI@%list%@AE@% is not given, the CodeView debugger prompts for new values that must be entered in decimal. Long-real numbers can be entered either in floating-point format or in scientific-notation format.%@NL@% %@NL@% %@CR:MCVA2904@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >EL 256 23.479 1/4 -1.65E+4 235%@NL@% >%@NL@% %@NL@% %@CR:MCVA2905@%%@4@%The example above replaces the four numbers at DS:256, DS:264, DS:272, and%@EH@% DS:280 with the real numbers %@AS@%23.479%@AE@%, %@AS@%0.25%@AE@%, %@AS@%-1650.0%@AE@%, and %@AS@%235.0%@AE@% . (These addresses correspond to the hexadecimal addresses DS:0100, DS:0108, DS:0110, and DS:0118.)%@NL@% %@NL@% >EL PI%@NL@% 3DA5:0064 42 79 74 65 DC OF 49 40 5.012391E+001 3.141593%@NL@% >%@AS@%%@NL@% %@NL@% %@CR:MCVA2906@%%@4@%The example above replaces the number at the symbolic address %@AS@%PI%@AE@% with%@EH@% %@AS@%3.141593%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVA2A00@%%@3@%%@AB@%10.2.10 Enter 10-Byte Reals Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA2A01@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ET%@AE@% %@AI@%address%@AE@%«%@AI@%list%@AE@%»%@NL@% %@NL@% %@CR:MCVA2A02@%%@4@%The Enter 10-Byte Reals command enters one or more 10-byte-real values into%@EH@% memory at %@AI@%address%@AE@%.%@NL@% %@NL@% %@CR:MCVA2A03@%%@4@%The optional %@AI@%list%@AE@% can be entered as a list of real numbers separated by%@EH@% spaces. The numbers must be entered in decimal, regardless of the current radix. If %@AI@%list%@AE@% is not given, the CodeView debugger prompts for new values that must be entered in decimal. The numbers can be entered either in floating-point format or in scientific-notation format.%@NL@% %@NL@% %@CR:MCVA2A04@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >ET 256 23.479 1/4 -1.65E+4 235%@NL@% >%@NL@% %@NL@% %@CR:MCVA2A05@%%@4@%The example above replaces the four numbers at DS:256, DS:266, DS:276, and%@EH@% DS:286 with the real numbers %@AS@%23.479%@AE@%, %@AS@%0.25%@AE@%, %@AS@%-1650.0%@AE@%, and %@AS@%235.0%@AE@%. (These addresses correspond to the hexadecimal addresses DS:0100, DS:010A, DS:0114, and DS:011E.)%@NL@% %@NL@% %@NL@% >ET PI%@NL@% 3DA5:0064 42 79 74 65 DC 0F 49 40 7F BD -3.292601E-193 3.141593%@NL@% >%@NL@% %@NL@% %@CR:MCVA2A06@%%@4@%The example above replaces the number at the symbolic address %@AS@%PI%@AE@% with%@EH@% %@AS@%3.141593%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVA3000@%%@2@%%@AB@%10.3 Fill Memory Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA3001@%%@4@%The Fill Memory command provides an efficient way of filling up a large or%@EH@% small block of memory with any values you specify. It is primarily of interest to assembly programmers because the command enters values directly into memory. However, you may find it useful for initializing large data areas such as an array or structure.%@NL@% %@NL@% %@CR:MCVA3002@%%@4@%You can enter arguments to the Fill Memory command using any radix.%@EH@%%@NL@% %@NL@% %@CR:MCVA3003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA3004@%%@4@%The Fill Memory command cannot be executed with a mouse.%@EH@%%@NL@% %@NL@% %@CR:MCVA3005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA3006@%%@4@%The Fill Memory command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCVA3007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA3008@%%@4@%To fill an area of memory with values you specify, enter the Fill Memory%@EH@% command as follow:%@NL@% %@NL@% %@AB@%F%@AE@% %@AI@%range%@AE@% %@AI@%list%@AE@%%@NL@% %@NL@% %@CR:MCVA3009@%%@4@%The Fill Memory command fills the addresses in the specified %@AI@%range%@AE@% with the%@EH@% byte values specified in %@AI@%list%@AE@%. The values in the list are repeated until the whole range is filled. (Thus, if you specify only one value, the entire range is filled with that same value.) If the %@AI@%list%@AE@% has more values than the number of bytes in the %@AI@%range%@AE@%, the command ignores any extra values.%@NL@% %@NL@% %@CR:MCVA300A@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >F 100 L 100 0 ;* hexadecimal radix assumed%@NL@% >%@NL@% %@NL@% %@CR:MCVA300B@%%@4@%The first example fills 255 (100 hexadecimal) bytes of memory starting at%@EH@% DS:0100 with the value 0. This command could be used to reinitialize the program's data without having to restart the program.%@NL@% %@NL@% >F table L 64 42 79 74 ;* hexadecimal radix assumed%@NL@% >%@NL@% %@NL@% %@CR:MCVA300C@%%@4@%The second example fills the 100 (64 hexadecimal) bytes starting at %@AS@%table%@AE@%%@EH@% with the following hexadecimal byte values: 42, 79, 74. These three values are repeated until all 100 bytes are filled.%@NL@% %@NL@% %@NL@% %@CR:MCVA4000@%%@2@%%@AB@%10.4 Move Memory Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA4001@%%@4@%The Move Memory command enables you to copy all the values in one block of%@EH@% memory directly to another block of memory of the same size. This command is of most interest to assembly programmers, but it can be used by anyone who wants to do large data transfers. For example, you can use this command to copy all the values in one array to the elements of another.%@NL@% %@NL@% %@CR:MCVA4002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA4003@%%@4@%The Move Memory command cannot be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCVA4004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA4005@%%@4@%The Move Memory command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCVA4006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA4007@%%@4@%To copy the values in one block of memory to another, enter the Move Memory%@EH@% command with the following syntax:%@NL@% %@NL@% %@AB@%M%@AE@% %@AI@%range%@AE@% %@AI@%address%@AE@%%@NL@% %@NL@% %@CR:MCVA4008@%%@4@%The values in the block of memory specified by %@AI@%range%@AE@% are copied to a block%@EH@% of the same size beginning at %@AI@%address%@AE@%. All data in %@AI@%range%@AE@% are guaranteed to be copied completely over to the destination block, even if the two blocks overlap. However, if they do overlap, some of the original data in %@AI@%range%@AE@% will be altered.%@NL@% %@NL@% %@CR:MCVA4009@%%@4@%To prevent loss of data, the Move Memory command copies data starting at the%@EH@% source block's lowest address whenever the source is at a higher address than the destination. If the source is at a lower address, the Move Memory command copies data beginning at the source block's highest address.%@NL@% %@NL@% %@CR:MCVA400A@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >M arr1(1) L arsize arr2(1) ;* FORTRAN example%@NL@% >%@NL@% %@NL@% %@CR:MCVA400B@%%@4@%In the example above, the block of memory beginning with the first element%@EH@% of %@AS@%arr1%@AE@% and %@AS@%arsize%@AE@% bytes long is copied directly to a block of the same size beginning at the address of the first element of %@AS@%arr2%@AE@%. In C, this command would be entered as %@AS@%M arr1[0] L arsize arr2[0]%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVA5000@%%@2@%%@AB@%10.5 Port Output Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA5001@%%@4@%The Port Output command sends specific byte values to hardware ports. It is%@EH@% primarily of use to assembly programmers writing code that interacts directly with hardware.%@NL@% %@NL@% %@CR:MCVA5002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA5003@%%@4@%The Port Output command cannot be executed with a mouse.%@EH@%%@NL@% %@NL@% %@CR:MCVA5004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA5005@%%@4@%The Port Output command cannot be executed with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCVA5006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA5007@%%@4@%To output to a hardware port, enter the Port Output command with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%O%@AE@% %@AI@%port byte%@AE@%%@NL@% %@NL@% %@CR:MCVA5008@%%@4@%The specified %@AI@%byte%@AE@% is sent to the specified %@AI@%port%@AE@% in which %@AI@%port%@AE@% is a 16-bit%@EH@% port address.%@NL@% %@NL@% %@CR:MCVA5009@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >O 2F8 4F %@AI@%;* hexadecimal system radix assumed%@AE@%%@NL@% >%@NL@% %@NL@% %@CR:MCVA500A@%%@4@%The byte value %@AS@%4F%@AE@% hexadecimal is sent to output port %@AS@%2F8%@AE@%.%@EH@%%@NL@% %@NL@% %@CR:MCVA500B@%%@4@%The example above assumes that the system radix is hexadecimal. However (as%@EH@% with all other CodeView commands), you can enter the Port Output command using any radix you prefer. Both the %@AI@%port%@AE@% and %@AI@%byte%@AE@% arguments assume system radix unless you specify a radix override.%@NL@% %@NL@% %@CR:MCVA500C@%%@4@%The Port Output command is often used in conjunction with the Port Input%@EH@% command discussed in Section 6.7%@BO: 546bf@%.%@NL@% %@NL@% %@NL@% %@CR:MCVA6000@%%@2@%%@AB@%10.6 Register Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA6001@%%@4@%The Register command has two functions: it displays the contents of the%@EH@% central processing unit registers and it changes the values of those registers. The modification features of the command are explained in this section. The display features of the Register command are explained in Section 6.8.%@BO: 54cca@%%@NL@% %@NL@% %@CR:MCVA6002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA6003@%%@4@%The only register that can be changed with the mouse is the flags register.%@EH@% The register's individual bits (called flags) can be set or cleared. To change a flag, first make sure the register window is open. The window can be opened by selecting Registers from the Options menu or by pressing F2.%@NL@% %@NL@% %@CR:MCVA6004@%%@4@%The flag values are shown as mnemonics in the bottom of the window. Point to%@EH@% the flag you want to change and click either button. The mnemonic word representing the flag value will change. The mnemonics for each flag are shown in the second and third columns of Table 10.1 below. The color or highlighting of the flag will also be reversed when you change a flag. Set flags are shown in red on color monitors and in high-intensity text on two-color monitors. Cleared flags are shown in light blue on color monitors or normal text on two-color monitors.%@NL@% %@NL@% %@CR:MCVA6005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA6006@%%@4@%The registers cannot be changed with keyboard commands.%@EH@%%@NL@% %@NL@% %@CR:MCVA6007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVA6008@%%@4@%To change the value of a register with a dialog command, enter a command%@EH@% line with the following syntax:%@NL@% %@NL@% %@AB@%R%@AE@% «%@AI@%registername%@AE@%««=»%@AI@%expression%@AE@%»»%@NL@% %@NL@% %@CR:MCVA6009@%%@4@%To modify the value in a register, type the command letter %@AS@%R%@AE@% followed by%@EH@% %@AI@%registername%@AE@%. The CodeView debugger displays the current value of the register and prompts for a new value. Press ENTER if you only want to examine the value. If you want to change it, type an expression for the new value and press ENTER.%@NL@% %@NL@% %@CR:MCVA600A@%%@4@%As an alternative, you can type both %@AI@%registername%@AE@% and %@AI@%expression%@AE@% in the same%@EH@% command. You can use the equal sign (=) between %@AI@%registername%@AE@% and %@AI@%expression%@AE@%, but a space has the same effect.%@NL@% %@NL@% %@CR:MCVA600B@%%@4@%The register name can be any of the following: AX, BX, CX, DX, CS, DS, SS,%@EH@% ES, SP, BP, SI, DI, IP, or F (for flags). If you have a 386-based machine and have turned the 386 option on, the register name can be one of the 32-bit register names shown in table 4.9.%@NL@% %@NL@% %@CR:MCVA600C@%%@4@%To change a flag value, supply the register name F when you enter the%@EH@% Register command. The command displays the value of each flag as a two-letter name.%@NL@% %@NL@% %@CR:MCVA600D@%%@4@%At the end of the list of values, the command displays a dash (-). Enter new%@EH@% values after the dash for the flags you wish to change, then press ENTER. You can enter flag values in any order. Flags for which new values are not entered remain unchanged. If you do not want to change any flags, press ENTER.%@NL@% %@NL@% %@CR:MCVA600E@%%@4@%If you enter an illegal flag name, an error message is displayed. The flags%@EH@% preceding the error are changed; flags at and following the error are not changed.%@NL@% %@NL@% %@CR:MCVA600F@%%@4@%The flag values are shown in Table 10.1.%@EH@%%@NL@% %@NL@% %@CR:MCVAT100@%%@4@%%@AB@%Table 10.1 Flag-Value Mnemonics%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%Flag Name Set Clear%@AE@% Overflow %@AB@%OV NV%@AE@% Direction %@AB@%DN UP%@AE@% Interrupt %@AB@%EI DI%@AE@% Sign %@AB@%NG PL%@AE@% Zero %@AB@%ZR NZ%@AE@% Auxiliary carry %@AB@%AC NA%@AE@% Parity %@AB@%PE PO%@AE@% Carry %@AB@%CY NC%@AE@% %@NL@% %@NL@% %@CR:MCVA600G@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >R IP 256%@NL@% >%@NL@% %@NL@% %@CR:MCVA600H@%%@4@%The example above changes the %@AS@%IP%@AE@% register to the value %@AS@%256%@AE@% (0100%@EH@% hexadecimal).%@NL@% %@NL@% >R AX%@NL@% AX OEOO%@NL@% :%@AH@% %@AE@%%@AS@%%@NL@% %@NL@% %@CR:MCVA600I@%%@4@%The example above displays the current value of the %@AS@%AX%@AE@% register and prompts%@EH@% for a new value (the reverse-video space (%@AH@% %@AE@%) represents the CodeView cursor). You can now type any 16-bit value after the colon.%@NL@% %@NL@% >R AX%@NL@% AX 0E00%@NL@% :256%@NL@% >%@AH@% %@AE@%%@AS@%%@NL@% %@NL@% %@CR:MCVA600J@%%@4@%The example above changes the value of %@AS@%AX%@AE@% to 256 (in the current radix).%@EH@%%@NL@% %@NL@% >R F UP EI PL%@AS@%%@NL@% %@NL@% %@CR:MCVA600K@%%@4@%The example above shows the command-line method of changing flag values.%@EH@%%@NL@% %@NL@% >R F%@NL@% NV(OV) UP(DN) EI(DI) PL(NG) NZ(ZR) AC(NA) PE(PO) NC(CY) -OV DI ZR%@NL@% >R F%@NL@% OV(NV) UP(DN) DI(EI) PL(NG) ZR(NZ) AC(NA) PE(PO) NC(CY) -%@NL@% >%@NL@% %@NL@% %@CR:MCVA600L@%%@4@%With the prompting method of changing flag values (shown above), the first%@EH@% mnemonic for each flag is the current value, and the second mnemonic (in parentheses) is the alternate value. You can enter one or more mnemonics at the dash prompt. In the example, the command is given a second time to show the results of the first command.%@NL@% %@NL@% %@NL@% %@CR:MCVB0000@%%@1@%%@AB@%Chapter 11 CodeView Control Commands%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVB0001@%%@4@%This chapter discusses commands that control the operation of the CodeView%@EH@% debugger. The commands in this category are listed below:%@NL@% %@NL@% %@CR:MCVB0002@%%@AB@%Command Action%@AE@%%@NL@% %@NL@% Help (%@AB@%H%@AE@%) Displays help%@NL@% %@NL@% Quit (%@AB@%Q%@AE@%) Returns to DOS%@NL@% %@NL@% Radix (%@AB@%N%@AE@%) Changes radix%@NL@% %@NL@% Redraw (%@AB@%@%@AE@%) Redraws screen%@NL@% %@NL@% Screen Exchange (%@AB@%\%@AE@%) Switches to output screen%@NL@% %@NL@% Search (%@AB@%/%@AE@%) Searches for regular expression%@NL@% %@NL@% Shell Escape (%@AB@%!%@AE@%) Starts new DOS shell%@NL@% %@NL@% Tab Set (%@AB@%#%@AE@%) Sets tab size%@NL@% %@NL@% Option (%@AB@%O%@AE@%) Views or sets CodeView options%@NL@% %@NL@% Redirection and related Control redirection of CodeView output or input%@NL@% commands %@NL@% %@NL@% %@CR:MCVB1000@%%@2@%%@AB@%11.1 Help Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB1001@%%@4@%CodeView has two help systems: a complete on-line Help system available only%@EH@% in window mode and a syntax summary available with sequential mode.%@NL@% %@NL@% %@CR:MCVB1002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB1003@%%@4@%To enter the complete on-line Help system with the mouse, point to View on%@EH@% the menu bar, press a mouse button and drag the highlight down to a Help selection, then release the button. The appropriate help screen will appear.%@NL@% %@NL@% %@CR:MCVB1004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB1005@%%@4@%If you are in window mode, press F1 to enter the complete on-line Help%@EH@% system. If you are in sequential mode, a syntax-summary screen appears when you press F1.%@NL@% %@NL@% %@CR:MCVB1006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB1007@%%@4@%If you are in window mode, you can view the complete on-line Help system%@EH@% with the following command:%@NL@% %@NL@% %@AB@%H%@AE@%%@NL@% %@NL@% %@CR:MCVB1008@%%@4@%If you are in sequential mode, this command displays a screen containing all%@EH@% CodeView dialog commands with the syntax for each. This screen is the only help available in sequential mode.%@NL@% %@NL@% %@NL@% %@CR:MCVB2000@%%@2@%%@AB@%11.2 Quit Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB2001@%%@4@%The Quit command terminates CodeView and returns control to DOS.%@EH@%%@NL@% %@NL@% %@CR:MCVB2002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB2003@%%@4@%To quit the CodeView debugger with the mouse, point to File on the menu,%@EH@% press a mouse button and drag the highlight down to the Exit selection, then release the button. The CodeView screen is replaced by the DOS screen with the cursor at the DOS prompt.%@NL@% %@NL@% %@CR:MCVB2004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB2005@%%@4@%To quit the CodeView debugger with a keyboard command, press ALT+F to open%@EH@% the File menu, then press X to select Exit. The CodeView screen is replaced by the DOS screen with the cursor at the DOS prompt.%@NL@% %@NL@% %@CR:MCVB2006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB2007@%%@4@%To quit the CodeView debugger with a dialog command, enter a command line%@EH@% with the following syntax:%@NL@% %@NL@% %@AB@%Q%@AE@%%@NL@% %@NL@% %@CR:MCVB2008@%%@4@%When the command is entered, the CodeView screen is replaced by the DOS%@EH@% screen with the cursor at the DOS prompt.%@NL@% %@NL@% %@NL@% %@CR:MCVB3000@%%@2@%%@AB@%11.3 Radix Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB3001@%%@4@%The Radix command changes the current radix for entering arguments and%@EH@% displaying the value of expressions. The default radix when you start the CodeView debugger is 10 (decimal). Radixes 8 (octal) and 16 (hexadecimal) can also be set. Binary and other radixes are not allowed.%@NL@% %@NL@% %@CR:MCVB3002@%%@4@%The following seven conditions are exceptions; they are not affected by the%@EH@% Radix command:%@NL@% %@NL@% %@CR:MCVB3003@% 1. The radix for entering a new radix is always decimal.%@NL@% %@NL@% 2. Format specifiers given with the Display Expression command or any of%@NL@% the Watch Statement commands override the current radix.%@NL@% %@NL@% 3. Addresses output by the Assemble, Dump, Enter, Examine Symbol, and%@NL@% Unassemble commands are always shown in hexadecimal.%@NL@% %@NL@% 4. In assembly mode, all values are shown in hexadecimal.%@NL@% %@NL@% 5. The display radix for Dump, Watch Memory, and Tracepoint Memory%@NL@% commands is always hexadecimal if the size is bytes, words, or double%@NL@% words and always decimal if the size is integers, unsigned integers,%@NL@% short reals, long reals, or 10-byte reals.%@NL@% %@NL@% 6. The input radix for the Enter commands with the prompting method is%@NL@% always hexadecimal if the size is bytes, words, or double words and%@NL@% always decimal if the size is integers, unsigned integers, short reals,%@NL@% long reals, or 10-byte reals. The current radix is used for all values%@NL@% given as part of a list, except real numbers, which must be entered in%@NL@% decimal.%@NL@% %@NL@% 7. The register display is always in hexadecimal.%@NL@% %@NL@% %@CR:MCVB3004@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB3005@%%@4@%You cannot change the input radix with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCVB3006@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB3007@%%@4@%You cannot change the input radix with a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCVB3008@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB3009@%%@4@%To change the input radix with a dialog command, enter a command line with%@EH@% the following syntax:%@NL@% %@NL@% %@AB@%N%@AE@%«%@AI@%radixnumber%@AE@%»%@NL@% %@NL@% %@CR:MCVB300A@%%@4@%The %@AI@%radixnumber%@AE@% can be 8 (octal), 10 (decimal), or 16 (hexadecimal). The%@EH@% default radix when you start the CodeView debugger is 10 (decimal), unless your%@NL@% %@NL@% %@CR:MCVB300B@%%@4@%main program is written with the Microsoft Macro Assembler, in which case%@EH@% the default radix is 16 (hexadecimal). If you give the Radix command with no argument, the debugger displays the current radix.%@NL@% %@NL@% %@CR:MCVB300C@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >N10%@NL@% >N%@NL@% 10%@NL@% >? prime%@NL@% 107%@NL@% >%@NL@% %@NL@% >N8 %@AI@%;* C example%@AE@%%@NL@% >? prime%@NL@% 0153%@NL@% >%@NL@% %@NL@% >N16 %@AI@%;* FORTRAN example%@AE@%%@NL@% >? prime%@NL@% #006b%@NL@% >%@NL@% %@NL@% >N8 %@AI@%;* BASIC example%@AE@%%@NL@% >? prime%@NL@% &O153%@NL@% >%@AS@%%@NL@% %@NL@% %@CR:MCVB300D@%%@4@%The example above shows how %@AS@%107%@AE@% decimal, stored in the variable %@AS@%prime%@AE@%, would%@EH@% be displayed with different radixes. Examples are taken from different languages; there is no logical connection between the radix and the language used in each example.%@NL@% %@NL@% >N8%@NL@% >? 34,i%@NL@% 28%@NL@% >N10%@NL@% >? 28,i%@NL@% 28%@NL@% >N16%@NL@% >? 1C,i%@NL@% 28%@NL@% >%@AS@%%@NL@% %@NL@% %@CR:MCVB300E@%%@4@%In the example above, the same number is entered in different radixes, but%@EH@% the %@AS@%i%@AE@% format specifier is used to display the result as a decimal integer in all three cases. See Chapter 6%@BO: 43f5c@%, "Examining Data and Expressions," for more information on format specifiers.%@NL@% %@NL@% %@NL@% %@CR:MCVB4000@%%@2@%%@AB@%11.4 Redraw Comm and%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB4001@%%@4@%The Redraw command can be used only in window mode; it redraws the CodeView%@EH@% screen. This command is seldom necessary, but you might need it if the output of the program being debugged disturbs the CodeView display temporarily.%@NL@% %@NL@% %@CR:MCVB4002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB4003@%%@4@%You cannot redraw the screen using the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCVB4004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB4005@%%@4@%You cannot redraw the screen using a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCVB4006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB4007@%%@4@%To redraw the screen with a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%@%@AE@%%@NL@% %@NL@% %@NL@% %@CR:MCVB5000@%%@2@%%@AB@%11.5 Screen Exchange Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB5001@%%@4@%The Screen Exchange command allows you to switch temporarily from the%@EH@% debugging screen to the output screen.%@NL@% %@NL@% %@CR:MCVB5002@%%@4@%The CodeView debugger will use either screen flipping or screen swapping to%@EH@% store the output and debugging screens. See Chapter 1%@BO: 9668@%, "Getting Started," for an explanation of flipping and swapping.%@NL@% %@NL@% %@CR:MCVB5003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB5004@%%@4@%To execute the Screen Exchange command with the mouse, open the View menu,%@EH@% then select Output. Press any key when you are ready to return to the debugging screen.%@NL@% %@NL@% %@CR:MCVB5005@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB5006@%%@4@%To execute the Screen Exchange command with a keyboard command, press F4.%@EH@% Press any key when you are ready to return to the debugging screen.%@NL@% %@NL@% %@CR:MCVB5007@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB5008@%%@4@%To execute the Screen Exchange command from the dialog window, enter a%@EH@% command line with the following syntax:%@NL@% %@NL@% %@AB@%\%@AE@%%@NL@% %@NL@% %@CR:MCVB5009@%%@4@%The output screen will then appear. Press any key when you are ready to%@EH@% return to the CodeView debugging screen.%@NL@% %@NL@% %@NL@% %@CR:MCVB6000@%%@2@%%@AB@%11.6 Search Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB6001@%%@4@%The Search command allows you to search for a regular expression in a source%@EH@% file. The expression being sought is specified either in a dialog box or as an argument to a dialog command. Once you have found an expression, you can search for the next or previous occurrence of the expression.%@NL@% %@NL@% %@CR:MCVB6002@%%@4@%Regular expressions are patterns of characters that may match one or many%@EH@% different strings. The use of patterns to match more than one string is similar to the DOS method of using wild-card characters in file names. Regular expressions are explained in detail in Appendix A%@BO: d21a7@%.%@NL@% %@NL@% %@CR:MCVB6003@%%@4@%You can use the Search command without understanding regular expressions.%@EH@% Since text strings are the simplest form of regular expressions, you can enter a string of characters as the expression you want to find. For example, you could enter %@AS@%COUNT%@AE@% if you wanted to search for the word "COUNT" in the source file.%@NL@% %@NL@% %@CR:MCVB6004@%%@4@%The following characters have special meanings in regular expressions:%@EH@% backslash (%@AB@%\%@AE@%), asterisk (%@AB@%*%@AE@%), left bracket (%@AB@%[%@AE@%), period (%@AB@%.%@AE@%), dollar sign (%@AB@%$%@AE@%), and caret (%@AB@%^%@AE@%). To find strings containing these characters, you must precede the characters with a backslash; this cancels their special meanings.%@NL@% %@NL@% %@CR:MCVB6005@%%@4@%For example, you would use %@AS@%\*%@AE@% to find %@AS@%x*y%@AE@%. The periods in the relational%@EH@% operators must also be preceded by a backslash.%@NL@% %@NL@% %@CR:MCVB6006@%%@4@%The Case Sense selection from the Options menu has no effect on searches for%@EH@% regular expressions.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% When you search for the next occurrence of a regular expression, the%@NL@% CodeView debugger searches to the end of the file, then wraps around and%@NL@% begins again at the start of the file. This can have unexpected results%@NL@% if the expression occurs only once. When you give the command repeatedly,%@NL@% nothing seems to happen. Actually, the debugger is repeatedly wrapping%@NL@% around and finding the same expression each time.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVB6007@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB6008@%%@4@%To find a regular expr with the mouse, point to Search on the menu bar,%@EH@% press a mouse button and drag the highlight down to the Find selection, then release the button. A dialog box appears, asking for the regular expression to be found. Type the expression and press either the ENTER key or a mouse button. The CodeView debugger starts searching at the current cursor position and puts the cursor at the next line containing the regular expression. An error message appears if the expression is not found. If you are in assembly mode, the debugger automatically switches to source mode when the expression is found.%@NL@% %@NL@% %@CR:MCVB6009@%%@4@%After you have found a regular expression, you can search for the next or%@EH@% previous occurrence of the expression. Point to Search on the menu bar, press a mouse button and drag the highlight down to the Next or Previous selection, then release the button. The cursor moves to the next or previous match of the expression.%@NL@% %@NL@% %@CR:MCVB600A@%%@4@%You can also search the executable code for a label (such as a routine name%@EH@% or an assembly-language label). Point to Search on the menu bar, press a mouse button and drag the highlight down to the Label selection, then release the button. A dialog box appears, asking for the label to be found. Type the label name, and press either ENTER or a mouse button. The cursor will move to the line containing the label. This selection differs from other search selections because it searches executable code rather than source code. The CodeView debugger switches to assembly mode, if necessary, to display a label in a library routine or assembly-language module.%@NL@% %@NL@% %@CR:MCVB600B@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB600C@%%@4@%To find a regular expression with a keyboard command, press ALT+S to open%@EH@% the Search menu, and then press F to select Find. A dialog box appears, asking for the regular expression to be found. Type the expression and press ENTER. The CodeView debugger starts searching at the current cursor position and puts the cursor at the next line containing the regular expression. An error message appears if the expression is not found. If you are in assembly mode, the debugger automatically switches to source mode when the expression is found.%@NL@% %@NL@% %@CR:MCVB600D@%%@4@%After you have found a regular expression, you can search for the next or%@EH@% previous occurrence of the expression. Press ALT+S to open the Search menu and then press N to select Next or P to select Previous. The cursor will move to the next or previous match of the expression.%@NL@% %@NL@% %@CR:MCVB600E@%%@4@%You can also search the executable code for a label (such as a routine name%@EH@% or an assembly-language label). Press ALT+S to open the Search menu and then press L to select Label. A dialog box appears, asking for the label to be found. Type the label name and press ENTER. The cursor moves to the line containing the label. This selection differs from other search selections because it searches executable code rather than source code. The CodeView debugger switches to assembly mode, if necessary, to display a label in a library routine or assembly-language module.%@NL@% %@NL@% %@CR:MCVB600F@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB600G@%%@4@%To find a regular expression using a dialog command, enter a command line%@EH@% with the following syntax:%@NL@% %@NL@% %@AB@%/%@AE@%«%@AI@%regularexpression%@AE@%»%@NL@% %@NL@% %@CR:MCVB600H@%%@4@%If %@AI@%regularexpression%@AE@% is given, the CodeView debugger searches the source%@EH@% file for the first line containing the expression. If no argument is given, the debugger searches for the next occurrence of the last regular expression specified.%@NL@% %@NL@% %@CR:MCVB600I@%%@4@%In window mode, the CodeView debugger starts searching at the current cursor%@EH@% position and puts the cursor at the next line containing the regular expression. In sequential mode, the debugger starts searching at the last source line displayed. It displays the source line in which the expression is found. An error message appears if the expression is not found. If you are in assembly mode, the CodeView debugger automatically switches to source mode when the expression is found.%@NL@% %@NL@% %@CR:MCVB600J@%%@4@%You cannot search for a label with the dialog version of the Search command,%@EH@% but you can use the View command with the label as an argument for the same effect.%@NL@% %@NL@% %@NL@% %@CR:MCVB7000@%%@2@%%@AB@%11.7 Shell Escape Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB7001@%%@4@%The Shell Escape command allows you to exit from the CodeView debugger to a%@EH@% DOS shell. You can execute DOS commands or programs from within the debugger, or you can exit from the debugger to DOS while retaining your current debugging context.%@NL@% %@NL@% %@CR:MCVB7002@%%@4@%The Shell Escape command works by saving the current processes in memory and%@EH@% then executing a second copy of COMMAND.COM. The COMSPEC environment variable is used to locate a copy of COMMAND.COM.%@NL@% %@NL@% %@CR:MCVB7003@%%@4@%Opening a shell requires a significant amount of free memory (usually more%@EH@% than 200K) because the CodeView debugger, the symbol table, COMMAND.COM, and the program being debugged must all be saved in memory. If you do not have enough memory, an error message appears. Even if you have enough memory to start a new shell, you may not have enough memory left to execute large programs from the shell.%@NL@% %@NL@% %@CR:MCVB7004@%%@4@%If you change directories while working in the shell, make sure you return%@EH@% to the original directory before returning to the CodeView debugger. If you don't, the debugger may not be able to find and load source files when it needs them.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% In order to use the Shell Escape command, the executable file being%@NL@% debugged must release unneeded memory. Programs created with Microsoft%@NL@% compilers release memory during start-up.%@NL@% %@NL@% You cannot use the Shell Escape command with assembler programs unless%@NL@% the program specifically releases memory by using the DOS function call%@NL@% 4A hexadecimal (Set Block) or is linked with the /CPARMAXALLOC link%@NL@% option.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVB7005@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB7006@%%@4@%To open a DOS shell with the mouse, point to File on the menu bar, press a%@EH@% mouse button and drag the highlight down to the DOS Shell selection, then release the button. If there is enough memory to open the shell, the DOS screen appears. You can execute any DOS command or any program. When you are ready to return to the debugging session, type the command %@AS@%exit%@AE@% (in any combination of uppercase and lowercase letters). The debugging screen will appear with the same status it had when you left it.%@NL@% %@NL@% %@CR:MCVB7007@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB7008@%%@4@%To open a DOS shell with a keyboard command, press ALT+F to open the File%@EH@% menu, then press D to select DOS Shell. If there is enough memory to open the shell, the DOS screen appears. You can execute any DOS internal command or any program. When you are ready to return to the debugging session, type the command %@AS@%exit%@AE@% (in any combination of uppercase and lowercase letters). The debugging screen will appear with the same status it had when you left it.%@NL@% %@NL@% %@CR:MCVB7009@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB700A@%%@4@%To open a DOS shell using a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%!%@AE@%«%@AI@%command%@AE@%»%@NL@% %@NL@% %@CR:MCVB700B@%%@4@%If you want to exit to DOS and execute several programs or commands, enter%@EH@% the command with no arguments. The CodeView debugger executes a new copy of COMMAND.COM, and the DOS screen appears. You can run programs or DOS internal commands. When you are ready to return to the debugger, type the command %@AS@%exit%@AE@% (in any combination of uppercase and lowercase letters). The debugging screen appears with the same status it had when you left it.%@NL@% %@NL@% %@CR:MCVB700C@%%@4@%If you want to execute a program or DOS internal command from within%@EH@% CodeView, enter the Shell Escape command (%@AB@%!%@AE@%) followed by the name of the command or the program you want to execute. The output screen appears, and the debugger executes the command or program. When the output from the command or program is completed, the message %@AS@%Press any key to %@AE@%%@AS@%continue...%@AE@% appears at the bottom of the screen. Press a key to make the debugging screen reappear with the same status it had when you left it.%@NL@% %@NL@% %@CR:MCVB700D@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >!%@NL@% %@NL@% %@CR:MCVB700E@%%@4@%In the above example, the CodeView debugger saves the current debugging%@EH@% context and executes a copy of COMMAND.COM. The DOS screen appears, and you can enter any number of commands. To return to the debugger, enter %@AS@%exit%@AE@%.%@NL@% %@NL@% >!DIR a:*.for%@NL@% %@NL@% %@CR:MCVB700F@%%@4@%In the example above, the DOS command %@AS@%DIR%@AE@% is executed with the argument%@EH@% %@AS@%a:*.for%@AE@%. The directory listing will be followed by a prompt telling you to press any key to return to the CodeView debugging screen.%@NL@% %@NL@% >!CHKDSK a:%@NL@% %@NL@% %@CR:MCVB700G@%%@4@%In the example above, the DOS command %@AS@%CHKDSK%@AE@% is executed, and the status of%@EH@% the disk in Drive A is displayed in the dialog window. The program name specified could be for any executable file, not just that for a DOS program.%@NL@% %@NL@% %@NL@% %@CR:MCVB8000@%%@2@%%@AB@%11.8 Tab Set Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB8001@%%@4@%The Tab Set command sets the width in spaces that the CodeView debugger%@EH@% fills for each tab character. The default tab is eight spaces. You might want to set a smaller tab size if your source code has so many levels of indentation that source lines extend beyond the edge of the screen. This command has no effect if your source code was written with an editor that indents with spaces rather than tab characters.%@NL@% %@NL@% %@CR:MCVB8002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB8003@%%@4@%You cannot set the tab size by using the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCVB8004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB8005@%%@4@%You cannot set the tab size by using a keyboard command.%@EH@%%@NL@% %@NL@% %@CR:MCVB8006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB8007@%%@4@%To set the tab size with a dialog command, enter a command line with the%@EH@% following syntax:%@NL@% %@NL@% %@AB@%#%@AE@%%@AI@%number%@AE@%%@NL@% %@NL@% %@CR:MCVB8008@%%@4@%The %@AI@%number%@AE@% is the new number of characters for each tab character. In window%@EH@% mode, the screen is redrawn with the new tab width when you enter the command. In sequential mode, any output of source lines reflects the new tab size.%@NL@% %@NL@% %@CR:MCVB8009@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >.%@NL@% 32: IF (X(I)) .LE. X(J)) GOTO 301%@NL@% >#4%@NL@% >.%@NL@% 32: IF (X(I)) .LE. X(J)) GOTO 301%@NL@% >%@NL@% %@NL@% %@CR:MCVB800A@%%@4@%In the example above, the Source Line command (%@AB@%.%@AE@%) is used to show the source%@EH@% line with the default tab width of eight spaces. Next, the Tab Set command is used to set the tab width to four spaces. The Source Line command then shows the same line.%@NL@% %@NL@% %@NL@% %@CR:MCVB9000@%%@2@%%@AB@%11.9 Option Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB9001@%%@4@%The Option command allows you to view the state of options in the Option%@EH@% menu (Flip/Swap, Bytes Coded, Case Sense, and 386) and to turn any of the these options on or off.%@NL@% %@NL@% %@CR:MCVB9002@%%@4@%For each different kind of source module that you debug, there is a%@EH@% different set of default settings. However, the use of the Option command overrides any of these settings.%@NL@% %@NL@% %@CR:MCVB9003@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB9004@%%@4@%To view the state of the options with a mouse, simply point to Options on%@EH@% the menu bar and click either button. Each option is displayed. Those options that are turned on have a double arrow immediately to the left. Options that are turned off have no double arrow.%@NL@% %@NL@% %@CR:MCVB9005@%%@4@%To change one of the Option settings, drag the highlight down to the option%@EH@% you wish to change and release the button. This reverses the state of the option. (An option that was on will be turned off and vice versa.)%@NL@% %@NL@% %@CR:MCVB9006@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB9007@%%@4@%To view the state of the Options menu with a keyboard command, press ALT+O%@EH@% to open the Options menu. Each option is displayed. Those options that are turned on have a double arrow immediately to the left. Options that are turned off have no double arrow.%@NL@% %@NL@% %@CR:MCVB9008@%%@4@%To change one of the Option settings, press the letter key corresponding to%@EH@% the option's mnemonic. This reverses the state of the option. (An option that was on will be turned off and vice versa.) You can also reverse an option by moving the highlight down with the arrow key and pressing ENTER.%@NL@% %@NL@% %@CR:MCVB9009@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVB900A@%%@4@%To view or change options with a dialog command, enter a command line with%@EH@% the following syntax:%@NL@% %@NL@% %@AB@%O%@AE@%«%@AI@%option%@AE@% «%@AB@%+%@AE@% | %@AB@%-%@AE@%»»%@NL@% %@NL@% %@CR:MCVB900B@%%@4@%In the above display, %@AI@%option%@AE@% is one of the following characters: %@AB@%F%@AE@%, %@AB@%B%@AE@%, %@AB@%C%@AE@%,%@EH@% or %@AB@%3%@AE@%. If used, there must be no spaces between the character and the %@AB@%O%@AE@%. These characters correspond to the options as shown below:%@NL@% %@NL@% %@CR:MCVB900C@%%@AB@%Command Correspondence%@AE@%%@NL@% %@NL@% %@AB@%OF%@AE@% Flip/Swap option%@NL@% %@NL@% %@AB@%OB%@AE@% Bytes-Coded option%@NL@% %@NL@% %@AB@%OC%@AE@% Case-Sense option%@NL@% %@NL@% %@AB@%O3%@AE@% 386 option%@NL@% %@NL@% %@AB@%O%@AE@% All options%@NL@% %@NL@% %@CR:MCVB900D@%%@4@%The %@AB@%O%@AE@% form of the command (all options) takes no arguments; it displays the%@EH@% state of all four options. The other forms of the command (%@AB@%OF%@AE@%, %@AB@%OB%@AE@%, %@AB@%OC%@AE@%, and %@AB@%O3%@AE@%) can be used either with no arguments (in which case they display the state of the option) or they can take the argument %@AB@%+%@AE@% or %@AB@%-%@AE@%.%@NL@% %@NL@% %@CR:MCVB900E@%%@4@%The %@AB@%+%@AE@% argument turns the option on. The %@AB@%-%@AE@% argument turns the option off.%@EH@%%@NL@% %@NL@% %@CR:MCVB900F@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >O%@NL@% Flip/Swap on%@NL@% Bytes Coded on%@NL@% Case Sense off%@NL@% 386 off%@NL@% >O3%@NL@% 386 off%@NL@% >O3+%@NL@% 386 on%@NL@% >OF%@NL@% Flip/Swap on%@NL@% >OF-%@NL@% Flip/Swap off%@NL@% %@NL@% %@CR:MCVB900G@%%@4@%In the example above, the %@AB@%O%@AE@%, %@AB@%O3%@AE@%, and %@AB@%OF%@AE@% commands are used to view the%@EH@% current state of an option. Each of the %@AB@%O3+%@AE@% and %@AB@%OF-%@AE@% commands modifies an option and then reports the results of the modification.%@NL@% %@NL@% %@CR:MCVB900H@%%@4@%The dialog version of the Option command is particularly useful for%@EH@% redirected CodeView commands (which cannot access menus) and for making the debugger start up with certain options. For example, the following DOS-level command line brings up CodeView with the 386 option on and Bytes Coded off:%@NL@% %@NL@% CV /c"O3+;OB-" test%@NL@% %@NL@% %@CR:MCVB900I@%%@4@%This command line could then be placed into a batch file for convenient%@EH@% execution.%@NL@% %@NL@% %@NL@% %@CR:MCVBA000@%%@2@%%@AB@%11.10 Redirection Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA001@%%@4@%The CodeView debugger provides several options for redirecting commands from%@EH@% or to devices or files. Furthermore, the debugger provides several other commands, which are relevant only when used with redirected files.%@NL@% %@NL@% %@CR:MCVBA002@%%@4@%%@AB@%Mouse%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA003@%%@4@%None of the redirection or related commands can be executed with the mouse.%@EH@%%@NL@% %@NL@% %@CR:MCVBA004@%%@4@%%@AB@%Keyboard%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA005@%%@4@%None of the redirection or related commands can be executed with keyboard%@EH@% commands.%@NL@% %@NL@% %@CR:MCVBA006@%%@4@%%@AB@%Dialog%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA007@%%@4@%The redirection commands are entered with dialog commands, as shown in%@EH@% Sections 11.10.1%@BO: 7e1b9@%-11.10.4.3 below.%@NL@% %@NL@% %@NL@% %@CR:MCVBA100@%%@3@%%@AB@%11.10.1 Redirecting CodeView Input%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA101@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%<%@AE@% %@AI@%devicename%@AE@%%@NL@% %@NL@% %@CR:MCVBA102@%%@4@%The Redirected Input command causes the CodeView debugger to read all%@EH@% subsequent command input from a device, such as another terminal or a file. The sample session supplied with most versions of the debugger is an example of commands being redirected from a file.%@NL@% %@NL@% %@CR:MCVBA103@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% ><COM1%@NL@% %@NL@% %@CR:MCVBA104@%%@4@%The example above redirects commands from the device (probably a remote%@EH@% terminal) designated as %@AS@%COM1%@AE@% to the CodeView terminal.%@NL@% %@NL@% ><INFILE.TXT%@NL@% %@NL@% %@CR:MCVBA105@%%@4@%The example above redirects command input from file %@AS@%INFILE.TXT%@AE@% to the%@EH@% CodeView debugger. You might use this command to prepare a CodeView session for someone else to run. You create a text file containing a series of commands separated by carriage-return and line-feed combinations or semicolons. When you redirect the file, the debugger executes the commands to the end of the file. One way to create such a file is to redirect commands from the CodeView debugger to a file (see Section 11.10.3%@BO: 7f0f6@% below) and then edit the file to eliminate the output and add comments.%@NL@% %@NL@% %@NL@% %@CR:MCVBA200@%%@3@%%@AB@%11.10.2 Redirecting CodeView Output%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA201@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% «%@AB@%T%@AE@%»%@AB@%>%@AE@%«%@AB@%>%@AE@%»%@AI@%devicename%@AE@%%@NL@% %@NL@% %@CR:MCVBA202@%%@4@%The Redirected Output command causes the CodeView debugger to write all%@EH@% subsequent command output to a device, such as another terminal, a printer, or a file. The term "output" includes not only the output from commands but also the command characters that are echoed as you type them.%@NL@% %@NL@% %@CR:MCVBA203@%%@4@%The optional %@AB@%T%@AE@% indicates that the output should be echoed to the CodeView%@EH@% screen. Normally, you will want to use the %@AB@%T%@AE@% if you are redirecting output to a file so you can see what you are typing. However, if you are redirecting output to another terminal, you may not want to see the output on the CodeView terminal.%@NL@% %@NL@% %@CR:MCVBA204@%%@4@%The second greater-than symbol (optional) appends the output to an existing%@EH@% file. If you redirect output to an existing file without this symbol, the existing file is replaced.%@NL@% %@NL@% %@CR:MCVBA205@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >>COM1%@AS@%%@NL@% %@NL@% %@CR:MCVBA206@%%@4@%In the example above, output is redirected to the device designated as %@AS@%COM1%@AE@%%@EH@% (probably a remote terminal). You might want to enter this command, for example, when you are debugging a graphics program and want CodeView commands to be displayed on a remote terminal while the program display appears on the originating terminal.%@NL@% %@NL@% >T>OUTFILE.TXT%@NL@% .%@NL@% .%@NL@% .%@NL@% >>CON%@NL@% .%@NL@% .%@NL@% .%@NL@% %@NL@% %@CR:MCVBA207@%%@4@%In the example above, output is redirected to the file %@AS@%OUTFILE.TXT%@AE@%. This%@EH@% command is helpful in keeping a permanent record of a CodeView session. Note that the optional %@AB@%T%@AE@% is used so that the session is echoed to the CodeView screen as well as to the file. After redirecting some commands to a file, output is returned to the console (terminal) with the command %@AS@%>CON%@AE@%.%@AS@%%@NL@% %@NL@% >T>>OUTFILE.TXT%@AS@%%@NL@% %@NL@% %@CR:MCVBA208@%%@4@%If, later in the session, you want to redirect more commands to the same%@EH@% file, use the double greater-than symbol, as in the example above, to append the output to the existing file.%@NL@% %@NL@% %@NL@% %@CR:MCVBA300@%%@3@%%@AB@%11.10.3 Redirecting CodeView Input and Output%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA301@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%=%@AE@% %@AI@%devicename%@AE@%%@NL@% %@NL@% %@CR:MCVBA302@%%@4@%The Redirected Input and Output command causes the CodeView debugger to%@EH@% write all subsequent command output to a device and simultaneously to receive input from the same device. This command is practical only if the device is a remote terminal.%@NL@% %@NL@% %@CR:MCVBA303@%%@4@%Redirecting input and output works best if you start in sequential mode%@EH@% (using the /T option). The CodeView debugger's window interface has little purpose in this situation since the remote terminal can act only as a sequential (nonwindow) device.%@NL@% %@NL@% %@CR:MCVBA304@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% >=COM1%@NL@% %@NL@% %@CR:MCVBA305@%%@4@%In the example above, output and input are redirected to the device%@EH@% designated as %@AS@%COM1%@AE@%. This command would be useful if you wanted to enter debugging commands and see the debugger output on a remote terminal while entering program commands and viewing program output on the terminal where the debugger is running.%@NL@% %@NL@% %@NL@% %@CR:MCVBA400@%%@3@%%@AB@%11.10.4 Commands Used with Redirection%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA401@%%@4@%The following commands are intended for use when redirecting commands to or%@EH@% from a file. Although they are always available, these commands have little practical use during a normal debugging session.%@NL@% %@NL@% %@CR:MCVBA402@%%@AB@%Command Action%@AE@%%@NL@% %@NL@% Comment (%@AB@%*%@AE@%) Displays comment%@NL@% %@NL@% Delay (%@AB@%:%@AE@%) Delays execution of commands from a redirected%@NL@% file%@NL@% %@NL@% Pause (%@AB@%"%@AE@%) Interrupts execution of commands from a%@NL@% redirected file until a key is pressed%@NL@% %@NL@% %@NL@% %@CR:MCVBA410@%%@4@%%@AB@%11.10.4.1 Comment Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA411@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%*%@AE@%%@AI@%comment%@AE@%%@NL@% %@NL@% %@CR:MCVBA412@%%@4@%The Comment command is an asterisk (%@AB@%*%@AE@%) followed by text. The CodeView%@EH@% debugger echoes the text of the comment to the screen (or other output device). This command is useful in combination with the redirection commands when you are saving a commented session or when writing a commented session that will be redirected to the debugger.%@NL@% %@NL@% %@CR:MCVBA413@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >T>OUTPUT.TXT%@NL@% >* Dump first 20 bytes of screen buffer%@NL@% >D #B800:0 L 20%@NL@% B800:0000 54 17 6F 17 20 17 72 17 65 17 74 17 75 17 72 17 T.o. .r.e.t.u.r.%@NL@% B800:0010 6E 17 20 17 n. .%@NL@% >%@NL@% %@NL@% %@CR:MCVBA414@%%@4@%In the example above, the user is sending a copy of a CodeView session to%@EH@% file %@AS@%OUTPUT.TXT%@AE@%. Comments are added to explain the purpose of the command. The text file will contain commands, comments, and command output.%@NL@% %@NL@% * Dump first 20 bytes of screen buffer%@NL@% D #B800:0 L 20%@NL@% .%@NL@% .%@NL@% .%@NL@% < CON%@NL@% %@NL@% %@CR:MCVBA415@%%@4@%The example above illustrates another way to use the Comment command. You%@EH@% can put comments into a text file of commands that are executed automatically when you redirect the file into the CodeView debugger. In this example, an editing program was used to create the text file called %@AS@%INPUT.TXT%@AE@%.%@NL@% %@NL@% ><INPUT.TXT%@NL@% >* Dump first 20 bytes of screen buffer%@NL@% >D #B800:0 L 20%@NL@% B800:0000 54 17 6F 17 20 17 72 17 65 17 74 17 75 17 72 17 T.o. .r.e.t.u.r.%@NL@% B800:0010 6E 17 20 17n. .%@AE@%%@NL@% .%@NL@% .%@NL@% .%@NL@% >< CON%@NL@% >%@NL@% %@NL@% %@CR:MCVBA416@%%@4@%When you read the file into the debugger by using the Redirected Input%@EH@% command, you see the comment, the command, and the output from the command, as in the example above.%@NL@% %@NL@% %@CR:MCVBA420@%%@4@%%@AB@%11.10.4.2 Delay Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA421@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%:%@AE@%%@NL@% %@NL@% %@CR:MCVBA422@%%@4@%The Delay command interrupts execution of commands from a redirected file%@EH@% and waits about half a second before continuing. You can put multiple Delay commands on a single line to increase the length of delay. The delay is the same length regardless of the processing speed of the computer.%@NL@% %@NL@% %@CR:MCVBA423@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% : ;* That was a short delay...%@NL@% ::::: ;* That was a longer delay...%@NL@% %@NL@% %@CR:MCVBA424@%%@4@%In the example above, the Delay command is used to slow execution of the%@EH@% redirected file into the CodeView debugger.%@NL@% %@NL@% %@CR:MCVBA430@%%@4@%%@AB@%11.10.4.3 Pause Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVBA431@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%"%@AE@%%@NL@% %@NL@% %@CR:MCVBA432@%%@4@%The Pause command interrupts execution of commands from a redirected file%@EH@% and waits for the user to press a key. Execution of the redirected commands begins as soon as a key is pressed.%@NL@% %@NL@% %@CR:MCVBA433@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% * Press any key to continue%@NL@% "%@NL@% %@NL@% %@CR:MCVBA434@%%@4@%In the example above from a text file that might be redirected into the%@EH@% CodeView debugger, a Comment command is used to prompt the user to press a key. The Pause command is then used to halt execution until the user responds.%@NL@% %@NL@% >* Press any key to continue%@NL@% >"%@NL@% %@NL@% %@CR:MCVBA435@%%@4@%The example above shows the output when the text is redirected into the%@EH@% debugger. The next CodeView prompt does not appear until the user presses a key.%@NL@% %@NL@% %@NL@% %@CR:MCVC0000@%%@1@%%@AB@%Chapter 12 Debugging in Protected Mode%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVC0001@%%@4@%The protected-mode CodeView debugger (CVP.EXE) supports all the special%@EH@% programming features of OS/2 protected mode: dynamic-link libraries, multiple processes, and multiple threads within a process. CodeView lets you stop execution, then switch between individual processes and threads.%@NL@% %@NL@% %@CR:MCVC0002@%%@4@%The support for thread debugging is especially powerful because it lets you%@EH@% block (or "freeze") selected threads while letting others run. You can set breakpoints applicable to all threads or only to a specific thread.%@NL@% %@NL@% %@CR:MCVC0003@%%@4@%Note that you must use the protected-mode CodeView debugger (CVP.EXE) in%@EH@% order to run CodeView in protected mode or debug protected-mode programs. Furthermore, before you run CVP you must set IOPL=YES in your CONFIG.SYS file.%@NL@% %@NL@% %@CR:MCVC0004@%%@4@%This chapter deals with the following topics:%@EH@%%@NL@% %@NL@% %@CR:MCVC0005@% ■ Using CodeView in real and protected mode%@NL@% %@NL@% ■ Debugging dynamic-link libraries%@NL@% %@NL@% ■ Debugging multiple processes%@NL@% %@NL@% ■ Debugging multiple threads%@NL@% %@NL@% %@CR:MCVC0006@%%@4@%All the techniques presented in this chapter can be used together. You can%@EH@% debug multiple processes, and within each process debug multiple threads.%@NL@% %@NL@% %@NL@% %@CR:MCVC1000@%%@2@%%@AB@%12.1 Using CodeView in Different Modes%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC1001@%%@4@%Chapters 1-11 assume that the real-mode CodeView debugger (CV.EXE) is%@EH@% running in real mode, debugging a real-mode program. This section summarizes the major considerations and limitations of other situations.%@NL@% %@NL@% %@CR:MCVC1002@%%@4@%As noted above, to debug a protected-mode program, you must run CVP.EXE in%@EH@% protected mode. You must first set IOPL=YES. This setting enables applications to run at Ring 3, giving programs low-level access. CodeView needs to run at this level because it does direct-hardware access.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%WARNING%@AE@%%@NL@% If you do not set IOPL=YES before running CVP, CVP fails to run and the%@NL@% system does not give you a clear message explaining why CodeView failed.%@NL@% The system may become unstable and fail at any time.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVC1003@%%@4@%You must also use CVP in order to debug a bound program. The restrictions%@EH@% mentioned above apply. Real-mode CodeView cannot debug a bound program.%@NL@% %@NL@% %@CR:MCVC1004@%%@4@%The real-mode debugger can run in the 3.x compatibility box. However, when%@EH@% you run CodeView in the compatibility box, include /S on the command line. Otherwise, the mouse pointer does not appear.%@NL@% %@NL@% %@NL@% %@CR:MCVC2000@%%@2@%%@AB@%12.2 Debugging Dynamic-Link Libraries%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC2001@%%@4@%The protected-mode CodeView debugger (CVP) can debug dynamic-link modules%@EH@% but only if it is told what libraries to search at run time. For more information on dynamic-link libraries, refer to the %@AI@%Microsoft Operating%@AE@% %@AI@%System/2 Programmer's Guide%@AE@%.%@NL@% %@NL@% %@CR:MCVC2002@%%@4@%When you place a module in a dynamic-link library, neither code nor symbolic%@EH@% information for that module is stored in the executable (.EXE) file; instead, the code and symbols are stored in the library and are not brought together with the main program until run time.%@NL@% %@NL@% %@CR:MCVC2003@%%@4@%Thus, the protected-mode debugger needs to search the dynamic-link library%@EH@% for symbolic information. Because the debugger does not automatically know what libraries to look for, CVP has an additional command-line option that enables you to specify dynamic-link libraries:%@NL@% %@NL@% %@CR:MCVC2004@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%/L%@AE@%%@AI@% file%@AE@%%@AB@%%@NL@% %@NL@% %@CR:MCVC2005@%%@4@%The /L option directs the CodeView debugger to search %@AI@%file%@AE@% for symbolic%@EH@% information. When you use this option, at least one space must separate /L from %@AI@%file%@AE@%.%@NL@% %@NL@% %@CR:MCVC2006@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% CVP /L DLIB1.DLL /L GRAFLIB.DLL PROG%@NL@% %@NL@% %@CR:MCVC2007@%%@4@%In the example above, CVP is invoked to debug the program PROG.EXE. To find%@EH@% symbolic information needed for debugging each module, CVP searches the libraries %@AS@%DLIB1.DLL%@AE@% and %@AS@%GRAFLIB.DLL%@AE@%, as well as the executable file %@AS@%PROG.EXE%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVC3000@%%@2@%%@AB@%12.3 Debugging Multiple Processes%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC3001@%%@4@%To enable debugging of multiple processes, you must first start up CodeView%@EH@% with the /O (offspring) option. The syntax of this option is simple, as it takes no arguments.%@NL@% %@NL@% %@CR:MCVC3002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%/O%@AE@%%@NL@% %@NL@% %@CR:MCVC3003@%%@4@%If you do not use the /O option (or the option cannot be used), CodeView%@EH@% lets your program spawn new processes, but you will not be able to view or trace through these processes. They run in the background as far as CodeView is concerned.%@NL@% %@NL@% %@CR:MCVC3004@%%@4@%For example, to debug multiple processes of the program SPACEMAN.EXE you%@EH@% would use the following command:%@NL@% %@NL@% CVP /O SPACEMAN%@NL@% %@NL@% %@CR:MCVC3005@%%@4@%The /O option has two limitations:%@EH@%%@NL@% %@NL@% %@CR:MCVC3006@% 1. You must have OS/2 Version 1.1 or later to use it.%@NL@% %@NL@% 2. This option is incompatible with the /2 option.%@NL@% %@NL@% %@CR:MCVC3007@%%@4@%The rest of this section assumes that you have successfully started CodeView%@EH@% with the /O option.%@NL@% %@NL@% %@CR:MCVC3008@%%@4@%Every time your program executes a line of code that spawns a child process,%@EH@% CodeView responds by displaying the process ID number (Pid) and asking if you wish to debug the child process. The message displayed is similar to the following:%@NL@% %@NL@% %@AS@%Pid 24 started. Do you wish to debug (y/n)?%@AE@%%@NL@% %@NL@% %@CR:MCVC3009@%%@4@%To debug the child process, type Y and then press ENTER. Type any other%@EH@% letter for no. CodeView takes a different course of action depending on your response.%@NL@% %@NL@% %@CR:MCVC300A@% ■ If you respond yes, CodeView spawns a new CodeView process. This%@NL@% process controls execution of your program's child process. Each%@NL@% instance of CodeView spawned in this way becomes a separate debugging%@NL@% session.%@NL@% %@NL@% A new process runs in the same screen group as its parent process%@NL@% (unless you call the DosStartSession system function). Using CodeView%@NL@% does not change this. However, each new instance of CodeView always%@NL@% runs in its own screen group. Since OS/2 supports a maximum of 16%@NL@% screen groups, the number of child processes that you can debug at one%@NL@% time is limited.%@NL@% %@NL@% ■ If you respond no, CodeView lets the program spawn the child process.%@NL@% However, you will not be able to control or trace the child process%@NL@% with CodeView. The child process is active but not accessible to%@NL@% CodeView commands.%@NL@% %@NL@% %@CR:MCVC300B@%%@4@%You can move between different CodeView processes in the following two ways:%@EH@% by using the OS/2 Session Manager or the Process command (%@AB@%|%@AE@%). The Process command, in turn, has two forms. You can use this command to view status of child processes or to switch directly to the debugging session of the child process.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% You may need to make note of process ID numbers when CodeView spawns a%@NL@% process. CodeView identifies multiple processes only by their ID numbers.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVC3100@%%@3@%%@AB@%12.3.1 Viewing Status%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC3101@%%@4@%To view the status of the child processes (of the current process), enter%@EH@% the Process command followed by no arguments:%@NL@% %@NL@% %@AB@%|%@AE@%%@NL@% %@NL@% %@CR:MCVC3102@%%@4@%CodeView responds by displaying three fields: process ID number, session%@EH@% (screen group) ID number, and yes or no, depending on whether or not each process has its own instance of CodeView. The following example shows a sample process status for a process with three children:%@NL@% %@NL@% 001|%@NL@% ProcessID SessionID Debugging%@NL@% 00024 00006 Yes%@NL@% 00026 00006 Yes%@NL@% 00028 00006 No%@NL@% %@NL@% %@CR:MCVC3103@%%@4@%In the example above, only processes 24 and 26 can be debugged. Each of%@EH@% these processes corresponds to a different instance of CodeView, and each instance runs in a separate screen group. Process 28 is active but cannot be debugged.%@NL@% %@NL@% %@NL@% %@CR:MCVC3200@%%@3@%%@AB@%12.3.2 Switching to a Child Process%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC3201@%%@4@%If a child process can be debugged, you can switch to that process directly%@EH@% by using the Process command. Use of this command accomplishes the same end as using the Session Manager but is more direct.%@NL@% %@NL@% %@CR:MCVC3202@%%@4@%To switch to the debugging session for a child process, enter the Process%@EH@% command with the following syntax:%@NL@% %@NL@% %@AB@%|%@AE@% %@AI@%processID%@AE@%%@AB@%%@NL@% %@NL@% %@CR:MCVC3203@%%@4@%in which %@AI@%processID%@AE@% is the process ID (Pid) of the process you wish to debug.%@EH@%%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The Process command only works with direct children. In other words, you%@NL@% can spawn a child which in turns spawns another child. The Process%@NL@% command does not give you direct access to the "grandchild." Instead, you%@NL@% must switch to the intermediate parent.%@NL@% %@NL@% To return to debugging a parent or grandparent, you must use the OS/2%@NL@% Session Manager.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVC4000@%%@2@%%@AB@%12.4 Debugging Multiple Threads%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC4001@%%@4@%A program running in OS/2 protected mode has one or more threads. Threads%@EH@% are the fundamental units of execution; OS/2 can execute a number of different threads concurrently. A thread is similar to a process, yet it can be created or terminated much faster. Threads begin at a function-definition heading in the same program in which they are invoked.%@NL@% %@NL@% %@CR:MCVC4002@%%@4@%The existence of multiple threads within a program presents a dilemma for%@EH@% debugging. For example, thread 1 may be executing source line 23 while thread 2 is executing source line 78. Which line of code does the CodeView debugger consider to be the current line?%@NL@% %@NL@% %@CR:MCVC4003@%%@4@%Conversely, you cannot always tell which thread is executing even if you%@EH@% know what the current source line is. In OS/2 protected mode, you can write a program in which two threads enter the same function.%@NL@% %@NL@% %@CR:MCVC4004@%%@4@%In Figure 12.1%@FN@% Figure 12.1 is found on page 214 of the printed version.%@EF@%, the function %@AS@%main%@AE@% uses the DOSCREATETHREAD system call to%@EH@% begin execution of thread 2. The function %@AS@%f2%@AE@% is the entry point of the new thread. Thread 2 begins and terminates inside the function %@AS@%f2%@AE@%. Before it terminates, however, thread 2 can enter other functions by means of ordinary function calls.%@AS@%%@NL@% %@NL@% %@CR:MCVC4005@%%@4@%Thread 1 begins execution in the function %@AS@%main%@AE@%, and thread 2 begins%@EH@% execution in the function %@AS@%f2%@AE@%. Later, both thread 1 and thread 2 enter the function %@AS@%f3%@AE@%. (Note that each thread returns to the proper place because each thread has its own stack.) When you use the debugger to examine the behavior of code within the function %@AS@%f3%@AE@%, how can you tell which thread you are tracking?%@AS@%%@NL@% %@NL@% %@CR:MCVC4006@%%@4@%The protected-mode CodeView debugger solves this dilemma by using a modified%@EH@% CodeView prompt and by providing the Thread command, which is only available with CVP.%@NL@% %@NL@% %@CR:MCVC4007@%%@4@%The command prompt for the protected-mode CodeView debugger is preceded by a%@EH@% three-digit number indicating the current thread.%@NL@% %@NL@% %@CR:MCVC4008@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% 001>%@NL@% %@NL@% %@CR:MCVC4009@%%@4@%The example above displays the protected-mode CodeView prompt, indicating%@EH@% that thread 1 is the current thread. Thread 1 is always the current thread when you begin a program. If the program never calls the DOSCREATETHREAD function, thread 1 will remain the only thread. Note that certain C library functions (such as BeginThread) call DOSCREATETHREAD for you.%@NL@% %@NL@% %@CR:MCVC400A@%%@4@%Each thread has its own stack and its own register values. When you change%@EH@% the current thread, you see several changes to the CodeView debugger display:%@NL@% %@NL@% %@CR:MCVC400B@% ■ The CodeView prompt displays a different three-digit number.%@NL@% %@NL@% ■ The register contents change.%@NL@% %@NL@% ■ The current source line and current instruction both change to reflect%@NL@% the new value of CS:IP. If you are running the debugger in window mode,%@NL@% you are likely to see different code in the display window.%@NL@% %@NL@% ■ The Calls menu and the Stack Trace command displays a different group%@NL@% of functions.%@NL@% %@NL@% %@NL@% %@CR:MCVC5000@%%@2@%%@AB@%12.5 The Thread Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC5001@%%@4@%This section discusses the Thread command and lists other CodeView commands%@EH@% that may work differently because of multiple threads.%@NL@% %@NL@% %@CR:MCVC5002@%%@4@%The syntax of the Thread command is displayed below:%@EH@%%@NL@% %@NL@% %@CR:MCVC5003@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%~%@AE@%«%@AI@%specifier%@AE@%«%@AI@%command%@AE@%» »%@NL@% %@NL@% %@CR:MCVC5004@%%@4@%In the syntax display above, the %@AI@%specifier%@AE@% determines to which thread or%@EH@% threads the command applies. You can specify all threads or just a particular thread. The %@AI@%command%@AE@% determines which activity the debugger carries out with regard to the specified thread. For example, you can execute the thread, freeze its execution, or select it as the current thread. If you omit %@AI@%command%@AE@%, the debugger displays the status of the specified thread. If you omit both %@AI@%command%@AE@% and %@AI@%specifier%@AE@%, the debugger displays the status of all threads.%@NL@% %@NL@% %@CR:MCVC5005@%%@4@%The status display for threads consists of the two fields%@EH@%%@NL@% %@NL@% %@CR:MCVC5006@%%@AI@%thread-id thread-state%@AE@%%@NL@% %@NL@% %@CR:MCVC5007@%%@4@%in which %@AI@%thread-id%@AE@% is an integer and %@AI@%thread-state%@AE@% has the value %@AS@%runnable%@AE@% or%@EH@% %@AS@%frozen%@AE@%. All threads not frozen by the debugger are displayed as %@AS@%runnable%@AE@%; this includes threads that may be blocked for reasons that have nothing to do with the debugger, such as a critical section.%@NL@% %@NL@% %@NL@% %@CR:MCVC5100@%%@3@%%@AB@%12.5.1 Legal Values for Specifier%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC5101@%%@4@%The legal values for %@AI@%specifier%@AE@% are listed below along with their effects.%@EH@%%@NL@% %@NL@% %@CR:MCVC5102@%%@AB@%Symbol Function%@AE@%%@NL@% %@NL@% (blank) Displays the status of all threads.%@NL@% %@NL@% If you omit the %@AI@%specifier%@AE@% field you cannot enter%@NL@% a %@AI@%command%@AE@%. Instead, you enter the tilde (%@AB@%~%@AE@%) by%@NL@% itself.%@NL@% %@NL@% %@AB@%#%@AE@% Specifies the last thread that was executed.%@NL@% %@NL@% This thread is not necessarily the current%@NL@% thread. For example, suppose you are tracing%@NL@% execution of thread 1, and then switch the%@NL@% current thread to thread 2. Until you execute%@NL@% some code in thread 2, the debugger still%@NL@% considers thread 1 to be the last thread%@NL@% executed.%@NL@% %@NL@% %@AB@%*%@AE@% Specifies all threads.%@NL@% %@NL@% %@AI@%n%@AE@% Specifies the indicated thread. The value of %@AI@%n%@AE@%%@NL@% must be a number corresponding to an existing%@NL@% thread. You can determine corresponding numbers%@NL@% for all threads by entering the command %@AB@%~*%@AE@%,%@NL@% which gives status of all threads.%@NL@% %@NL@% %@AB@%.%@AE@% Specifies the current thread.%@NL@% %@NL@% %@NL@% %@CR:MCVC5200@%%@3@%%@AB@%12.5.2 Legal Values fo rCommand%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC5201@%%@4@%The legal values for %@AI@%command%@AE@% are listed below, along with their effects.%@EH@%%@NL@% %@CR:MCVC5202@%%@NL@% %@TH: 90 5206 2 28 49 @%%@AB@%Command Function%@AE@%(blank) The status of the selected thread (or threads) is displayed.%@AB@%BP%@AE@% A breakpoint is set for the specified thread or threads. As explained earlier, it is possible to write your program so that the same function is executed by more than one thread. By using this version of the Thread command, you can specify a breakpoint that applies only to a particular thread. The letters %@AB@%BP%@AE@% are followed by normal syntax for the Breakpoint Set command, as described in Chapter 7%@BO: 579f3@%, "Managing Breakpoints." Therefore you can include the optional pass count and command fields.%@AB@%E%@AE@% The specified thread is executed in slow motion. When you specify a single thread with %@AB@%E%@AE@%, the specified thread becomes the current thread and is executed without any other threads running in the background. The command %@AB@%~*E%@AE@%%@AS@%%@AE@% is a special case. It is legal only in source mode and executes the current thread in slow motion, but lets all other threads run (except those that are frozen). You see only the current thread executing in the debugger display.%@AB@%F%@AE@% The specified thread (or threads) is frozen. A frozen thread will not run in the background or in response to the debugger Go command. However, if you use the %@AB@%E%@AE@%, %@AB@%G%@AE@%, %@AB@%P%@AE@%, or %@AB@%T%@AE@% variation of the Thread command, the specified thread is temporarily unfrozen while the debugger executes the command.%@AB@%G%@AE@% Control is passed to the specified thread until it terminates or until a breakpoint is reached. If you give the command %@AB@%~*G%@AE@%, all threads execute concurrently (except for those that are frozen). If you specify a particular thread, the debugger temporarily freezes all other threads and executes the specified thread.%@AB@%P%@AE@% The debugger executes a program step for the specified thread. If you specify a particular thread, the debugger executes one source line or instruction of the thread. All other threads are temporarily frozen. This version of the Thread command does not change the current thread. Therefore if you specify a thread other than the current thread, you will not see immediate results. However, the subsequent behavior of the current thread may be affected. The command %@AB@%~*P%@AE@% is a special case. It is legal only in source mode, and causes the debugger to step to the next source line while letting all other threads run (except for those that are frozen). You see only the current thread execute in the debugger display.%@AB@%S%@AE@% The specified thread is selected as the current thread. This version of the Thread command can apply to only one thread at a time. Thus, the command %@AB@%~*S%@AE@% results in an error message. Note that the command %@AB@%~.S%@AE@% is legal, but has no effect.%@AB@%T%@AE@% The specified thread is traced. This version of the Thread command works in a manner identical to %@AB@%P%@AE@%, described above, except that %@AB@%T%@AE@% traces through function calls and interrupts, whereas %@AB@%P%@AE@% does not.%@AB@%U%@AE@% The specified thread or threads are unfrozen. This command reverses the effect of a freeze.%@TE: 90 5206 2 28 49 @% %@NL@% %@CR:MCVC5203@%%@4@%With the Thread command, only the %@AB@%S%@AE@% (select) and %@AB@%E%@AE@% (execute) variations cause%@EH@% the debugger to switch the current thread. However, when a thread causes program execution to stop by hitting a breakpoint, the debugger selects that thread as the current thread.%@NL@% %@NL@% %@CR:MCVC5204@%%@4@%You can prevent the debugger from changing the current thread by including%@EH@% the breakpoint command %@AB@%"~.S"%@AE@%. This command directs the debugger to switch to the current thread rather than the thread that hit the breakpoint. For example, the following command sets a breakpoint at line %@AS@%120%@AE@% and prevents the current thread from changing:%@NL@% %@NL@% BP .120 "~.S"%@NL@% %@NL@% %@NL@% %@CR:MCVC5300@%%@3@%%@AB@%12.5.3 Entries to the Thread Command%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC5301@%%@4@%The Thread command can have several possible entries. They are summarized in%@EH@% the syntax display below.%@NL@% %@NL@% %@CR:MCVC5302@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%~{#%@AE@%|%@AB@%*%@AE@%|%@AI@%n%@AE@%|%@AB@%.}%@AE@%«%@AB@%BP%@AE@%|%@AB@%E%@AE@%|%@AB@%F%@AE@%|%@AB@%G%@AE@%|%@AB@%P%@AE@%|%@AB@%S%@AE@%|%@AB@%T%@AE@%|%@AB@%U%@AE@%»%@NL@% %@NL@% %@CR:MCVC5303@%%@4@%Note that you must include one of the symbols from the first set (which%@EH@% gives possible values for the specifier), but you do not have to include a symbol from the second set (which gives possible values for the command).%@NL@% %@NL@% %@CR:MCVC5304@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% 004>~%@NL@% %@NL@% %@CR:MCVC5305@%%@4@%The example above displays the status of all threads, including their%@EH@% corresponding numbers.%@NL@% %@NL@% 004>~2%@NL@% %@NL@% %@CR:MCVC5306@%%@4@%The example above displays the status of thread 2.%@EH@%%@NL@% %@NL@% 004>~5S%@NL@% %@NL@% %@CR:MCVC5307@%%@4@%The example above selects thread 5 as the current thread. Since the current%@EH@% thread was 4 (a fact apparent from the CodeView prompt), the current thread is changing and therefore the registers and the code displayed can be expected to all change.%@NL@% %@NL@% 005>~3BP .64%@NL@% %@NL@% %@CR:MCVC5308@%%@4@%The example above sets a breakpoint at source line 64, an action that stops%@EH@% program execution only when thread 3 executes to this line.%@NL@% %@NL@% 005>~1F%@NL@% %@NL@% %@CR:MCVC5309@%%@4@%The example above freezes thread 1.%@EH@%%@NL@% %@NL@% 005>~*U%@NL@% %@NL@% %@CR:MCVC530A@%%@4@%The example above thaws (unfreezes) all threads; any threads that were%@EH@% frozen before will now be free to execute whenever the Go command is given. If no threads are frozen, this command has no effect.%@NL@% %@NL@% 005>~2E%@NL@% %@NL@% %@CR:MCVC530B@%%@4@%The example above selects thread 2 as the current thread, then proceeds to%@EH@% execute thread 2 in slow motion.%@NL@% %@NL@% 002>~3S%@NL@% 003>~.F%@NL@% 003>~#S%@NL@% 002>%@NL@% %@NL@% %@CR:MCVC530C@%%@4@%The example above selects thread 3 as the current thread, freezes the%@EH@% current thread (thread 3), and switches back to thread 2. After switching to thread 3, no code was executed; therefore, the debugger considers the last-thread-executed symbol (%@AB@%#%@AE@%) to refer to thread 2.%@NL@% %@NL@% %@NL@% %@CR:MCVC5400@%%@3@%%@AB@%12.5.4 Effect of Threads on CodeView Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVC5401@%%@4@%Whether or not you use the Thread Command, the existence of threads affects%@EH@% your CodeView debugging session at all times. Particular debugger commands are strongly affected. Each of these commands is discussed below.%@NL@% %@CR:MCVC5402@%%@NL@% %@TH: 41 2613 2 28 48 @%%@AB@%Command Behavior in Multiple-Thread Programs%@AE@%%@AB@%.%@AE@% The Current Line command always uses the current value of CS:IP to determine what the current instruction is. Thus, the Current Line command applies to the current thread.%@AB@%E%@AE@% When the debugger is in source mode, the Execute command is equivalent to the %@AB@%~*E%@AE@% command; the current thread is executed in slow motion while all other threads are also running. When the debugger is in mixed or assembly mode, the Execute command is equivalent to the command %@AB@%~.P%@AE@%, which does not let other threads run concurrently.%@AB@%BP%@AE@% The Set Breakpoint command is equivalent to the %@AB@%~*BP%@AE@% command; the breakpoint applies to all threads.%@AB@%G%@AE@% The Go command is equivalent to the %@AB@%~*G%@AE@%%@AS@%%@AE@% command; control is passed to the operating system, which executes all threads in the program except for those that are frozen.%@AB@%P%@AE@% When the debugger is in source mode, the Program Step command is equivalent to the command %@AB@%~*P%@AE@%, which lets other threads run concurrently. When the debugger is in mixed or assembly mode, the Program Step command is equivalent to the command %@AB@%~.P%@AE@%, which lets no other threads run.%@AB@%K%@AE@% The Stack Trace command displays the stack of the current thread.%@AB@%T%@AE@% When the debugger is in source mode, the Trace command is equivalent to the command %@AB@%~*T%@AE@%, which lets other threads run concurrently. When the debugger is in mixed or assembly mode, the Trace command is equivalent to the command %@AB@%~.T%@AE@%, which lets no other threads run.%@TE: 41 2613 2 28 48 @% %@NL@% %@CR:MCVC5403@%%@4@%In general, CodeView commands apply to all threads unless the nature of the%@EH@% command makes it appropriate to deal with only one thread at a time. In this case, the command applies only to the current thread. (For example, since each thread has its own stack, the Stack Trace command does not apply to all threads.)%@NL@% %@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@CR:MCVP2000@%%@1@%%@AB@%Part 2 Utilities%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVP2004@%%@4@%Part 2 describes the use of each of the DOS and OS/2 programming utilities%@EH@% (exit codes and messages for these utilities are presented in the appendixes).%@NL@% %@NL@% %@CR:MCVP2005@%%@4@%Some of the material is this part, most notably the information on LINK, is%@EH@% presented in partial form in the user's guides for Microsoft compilers. However, you will find here the only complete, authoritative reference on utility operation and available options.%@NL@% %@NL@% %@CR:MCVP2006@%%@4@%Chapters 13-17 document utilities you can use to produce either OS/2 or DOS%@EH@% programs. Chapters 18-22 document utilities and special concepts-such as module-definition files-developed specifically for the creation of OS/2 programs.%@NL@% %@NL@% %@NL@% %@CR:MCVD0000@%%@1@%%@AB@%Chapter 13 Linking Object Files with LINK%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVD0001@%%@4@%The Microsoft Segmented-Executable Linker (LINK) is used to combine object%@EH@% files into a single executable file. It can be used with object files compiled or assembled for 8086/8088, 80286, or 80386 machines. The format of input to the linker is the Microsoft Relocatable Object-Module Format (OMF), which is based on the Intel 8086 OMF.%@NL@% %@NL@% %@CR:MCVD0002@%%@4@%The output file from LINK (that is, the executable file) is not bound to%@EH@% specific memory addresses. Thus, the operating system can load and execute this file at any convenient address. LINK can produce executable files containing up to 1 megabyte of code and data.%@NL@% %@NL@% %@CR:MCVD0003@%%@4@%The following sections explain how to run the linker and specify options%@EH@% that control its operation.%@NL@% %@NL@% %@NL@% %@CR:MCVD1000@%%@2@%%@AB@%13.1 Determining Linker Output%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD1001@%%@4@%The linker can produce either an application that runs under real mode (DOS%@EH@% 2.x, 3.x, or 3.x compatibility box), an application that runs under OS/2 protected mode (or Microsoft Windows), or an OS/2 dynamic-link library. If you are developing programs for real mode only, leave the %@AI@%deffile%@AE@% field on the LINK command line empty and ignore the following discussion. If you are developing programs for OS/2, read this section to understand what kind of executable file the linker produces. Chapters 18 and 19 explain in detail the terms and concepts mentioned below.%@NL@% %@NL@% %@CR:MCVD1002@%%@4@%The following rules determine what output the linker produces:%@EH@%%@NL@% %@NL@% %@CR:MCVD1003@% 1. If no module-definition file or import library resolves any external%@NL@% references, the linker produces a real-mode application. (In other%@NL@% words, the linker creates a real-mode application unless you specify a%@NL@% module-definition file or import library, and that file or library%@NL@% resolves at least one external reference.)%@NL@% %@NL@% 2. If a module-definition file with a LIBRARY statement is given, the%@NL@% linker produces a dynamic-link library for OS/2 protected mode or%@NL@% Windows.%@NL@% %@NL@% 3. Otherwise, the linker produces an application for OS/2 protected mode%@NL@% or Windows.%@NL@% %@NL@% %@CR:MCVD1004@%%@4@%You can therefore produce an OS/2 protected-mode application by linking with%@EH@% an import library or a module-definition file, as long as you do not use a %@AB@%LIBRARY%@AE@% statement. (The LIBRARY statement is described in Chapter 19%@BO: c14f2@%, "Using Module-Definition Files.") The file DOSCALLS.LIB is an import library. Therefore, if you link with DOSCALLS.LIB, you produce either an OS/2 application or a dynamic-link library.%@NL@% %@NL@% %@CR:MCVD1005@%%@4@%When you use a Microsoft high-level language to compile for protected mode,%@EH@% it automatically specifies DOSCALLS.LIB as a default library.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Throughout this chapter, all references to OS/2 protected mode also apply%@NL@% to Microsoft Windows. Other chapters may make a distinction between%@NL@% protected mode and Windows. Each reference to "library," unless otherwise%@NL@% noted, refers to a standard (object-code) library, not a dynamic-link%@NL@% library.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVD1006@%%@4@%The linker produces files that run in protected mode only or in real mode%@EH@% only. However, OS/2 applications that make dynamic-link calls only to the Family API (a subset of the functions defined in DOSCALLS.LIB) can be made to run under DOS 3.x with the BIND utility. (BIND is discussed in Chapter 20%@BO: ccaeb@%).%@NL@% %@NL@% %@NL@% %@CR:MCVD2000@%%@2@%%@AB@%13.2 Specifying Files for Linking%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2001@%%@4@%Instead of using high-level-language commands to invoke the linker, you can%@EH@% use the LINK command to invoke LINK directly.You can specify the input required for this command in one of three ways:%@NL@% %@NL@% %@CR:MCVD2002@% 1. By placing it on the command line.%@NL@% %@NL@% 2. By responding to prompts.%@NL@% %@NL@% 3. By specifying a file containing responses to prompts. This type of file%@NL@% is known as a "response file."%@NL@% %@NL@% %@CR:MCVD2003@%%@4@%Regardless of the way in which LINK was invoked, press CTRL+C at any time to%@EH@% terminate LINK operation and exit back to DOS.%@NL@% %@NL@% %@NL@% %@CR:MCVD2100@%%@3@%%@AB@%13.2.1 Specifying File Names%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2101@%%@4@%You can use any combination of uppercase and lowercase letters for the file%@EH@% names you specify on the LINK command line or give in response to the LINK command prompts. For example, LINK considers the following three file names to be equivalent:%@NL@% %@NL@% %@CR:MCVD2102@%%@AS@%abcde.fgh%@AE@%%@NL@% %@AS@%AbCdE.FgH%@AE@%%@NL@% %@AS@%ABCDE.fgh%@AE@%%@NL@% %@NL@% %@CR:MCVD2103@%%@4@%If you specify file names without extensions, LINK uses the following%@EH@% default file-name extensions:%@NL@% %@NL@% %@CR:MCVD2104@%%@AB@%File Type Default Extension%@AE@%%@NL@% %@NL@% Object .OBJ%@NL@% %@NL@% Executable .EXE%@NL@% %@NL@% Map .MAP%@NL@% %@NL@% Library .LIB%@NL@% %@NL@% Module definition .DEF%@NL@% (protected-mode use only) %@NL@% %@CR:MCVD2105@%%@4@%You can override the default extension for a particular command-line field%@EH@% or prompt by specifying a different extension. To enter a file name that has no extension, type the name followed by a period.%@NL@% %@NL@% %@CR:MCVD2106@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2107@%%@4@%Consider the following two file specifications:%@EH@%%@NL@% %@NL@% %@CR:MCVD2108@%%@AS@%ABC.%@AE@% %@AS@%ABC%@AE@%%@NL@% %@NL@% %@CR:MCVD2109@%%@4@%If you use the first file specification, LINK assumes that the file has no%@EH@% extension. If you use the second file specification, LINK uses the default extension for that prompt.%@NL@% %@NL@% %@NL@% %@CR:MCVD2200@%%@3@%%@AB@%13.2.2 Linking with the LINK Command Line%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2201@%%@4@%Use the following form of the LINK command to specify input on the command%@EH@% line:%@NL@% %@NL@% %@AB@%LINK%@AE@% %@AI@%objfiles%@AE@%«%@AB@%,%@AE@%«%@AI@%exefile%@AE@%»«%@AB@%,%@AE@%«%@AI@%mapfile%@AE@%»«%@AB@%,%@AE@%«%@AI@%libraries%@AE@%»«%@AB@%,%@AE@%%@AI@%deffile%@AE@%%@AB@%;%@AE@%%@NL@% %@NL@% %@CR:MCVD2202@%%@4@%Each of the command-line fields is explained below. In these explanations,%@EH@% reference is made to libraries. Unless qualified by the term "dynamic-link," the word "libraries" refers to import libraries and standard (object-code) libraries, both of which have the default extension .LIB. (Note that dynamic-link libraries have the default extension .DLL, and therefore are usually easy to distinguish from other libraries.) You can specify import libraries anywhere you can specify standard libraries.You can also combine import libraries and standard libraries by using the Library Manager; these combined libraries can then be specified in place of standard libraries.%@NL@% %@NL@% %@CR:MCVD2210@%%@4@%%@AB@%The objfiles field%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2211@%%@4@%The %@AI@%objfiles%@AE@% field allows you to specify the names of the object files you%@EH@% are linking. At least one object-file name is required. A space or plus sign (+) must separate each pair of object-file names. LINK automatically supplies the .OBJ extension when you give a filename without an extension. If your object file has a different extension, or if it appears in another directory or on another disk, you must give the full name──including the extension and path name──for the file to be found. If LINK cannot find a given object file, and the drive associated with the object file is a removable (floppy) drive, LINK displays a message and waits for you to change disks.%@NL@% %@NL@% %@CR:MCVD2212@%%@4@%You may also specify one or more libraries in the %@AI@%objfiles%@AE@% field. To enter a%@EH@% library in this field, make sure that you include the .LIB extension; otherwise LINK assumes an .OBJ extension. Libraries entered in this field are called "load libraries" as opposed to "regular libraries." LINK automatically links in every object module in a load library; it does not search for unresolved external references first. The effect of entering a load library is exactly the same as if you had entered all the names of the library's object modules into the %@AI@%objfiles%@AE@% field. This feature is useful if you are developing software using many modules and wish to avoid having to retype each module on the LINK command line.%@NL@% %@NL@% %@CR:MCVD2220@%%@4@%%@AB@%The exefile field%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2221@%%@4@%The %@AI@%exefile%@AE@% field allows you to specify the name of the executable file. If%@EH@% the file name you give does not have an extension, LINK automatically adds .EXE as the extension. You can give any file name you like; however, if you are specifying an extension, you should always use .EXE because DOS expects executable files to have either this extension or the .COM extension.%@NL@% %@NL@% %@CR:MCVD2230@%%@4@%%@AB@%The mapfile field%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2231@%%@4@%The %@AI@%mapfile%@AE@% field allows you to specify the name of the map file if you are%@EH@% creating one. To include public symbols and their addresses in the map file, specify the /MAP option on the LINK command line. (See Section 13.3.15%@BO: 94a90@%, "Listing Public Symbols.") If you specify a map-filename without an extension, LINK automatically adds an extension of .MAP. LINK creates the map file in the current working directory unless you specify a path name for the map file.%@NL@% %@NL@% %@CR:MCVD2240@%%@4@%%@AB@%The libraries field%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2241@%%@4@%The %@AI@%libraries%@AE@% field allows you to specify the name of a library that you%@EH@% want linked to the object file(s). (When LINK finds the name of a library in this field, the library is a "regular library," and LINK will link in only those object modules needed to resolve external references.) Each time you compile a source file for a high-level language, the compiler places the name of one or more libraries in the object file that it creates; the linker automatically searches for a library with this name. Because of this, you do not need to give library names on the LINK command line unless you want to add the names of other libraries, search for libraries in different locations, or override the use of the library named in the object file.%@NL@% %@NL@% %@CR:MCVD2250@%%@4@%%@AB@%The deffile field%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2251@%%@4@%The %@AI@%deffile%@AE@% field allows you to specify the file name of a module-definition%@EH@% file. Leave this field blank if you are linking for real mode. The use of a module-definition file is optional for applications, but required for dynamic-link libraries. See Chapters 18%@BO: be41d@% and 19%@BO: c14f2@% for more information on module-definition files.%@NL@% %@NL@% %@CR:MCVD2252@%%@4@%You may specify command-line options after any field──but before the comma%@EH@% that terminates the field. The options are described in sections 13.3.1%@BO: 900cf@%-13.3.32. You do not have to give any options when you run the linker.%@NL@% %@NL@% %@CR:MCVD2253@%%@4@%If you include a comma (to indicate where a field would be) but do not put a%@EH@% file name before the comma, LINK will select the default for that field. However, if you use a comma to include the %@AI@%mapfile%@AE@% field (but do not include a name), LINK creates a map file. This file has the same base name as the executable file. Use NUL for the map-filename if you do not want to produce a map file.%@NL@% %@NL@% %@CR:MCVD2254@%%@4@%You can also select default responses by using a semicolon (%@AB@%;%@AE@%). The%@EH@% semicolon tells LINK to use the defaults for all remaining fields. If you do not give all file names on the command line, or if you do not end the command line with a semicolon, the linker prompts you for the files you omitted, using the prompts described in Section 13.2.3%@BO: 8baf9@%, "Linking with the LINK Prompts."%@NL@% %@NL@% %@CR:MCVD2255@%%@4@%If you do not specify a drive or directory for a file, the linker assumes%@EH@% that the file is on the current drive and directory. If you want the linker to create files in a location other than the current drive and directory, you must specify the new drive and directory for each such file on the command line.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The OS/2 linker supports overlays only when producing a real-mode%@NL@% application.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVD2256@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% LINK FUN+TEXT+TABLE+CARE, ,FUNLIST, XLIB.LIB%@NL@% %@NL@% %@CR:MCVD2257@%%@4@%The command line above causes LINK to load and link the object modules %@EH@% %@AS@%FUN.OBJ%@AE@%, %@AS@%TEXT.OBJ%@AE@%, %@AS@%TABLE.OBJ%@AE@%, and %@AS@%CARE.OBJ%@AE@%, and to search for unresolved references in the library file %@AS@%XLIB.LIB%@AE@% and the default libraries. By default, the executable file produced by%@AS@%LINK%@AE@% is named %@AS@%FUN.EXE%@AE@%. LINK also produces a map file, %@AS@%FUNLIST.MAP%@AE@%.%@NL@% %@NL@% LINK FUN,,;%@NL@% %@NL@% %@CR:MCVD2258@%%@4@%This command line produces a map file named %@AS@%FUN.MAP%@AE@% since a comma appears as%@EH@% a placeholder for the %@AI@%mapfile%@AE@% specification on the command line.%@NL@% %@NL@% LINK FUN,;%@NL@% LINK FUN;%@NL@% %@NL@% %@CR:MCVD2259@%%@4@%These command lines do not produce a map file, since commas do not appear as%@EH@% placeholders for the %@AI@%mapfile%@AE@% specification.%@NL@% %@NL@% LINK MAIN+GETDATA+PRINTIT, , MAIN;%@NL@% %@NL@% %@CR:MCVD225A@%%@4@%The command in the line above causes LINK to link the files %@AS@%MAIN.OBJ%@AE@%,%@EH@% %@AS@%GETDATA.OBJ%@AE@%, and %@AS@%PRINTIT.OBJ%@AE@% into a real-mode executable file since there is no module-definition file. A map file named %@AS@%MAIN.MAP%@AE@% is also produced.%@NL@% %@NL@% LINK GETDATA+PRINTIT, , , MODDEF%@NL@% %@NL@% %@CR:MCVD225B@%%@4@%This command causes LINK to link %@AS@%GETDATA.OBJ%@AE@% and%@AS@%PRINTIT.OBJ%@AE@% into an OS/2%@EH@% dynamic-link library if %@AS@%MODDEF.DEF%@AE@% contains a %@AB@%LIBRARY%@AE@% statement. Otherwise, an OS/2 protected-mode application is produced.%@NL@% %@NL@% %@NL@% %@CR:MCVD2300@%%@3@%%@AB@%13.2.3 Linking with the LINK Prompts%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2301@%%@4@%If you want to use the LINK prompts to specify input to the linker, start%@EH@% the linker by typing LINK at the DOS command level. LINK prompts you for the input it needs by displaying the following lines, one at a time:%@NL@% %@NL@% Object Modules [.OBJ]:%@NL@% Run File [%@AI@%basename%@AE@%.EXE]:%@NL@% List File [NUL.MAP]:%@NL@% Libraries [.LIB]:%@NL@% Definitions File [NUL.DEF]:%@NL@% %@NL@% %@CR:MCVD2302@%%@4@%LINK waits for you to respond to each prompt before printing the next one.%@EH@% Section 13.2.1%@BO: 892c3@% gives the rules for specifying file names in response to these prompts.%@NL@% %@NL@% %@CR:MCVD2303@%%@4@%The responses you give to the LINK command prompts correspond to the fields%@EH@% on the LINK command line. (See Section 13.2.2%@BO: 89934@% for a discussion of the LINK command line.) The following list shows these correspondences:%@NL@% %@NL@% %@CR:MCVD2304@%%@AB@%Prompt Command-Line Fields%@AE@%%@NL@% %@NL@% %@AS@%Object Module%@AE@% %@AI@%objfiles%@AE@%%@NL@% %@NL@% %@AS@%Run File%@AE@% %@AI@%exefile%@AE@%%@NL@% %@NL@% %@AS@%List File%@AE@% %@AI@%mapfile%@AE@%%@NL@% %@NL@% %@AS@%Libraries%@AE@% %@AI@%libraries%@AE@%%@NL@% %@NL@% %@AS@%Definitions File%@AE@% %@AI@%deffile%@AE@%%@NL@% %@NL@% %@CR:MCVD2305@%%@4@%If a plus sign (%@AB@%+%@AE@%) is the last character you type on a response line, the%@EH@% prompt appears on the next line, and you can continue typing responses. In this case, the plus sign must appear at the end of a complete file or library name, path name, or drive name.%@NL@% %@NL@% %@CR:MCVD2306@%%@4@%To select the default response to the current prompt, type a carriage return%@EH@% without giving a file name. The next prompt will appear.%@NL@% %@NL@% %@CR:MCVD2307@%%@4@%To select default responses to the current prompt and all remaining prompts,%@EH@% type a semicolon (%@AB@%;%@AE@%) followed immediately by a carriage return. After you enter a semicolon, you cannot respond to any of the remaining prompts for that link session. Use this option to save time when you want to use the default responses. However, you cannot enter a semicolon in response to the %@AS@%Object Modules%@AE@% prompt, because there is no default response for that prompt.%@NL@% %@NL@% %@CR:MCVD2308@%%@4@%The following list shows the defaults for the other linker prompts:%@EH@%%@NL@% %@NL@% %@CR:MCVD2309@%%@AB@%Prompt Default%@AE@%%@NL@% %@NL@% %@AS@%Run File%@AE@% The name of the first object file submitted for%@NL@% the %@AS@%Object%@AE@% %@AS@%modules%@AE@% prompt, with the .EXE%@NL@% extension replacing the .OBJ extension%@NL@% %@NL@% %@AS@%List File%@AE@% The special file name NUL.MAP, which tells LINK%@AI@%%@AE@%%@NL@% not to create a map file%@NL@% %@NL@% %@AS@%Libraries%@AE@% The default libraries encoded in the object%@NL@% module (see Section 13.2.5%@BO: 8d60c@%, "How LINK Searches%@NL@% for Libraries")%@NL@% %@NL@% %@AS@%Definitions File%@AE@% The special file name NUL.DEF, which tells LINK%@NL@% not to use a definitions file%@NL@% %@NL@% %@NL@% %@CR:MCVD2400@%%@3@%%@AB@%13.2.4 Linking with a Response File%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2401@%%@4@%To operate the linker with a response file, you must set up the response%@EH@% file and type the following:%@NL@% %@NL@% %@AB@%LINK @%@AE@%%@AI@%responsefile%@AE@%%@NL@% %@NL@% %@CR:MCVD2402@%%@4@%Here %@AI@%responsefile%@AE@% specifies the name or pathname of the response file that%@EH@% starts the linker. You can also enter the name of a response file after any LINK command prompt or at any position in the LINK command line.%@NL@% %@NL@% %@CR:MCVD2403@%%@4@%A response file contains responses to the LINK prompts. The responses must%@EH@% be in the same order as the LINK prompts discussed in Section 13.2.3%@BO: 8baf9@%. Each new response must appear on a new line or begin with a comma; however, you can extend long responses across more than one line by typing a plus sign (+) as the last character of each incomplete line. You may give options at the end of any response or place them on one or more separate lines.%@NL@% %@NL@% %@CR:MCVD2404@%%@4@%LINK treats the input from the response file just as if you had entered it%@EH@% in response to prompts or in a command line. It treats any carriage-return and line-feed combination in the response file the same as if you had pressed ENTER in response to a prompt or included a comma in a command line.%@NL@% %@NL@% %@CR:MCVD2405@%%@4@%You can use options and command characters in the response file in the same%@EH@% way as you would in responses you type at the keyboard. For example, if you type a semicolon on the line of the response file corresponding to the %@AS@%Run%@AE@% %@AS@%File%@AE@% prompt, LINK uses the default responses for the executable file and for the remaining prompts.%@NL@% %@NL@% %@CR:MCVD2406@%%@4@%When you enter the LINK command with a response file, each LINK prompt is%@EH@% displayed on your screen with the corresponding response from your response file. If the response file does not include a line with a file name, semicolon, or carriage return for each prompt, LINK displays the appropriate prompt and waits for you to enter a response. When you type an acceptable response, LINK continues.%@NL@% %@NL@% %@CR:MCVD2407@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2408@%%@4@%Assume that the following response file is named %@AS@%FUN.LNK%@AE@%:%@EH@%%@NL@% %@NL@% FUN TEXT TABLE CARE%@NL@% /PAUSE /MAP%@NL@% FUNLIST%@NL@% GRAF.LIB%@NL@% %@NL@% %@CR:MCVD2409@%%@4@%You can type the following command to run LINK and tell it to use the%@EH@% responses in %@AS@%FUN.LNK%@AE@%:%@NL@% %@NL@% LINK @FUN.LNK%@NL@% %@NL@% %@CR:MCVD240A@%%@4@%The response file tells LINK to load the four object modules %@AS@%FUN%@AE@%, %@AS@%TEXT%@AE@%,%@EH@% %@AS@%TABLE%@AE@%, and %@AS@%CARE%@AE@%. LINK produces an executable file named %@AS@%FUN.EXE%@AE@% and a map file named %@AS@%FUNLIST.MAP%@AE@%. The %@AS@%/PAUSE%@AE@% option tells LINK to pause before it produces the executable file so you can swap disks, if necessary. The %@AS@%/MAP%@AE@% option tells LINK to include public symbols and addresses in the map file. LINK also links any needed routines from the library file %@AS@%GRAF.LIB%@AE@%. See the discussions of the /PAUSE and /MAP options in Sections 13.3.28%@BO: 98338@% and 13.3.15%@BO: 94620@%, respectively, for more information about these options.%@NL@% %@NL@% %@NL@% %@CR:MCVD2500@%%@3@%%@AB@%13.2.5 How LINK Searches for Libraries%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2501@%%@4@%The material in this section does not apply to libraries that LINK finds in%@EH@% the %@AI@%objectfiles%@AE@% field, either on the command line or in response to the %@AS@%Object Modules%@AE@% prompt. Those libraries are treated simply as a series of object files, and LINK does not conduct extensive searches in such cases.%@NL@% %@NL@% %@CR:MCVD2502@%%@4@%LINK may be directed to find a particular library by the user (who specifies%@EH@% a library in the %@AI@%libraries%@AE@% field) or by an object module. (When a compiler creates an object module from a higher-level-language program, that object module will contain the names of one or more "default" libraries.) However the linker is directed to a library, LINK uses the same method for finding that library.%@NL@% %@NL@% %@CR:MCVD2503@%%@4@%If the library name includes a path specification, LINK searches only that%@EH@% directory for the library. Libraries specified by object modules (that is, default libraries) will normally not include a path specification.%@NL@% %@NL@% %@CR:MCVD2504@%%@4@%If a library name is given without a path specification, LINK searches in%@EH@% the following three locations to find the given library file:%@NL@% %@NL@% %@CR:MCVD2505@% 1. The current working directory%@NL@% %@NL@% 2. Any path specifications or drive names that you give on the command%@NL@% line or type in response to the %@AS@%Libraries%@AE@% prompt, in the order in which%@NL@% they appear (see Section 13.2.3%@BO: 8baf9@%)%@NL@% %@NL@% 3. The locations given by the LIB environment variable%@NL@% %@NL@% %@CR:MCVD2506@%%@4@%Because object files created by compilers and assemblers usually contain the%@EH@% names of all the standard libraries you need, you are not required to specify a library on the LINK command line or in response to the LINK %@AS@%Libraries%@AE@% prompt unless you want to do one of the following:%@NL@% %@NL@% %@CR:MCVD2507@% ■ Add the names of additional libraries to be searched%@NL@% %@NL@% ■ Search for libraries in different locations%@NL@% %@NL@% ■ Override the use of one or more default libraries%@NL@% %@NL@% %@CR:MCVD2508@%%@4@%For example, if you have developed your own customized libraries, you might%@EH@% want to include one or more of them as additional libraries at linking time.%@NL@% %@NL@% %@CR:MCVD2510@%%@4@%%@AB@%Searching Additional Libraries%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2511@%%@4@%You can tell LINK to search additional libraries by specifying one or more%@EH@% library files on the command line or in response to the %@AS@%Libraries%@AE@% prompt. LINK searches these libraries before it searches default libraries. It searches these libraries in the order you specify.%@NL@% %@NL@% %@CR:MCVD2512@%%@4@%LINK automatically supplies the .LIB extension if you omit it from a%@EH@% library-file name. If you want to link a library file that has a different extension, be sure to specify the extension.%@NL@% %@NL@% %@CR:MCVD2520@%%@4@%%@AB@%Searching Different Locations for Libraries%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2521@%%@4@%You can tell LINK to search additional locations for libraries by giving a%@EH@% drive name or path specification in the %@AI@%libraries%@AE@% field on the command line or in response to the %@AS@%Libraries%@AE@% prompt. You can specify up to 32 additional paths. If you give more than 32 paths, LINK ignores the additional paths without displaying an error message.%@NL@% %@NL@% %@CR:MCVD2530@%%@4@%%@AB@%Overriding Libraries Named in Object Files%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2531@%%@4@%If you do not want to link with the library whose name is included in the%@EH@% object file, you can give the name of a different library instead. You might want to specify a different library name in the following cases:%@NL@% %@NL@% %@CR:MCVD2532@% ■ If you assigned a "custom" name to a standard library when you set up%@NL@% your libraries%@NL@% %@NL@% ■ If you want to link with a library that supports a different math%@NL@% package other than the math package you gave on the compiler command%@NL@% line (or the default)%@NL@% %@NL@% %@CR:MCVD2533@%%@4@%If you specify a new library name on the LINK command line, the linker%@EH@% searches the new library to resolve external references before it searches the library specified in the object file.%@NL@% %@NL@% %@CR:MCVD2534@%%@4@%If you want the linker to ignore the library whose name is included in the%@EH@% object file, use the /NOD option. This option tells LINK to information that is encoded in the object files created by high-level-language compilers. Use this option with caution; see the discussion of the /NOD option in Section 13.3.16%@BO: 94e75@% for more information.%@NL@% %@NL@% %@CR:MCVD2535@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% LINK%@NL@% %@NL@% Object Modules [.OBJ]: FUN TEXT TABLE CARE%@NL@% Run File [FUN.EXE]:%@NL@% List File [NUL.MAP]:%@NL@% Libraries [.LIB]: C:\TESTLIB\ NEWLIBV3%@AB@%%@NL@% %@NL@% %@CR:MCVD2536@%%@4@%This example links four object modules to create an executable file named%@EH@% %@AS@%FUN.EXE%@AE@%. LINK searches %@AS@%NEWLIBV3.LIB%@AE@% before searching the default libraries to resolve references. To locate %@AS@%NEWLIBV3.LIB%@AE@% and the default libraries, the linker searches the current working directory, then the %@AS@%C:\TESTLIB\%@AE@% directory, and finally the locations given by the LIB environment variable. %@AS@%%@NL@% %@NL@% %@NL@% %@CR:MCVD2600@%%@3@%%@AB@%13.2.6 LINK Memory Requirements%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD2601@%%@4@%LINK uses available memory for the link session. If the files to be linked%@EH@% create an output file that exceeds available memory, LINK creates a temporary disk file to serve as memory. This temporary file is handled in one of the following ways, depending on the DOS version:%@NL@% %@NL@% %@CR:MCVD2602@% ■ The linker will use the directory specified by the TMP environment%@NL@% variable, for the purpose of creating a temporary file. For example, if%@NL@% the TMP variable were set to %@AS@%C:\TEMPDIR%@AE@%, LINK would put the temporary%@NL@% file in %@AS@%C:\TEMPDIR%@AE@%.%@NL@% %@NL@% If there is no TMP environment variable, or if the directory specified%@NL@% by TMP does not exist, then LINK will put the temporary file in the%@NL@% current working directory.%@NL@% %@NL@% ■ If the linker is running on DOS Version 3.0 or later, it uses a DOS%@NL@% system call to create a temporary file with a unique name in the%@NL@% temporary-file directory.%@NL@% %@NL@% ■ If the linker is running on a version of DOS prior to 3.0, it creates a%@NL@% temporary file named VM.TMP.%@NL@% %@NL@% %@CR:MCVD2603@%%@4@%When the linker creates a temporary disk file, you see the message%@EH@%%@NL@% %@NL@% %@AS@%Temporary file%@AE@% %@AI@%tempfile%@AE@% %@AS@%has been created.%@AE@%%@NL@% %@AS@%Do not change diskette in drive,%@AE@% %@AI@%letter%@AE@%.%@NL@% %@NL@% %@CR:MCVD2604@%%@4@%In the message displayed above, %@AI@%tempfile%@AE@% is "%@AB@%.\%@AE@%" followed by either VM.TMP%@EH@% or a name generated by DOS, and %@AI@%letter%@AE@% is the drive containing the temporary file.%@NL@% %@NL@% %@CR:MCVD2605@%%@4@%The message %@AS@%Do not change diskette in drive%@AE@% will not appear unless the drive%@EH@% is a removable disk. After this message appears, do not remove the disk from the drive specified by %@AI@%letter%@AE@% until the link session ends. If the disk is removed, the operation of LINK is unpredictable, and you may see the following message:%@NL@% %@NL@% %@AS@%Unexpected end-of-file on scratch file%@AE@%%@NL@% %@NL@% %@CR:MCVD2606@%%@4@%When this happens, rerun the link session. The temporary file created by%@EH@% LINK is a working file only. LINK deletes it at the end of the link session.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Do not give any of your own files the name VM.TMP. The linker displays an%@NL@% error message if it encounters an existing file with this name.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD3000@%%@2@%%@AB@%13.3 Specifying Linker Options%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3001@%%@4@%This section explains how to use linker options to specify and control the%@EH@% tasks performed by LINK. All options begin with the linker's option character, the forward slash (%@AB@%/%@AE@%).%@NL@% %@NL@% %@CR:MCVD3002@%%@4@%When you use the LINK command line to invoke LINK, options can appear at the%@EH@% end of the line or after individual fields on the line. However, they must precede the comma that separates each field from the next.%@NL@% %@NL@% %@CR:MCVD3003@%%@4@%If you respond to the individual prompts for the LINK command, you can%@EH@% specify linker options at the end of any response. When you specify more than one option, you can either group the options at the end of a single response or distribute the options among several responses. Every option must begin with the slash character (%@AB@%/%@AE@%), even if other options precede it on the same line. Similarly, in a response file, options can appear on a line by themselves or after individual response lines.%@NL@% %@NL@% %@CR:MCVD3010@%%@4@%%@AB@%Abbreviations%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3011@%%@4@%Since linker options are named according to their functions, some of these%@EH@% names are quite long. You can abbreviate the options to save space and effort. Be sure that your abbreviation is unique so the linker can determine which option you want. (The minimum legal abbreviation for each option is indicated in the syntax description of the option.)%@NL@% %@NL@% %@CR:MCVD3012@%%@4@%Abbreviations must begin with the first letter of the option and must be%@EH@% continuous through the last letter typed. No gaps or transpositions are allowed. Options may be entered as uppercase or lowercase.%@NL@% %@NL@% %@CR:MCVD3020@%%@4@%%@AB@%Numerical Arguments%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3021@%%@4@%Some linker options take numeric arguments. A numeric argument can be any of%@EH@% the following:%@NL@% %@NL@% %@CR:MCVD3022@% ■ A decimal number from 0 to 65,535.%@NL@% %@NL@% ■ An octal number from 0 to 177,777. A number is interpreted as octal if%@NL@% it starts with 0. For example, the number %@AS@%10%@AE@% is interpreted as a%@NL@% decimal number, but the number %@AS@%010%@AE@% is interpreted as an octal number,%@NL@% equivalent to 8 in decimal.%@NL@% %@NL@% ■ A hexadecimal number from 0 to FFFF. A number is interpreted as%@NL@% hexa-decimal if it starts with 0X. For example, %@AS@%0X10%@AE@% is a hexadecimal%@NL@% number, equivalent to 16 in decimal.%@NL@% %@NL@% %@NL@% %@CR:MCVD3100@%%@3@%%@AB@%13.3.1 Aligning Segment Data (/A)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3101@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/A%@AE@%«%@AB@%LIGNMENT%@AE@%»%@AB@%:%@AE@%%@AI@%size%@AE@%%@NL@% %@NL@% %@CR:MCVD3102@%%@4@%The ALIGNMENT option directs LINK to align segment data in the executable%@EH@% file along the boundaries specified by %@AI@%size%@AE@%. The %@AI@%size%@AE@% argument must be a power of two. For example,%@NL@% %@NL@% /ALIGNMENT:16%@NL@% %@NL@% %@CR:MCVD3103@%%@4@%indicates an alignment boundary of 16 bytes. The default alignment for%@EH@% OS/2-application and dynamic-link segments is 512. This option is used for linking Windows applications or protected-mode programs.%@NL@% %@NL@% %@NL@% %@CR:MCVD3200@%%@3@%%@AB@%13.3.2 Running in Batch Mode (/BA)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3201@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/BA%@AE@%«%@AB@%TCH%@AE@%»%@NL@% %@NL@% %@CR:MCVD3202@%%@4@%By default, the linker prompts you for a new path name whenever it cannot%@EH@% find a library it has been directed to use. It also prompts you if it cannot find an object file, and it expects that file to be on a removable disk. If the /BA option is used, however, the linker will not prompt you for any libraries or object files it cannot find. Instead, the linker will generate an error or warning message, if appropriate. The /BA option also prevents LINK from printing the sign-on banner and echoing input from response files.%@NL@% %@NL@% %@CR:MCVD3203@%%@4@%Using this option can cause unresolved external references. It is intended%@EH@% primarily for users who use batch or MAKE files for linking many executable files with a single command, and who wish to prevent linker operation from halting.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% This option does %@AI@%not%@AE@% prevent the linker from prompting for command-line%@NL@% arguments. You can prevent such prompting only by using a semicolon on%@NL@% the command line.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD3300@%%@3@%%@AB@%13.3.3 Producing a .COM File (/BI)%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%/BI%@AE@%«%@AB@%NARY%@AE@%»%@NL@% %@NL@% %@CR:MCVD3301@%%@4@%The /BI option directs the linker to produce a .COM file instead of an .EXE%@EH@% file. Not every program can be produced in the .COM format. The following restrictions apply:%@NL@% %@NL@% %@CR:MCVD3302@% 1. The program must consist of only one physical segment. If you have%@NL@% written an assembly-language program, you can declare more than one%@NL@% segment; however, the segments must be in the same group.%@NL@% %@NL@% 2. The code must have no far-segment references.%@NL@% %@NL@% Specifically, segment addresses cannot be used as immediate data for%@NL@% instructions. You could not, for example, use the following%@NL@% instruction:%@NL@% %@NL@% %@AS@%mov ax,CODESEG%@AE@%%@NL@% %@NL@% 3. Programs for the Windows and OS/2 protected-mode environments cannot be%@NL@% converted to .COM file.%@NL@% %@NL@% %@CR:MCVD3303@%%@4@%When you use the /BI option, the default file extension of the output file%@EH@% is .COM rather than .EXE.%@NL@% %@NL@% %@NL@% %@CR:MCVD3400@%%@3@%%@AB@%13.3.4 Preparing for Debugging (/CO)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3401@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/CO%@AE@%«%@AB@%DEVIEW%@AE@%»%@NL@% %@NL@% %@CR:MCVD3402@%%@4@%The /CO option is used to prepare for debugging with the CodeView%@EH@% window-oriented debugger. This option tells the linker to prepare a special executable file containing symbolic data and line-number information.%@NL@% %@NL@% %@CR:MCVD3403@%%@4@%You can run this executable file outside the CodeView debugger; the extra%@EH@% data in the file will be ignored. However, to keep file size to a minimum, use the special-format executable file only for debugging. You can then link a separate version without the /CO option after the program is debugged.%@NL@% %@NL@% %@NL@% %@CR:MCVD3500@%%@3@%%@AB@%13.3.5 Setting the Maximum Allocation Space (/CP)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3501@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/CP%@AE@%«%@AB@%ARMAXALLOC%@AE@%»%@AB@%:%@AE@%%@AI@%number%@AE@%%@NL@% %@NL@% %@CR:MCVD3502@%%@4@%The /CP option sets the maximum number of 16-byte paragraphs needed by the%@EH@% program when it is loaded into memory. The operating system uses this value when allocating space for the program before loading it. The option is useful when you want to execute another program from within your program and you need to reserve space for the executed program. This option is valid only when linking real-mode programs.%@NL@% %@NL@% %@CR:MCVD3503@%%@4@%LINK normally requests the operating system to set the maximum number of%@EH@% paragraphs to 65,535. Since this represents more memory than could be available under DOS, the operating system always denies the request and allocates the largest contiguous block of memory it can find. If the /CP option is used, the operating system allocates no more space than the option specified. This means any additional space in memory is free for other programs.%@NL@% %@NL@% %@CR:MCVD3504@%%@4@%The %@AI@%number%@AE@% can be any integer value in the range 1 to 65,535. If %@AI@%number%@AE@% is%@EH@% less than the minimum number of paragraphs needed by the program, LINK ignores your request and sets the maximum value equal to whatever the minimum value happens to be. The minimum number of paragraphs needed by a program is never less than the number of paragraphs of code and data in the program. To free more memory for programs compiled in the medium- and large-memory models, link with /CP:1; this leaves no space for the near heap.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% You can change the maximum allocation after linking by using the %@AI@%EXEMOD%@AE@%%@NL@% utility, which modifies the executable-file header, as described in%@NL@% Section 17.1.%@BO: ba961@% The format of the executable-file header is also discussed%@NL@% in that section, as well as in the %@AI@%Microsoft MS-DOS Programmer's%@AE@%%@NL@% %@AI@%Reference%@AE@% and in other reference books on DOS.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD3600@%%@3@%%@AB@%13.3.6 Ordering Segments (/DO)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3601@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/DO%@AE@%«%@AB@%SSEG%@AE@%»%@NL@% %@NL@% %@CR:MCVD3602@%%@4@%The /DO option is automatically enabled by a special object-module record in%@EH@% Microsoft language libraries. If you are linking to one of these libraries, you do not need to specify this option.%@NL@% %@NL@% %@CR:MCVD3603@%%@4@%This option is also enabled by assembly modules that use the Microsoft Macro%@EH@% Assembler directive %@AB@%.DOSSEG%@AE@%.%@NL@% %@NL@% %@CR:MCVD3604@%%@4@%The /DO option forces segments to be ordered as follows:%@EH@%%@NL@% %@NL@% %@CR:MCVD3605@% 1. All segments with a class name ending in CODE%@NL@% %@NL@% 2. All other segments outside DGROUP%@NL@% %@NL@% 3. DGROUP segments, in the following order:%@NL@% %@NL@% a. Any segments of class BEGDATA (this class name reserved for Microsoft use)%@NL@% %@NL@% b. Any segments not of class BEGDATA, BSS, or STACK%@NL@% %@NL@% c. Segments of class BSS%@NL@% %@NL@% d. Segments of class STACK%@NL@% %@NL@% %@CR:MCVD3606@%%@4@%Note that when the /DO option is in effect the linker initializes two%@EH@% special variables as follows:%@NL@% %@NL@% _edata = DGROUP : BSS%@NL@% _end = DGROUP : STACK%@NL@% %@NL@% %@CR:MCVD3607@%%@4@%The variables %@AS@%_edata%@AE@% and %@AS@%_end%@AE@% have special meanings for the Microsoft C and%@EH@% FORTRAN compilers, so it is not wise to give these names to your own program variables. Assembly modules can reference these variables but should not change them.%@NL@% %@NL@% %@NL@% %@CR:MCVD3700@%%@3@%%@AB@%13.3.7 Controlling Data Loading (/DS)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3701@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/DS%@AE@%«%@AB@%ALLOCATE%@AE@%»%@NL@% %@NL@% %@CR:MCVD3702@%%@4@%By default, LINK loads all data starting at the low end of the data segment.%@EH@% At run time, the data segment (DS) register is set to the lowest possible address to allow the entire data segment to be used. This option is valid only when linking real-mode programs.%@NL@% %@NL@% %@CR:MCVD3703@%%@4@%Use the /DS option to tell LINK to load all data starting at the high end of%@EH@% the data segment instead. In this case, the DS register is set at run time to the lowest data-segment address that contains program data.%@NL@% %@NL@% %@CR:MCVD3704@%%@4@%The /DS option is typically used with the /HI option, discussed in Section%@EH@% 13.3.11%@BO: 93a86@%, to take advantage of unused memory within the data segment.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%WARNING%@AE@%%@NL@% This option should be used only with assembly-language programs.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD3800@%%@3@%%@AB@%13.3.8 Packing Executable Files (/E)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3801@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/E%@AE@%«%@AB@%XEPACK%@AE@%»%@NL@% %@NL@% %@CR:MCVD3802@%%@4@%The /E option directs LINK to remove sequences of repeated bytes (typically%@EH@% null characters) and to optimize the load-time-relocation table before creating the executable file. (The load-time-relocation table is a table of references relative to the start of the program, each of which changes when the executable image is loaded into memory and an actual address for the entry point is assigned.)%@NL@% %@NL@% %@CR:MCVD3803@%%@4@%Executable files linked with this option may be smaller, and thus load%@EH@% faster, than files linked without this option. However, you cannot use the Symbolic Debug Utility (SYMDEB) or the CodeView window-oriented debugger to debug packed files. The /EXEPACK option strips symbolic information from the input file and notifies you of this with a warning message.%@NL@% %@NL@% %@CR:MCVD3804@%%@4@%The /E option does not always give a significant saving in disk space and%@EH@% may sometimes actually increase file size. Programs that have a large number of load-time relocations (about 500 or more) and long streams of repeated characters are usually shorter if packed. LINK notifies you if the packed file is larger than the unpacked file.%@NL@% %@NL@% %@NL@% %@CR:MCVD3900@%%@3@%%@AB@%13.3.9 Optimizing Far Calls (/F)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3901@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/F%@AE@%«%@AB@%ARCALLTRANSLATION%@AE@%»%@NL@% %@NL@% %@CR:MCVD3902@%%@4@%Using the /F option may result in slightly faster code and smaller%@EH@% executable-file size. It should be used with the /PACKD option, described in Section 13.3.25%@BO: 97257@%, in order to achieve significant results. The gain in speed is most apparent for 286- and 386-based machines. Though some assembly programs should not be linked with this option, it is generally safe for use with high-level-language programs. This option is off by default; furthermore, it can always be turned off with the /NOF option described in Section 13.3.18.%@BO: 95405@%%@NL@% %@NL@% %@CR:MCVD3903@%%@4@%The rest of this section describes the low-level details of /F. It is not%@EH@% necessary that you understand these details in order to use the option.%@NL@% %@NL@% %@CR:MCVD3904@%%@4@%The /F option directs the linker to optimize far calls to procedures that%@EH@% lie in the same segment as the caller. For example, a medium- or large-model program may have a machine instruction that makes a far call to a procedure in the same segment. Since the segment address is the same (for both the instruction and the procedure it calls), only a near call should be necessary.%@NL@% %@NL@% %@CR:MCVD3905@%%@4@%A near-call instruction does not require an entry in the relocation table,%@EH@% whereas a far-call instruction does. Therefore, use of /F (together with /PACKD) often results in smaller executable files because the relocation table is smaller. Such files will load faster.%@NL@% %@NL@% %@CR:MCVD3906@%%@4@%When /F has been specified, the linker will optimize code by removing the%@EH@% instruction %@AS@%call FAR label%@AE@% and substituting the following sequence:%@NL@% %@NL@% push cs%@NL@% call NEAR %@AI@%label%@AE@%%@NL@% nop%@NL@% %@NL@% %@CR:MCVD3907@%%@4@%Upon execution, the called procedure will still return with a far-return%@EH@% instruction. However, because both the code segment and the near address are on the stack, the far return will be executed correctly. The %@AS@%nop%@AE@% (no-op) instruction appears so that exactly five bytes replace the five-byte far-call instruction; the linker may in some cases place the %@AS@%nop%@AE@% at the beginning of the sequence.%@NL@% %@NL@% %@CR:MCVD3908@%%@4@%The /F option has no effect on programs that only make near calls. Of the%@EH@% high-level Microsoft languages, only small- and compact-model C programs use near calls.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% There is a small risk involved with the /F option: the linker may%@NL@% mistakenly translate a byte in a code segment that happens to have the%@NL@% far-call opcode (9A hexadecimal). If a program linked with /F%@NL@% inexplicably fails, you may want to try linking with this option off.%@NL@% However, object modules produced by Microsoft high-level languages should%@NL@% be safe from this problem because little immediate data is stored in code%@NL@% segments.%@NL@% %@NL@% In general, assembly-language programs are safe for use with the /F%@NL@% option if they do not involve advanced system-level code, such as might%@NL@% be found in operating systems or interrupt handlers.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD3A00@%%@3@%%@AB@%13.3.10 Viewing the Options List (/HE)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3A01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/HE%@AE@%«%@AB@%LP%@AE@%»%@NL@% %@NL@% %@CR:MCVD3A02@%%@4@%The /HELP option causes LINK to display a list of the available options on%@EH@% the screen. This gives you a convenient reminder of the available options. Do not give a file name when using the /HELP option.%@NL@% %@NL@% %@NL@% %@CR:MCVD3B00@%%@3@%%@AB@%13.3.11 Controlling Executable-File Loading (/HI)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3B01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/HI%@AE@%«%@AB@%GH%@AE@%»%@NL@% %@NL@% %@CR:MCVD3B02@%%@4@%At load time, the executable file can be placed either as low or as high in%@EH@% memory as possible. Use of the /HI option causes DOS to place the executable file as high as possible in memory. Without the /HI option, DOS places the executable file as low as possible. This option is valid only when linking real-mode programs.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% This option should be used only with assembly-language programs.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD3C00@%%@3@%%@AB@%13.3.12 Preparing for Incremental Linking (/INC)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3C01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/INC%@AE@%«%@AB@%REMENTAL%@AE@%»%@NL@% %@NL@% %@CR:MCVD3C02@%%@4@%The /INC option must be used in order to prepare for subsequent linking with%@EH@% ILINK. The use of this option produces a .SYM file and an .ILK file, each containing extra information needed by ILINK. Note that this option is not compatible with the /EXEPACK option. (See Chapter 14%@BO: 9eada@%, "Incremental Linking with ILINK," for more information on this option.)%@NL@% %@NL@% %@NL@% %@CR:MCVD3D00@%%@3@%%@AB@%13.3.13 Displaying Linker Process Information (/INF)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3D01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/INF%@AE@%«%@AB@%ORMATION%@AE@%»%@NL@% %@NL@% %@CR:MCVD3D02@%%@4@%The /INF option tells the linker to display information about the linking%@EH@% process, including the phase of linking and the names of the object files being linked. This option is useful if you want to determine the locations of the object files being linked and the order in which they are linked.%@NL@% %@NL@% %@CR:MCVD3D03@%%@4@%Output from this option is sent to standard output.%@EH@%%@NL@% %@NL@% %@CR:MCVD3D04@%%@4@%The following is a sample of the linker output when the /INF and /MAP%@EH@% options are specified on the LINK command line:%@NL@% %@NL@% **** PASS ONE ****%@NL@% TEST.OBJ(test.for)%@NL@% **** LIBRARY SEARCH ****%@NL@% LLIBFOR7.LIB(wr)%@NL@% LLIBFOR7.LIB(fmtout)%@NL@% LLIBFOR7.LIB(ldout)%@NL@% .%@NL@% .%@NL@% .%@NL@% **** ASSIGN ADDRESSES ****%@NL@% 1 segment "TEST_TEXT" length 122H bytes%@NL@% 2 segment "_DATA" length 912H bytes%@NL@% 3 segment "CONST" length 12H bytes%@NL@% .%@NL@% .%@NL@% .%@NL@% **** PASS TWO ****%@NL@% TEST.OBJ(test.for)%@NL@% LLIBFOR7.LIB(wr)%@NL@% LLIBFOR7.LIB(fmtout)%@NL@% LLIBFOR7.LIB(ldout)%@NL@% .%@NL@% .%@NL@% .%@NL@% **** WRITING EXECUTABLE ****%@NL@% %@NL@% %@NL@% %@CR:MCVD3E00@%%@3@%%@AB@%13.3.14 Including Line Numbers in the Map File (/LI)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3E01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/LI%@AE@%«%@AB@%NENUMBERS%@AE@%»%@NL@% %@NL@% %@CR:MCVD3E02@%%@4@%You can include the line numbers and associated addresses of your source%@EH@% program in the map file by using the /LI option. Ordinarily the map file does not contain line numbers. To produce a map file with line numbers, you must give LINK an object file (or files) with line-number information. You can use the /Zd option with any Microsoft compiler to include line numbers in the object file. If you give LINK an object file without line-number information, the /LI option has no effect.%@NL@% %@NL@% %@CR:MCVD3E03@%%@4@%The /LI option forces LINK to create a map file even if you did not%@EH@% explicitly tell the linker to create a map file. By default, the file is given the same base name as the executable file, plus the extension .MAP. You can override the default name by specifying a new map file on the LINK command line or in response to the %@AS@%List File%@AE@% prompt.%@NL@% %@NL@% %@NL@% %@CR:MCVD3F00@%%@3@%%@AB@%13.3.15 Listing Public Symbols (/M)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3F01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/M%@AE@%«%@AB@%AP%@AE@%»%@NL@% %@NL@% %@CR:MCVD3F02@%%@4@%You can list all public (global) symbols defined in the object file(s) by%@EH@% using the /M option. When you invoke LINK with the /M option, the map file will contain a list of all the symbols sorted by name and a list of all the symbols sorted by address. If you do not use this option, the map file contains only a list of segments.%@NL@% %@NL@% %@CR:MCVD3F03@%%@4@%When you use this option, the default for the %@AI@%mapfile%@AE@% field or prompts%@EH@% response is no longer NUL. Instead, the default is a name that combines the base name of the executable file with a .MAP extension. It is still possible for you to specify NUL in the %@AI@%mapfile%@AE@% field (which indicates that no map file is to be generated); if you do, then the /M option will have no effect.%@NL@% %@NL@% %@NL@% %@CR:MCVD3G00@%%@3@%%@AB@%13.3.16 Ignoring Default Libraries (/NOD)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3G01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/NOD%@AE@%«%@AB@%EFAULTLIBRARYSEARCH%@AE@%»«%@AB@%:%@AE@%%@AI@%filename%@AE@%»%@NL@% %@NL@% %@CR:MCVD3G02@%%@4@%The /NOD option tells LINK not to search any library specified in the object%@EH@% file to resolve external references. If you specify %@AI@%filename%@AE@%, LINK searches all libraries specified in the object file except for %@AI@%filename%@AE@%.%@NL@% %@NL@% %@CR:MCVD3G03@%%@4@%In general, higher-level-language programs do not work correctly without a%@EH@% standard library. Thus, if you use the /NOD option, you should explicitly specify the name of a standard library.%@NL@% %@NL@% %@NL@% %@CR:MCVD3H00@%%@3@%%@AB@%13.3.17 Ignoring Extended Dictionary (/NOE)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3H01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/NOE%@AE@%«%@AB@%XTDICTIONARY%@AE@%»%@NL@% %@NL@% %@CR:MCVD3H02@%%@4@%The /NOE option prevents the linker from searching the extended dictionary,%@EH@% which is an internal list of symbol locations that the linker maintains. Normally, the linker consults this list to speed up library searches.The effect of the /NOE option is to slow the linker. You often need to use this option when a library symbol is redefined. The linker issues error %@AS@%L2044%@AE@% if you need to use this option.%@NL@% %@NL@% %@NL@% %@CR:MCVD3I00@%%@3@%%@AB@%13.3.18 Disabling Far-Call Optimization (/NOF)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3I01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/NOF%@AE@%«%@AB@%ARCALLTRANSLATION%@AE@%»%@NL@% %@NL@% %@CR:MCVD3I02@%%@4@%This option normally is not necessary because far-call optimization%@EH@% (translation) is turned off by default. However, if an environment variable such as LINK (or CL) turns on far-call translation automatically, you can use /NOF to turn far-call translation back off again.%@NL@% %@NL@% %@NL@% %@CR:MCVD3J00@%%@3@%%@AB@%13.3.19 Preserving Compatibility (/NOG)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3J01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/NOG%@AE@%«%@AB@%ROUPASSOCIATION%@AE@%»%@NL@% %@NL@% %@CR:MCVD3J02@%%@4@%The /NOG option causes the linker to ignore group associations when%@EH@% assigning addresses to data and code items. It is provided primarily for compatibility with previous versions of the linker (Versions 2.02 and earlier) and early versions of Microsoft language compilers. This option is valid only when linking real-mode programs.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% This option should be used only with assembly-language programs.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD3K00@%%@3@%%@AB@%13.3.20 Preserving Case Sensitivity (/NOI)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3K01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/NOI%@AE@%«%@AB@%GNORECASE%@AE@%»%@NL@% %@NL@% %@CR:MCVD3K02@%%@4@%By default, LINK treats uppercase letters and lowercase letters as%@EH@% equivalent. Thus %@AS@%ABC%@AE@%, %@AS@%abc%@AE@%, and %@AS@%Abc%@AE@% are considered the same name. When you use the /NOI option, the linker distinguishes between uppercase letters and lowercase letters, and considers %@AS@%ABC%@AE@%, %@AS@%abc%@AE@%, and %@AS@%Abc%@AE@% to be three separate names. Since names in some high-level languages are not case sensitive, this option can have minimal importance. However, in some languages──such as C──case is significant. If you plan to link your files from other high-level languages with C routines, you may want to use this option.%@NL@% %@NL@% %@NL@% %@CR:MCVD3L00@%%@3@%%@AB@%13.3.21 Ordering Segments without Inserting NULL Bytes (/NON)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3L01@%%@4@%%@AB@%Options%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%/NON%@AE@%«%@AB@%ULLSDOSSEG»%@AE@%%@NL@% %@NL@% %@CR:MCVD3L02@%%@4@%The /NON option directs the linker to arrange segments in the same order as%@EH@% they are arranged by the /DOSSEG option. The only difference is that the /DOSSEG option inserts 16 null bytes at the beginning of the _TEXT segment (if it is defined), whereas /NON does not insert these extra bytes.%@NL@% %@NL@% %@CR:MCVD3L03@%%@4@%If the linker is given both the /DOSSEG and /NON options, the /NON option%@EH@% will always take precedence. Therefore, you can use /NON to override the /DOSSEG comment record commonly found in run-time libraries. This option is for linking protected-mode programs or Windows applications.%@NL@% %@NL@% %@NL@% %@CR:MCVD3M00@%%@3@%%@AB@%13.3.22 Disabling Segment Packing (/NOP)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3M01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/NOP%@AE@%«%@AB@%ACKCODE%@AE@%»%@NL@% %@NL@% %@CR:MCVD3M02@%%@4@%This option is normally not necessary because code-segment packing is turned%@EH@% off by default. However, if an environment variable such as LINK (or CL) turns on code-segment packing automatically, you can use /NOP to turn segment packing back off again.%@NL@% %@NL@% %@NL@% %@CR:MCVD3N00@%%@3@%%@AB@%13.3.23 Setting the Overlay Interrupt (/O)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3N01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/O%@AE@%«%@AB@%VERLAYINTERRUPT%@AE@%»%@AB@%:%@AI@%number%@AE@%%@NL@% %@NL@% %@CR:MCVD3N02@%%@4@%By default, the interrupt number used for passing control to overlays is 63%@EH@% (3F hexadecimal). The /O option allows the user to select a different interrupt number. This option is valid only when linking real-mode programs.%@NL@% %@NL@% %@CR:MCVD3N03@%%@4@%The %@AI@%number%@AE@% can be a decimal number from 0 to 255, an octal number from octal%@EH@% 0 to octal 0377, or a hexadecimal number from hexadecimal 0 to hexadecimal FF. Numbers that conflict with DOS interrupts can be used; however, their use is not advised.%@NL@% %@NL@% %@CR:MCVD3N04@%%@4@%You should use this option only when you want to uses overlays with a%@EH@% program that already reserves interrupt 63 for some other purpose.%@NL@% %@NL@% %@NL@% %@CR:MCVD3O00@%%@3@%%@AB@%13.3.24 Packing Contiguous Data Segments (/PACKC)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3O01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/PACKC%@AE@%«%@AB@%ODE%@AE@%»«%@AB@%:%@AE@%%@AI@%number%@AE@%»%@NL@% %@NL@% %@CR:MCVD3O02@%%@4@%This option only affects code segments in medium- and large-model programs.%@EH@% It is intended to be used with the /F option, which is described in Section 13.3.9.%@BO: 92ae0@% It is not necessary to understand the details of the /PACKC option in order to use it. You only need to know that this option, used in conjunction with /F, produces slightly faster and more compact code. The /PACKC option is off by default, and can always be turned off with the /NOP option described in Section 13.3.22.%@BO: 96061@%%@NL@% %@NL@% %@CR:MCVD3O03@%%@4@%The /PACKC option directs the linker to group together neighboring code%@EH@% segments. Segments in the same group are assigned the same segment address; offset addresses are adjusted upward accordingly. In other words, all items will have the correct physical address whether the /PACKC option is used or not. However, /PACKC changes segment and offset addresses so that all items in a group share the same segment address.%@NL@% %@NL@% %@CR:MCVD3O04@%%@4@%The %@AI@%number%@AE@% field specifies the maximum size of groups formed by /PACKC. The%@EH@% linker will stop adding segments to a group as soon as it cannot add another segment without exceeding %@AI@%number%@AE@%. At that point, the linker starts forming a new group. The default for %@AI@%number%@AE@% is 65,530.%@NL@% %@NL@% %@CR:MCVD3O05@%%@4@%The packaging of code segments provides more opportunities for far-call%@EH@% optimization, which is enabled with /F. Generally speaking, /F and /PACKC are designed to be used together.%@NL@% %@NL@% %@CR:MCVD3O06@%%@4@%Programs developed with Microsoft high-level languages can safely use%@EH@% /PACKC. The /PACKC option is unsafe only when used with assembly programs that make assumptions about the relative order of code segments. For example, the following assembly code attempts to calculate the distance between %@AS@%CSEG1%@AE@% and %@AS@%CSEG2%@AE@%. This code would produce incorrect results when used with /PACKC, because /PACKC causes the two segments to share segment address. Therefore the procedure would always return zero.%@NL@% %@NL@% CSEG1 SEGMENT PUBLIC 'CODE'%@NL@% .%@NL@% .%@NL@% .%@NL@% CSEG1 ENDS%@NL@% %@NL@% CSEG2 SEGMENT PARA PUBLIC 'CODE'%@NL@% ASSUME cs:CSEG2%@NL@% %@NL@% %@AI@%; Return the length of CSEG1 in AX.;%@AE@%%@NL@% %@NL@% codesize PROC NEAR%@NL@% mov ax,CSEG2 %@AI@%; Load para address of CSEG1;%@AE@%%@NL@% sub ax,CSEG1 %@AI@%; Load para address of CSEG2;%@AE@%%@NL@% mov cx,4 %@AI@%; Load count, and%@AE@%%@NL@% shl ax,c l %@AI@%; convert distance from paragraphs%@AE@%%@NL@% %@AI@%; to bytes;%@AE@%%@NL@% codesize ENDP%@NL@% %@NL@% CSEG2 ENDS%@NL@% %@NL@% %@NL@% %@CR:MCVD3P00@%%@3@%%@AB@%13.3.25 Packing Contiguous Data Segments (/PACKD)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3P01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/PACKD%@AE@%«%@AB@%ATA%@AE@%»«%@AB@%:%@AE@%%@AI@%number%@AE@%»%@NL@% %@NL@% %@CR:MCVD3P02@%%@4@%This option only affects code segments in medium- and large-model programs.%@EH@% This option is also safe with all Microsoft high-level language compilers. It behaves exactly like /PACKCODE except it applies to data segments, not code segments. The linker recognizes data segments as any segment definition with a class name which does not end in %@AS@%CODE%@AE@%. The adjacent data segment definitions are combined into the same physical segment up to the given limit. The default limit is 65,536.%@NL@% %@NL@% %@CR:MCVD3P03@%%@4@%With large and compact-model programs containing many modules, it may be%@EH@% necessary to use this option to get around the limit of 255 physical data segments per executable file imposed by OS/2 and Windows. If you get error %@AS@%L1073%@AE@% from the liner, try using this option.%@NL@% %@NL@% %@CR:MCVD3P04@%%@4@%The %@AI@%number%@AE@% field specifies the maximum size of groups formed by /PACKD. The%@EH@% linker will stop adding segments to a group as soon as it cannot add another segment without exceeding %@AI@%number%@AE@%. At that point, the linker starts forming a new group. The default for %@AI@%number%@AE@% is 65,530.%@NL@% %@NL@% %@CR:MCVD3P05@%%@4@%This option may not be safe with other compilers that do not generate fixup%@EH@% records for all far data references. This option is valid for OS/2 and Windows programs only.%@NL@% %@NL@% %@NL@% %@CR:MCVD3Q00@%%@3@%%@AB@%13.3.26 Padding Code Segments (/PADC)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3Q01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/PADC%@AE@%«%@AB@%ODE%@AE@%»%@AB@%:%@AE@%%@AI@%padsize%@AE@%%@NL@% %@NL@% %@CR:MCVD3Q02@%%@4@%The /PADC option causes LINK to add filler bytes to the end of each code%@EH@% module for subsequent linking with ILINK. The option is followed by a colon and the number of bytes to add. (A decimal radix is assumed, but you can specify octal or hexadecimal numbers by using a C-language prefix.) Thus%@NL@% %@NL@% /PADCODE:256%@NL@% %@NL@% %@CR:MCVD3Q03@%%@4@%adds an additional 256 bytes to each module. The default size for%@EH@% code-module padding is 0 bytes. If you are going to use this option, you must also specify the /INC option.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Code padding is usually not necessary for large-and medium-memory-model%@NL@% programs, but is recommended for small-compact and mixed-memory-model%@NL@% programs, and for Microsoft Macro Assembler (%@AB@%MASM%@AE@%) programs in which%@NL@% code segments are grouped.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVD3Q04@%%@4@%To be recognized as a code segment, a segment must be declared with class%@EH@% name 'CODE'. The class name need only end with 'CODE' (Microsoft high-level languages automatically use this declaration for code segments.)%@NL@% %@NL@% %@NL@% %@CR:MCVD3R00@%%@3@%%@AB@%13.3.27 Padding Data Segments (/PADD)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3R01@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%/PADD%@AE@%«%@AB@%ATA%@AE@%»%@AB@%:%@AE@%%@AI@%padsize%@AE@%%@NL@% %@NL@% %@CR:MCVD3R02@%%@4@%The /PADD option performs a function similar to the /PADCODE option, except%@EH@% it specifies padding for data segments (or data modules, if the program uses small- or medium-memory model). This option is supplied for subsequent linking with ILINK. Thus%@NL@% %@NL@% /PADDATA:32%@NL@% %@NL@% %@CR:MCVD3R03@%%@4@%adds an additional 32 bytes to each data module. The default size for%@EH@% data-segment padding is 16 bytes. If you are going to use the /PADD option, you must also specify the /INC option.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% If you specify too large a value for %@AI@%padsize%@AE@%, you may exceed the 64K%@NL@% limitation on the size of the default data segment.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD3S00@%%@3@%%@AB@%13.3.28 Pausing during Linking (/PAU)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3S01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/PAU%@AE@%«%@AB@%SE%@AE@%»%@NL@% %@NL@% %@CR:MCVD3S02@%%@4@%Unless you instruct it otherwise, LINK performs the linking session from%@EH@% beginning to end without stopping. The /PAU option tells LINK to pause in the session before it writes the executable (.EXE) file to disk. This option allows you to swap disks before LINK writes the executable file.%@NL@% %@NL@% %@CR:MCVD3S03@%%@4@%If you specify the /PAU option, LINK displays the following message before%@EH@% it creates the run file:%@NL@% %@NL@% %@AS@%About to generate .EXE file%@AE@%%@NL@% %@AS@%Change diskette in drive%@AE@% %@AI@%letter%@AE@%%@AS@% and press <ENTER>%@AE@%%@NL@% %@NL@% %@CR:MCVD3S04@%%@4@%The %@AI@%letter%@AE@% corresponds to the current drive. LINK resumes processing when%@EH@% you press ENTER .%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Do not remove the disk that will receive the list file or the disk used%@NL@% for the temporary file.%@NL@% %@NL@% If a temporary file is created on the disk you plan to swap, press CTRL+C%@NL@% to terminate the LINK session. Rearrange your files so that the temporary%@NL@% file and the executable file can be written to the same disk. Then try%@NL@% linking again.%@NL@% %@NL@% For more information on how LINK determines where to put the temporary%@NL@% file, see Section 13.2.6%@BO: 8ebda@%, "LINK Memory Requirements."%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD3T00@%%@3@%%@AB@%13.3.29 Specifying User Libraries for Quick Languages (/Q)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3T01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/Q%@AE@%«%@AB@%UICKLIB%@AE@%»%@NL@% %@NL@% %@CR:MCVD3T02@%%@4@%The /Q option directs the linker to produce a "Quick library,"suitable for%@EH@% use with Microsoft QuickBASIC or Microsoft QuickC(R) programs, instead of producing a stand-alone application. (Stand-alone applications are executable files that need only the presence of DOS to run. The linker produces these by default.)%@NL@% %@NL@% %@CR:MCVD3T03@%%@4@%No other option is necessary to enable Quick-library creation. When you use%@EH@% /Q, the %@AI@%exefile%@AE@% field refers to a Quick library instead of to an application. The default extension for this field is then .QLB instead of .EXE. You can use all of the linker features to build a Quick library that you would otherwise use to build an application. The principal difference is that a Quick library does not require (and should not contain) any main-program-level code.%@NL@% %@NL@% %@CR:MCVD3T04@%%@4@%A Quick library is similar to a standard software library in that both%@EH@% contain a collection of routines that may be called upon by a program. The two libraries are different, however: a standard library is brought together with a program at link time; a Quick library, by contrast, is brought together with a program at run time.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Two special restrictions apply to use of a Quick library:%@NL@% %@NL@% 1. Quick libraries can be loaded only by programs created with QuickC or%@NL@% QuickBASIC. These programs have the special code that properly loads a%@NL@% Quick library at run time.%@NL@% %@NL@% 2. Routines in a Quick library can be called from any module at run time.%@NL@% However, Quick-library routines cannot themselves make calls to routines%@NL@% outside the library. In other words, Quick libraries must be%@NL@% self-contained.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVD3T05@%%@4@%The linker creates a Quick library not by linking it to a program, but%@EH@% instead by placing into a file all of the object modules to be included and by adding a location table of all of the library routines. This table allows references to be resolved at run time, after the entire library is loaded into memory. For further information on the use of these libraries, consult the user's guide for QuickBASIC or QuickC.%@NL@% %@NL@% %@NL@% %@CR:MCVD3U00@%%@3@%%@AB@%13.3.30 Setting Maximum Number of Segments (/SE)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3U01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/SE%@AE@%«%@AB@%GMENTS%@AE@%»%@AB@%:%@AE@%%@AI@%number%@AE@%%@NL@% %@NL@% %@CR:MCVD3U02@%%@4@%The /SE option controls the number of segments the linker allows a program%@EH@% to have. The default is 128, but you can set %@AI@%number%@AE@% to any value (decimal, octal, or hexadecimal) in the range 1 to 3,072 (decimal). However, the number of segment definitions is constrained by memory usage. Therefore, the practical limit to the number is around 1,500.%@NL@% %@NL@% %@CR:MCVD3U03@%%@4@%For each segment, the linker must allocate some space to keep track of%@EH@% segment information. By using a relatively low segment limit as a default (128), the linker is able to link faster and allocate less storage space.%@NL@% %@NL@% %@CR:MCVD3U04@%%@4@%When you set the segment limit higher than 128, the linker allocates more%@EH@% space for segment information. This option allows you to raise the segment limit for programs with a large number of segments. For programs with fewer than 128 segments, you can keep the storage requirements of the linker at the lowest level possible by setting the segment %@AI@%number%@AE@% field to reflect the actual number of segments in the program. If the number of segments allocated is too high for the amount of memory LINK has available to it, you will see the following error message:%@NL@% %@NL@% %@AS@%segment limit too high%@AE@%%@NL@% %@NL@% %@CR:MCVD3U05@%%@4@%To specify a number of segments that will fit in the amount of memory%@EH@% available, set the segment lower and relink the object files.%@NL@% %@NL@% %@NL@% %@CR:MCVD3V00@%%@3@%%@AB@%13.3.31 Controlling Stack Size (/ST)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3V01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/ST%@AE@%«%@AB@%ACK%@AE@%»%@AB@%:%@AE@%%@AI@%number%@AE@%%@NL@% %@NL@% %@CR:MCVD3V02@%%@4@%The /ST option allows you to specify the size of the stack for your program.%@EH@% The %@AI@%number%@AE@% is any positive value (decimal, octal,or hexadecimal) up to 65,535 (decimal). It represents the size, in bytes, of the stack.%@NL@% %@NL@% %@CR:MCVD3V03@%%@4@%If you get a stack-overflow message, you may need to increase the size of%@EH@% the stack. In contrast, if your program uses the stack very little, you may save some space by decreasing the stack size.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% You can also use the %@AB@%EXEMOD%@AE@% utility, described in Section 17.1%@BO: ba961@%, to%@NL@% change the default stack size in DOS executable files by modifying the%@NL@% executable-file header. The format of the executable-file header is%@NL@% discussed in that section as well as in the Microsoft MS-DOS programmer's%@NL@% Reference and in other reference books on DOS.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD3W00@%%@3@%%@AB@%13.3.32 Issuing Fixup Warnings (/W)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD3W01@%%@AB@%Option%@AE@%%@NL@% %@NL@% %@AB@%/W%@AE@%«%@AB@%ARNFIXUP%@AE@%»%@NL@% %@NL@% %@CR:MCVD3W02@%%@4@%The /WARNFIXUP option directs the linker to issue a warning for each segment%@EH@% relative fixup of location-type "offset," such that the segment is contained within a group but is not at the beginning of the group. The linker will include the displacement of the segment from the group in determining the final value of the fixup, contrary to what happens with DOS executable files. This option is for linking protected-mode programs or Windows applications.%@NL@% %@NL@% %@NL@% %@CR:MCVD4000@%%@2@%%@AB@%13.4 Selecting Options with the LINK Environment Variable%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD4001@%%@4@%You can use the LINK environment variable to cause certain options to be%@EH@% used each time you link. The linker checks the environment variable for options, if the variable exists.%@NL@% %@NL@% %@CR:MCVD4002@%%@4@%The linker expects to find options listed in the variable exactly as you%@EH@% would type them on the command line. It will not accept other kinds of arguments; file names in the environment variable will cause the following error message:%@NL@% %@NL@% %@AS@%unrecognized option%@AE@%%@NL@% %@NL@% %@CR:MCVD4003@%%@4@%Each time you link, you can specify other options in addition to the ones%@EH@% specified in the LINK environment variable. If you type an option both on the command line and in the environment variable, the effect will be the same as if the option were given once.%@NL@% %@NL@% %@CR:MCVD4004@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD4005@%>SET LINK=/NOI /SE:256 /CO >LINK TEST; >LINK /NOD /CO PROG;%@NL@% %@NL@% %@CR:MCVD4006@%%@4@%In the example above, the file %@AS@%TEST.OBJ%@AE@% is linked with the options %@AS@%/NOI%@AE@%,%@EH@% %@AS@%/SE:256%@AE@%, and %@AS@%/CO%@AE@%. The file %@AS@%PROG.OBJ%@AE@% is then linked with the option %@AS@%/NOD%@AE@%, in addition to %@AS@%/NOI%@AE@%, %@AS@%/SE:256%@AE@%, and %@AS@%/CO%@AE@%.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% A command-line option will override the effect of any%@NL@% environment-variable option that it conflicts with. For example, the%@NL@% command-line option%@AS@%/SE:512%@AE@% cancels the effect of the environment-variable%@NL@% option %@AS@%/SE:256%@AE@%.%@NL@% %@NL@% The only way to prevent an option in the environment variable from being%@NL@% used is to reset the environment variable itself.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVD5000@%%@2@%%@AB@%13.5 Linker Operation%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD5001@%%@4@%LINK performs the following steps to combine object modules and produce an%@EH@% executable file:%@NL@% %@NL@% %@CR:MCVD5002@% 1. Reads the object modules submitted%@NL@% %@NL@% 2. Searches the given libraries, if necessary, to resolve external%@NL@% references%@NL@% %@NL@% 3. Assigns addresses to segments%@NL@% %@NL@% 4. Assigns addresses to public symbols%@NL@% %@NL@% 5. Reads code and data in the segments%@NL@% %@NL@% 6. Reads all relocation references in object modules%@NL@% %@NL@% 7. Performs fixups%@NL@% %@NL@% 8. Outputs an executable file (executable image and relocation%@NL@% information)%@NL@% %@NL@% %@CR:MCVD5003@%%@4@%Steps 5, 6, and 7 are performed concurrently──in other words, LINK moves%@EH@% back and forth between these steps before it progresses to step 8.%@NL@% %@NL@% %@CR:MCVD5004@%%@4@%The "executable image" contains the code and data that constitute the%@EH@% executable file. The "relocation information" is a list of references relative to the start of the program, each of which changes when the executable image is loaded into memory and an actual address for the entry point is assigned.%@NL@% %@NL@% %@CR:MCVD5005@%%@4@%The following sections explain the process LINK uses to concatenate segments%@EH@% and resolve references to items in memory.%@NL@% %@NL@% %@NL@% %@CR:MCVD5100@%%@3@%%@AB@%13.5.1 Alignment of Segments%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD5101@%%@4@%LINK uses a segment's alignment type to set the starting address for the%@EH@% segment. The alignment types are %@AB@%BYTE, WORD, PARA%@AE@%, and %@AB@%PAGE%@AE@%. These correspond to starting addresses at byte, word, paragraph, and page boundaries, representing addresses that are multiples of 1, 2, 16, and 256, respectively. The default alignment is %@AB@%PARA%@AE@%.%@NL@% %@NL@% %@CR:MCVD5102@%%@4@%When LINK encounters a segment, it checks the alignment type before copying%@EH@% the segment to the executable file. If the alignment is %@AB@%WORD%@AE@%, %@AB@%PARA%@AE@%, or %@AB@%PAGE%@AE@%, LINK checks the executable image to see if the last byte copied ends at an appropriate boundary. If not, LINK pads the image with extra null bytes.%@NL@% %@NL@% %@NL@% %@CR:MCVD5200@%%@3@%%@AB@%13.5.2 Frame Number%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD5201@%%@4@%LINK computes a starting address for each segment in a program. The starting%@EH@% address is based on a segment's alignment and the sizes of the segments already copied to the executable file (as described in Section 13.5.1%@BO: 9b071@%, above). The address consists of an offset and a "canonical frame number." The canonical frame number specifies the address of the first paragraph in memory containing one or more bytes of the segment. (A paragraph is 16 bytes of memory; therefore, to compute a physical location in memory, multiply the frame number by 16 and add the offset.) The offset is the number of bytes from the start of the paragraph to the first byte in the segment. For %@AB@%BYTE%@AE@% and %@AB@%WORD%@AE@% alignments, the offset may be nonzero. The offset is always zero for %@AB@%PARA%@AE@% and %@AB@%PAGE%@AE@% alignments. (An offset of zero means that the physical location is an exact multiple of 16.)%@NL@% %@NL@% %@CR:MCVD5202@%%@4@%The frame number of a segment can be obtained from the map file created by%@EH@% LINK. The first four digits of the start address give the frame number in hexadecimal. For example, a start address of %@AS@%0C0A6%@AE@% gives a frame number of %@AS@%0C0A%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVD5300@%%@3@%%@AB@%13.5.3 Order of Segments%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD5301@%%@4@%LINK copies segments to the executable file in the same order that it%@EH@% encounters them in the object files. This order is maintained throughout the program unless LINK encounters two or more segments having the same class name. Segments having identical class names belong to the same class type and are copied as a contiguous block to the executable file.%@NL@% %@NL@% %@CR:MCVD5302@%%@4@%The /DOSSEG option may change the way in which segments are ordered.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCVD5400@%%@3@%%@AB@%13.5.4 Combined Segments%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD5401@%%@4@%LINK uses combine types to determine whether or not two or more segments%@EH@% sharing the same segment name should be combined into one large segment. The valid combine types are %@AB@%PUBLIC, STACK, COMMON%@AE@%, and %@AB@%PRIVATE.%@AE@%%@NL@% %@NL@% %@CR:MCVD5402@%%@4@%If a segment has combine type %@AB@%PUBLIC%@AE@%, LINK automatically combines it with%@EH@% any other segments having the same name and belonging to the same class. When LINK combines segments, it ensures that the segments are contiguous and that all addresses in the segments can be accessed using an offset from the same frame address. The result is the same as if the segment were defined as a whole in the source file.%@NL@% %@NL@% %@CR:MCVD5403@%%@4@%LINK preserves each individual segment's alignment type. This means that%@EH@% even though the segments belong to a single, large segment, the code and data in the segments do not lose their original alignment. If the combined segments exceed 64K, LINK displays an error message.%@NL@% %@NL@% %@CR:MCVD5404@%%@4@%If a segment has combine type %@AB@%STACK%@AE@%, then LINK carries out the same combine%@EH@% operation as for %@AB@%PUBLIC%@AE@% segments. The only exception is %@AB@%STACK%@AE@% segments cause LINK to copy an initial stack-pointer value to the executable file. This stack-pointer value is the offset to the end of the first stack segment (or combined stack segment) encountered.%@NL@% %@NL@% %@CR:MCVD5405@%%@4@%If a segment has combine type %@AB@%COMMON%@AE@%, then LINK automatically combines it%@EH@% with any other segments having the same name and belonging to the same class. When LINK combines %@AB@%COMMON%@AE@% segments, however, it places the start of each segment at the same address, creating a series of overlapping segments. The result is a single segment no larger than the largest segment combined.%@NL@% %@NL@% %@CR:MCVD5406@%%@4@%A segment has combine type %@AB@%PRIVATE%@AE@% only if no explicit combine type is%@EH@% defined for it in the source file. LINK does not combine private segments.%@NL@% %@NL@% %@NL@% %@CR:MCVD5500@%%@3@%%@AB@%13.5.5 Groups%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD5501@%%@4@%Groups allow segments to be addressed relative to the same frame address.%@EH@% When LINK encounters a group, it adjusts all memory references to items in the group so that they are relative to the same frame address.%@NL@% %@NL@% %@CR:MCVD5502@%%@4@%Segments in a group do not have to be contiguous, belong to the same class,%@EH@% or have the same combine type. The only requirement is all segments in the group fit within 64K.%@NL@% %@NL@% %@CR:MCVD5503@%%@4@%Groups do not affect the order in which the segments are loaded. Unless you%@EH@% use class names and enter object files in the right order, there is no guarantee that the segments will be contiguous. In fact, LINK may place segments that do not belong to the group in the same 64K of memory. LINK does not explicitly check that all segments in a group fit within 64K of memory; however, LINK is likely to encounter a fixup-overflow error if this requirement is not met.%@NL@% %@NL@% %@NL@% %@CR:MCVD5600@%%@3@%%@AB@%13.5.6 Fixups%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD5601@%%@4@%Once the starting address of each segment in a program is known and all%@EH@% segment combinations and groups have been established, LINK can "fix up" any unresolved references to labels and variables. To fix up unresolved references, LINK computes an appropriate offset and segment address and replaces the temporary values generated by the assembler with the new values.%@NL@% %@NL@% %@CR:MCVD5602@%%@4@%LINK carries out fixups for the types of references shown in the following%@EH@% list:%@NL@% %@CR:MCVD5603@%%@NL@% %@TH: 43 2426 2 28 48 @%%@AB@%Type of Reference Description%@AE@%Short Occurs in %@AB@%JMP%@AE@% instructions that attempt to pass control to labeled instructions in the same segment or group. The target instruction must be no more than 128 bytes from the point of reference. LINK computes a signed, 8-bit number for this reference. It displays an error message if the target instruction belongs to a different segment or group (has a different frame address), or if the target is more than 128 bytes distant in either direction.Near self relative Occurs in instructions that access data relative to the same segment or group. LINK computes a 16-bit offset for this reference. It displays an error if the data are not in the same segment or group.Near segment relative Occurs in instructions that attempt to access data in a specified segment or group, or relative to a specified segment register. LINK computes a 16-bit offset for this reference. It displays an error message if the offset of the target within the specified frame is greater than 64K or less than 0, or if the beginning of the canonical frame of the target is not addressable.Long Occurs in %@AB@%CALL%@AE@% instructions that attempt to access an instruction in another segment or group. LINK computes a 16-bit frame address and 16-bit offset for this reference. LINK displays an error message if the computed offset is greater than 64K or less than 0, or if the beginning of the canonical frame of the target is not addressable.%@TE: 43 2426 2 28 48 @% %@NL@% %@CR:MCVD5604@%%@4@%The size of the value to be computed depends on the type of reference. If%@EH@% LINK discovers an error in the anticipated size of a reference, it displays a fixup-overflow message. This can happen, for example, if a program attempts to use a 16-bit offset to reach an instruction which is more than 64K away. It can also occur if all segments in a group do not fit within a single 64K block of memory.%@NL@% %@NL@% %@NL@% %@CR:MCVD6000@%%@2@%%@AB@%13.6 Using Overlays%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD6001@%%@4@%You can direct LINK to create an overlaid version of a program. In an%@EH@% overlaid version of a program, specified parts of the program (known as "overlays") are loaded only if and when they are needed. These parts share the same space in memory. Only code is overlaid; data are never overlaid. Programs that use overlays usually require less memory, but they run more slowly because of the time needed to read and reread the code from disk into memory.%@NL@% %@NL@% %@CR:MCVD6002@%%@4@%When you use overlays, the linker loads in code for the overlay manager.%@EH@% This code resides in each of the Microsoft high-level language libraries (so you must link with at least one such library), and is between 2K and 3K in size.%@NL@% %@NL@% %@CR:MCVD6003@%%@4@%You specify overlays by enclosing them in parentheses in the list of object%@EH@% files that you submit to the linker. Each module in parentheses represents one overlay. For example, you could give the following object-file list in the %@AI@%objfiles%@AE@% field of the LINK command line:%@NL@% %@NL@% a + (b+c) + (e+f) + g + (i)%@NL@% %@NL@% %@CR:MCVD6004@%%@4@%In this example, the modules %@AS@%(b+c)%@AE@%, %@AS@%(e+f)%@AE@%, and %@AS@%(i)%@AE@% are overlays. The remaining%@EH@% modules, and any drawn from the run-time libraries, constitute the resident part (or root) of your program. Overlays are loaded into the same region of memory, so only one can be resident at a time. Duplicate names in different overlays are not supported, so each module can appear only once in a program.%@NL@% %@NL@% %@CR:MCVD6005@%%@4@%The linker replaces calls from the root to an overlay and calls from an%@EH@% overlay to another overlay with an interrupt (followed by the module identifier and offset). By default, the interrupt number is 63 (3F hexadecimal). You can use the /OVERLAYINTERRUPT option of the LINK command to change the interrupt number.%@NL@% %@NL@% %@CR:MCVD6006@%%@4@%The CodeView debugger is now compatible with overlaid modules. In fact, in%@EH@% the case of large programs, you may need to use overlays%@NL@% %@NL@% %@NL@% %@CR:MCVD6100@%%@3@%%@AB@%13.6.1 Restrictions on Overlays%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD6101@%%@4@%You can overlay only modules to which control is transferred and returned by%@EH@% a standard 8086 long (32-bit) call/return instruction. Therefore, because calls to subroutines modified with the %@AB@%NEAR%@AE@% attribute are short (16-bit) calls, you cannot overlay modules containing %@AB@%NEAR%@AE@% subroutines if other modules call those subroutines. You cannot use long jumps with the %@AB@%longjmp%@AE@% library function. Also, the linker does not produce overlay modules that can be called indirectly through function pointers.%@NL@% %@NL@% %@NL@% %@CR:MCVD6200@%%@3@%%@AB@%13.6.2 Overlay-Manager Prompts%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVD6201@%%@4@%The overlay manager is part of the language's run-time library. If you%@EH@% specify overlays during linking, the code for the overlay manager is automatically linked with the other modules of your program.%@NL@% %@NL@% %@CR:MCVD6202@%%@4@%When the executable file is run, the overlay manager searches for that file%@EH@% whenever another overlay needs to be loaded. The overlay manager first searches for the file in the current directory; then, if it does not find the file, the manager searches the directories listed in the PATH environment variable. When it finds the file, the overlay manager extracts the overlay modules specified by the root program. If the overlay manager cannot find an overlay file when needed, it prompts the user to enter the file name.%@NL@% %@NL@% %@CR:MCVD6203@%%@4@%Even with overlays, the linker produces only one .EXE file. This file is%@EH@% opened again and again as long as the overlay manager needs to extract new overlay modules.%@NL@% %@NL@% %@CR:MCVD6204@%%@4@%For example, assume that an executable program called %@AS@%PAYROLL.EXE%@AE@% uses%@EH@% overlays and does not exist in either the current directory or the directories specified by PATH. If the user runs %@AS@%PAYROLL.EXE%@AE@% (by entering a complete path specification), the overlay manager displays the following message when it attempts to load overlay files:%@NL@% %@NL@% %@AS@%Cannot find PAYROLL.EXE%@AE@%%@NL@% %@AS@%Please enter new program spec:%@AE@%%@NL@% %@NL@% %@CR:MCVD6205@%%@4@%The user can then enter the drive or directory, or both, where %@AS@%PAYROLL.EXE%@AE@%%@EH@% is located. For example, if the file is located in directory %@AS@%\EMPLOYEE\DATA\%@AE@% on drive B, the user could enter %@AS@%B:\EMPLOYEE\DATA\%@AE@% or simply enter %@AS@%\EMPLOYEE\DATA\%@AE@% if the current drive is B.%@NL@% %@NL@% %@CR:MCVD6206@%%@4@%If the user later removes the disk in drive B and the overlay manager needs%@EH@% to access the overlay again, it does not find %@AS@%PAYROLL.EXE%@AE@% and displays the following message:%@NL@% %@NL@% %@AS@%Please insert diskette containing B:\EMPLOYEE\DATA\PAYROLL.EXE%@AE@%%@NL@% %@AS@%in drive B: and strike any key when ready.%@AE@%%@NL@% %@NL@% %@CR:MCVD6207@%%@4@%After the overlay file has been read from the disk, the overlay manager%@EH@% displays the following message:%@NL@% %@NL@% %@AS@%Please restore the original diskette.%@AE@%%@NL@% %@AS@%Strike any key when ready.%@AE@%%@NL@% %@NL@% %@NL@% %@CR:MCVE0000@%%@1@%%@AB@%Chapter 14 Incremental Linking with ILINK%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVE0001@%%@4@%The Microsoft Incremental Linker (ILINK) is a utility that enables you to%@EH@% link your application much faster. You can benefit from its use when you change a small subset of the modules used to link a program. The program can use any memory model, but in the small model LINK is not efficient unless no symbolic change address is used. Furthermore, to benefit from ILINK, you need to follow certain restrictions that are described in this chapter. Should ILINK fail to link your changes into the executable file, it attempts to invoke the full linker, LINK, or carry out any other commands you specify on the command line. Before you can use ILINK, you must first run the full linker with special options.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% You can use ILINK to develop dynamic-link libraries as well as%@NL@% applications. Everything said in this chapter about applications and%@NL@% executable files applies to dynamic-link libraries as well. This chapter%@NL@% uses the term "library" to refer specifically to an object-code library%@AE@%%@NL@% (a .LIB file).%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVE1000@%%@2@%%@AB@%14.1 Definitions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE1001@%%@4@%Incremental linking involves certain specialized concepts. You may need to%@EH@% review the following list of terms in order to understand the rest of this chapter:%@NL@% %@CR:MCVE1002@%%@NL@% %@TH: 39 2250 2 28 48 @%%@AB@%Term Meaning%@AE@%Segment A contiguous area of memory up to 64K in size. See the definitions of "physical segment" and "logical segment" below.Module A unit of code or data defined by one source file. In BASIC, Pascal, and large-memory-model C and FORTRAN programs, each module corresponds to a different segment. In small-memory-model programs, all code modules contribute to one code segment, and all data modules contribute to one data segment.Memory model The memory model determines the number of code and data segments in a program. BASIC programs are always large memory model.Physical segment A segment listed in the executable file's segment table. Each physical segment has a distinct segment address, whereas logical segments may share a segment address. A physical segment usually contains one logical segment, but it can contain more.Logical segment A segment defined in an object module. Each physical segment other than DGROUP contains exactly one logical segment, except when you use the GROUP directive in a MASM module. (Linking with the /PACKCODE option can also create more than one logical segment per physical segment.)Code symbol The address of a function, subroutine, or procedure.Data symbol The address of a global or static data object. The concept of data symbol includes all data objects except local (stack-allocated) or dynamically allocated data.%@TE: 39 2250 2 28 48 @% %@NL@% %@CR:MCVE2000@%%@2@%%@AB@%14.2 Guidelines for Using ILINK%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE2001@%%@4@%Since ILINK can automatically invoke LINK when an incremental link fails,%@EH@% you do not have to concern yourself with the following guidelines. However, if you are interested in how ILINK works and want to take full advantage of ILINK, follow the guidelines presented in this section.%@NL@% %@NL@% %@CR:MCVE2002@%%@4@%The incremental linker, ILINK, works much faster than the full linker%@EH@% because ILINK replaces only those modules that have changed since the last linking. It avoids much of the work done by LINK.%@NL@% %@NL@% %@CR:MCVE2003@%%@4@%To enable incremental linking, follow the major guidelines below. If your%@EH@% changes exceed the scope allowed by these guidelines, a full link is necessary.%@NL@% %@NL@% %@CR:MCVE2004@% 1. Do not alter any .LIB files you are using to create the executable%@NL@% file.%@NL@% %@NL@% 2. Put padding at the end of data and small-memory-model code modules by%@NL@% specifying the /PADCODE and /PADDATA options during full linking with%@NL@% LINK.%@NL@% %@NL@% By putting padding at the end of a module, you enable the module to%@NL@% grow without forcing a full relinking. However, if the module is the%@NL@% only module contributing to its physical segment, padding is not%@NL@% necessary.%@NL@% %@NL@% You can avoid padding if you have a BASIC, Pascal, FORTRAN, or C%@NL@% program (other than a small-memory-model C program), if you do not call%@NL@% a MASM module that uses the %@AB@%GROUP%@AE@% directive, and if you do not add to%@NL@% the size of the default data segment. (See your language documentation%@NL@% for information about what is placed in the default data segment.)%@NL@% %@NL@% 3. Do not delete code symbols (functions and procedures) referenced by%@NL@% another module. You can, however, move or add to these symbols.%@NL@% %@NL@% 4. Do not move or delete data symbols (global data). You can add data%@NL@% symbols at the end of your data definitions, but you cannot add new%@NL@% communal data symbols (for example, C uninitialized variables or BASIC%@NL@% %@AB@%COMMON%@AE@% statements).%@NL@% %@NL@% %@NL@% %@CR:MCVE3000@%%@2@%%@AB@%14.3 The Development Process%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE3001@%%@4@%To develop a software project with ILINK, follow the steps listed below:%@EH@%%@NL@% %@NL@% %@CR:MCVE3002@% 1. Use the full linker during early stages of developing your application%@NL@% or dynamic-link library. ILINK produces no significant gain in speed%@NL@% until you have a number of different code and data modules present.%@NL@% %@NL@% 2. Prepare for incremental linking by using the special liner options%@NL@% mentioned below.%@NL@% %@NL@% 3. Incrementally link with ILINK after any small changes are made.%@NL@% %@NL@% 4. Relink with LINK after any major changes are made (for example, if you%@NL@% want to add an entirely new module, greatly expand one of the segments%@NL@% or modules, or redefine symbols that are shared between segments).%@NL@% %@NL@% 5. Repeat steps 3 and 4 as necessary.%@NL@% %@NL@% %@CR:MCVE3003@%%@4@%You may find it easiest to use a make file to invoke ILINK and LINK. The%@EH@% following sample make file attempts to use ILINK each time, but invokes the full linker whenever incremental linking is not possible:%@NL@% %@NL@% dog.exe: obj1.obj; obj2.obj; obj3.obj%@NL@% ILINK -e "LINK /incr @dog.lnk" -a dog%@NL@% %@NL@% %@CR:MCVE3004@%%@4@%Three options──/INCREMENTAL, /PADCODE, and /PADDATA──have been added to LINK%@EH@% to allow the use of ILINK. Here is an example of how they might appear on the command line:%@NL@% %@NL@% LINK /INCREMENTAL /PADDATA:16 /PADCODE:256 @PROJNAME.LNK%@NL@% %@NL@% %@CR:MCVE3005@%%@4@%These options are described in detail in Sections 13.3.12%@BO: 93dca@%, 13.3.27%@BO: 97ed1@%, and%@EH@% 13.3.26%@BO: 978cc@%, respectively.%@NL@% %@NL@% %@NL@% %@CR:MCVE4000@%%@2@%%@AB@%14.4 Running ILINK%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE4001@%%@4@%You can attempt to link the project with ILINK at any time after the project%@EH@% has been linked with the /INCREMENTAL option. The following two sections discuss the files needed for linking with ILINK and the command required to invoke ILINK.%@NL@% %@NL@% %@NL@% %@CR:MCVE4100@%%@3@%%@AB@%14.4.1 Files Required for Using ILINK%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE4101@%%@4@%The files that are required for linking using ILINK are ILINK.EXE,%@EH@% ILINKSTB.OVL, and your project files that include the following:%@NL@% %@NL@% %@CR:MCVE4102@% 1. %@AI@%projname%@AE@%.EXE (the file to be incrementally linked)%@NL@% %@NL@% 2. %@AI@%projname%@AE@%.SYM (the symbol file)%@NL@% %@NL@% 3. %@AI@%projname%@AE@%.ILK (the ILINK support file)%@NL@% %@NL@% 4. *.OBJ (the changed .OBJ files)%@NL@% %@NL@% %@CR:MCVE4103@%%@4@%ILINK.EXE and ILINKSTB.OVL should be in a directory listed in the PATH%@EH@% environment variable, and the rest of the project files should be in the current directory.%@NL@% %@NL@% %@NL@% %@CR:MCVE4200@%%@3@%%@AB@%14.4.2 The ILINK Command Line%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE4201@%%@4@%The syntax for the ILINK command line is shown below. ILINK options are not%@EH@% case sensitive.%@NL@% %@NL@% ILINK «/a» «/c» «/v» «/i» «/e "%@AI@%commands%@AE@%"» %@AI@%projname%@AE@%«%@AI@%modulelist%@AE@%»%@NL@% %@NL@% %@CR:MCVE4202@%%@4@%The /a option specifies that all object files are to be checked to see if%@EH@% they have changed since the last linking process. This is done by comparing the dates and times of all .OBJ files with those of the executable file. An attempt is made to incrementally link all of the files that have changed.%@NL@% %@NL@% %@CR:MCVE4203@%%@4@%The /c option specifies case sensitivity for all public symbol names.%@EH@%%@NL@% %@NL@% %@CR:MCVE4204@%%@4@%The /v option specifies verbose mode and directs ILINK to display more%@EH@% information. Specifically, when in verbose mode ILINK lists the modules that have changed.%@NL@% %@NL@% %@CR:MCVE4205@%%@4@%The /i option specifies that only an incremental link is to be attempted. If%@EH@% the incremental link fails, a full link is not performed.%@NL@% %@NL@% %@CR:MCVE4206@%%@4@%The /e option specifies a list of commands to be executed if the incremental%@EH@% link fails. The commands are enclosed in double quotes, and if more than one command is given, they must be separated by spaces and a semicolon.%@NL@% %@NL@% %@CR:MCVE4207@%%@4@%The %@AI@%projname%@AE@% field contains the name of the executable file that is to be%@EH@% incrementally linked.%@NL@% %@NL@% %@CR:MCVE4208@%%@4@%You can use the optional %@AI@%modulelist%@AE@% field to list all the modules that have%@EH@% changed. (No extensions are required.) This field is an alternative to using the /a flag.%@NL@% %@NL@% %@CR:MCVE4209@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% ILINK /i wizard input sort output%@NL@% %@NL@% %@CR:MCVE420A@%%@4@%In the above example, the altered modules (%@AS@%input%@AE@%, %@AS@%sort%@AE@%, and %@AS@%output%@AE@%) are%@EH@% explicitly listed on the command line.%@NL@% %@NL@% ILINK /e "link @%s.obj ; rc %s.exe" myproj%@NL@% %@NL@% %@CR:MCVE420B@%%@4@%In the example above, the characters %@AS@%%s%@AE@% are replaced by %@AI@%projname%@AE@% when the%@EH@% command is carried out. If the incremental link fails, ILINK carries out the commands %@AS@%link myproj.obj%@AE@% and %@AS@%rc myproj.exe%@AE@%.%@NL@% %@NL@% ILINK /a /e "link @%s.lnk ; rc %s.exe" wizard%@NL@% %@NL@% %@CR:MCVE420C@%%@4@%In the final example above, the /a option directs ILINK to scan all files in%@EH@% the project in order to discover which modules have changed. This example also lists commands to be executed in case incremental linking fails.%@NL@% %@NL@% %@NL@% %@CR:MCVE5000@%%@2@%%@AB@%14.5 How ILINK Works%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE5001@%%@4@%Instead of searching for records and resolving external references for the%@EH@% entire program, ILINK carries out the following operations:%@NL@% %@NL@% %@CR:MCVE5002@% 1. ILINK replaces the portion of each module that has changed since the%@NL@% last linking (incremental or full linking).%@NL@% %@NL@% 2. ILINK alters relocation-table entries for any far (segmented) code%@NL@% symbols that have moved within a segment. For each reference to a far%@NL@% code symbol, such as a far function call, there is an entry in the%@NL@% relocation table in the executable file's header. The relocation table%@NL@% of the application contains full addresses. Therefore, by fixing%@NL@% relocation table entries for a code symbol, ILINK ensures that all%@NL@% references to the symbol will be correct.)%@NL@% %@NL@% %@CR:MCVE5003@%%@4@%ILINK makes no modification to modules that have not been changed since the%@EH@% last linking.%@NL@% %@NL@% %@NL@% %@CR:MCVE6000@%%@2@%%@AB@%14.6 Incremental Violations%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE6001@%%@4@%There are two kinds of ILINK failures: real errors and incremental%@EH@% violations. Real errors are errors that will not be resolved by a full link, such as undefined symbols or invalid .OBJ files. If ILINK detects a real error, it displays %@AS@%ERROR%@AE@% with an explanation and returns a nonzero error code to the operating system. Incremental violations consist of changes that are beyond the scope of incremental linking, but can generally be resolved by full linking.%@AS@%%@NL@% %@NL@% %@CR:MCVE6002@%%@4@%Section C.2%@BO: ddc92@%, "LINK Error Messages," explains real errors in detail. The rest%@EH@% of this section describes incremental violations.%@NL@% %@NL@% %@NL@% %@CR:MCVE6100@%%@3@%%@AB@%14.6.1 Changing Libraries%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE6101@%%@4@%An incremental violation occurs when a library changes. Furthermore, if an%@EH@% altered module shares a code segment with a library, ILINK needs access to the library as well as to the new module.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% If you add a function, procedure, or subroutine call to a library that%@NL@% has never been called before, ILINK fails with an undefined-symbol error.%@NL@% Performing a full link should resolve this problem.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVE6200@%%@3@%%@AB@%14.6.2 Exceeding Code/Data Padding%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE6201@%%@4@%An incremental violation will occur if two or more modules contribute to the%@EH@% same physical segment and either module exceeds its padding. As discussed in Section 14.2%@BO: 9fa9a@%, "Guidelines for Using ILINK," padding is the process of adding filler bytes to the end of a module. The filler bytes serve as a buffer zone whenever the module grows in size──that is, whenever the new version of the module is larger than the old.%@NL@% %@NL@% %@NL@% %@CR:MCVE6300@%%@3@%%@AB@%14.6.3 Moving/Deleting Data Symbols%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE6301@%%@4@%An incremental violation occurs if a data symbol is moved or deleted. To add%@EH@% new data symbols without requiring a full link, add the new symbols at the end of all other data symbols in the module.%@NL@% %@NL@% %@NL@% %@CR:MCVE6400@%%@3@%%@AB@%14.6.4 Deleting Code Symbols%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE6401@%%@4@%You can move or add code symbols, but an incremental violation occurs if you%@EH@% delete any code symbols from a module. Code symbols can be moved within a module but cannot be moved between modules.%@NL@% %@NL@% %@NL@% %@CR:MCVE6500@%%@3@%%@AB@%14.6.5 Changing Segment Definitions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE6501@%%@4@%An incremental violation results if you add, delete, or change the order of%@EH@% segment definitions. If you are programming in MASM, an incremental violation will also result if you alter any %@AB@%GROUP%@AE@% directives.%@NL@% %@NL@% %@CR:MCVE6502@%%@4@%If you are programming with a high-level language, remember not to add or%@EH@% delete modules between incremental links.%@NL@% %@NL@% %@NL@% %@CR:MCVE6600@%%@3@%%@AB@%14.6.6 Adding CodeView Debugger Information%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVE6601@%%@4@%If you included CodeView debugger information for a module the last time you%@EH@% ran a full link (by compiling and linking with CodeView debugger support), ILINK fully supports CodeView debugger information for the module. ILINK maintains symbolic information for current symbols, and it adds information for any new symbols. However, if you include CodeView debugger information for a module that previously did not have CodeView debugger support, an incremental violation results.%@NL@% %@NL@% %@NL@% %@CR:MCVF0000@%%@1@%%@AB@%Chapter 15 Managing Libraries with LIB%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVF0001@%%@4@%The Microsoft Library Manager (LIB) is a utility designed to help you%@EH@% create, organize, and maintain run-time libraries. "Run-time" libraries are collections of compiled or assembled functions that provide a common set of useful routines. After you have linked a program with a run-time library file, that program can call a run-time routine exactly as if the function were included in the program. The call to the run-time routine is resolved by finding that routine in the library file.%@NL@% %@NL@% %@CR:MCVF0002@%%@4@%Run-time libraries are created by combining separately compiled object files%@EH@% into one library file. Library files are usually identified by their .LIB extension, although other extensions are allowed.%@NL@% %@NL@% %@CR:MCVF0003@%%@4@%In addition to accepting DOS object files and library files, LIB can read%@EH@% the contents of 286 XENIX(R) archives and Intel-style libraries and combine their contents with DOS libraries. To see how you can add the contents of a 286 XENIX archive or an Intel-style library to a DOS library, refer to Section 15.2.8%@BO: ab138@%, "Combining Libraries."%@NL@% %@NL@% %@CR:MCVF0004@%%@4@%Using LIB, you can create a new library file, add object files to an%@EH@% existing library, delete library modules, replace library modules, and create object files from library modules. LIB also lets you combine the contents of two libraries into one library file.%@NL@% %@NL@% %@CR:MCVF0005@%%@4@%The command syntax is straightforward: you can give LIB all the input it%@EH@% requires directly from the command line. You can also use one of the two alternative methods of invoking LIB by responding to prompts or by creating a response file, described in Sections 15.1.2%@BO: a74a1@% and 15.1.3%@BO: a8274@% below.%@NL@% %@NL@% %@NL@% %@CR:MCVF1000@%%@2@%%@AB@%15.1 Managing Libraries%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1001@%%@4@%You run LIB by typing the LIB command on the DOS command line. You can%@EH@% specify the input required for this command in one of three ways:%@NL@% %@NL@% %@CR:MCVF1002@% 1. By placing it on the command line%@NL@% %@NL@% 2. By responding to prompts%@NL@% %@NL@% 3. By specifying a file containing responses to prompts (This type of file%@NL@% is known as a "response file.")%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Once an object file is incorporated into a library, it becomes an object%@NL@% "module." %@AB@%LIB%@AE@% makes a distinction between object files and object%@NL@% modules: an object "file" exists as an independent file, while an object%@NL@% "module" is part of a larger library file. An object file can have a full%@NL@% path name, including a drive designation, directory path name, and%@NL@% file-name extension (usually .OBJ). Object modules have only a name. For%@NL@% example, %@AS@%B:\RUN\SORT.OBJ%@AE@% is an object-file name, while %@AS@%SORT%@AE@% is an%@NL@% object-module name.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVF1100@%%@3@%%@AB@%15.1.1 Managing Libraries with the LIB Command Line%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1101@%%@4@%You can start LIB and specify all the input it needs from the command line.%@EH@% In this case, the LIB command line has the following form:%@NL@% %@NL@% %@AB@%LIB%@AE@% %@AI@%oldlibrary%@AE@% «%@AI@%options%@AE@%» «%@AI@%commands%@AE@%»«%@AB@%,%@AE@%«%@AI@%listfile%@AE@%»«%@AB@%,%@AE@%« %@AI@%newlibrary%@AE@%»»»«%@AB@%;%@AE@%»%@NL@% %@NL@% %@CR:MCVF1102@%%@4@%To tell LIB to use the default responses for the remaining fields, use a%@EH@% semicolon (%@AB@%;%@AE@%) after any field except the %@AI@%oldlibrary%@AE@% field. The semicolon should be the last character on the command line.%@NL@% %@NL@% %@CR:MCVF1103@%%@4@%Sections 15.1.1.1%@BO: a3d1a@%-15.1.1.5 below describe the input you give in each%@EH@% command-line field.%@NL@% %@NL@% %@CR:MCVF1110@%%@4@%%@AB@%15.1.1.1 Specifying the Library File%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1111@%%@4@%%@AB@%Field%@AE@%%@EH@%%@NL@% %@NL@% %@AI@%oldlibrary%@AE@%«%@AB@%;%@AE@%»%@NL@% %@NL@% %@CR:MCVF1112@%%@4@%The %@AI@%oldlibrary%@AE@% field allows you to specify the name of the existing library%@EH@% to be used. Usually library files are named with the .LIB extension. You can omit the .LIB extension when you give the library-file name since LIB assumes that the file-name extension is .LIB. If your library file does not have the .LIB extension, be sure to include the extension when you give the library-file name. Otherwise, LIB cannot find the file.%@NL@% %@NL@% %@CR:MCVF1113@%%@4@%Path names are allowed with the library-file name. You can give LIB the path%@EH@% name of a library file in another directory or on another disk. There is no default for this field. LIB produces an error message if you do not give a file name.%@NL@% %@NL@% %@CR:MCVF1114@%%@4@%If you give the name of a library file that does not exist, LIB displays the%@EH@% following prompt:%@NL@% %@NL@% %@AS@%Library file does not exist. Create?%@AE@%%@NL@% %@NL@% %@CR:MCVF1115@%%@4@%Type Y to create the library file, or N to terminate LIB. This message is%@EH@% suppressed if the nonexistent library name you give is followed immediately by commands, a comma, or a semicolon.%@NL@% %@NL@% %@CR:MCVF1116@%%@4@%If you type a library name and follow it immediately with a semicolon (%@AB@%;%@AE@%),%@EH@% LIB performs only a consistency check on the given library. A consistency check tells you whether all the modules in the library are in usable form. LIB prints a message only if it finds an invalid object module; no message appears if all modules are intact.%@NL@% %@NL@% %@CR:MCVF1120@%%@4@%%@AB@%15.1.1.2 Specifying Options%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1121@%%@4@%%@AB@%Field%@AE@%%@EH@%%@NL@% %@NL@% «%@AI@%options%@AE@%»%@NL@% %@NL@% %@CR:MCVF1122@%%@4@%The following list gives the options available and the function of each:%@EH@%%@NL@% %@CR:MCVF1123@%%@NL@% %@TH: 49 3277 2 28 48 @%%@AB@%Option Function%@AE@%%@AB@%/PA%@AE@%«%@AB@%GESIZE%@AE@%»%@AB@%:%@AE@%%@AI@%number%@AE@% This option allows you to specify the library-page size of a new library or change the library-page size of an existing library. The page size of a library affects the alignment of modules stored in the library. Modules in the library are always aligned to start at a position that is a multiple of the page size (in bytes) from the beginning of the file. The default page size for a new library is 16 bytes. See Section 15.2.11%@BO: abfb6@%, "Setting the Library Page Size," for more information. The abbreviation for this option is /PA.%@AB@%/NOI%@AE@%«%@AB@%GNORECASE%@AE@%» This option tells LIB not to ignore case when comparing symbols. By default, LIB ignores case. Using this option allows symbols that are the same except for case to be put in the same library. The abbreviation for this option is /NOI. Note that if a library is built with /NOI, the library is internally "marked" to indicate /NOI is%@AB@%%@AE@% in effect. All libraries built with earlier versions of LIB are not marked. If you combine multiple libraries, and any one of them is marked /NOI, then /NOI is assumed to be in effect for the output library.%@AB@%/I%@AE@%«%@AB@%GNORECASE%@AE@%» This option tells LIB to ignore case when comparing symbols, as LIB does by default. Use this option when you are combining a library that is marked /NOI with others that are unmarked and want the new library to be unmarked. (See the explanation for the /NOI option above.) The abbreviation for this option is /I.%@AB@%/NOE%@AE@%«%@AB@%XTDICTIONARY%@AE@%» This option is used to prevent LIB from creating an extended dictionary. The extended dictionary is used by LINK to speed up a library search. Without an extended dictionary, the .LIB extension is still a valid library, but LINK takes longer to find modules in this file. Use it if you get error messages %@AS@%U1172%@AE@% or %@AS@%U4158%@AE@%. The option /NOE «XTDICTIONARY» also occurs in LINK. In LINK the option means, "do not read an extended dictionary."%@TE: 49 3277 2 28 48 @% %@NL@% %@CR:MCVF1130@%%@4@%%@AB@%15.1.1.3 Giving LIB Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1131@%%@4@%%@AB@%Field%@AE@%%@EH@%%@NL@% %@NL@% «%@AI@%commands%@AE@%»%@NL@% %@NL@% %@CR:MCVF1132@%%@4@%The %@AI@%commands%@AE@% field allows you to specify the command symbols for%@EH@% manipulating modules. To use this field, type a command symbol (such as%@AB@%+%@AE@%, %@AB@%-%@AE@%, %@AB@%-+%@AE@%, %@AB@%*%@AE@%, or %@AB@%-*%@AE@%), followed immediately by a module name or an object-file name. You can specify more than one operation in this field in any order. LIB does not make any changes to %@AI@%oldlibrary%@AE@% if you leave the %@AI@%commands%@AE@% field blank.%@NL@% %@CR:MCVF1133@%%@NL@% %@TH: 57 3628 3 28 48 @%%@AB@%Command%@AE@%%@AB@%Symbol Meaning%@AE@%%@AB@%+%@AE@% The add command symbol. A plus sign makes an object file the last module in the library file. Immediately following the plus sign, give the name of the object file. You may use path names for the object file. LIB automatically supplies the .OBJ extension so you can omit the extension from the object-file name. You can also use the plus sign to combine two libraries. When you give a library name following the plus sign, a copy of the contents of the given library is added to the library file being modified. You must include the .LIB extension when you give a library-file name. Otherwise, LIB uses the default .OBJ extension when it looks for the file.%@AB@%-%@AE@% The delete command symbol. A minus sign deletes a module from the library file. Immediately following the minus sign, give the name of the module to be deleted. A module name has no path name and no extension.%@AB@%-+%@AE@% The replace command symbol. A minus sign followed by a plus sign replaces a module in the library. Following the replacement symbol, give the name of the module to be replaced. Module names have no path names and no extensions. To replace a module, LIB deletes the given module, then appends the object file having the same name as the module. The object file is assumed to have an .OBJ extension and to reside in the current working directory.%@AB@%*%@AE@% The copy command symbol. An asterisk followed by a module name copies a module from the library file into an object file of the same name. The module remains in the library file. When LIB copies the module to an object file, it adds to the module name the .OBJ extension and the drive designation and path name of the current working directory, thus forming a complete object-file name. You cannot override the .OBJ extension, drive designation, or path name given to the object file. However, you can later rename the file or copy it to any location you like.%@AB@%-*%@AE@% The move command symbol. A minus sign followed moves an object module from the library file to an object file. This operation is equivalent to copying the module to an object file, as described above, then deleting the module from the library.%@TE: 57 3628 3 28 48 @%%@NL@% %@CR:MCVF1140@%%@4@%%@AB@%15.1.1.4 Specifying a Cross-Reference-Listing File%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1141@%%@4@%%@AB@%Field%@AE@%%@EH@%%@NL@% %@NL@% «%@AI@%listfile%@AE@%»%@NL@% %@NL@% %@CR:MCVF1142@%%@4@%The %@AI@%listfile%@AE@% field allows you to specify a file name for a%@EH@% cross-reference-listing file. You can specify a full path name for the listing file to cause it to be created outside your current working directory. You can give the listing file any name and any extension. LIB does not supply a default extension if you omit the extension. The default when you omit the response to this prompt is the special file named NUL, which tells LIB not to create a listing file.%@NL@% %@NL@% %@CR:MCVF1143@%%@4@%A cross-reference-listing file contains the following two lists:%@EH@%%@NL@% %@NL@% %@CR:MCVF1144@% 1. An alphabetical list of all public symbols in the library.%@NL@% %@NL@% Each symbol name is followed by the module name in which it is%@NL@% referenced.%@NL@% %@NL@% 2. A list of the modules in the library.%@NL@% %@NL@% Under each module name is an alphabetical listing of the public symbols%@NL@% defined in that module.%@NL@% %@NL@% %@CR:MCVF1150@%%@4@%%@AB@%15.1.1.5 Specifying an Output Library%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1151@%%@4@%%@AB@%Field%@AE@%%@EH@%%@NL@% %@NL@% «%@AI@%newlibrary%@AE@%»%@NL@% %@NL@% %@CR:MCVF1152@%%@4@%The %@AI@%newlibrary%@AE@% field allows you to specify the name of the new library file%@EH@% that contains the specified changes. You need not give this name unless you specify changes to the library in the %@AI@%commands%@AE@% field. The default is the current library-file name.%@NL@% %@NL@% %@CR:MCVF1153@%%@4@%If you do not specify a new library-file name, the original, unmodified%@EH@% library is saved in a library file with the same name but with a .BAK extension replacing the .LIB extension.%@NL@% %@NL@% %@CR:MCVF1154@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% LIB LANG-+HEAP;%@NL@% %@NL@% %@CR:MCVF1155@%%@4@%The example above uses the replace command symbol (%@AB@%-+%@AE@%) to instruct LIB to%@EH@% replace the %@AS@%HEAP%@AE@% module in the library %@AS@%LANG.LIB%@AE@%. LIB deletes the %@AS@%HEAP%@AE@% module from the library, then appends the object file %@AS@%HEAP.OBJ%@AE@% as a new module in the library. The semicolon at the end of the command line tells LIB to use the default responses for the remaining prompts. This means no listing file is created and the changes are written to the original library file instead of a new library file.%@NL@% %@NL@% LIB LANG-HEAP+HEAP;%@NL@% %@NL@% LIB LANG+HEAP-HEAP;%@NL@% %@NL@% %@CR:MCVF1156@%%@4@%The examples above perform the same function as the first example in this%@EH@% section, but in two separate operations, using the add (%@AB@%+%@AE@%) and delete (%@AB@%-%@AE@%) command symbols. The effect is the same for these examples because delete operations are always carried out before add operations, regardless of the order of the operations in the command line. This order of execution prevents confusion when a new version of a module replaces an old version in the library file.%@NL@% %@NL@% LIB FOR;%@NL@% %@NL@% %@CR:MCVF1157@%%@4@%The example above causes LIB to perform a consistency check of the library%@EH@% file %@AS@%FOR.LIB%@AE@%. No other action is performed. LIB displays any consistency errors it finds and returns to the operating-system level.%@NL@% %@NL@% LIB LANG,LCROSS.PUB%@NL@% %@NL@% %@CR:MCVF1158@%%@4@%This example tells LIB to perform a consistency check of the library file%@EH@% %@AS@%LANG.LIB%@AE@% and then create a cross-reference-listing file named %@AS@%LCROSS.PUB%@AE@%.%@NL@% %@NL@% LIB FIRST -*STUFF *MORE, ,SECOND%@NL@% %@NL@% %@CR:MCVF1159@%%@4@%This last example instructs LIB to move the module %@AS@%STUFF%@AE@% from the library%@EH@% %@AS@%FIRST.LIB%@AE@% to an object file called %@AS@%STUFF.OBJ%@AE@%. The module %@AS@%STUFF%@AE@% is removed from the library in the process. The module %@AS@%MORE%@AE@% is copied from the library to an object file called %@AS@%MORE.OBJ%@AE@%; the module remains in the library. The revised library is called %@AS@%SECOND.LIB%@AE@%. It contains all the modules in %@AS@%FIRST.LIB%@AE@% except %@AS@%STUFF%@AE@%, which was removed by using the move command symbol (%@AB@%-*%@AE@%). The original library, %@AS@%FIRST.LIB%@AE@%, remains unchanged.%@NL@% %@NL@% %@NL@% %@CR:MCVF1200@%%@3@%%@AB@%15.1.2 Managing Libraries with the LIB Prompts%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1201@%%@4@%If you want to respond to individual prompts to give input to LIB, start LIB%@EH@% at the DOS command level by typing LIB. The library manager prompts you for the input it needs by displaying the following four messages, one at a time:%@NL@% %@NL@% Library name:%@NL@% Operations:%@NL@% List file:%@NL@% Output library:%@NL@% %@NL@% %@CR:MCVF1202@%%@4@%LIB waits for you to respond to each prompt, then prints the next prompt.%@EH@%%@NL@% %@NL@% %@CR:MCVF1203@%%@4@%The responses you give to the LIB command prompts correspond to the fields%@EH@% on the LIB command line. (See Section 15.1.1%@BO: a39b0@% for a discussion of the LIB command line.) The following list shows these correspondences:%@NL@% %@NL@% %@CR:MCVF1204@%%@AB@%Prompt Command-Line Field%@AE@%%@NL@% %@NL@% %@AS@%Library name%@AE@% The %@AI@%oldlibrary%@AE@% field and the options (see%@NL@% Sections 15.1.1.1%@BO: a3d1a@% and 15.1.1.2%@BO: a4409@%, respectively).%@NL@% If you want to perform a consistency check on%@NL@% the library, type a semicolon (%@AB@%;%@AE@%) immediately%@NL@% after the library name.%@NL@% %@NL@% %@AS@%Operations%@AE@% Any of the commands allowed in the %@AI@%commands%@AE@%%@NL@% field (see Section 15.1.1.3%@BO: a522b@%).%@NL@% %@NL@% %@AS@%List file%@AE@% The %@AI@%listfile%@AE@% field (see Section 15.1.1.4%@BO: a6337@%).%@NL@% %@NL@% %@AS@%Output library%@AE@% The %@AI@%newlibrary%@AE@% field (see Section 15.1.1.5%@BO: a67e6@%).%@NL@% %@NL@% %@CR:MCVF1210@%%@4@%%@AB@%15.1.2.1 Extending Lines%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1211@%%@4@%If you have many operations to perform during a library session, use the%@EH@% ampersand command symbol (%@AB@%&%@AE@%) to extend the operations line. Give the ampersand symbol after an object-module or object-file name; do not put the ampersand between an operation's symbol and a name.%@NL@% %@NL@% %@CR:MCVF1212@%%@4@%The ampersand causes LIB to repeat the %@AS@%Operations%@AE@% prompt, allowing you to%@EH@% type more operations.%@NL@% %@NL@% %@CR:MCVF1220@%%@4@%%@AB@%15.1.2.2 Using Default Responses%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1221@%%@4@%After any entry but the first, use a single semicolon (%@AB@%;%@AE@%) followed%@EH@% immediately by a carriage return to select default responses to the remaining prompts. You can use the semicolon command symbol with the command-line and response-file methods of invoking LIB, but it is not necessary since LIB supplies the default responses wherever you omit responses.%@NL@% %@NL@% %@CR:MCVF1222@%%@4@%The following list shows the defaults for LIB prompts:%@EH@%%@NL@% %@NL@% %@CR:MCVF1223@%%@AB@%Prompt Default%@AE@%%@NL@% %@NL@% %@AS@%Operations%@AE@% No operation; no change to library file.%@NL@% %@NL@% %@AS@%List file%@AE@% The special file name NUL, which tells LIB not%@NL@% to create a listing file.%@NL@% %@NL@% %@AS@%Output library%@AE@% The current library name. Only if you specify at%@NL@% least one operation at the %@AS@%Operations%@AE@% prompt%@NL@% will this prompt appear.%@NL@% %@NL@% %@NL@% %@CR:MCVF1300@%%@3@%%@AB@%15.1.3 Managing Libraries with a Response File%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1301@%%@4@%To operate LIB with a response file, you must first set up the response file%@EH@% and then type the following at the DOS command line:%@NL@% %@NL@% %@AB@%LIB @%@AE@%%@AI@%responsefile%@AE@%%@NL@% %@NL@% %@CR:MCVF1302@%%@4@%The %@AI@%responsefile%@AE@% is the name of a response file. The response-file name can%@EH@% be qualified with a drive and directory specification to name a response file from a directory other than the current working directory.%@NL@% %@NL@% %@CR:MCVF1303@%%@4@%You can also enter the name of a response file at any position in a command%@EH@% line or after any of the linker prompts. The input from the response file is treated exactly as if it had been entered in command lines or after prompts. A carriage-return and line-feed combination in the response file is treated the same as pressing ENTER in response to a prompt or using a comma in a command line.%@NL@% %@NL@% %@CR:MCVF1304@%%@4@%Before you use this method, you must set up a response file containing%@EH@% responses to the LIB prompts. This method lets you conduct the library session without typing responses to prompts at the keyboard.%@NL@% %@NL@% %@CR:MCVF1305@%%@4@%A response file has one text line for each prompt. Responses must appear in%@EH@% the same order as the command prompts appear. Use command symbols in the response file the same way you would use responses typed on the keyboard. You can type an ampersand at the end of the response to the %@AS@%Operations%@AE@% prompt and continue typing operations on the next line.%@NL@% %@NL@% %@CR:MCVF1306@%%@4@%When you run LIB with a response file, the prompts are displayed with the%@EH@% responses from the response file. If the response file does not contain responses for all the prompts, LIB uses the default responses.%@NL@% %@NL@% %@CR:MCVF1307@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% LIBFOR%@NL@% +CURSOR+HEAP-HEAP*FOIBLES%@NL@% CROSSLST%@NL@% %@NL@% %@CR:MCVF1308@%%@4@%The contents of the above response file cause LIB to delete the module %@AS@%HEAP%@AE@%%@EH@% from the %@AS@%LIBFOR.LIB%@AE@% library file, copy the module %@AS@%FOIBLES%@AE@%, place it in an object file %@AS@%FOIBLES.OBJ%@AE@%, and append the object files %@AS@%CURSOR.OBJ%@AE@% and %@AS@%HEAP.OBJ%@AE@% as the last two modules in the library. LIB creates a cross-reference-listing file named %@AS@%CROSSLST%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVF1400@%%@3@%%@AB@%15.1.4 Terminating the LIB Session%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF1401@%%@4@%You can press CTRL+C at any time during a library session to terminate the%@EH@% session and return to DOS. If you notice that you have entered an incorrect response at a previous prompt, you should press CTRL+C to exit LIB and begin again. You can use the normal DOS editing keys to correct errors at the current prompt.%@NL@% %@NL@% %@NL@% %@CR:MCVF2000@%%@2@%%@AB@%15.2 Performing Library-Management Tasks with LIB%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2001@%%@4@%You can perform a number of library-management functions with LIB, including%@EH@% the following tasks:%@NL@% %@NL@% %@CR:MCVF2002@% ■ Create a library file%@NL@% ■ Delete modules%@NL@% ■ Copy a module to a separate object file%@NL@% ■ Move a module out of a library and into an object file (extract module)%@NL@% ■ Append an object file as a module of a library%@NL@% ■ Replace a module in the library file with a new module%@NL@% ■ Produce a listing of all public symbols in the library modules%@NL@% %@NL@% %@CR:MCVF2003@%%@4@%For each library session, LIB reads and interprets the user's commands in%@EH@% the order listed below. It determines whether a new library is being created or an existing library is being examined or modified.%@NL@% %@NL@% %@CR:MCVF2004@% 1. LIB processes any deletion and move commands.%@NL@% %@NL@% LIB does not actually delete modules from the existing file. Instead,%@NL@% it marks the selected modules for deletion, creates a new library file,%@NL@% and copies only the modules not marked for deletion into the new%@NL@% library file.%@NL@% %@NL@% 2. LIB processes any additional commands.%@NL@% %@NL@% Like deletions, additions are not performed on the original library%@NL@% file. Instead, the additional modules are appended to the new library%@NL@% file. (If there were no deletion or move commands, a new library file%@NL@% would be created in the addition stage by copying the original library%@NL@% file.)%@NL@% %@NL@% %@CR:MCVF2005@%%@4@%As LIB carries out these commands, it reads the object modules in the%@EH@% library, checks them for validity, and gathers the information necessary to build a library index and a listing file. The linker uses the library index to search the library.%@NL@% %@NL@% %@CR:MCVF2006@%%@4@%The listing file contains a list of all public symbols in the index and the%@EH@% names of the modules in which they are defined. LIB produces the listing file only if you ask for it during the library session.%@NL@% %@NL@% %@CR:MCVF2007@%%@4@%LIB never makes changes to the original library; it copies the library and%@EH@% makes changes to the copy. Therefore, when you terminate LIB for any reason, you do not lose your original file. It also means that when you run LIB, enough space must be available on your disk for both the original library file and the copy.%@NL@% %@NL@% %@CR:MCVF2008@%%@4@%When you change a library file, LIB lets you specify a different name for%@EH@% the file containing the changes. If you use this option, the modified library is stored under the name you give, and the original, unmodified version is preserved under its own name. If you choose not to give a new name, LIB gives the modified file the original library name, but keeps a backup copy of the original library file. This copy has the extension .BAK instead of .LIB.%@NL@% %@NL@% %@NL@% %@CR:MCVF2100@%%@3@%%@AB@%15.2.1 Creating a Library File%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2101@%%@4@%To create a new library file, give the name of the library file you want to%@EH@% create in the %@AI@%oldlibrary%@AE@% field of the command line or at the %@AS@%Library name%@AE@% prompt. LIB supplies the .LIB extension.%@NL@% %@NL@% %@CR:MCVF2102@%%@4@%The name of the new library file must not be the name of an existing file.%@EH@% If it is, LIB assumes that you want to change the existing file. When you give the name of a library file that does not currently exist, LIB displays the following prompt:%@NL@% %@NL@% %@AS@%Library file does not exist. Create?%@AE@%%@NL@% %@NL@% %@CR:MCVF2103@%%@4@%Type %@AS@%y%@AE@% to create the file, or %@AS@%n%@AE@% to terminate the library session. This%@EH@% message is suppressed if the nonexistent library name you give is followed immediately by commands, a comma, or a semicolon.%@NL@% %@NL@% %@CR:MCVF2104@%%@4@%You can specify a page size for the library when you create it. The default%@EH@% page size is 16 bytes. See Section 15.2.11%@BO: abfb6@%, "Setting the Library-Page Size," for a discussion of this option.%@NL@% %@NL@% %@CR:MCVF2105@%%@4@%Once you have given the name of the new library file, you can insert object%@EH@% modules into the library by using the add +) in the %@AI@%commands%@AE@% field of the command line or at the %@AS@%Operations%@AE@% prompt. You can also add the contents of another library, if you wish. See Section 15.2.3%@BO: aa52d@%, "Adding Library Modules," and Section 15.2.8%@BO: ab138@%, "Combining Libraries," for a discussion of these options.%@NL@% %@NL@% %@NL@% %@CR:MCVF2200@%%@3@%%@AB@%15.2.2 Changing a Library File%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2201@%%@4@%You can change an existing library file by giving the name of the library%@EH@% file at the %@AS@%Library name%@AE@% prompt. All operations you specify in the %@AI@%oldlibrary%@AE@% field of the command line or at the %@AS@%Operations%@AE@% prompt are performed on that library.%@NL@% %@NL@% %@CR:MCVF2202@%%@4@%However, LIB lets you keep both the unchanged library file and the newly%@EH@% changed version, if you like. You can do this by giving the name of a new library file in the %@AI@%newlibrary%@AE@% field or at the %@AS@%Output library%@AE@% prompt. The changed library file is stored under the new library-file name, while the original library file remains unchanged.%@NL@% %@NL@% %@CR:MCVF2203@%%@4@%If you don't give a new file name, the changed version of the library file%@EH@% replaces the original library file. Even in this case, LIB saves the original, unchanged library file with the extension .BAK instead of .LIB. Thus, at the end of the session you have two library files: the changed version with the .LIB extension and the original, unchanged version with the .BAK extension.%@NL@% %@NL@% %@NL@% %@CR:MCVF2300@%%@3@%%@AB@%15.2.3 Adding Library Modules%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2301@%%@4@%Use the add command symbol (%@AB@%+%@AE@%) in the %@AI@%commands%@AE@% field of the command line or%@EH@% at the %@AS@%Operations%@AE@% prompt to add an object module to a library. Give the name of the object file to be added without the .OBJ extension, immediately following the plus sign.%@NL@% %@NL@% %@CR:MCVF2302@%%@4@%LIB strips the drive designation and the extension from the object-file%@EH@% specification, leaving only the base name. This becomes the name of the object module in the library. For example, if the object file %@AS@%B:\CURSOR%@AE@% is added to a library file, the name of the corresponding object module is%@AE@% %@AS@%CURSOR.%@AE@%%@NL@% %@NL@% %@CR:MCVF2303@%%@4@%Object modules are always added to the end of a library file.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCVF2400@%%@3@%%@AB@%15.2.4 Deleting Library Modules%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2401@%%@4@%Use the delete command symbol (%@AB@%-+%@AE@%) in the %@AI@%commands%@AE@% field of the command line%@EH@% or at the %@AS@%Operations%@AE@% prompt to delete an object module from a library. After the minus sign, give the name of the module to be deleted. A module name does not have a path name or extension; it is simply a name, such as %@AS@%CURSOR%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVF2500@%%@3@%%@AB@%15.2.5 Replacing Library Modules%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2501@%%@4@%Use the replace command symbol (%@AB@%-+%@AE@%) in the %@AI@%commands%@AE@% field to replace a%@EH@% module in the library. Following the replace command symbol, give the name of the module to be replaced. Remember that module names do not have path names or extensions.%@NL@% %@NL@% %@CR:MCVF2502@%%@4@%To replace a module, LIB deletes the given module, then appends the object%@EH@% file having the same name as the module. The object file is assumed to have an .OBJ extension and to reside in the current working directory.%@NL@% %@NL@% %@NL@% %@CR:MCVF2600@%%@3@%%@AB@%15.2.6 Copying Library Modules%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2601@%%@4@%To copy a module from the library file into an object file of the same name,%@EH@% use the copy command symbol (%@AB@%*%@AE@%) followed by a module name in the %@AI@%commands%@AE@% field. The module remains in the library file. When LIB copies the module to an object file, it adds the .OBJ extension and the drive designation and path name of the current working directory to the module name. This forms a complete object-file name. You cannot override the .OBJ extension, drive designation, or path name given to the object file, but you can later rename the file or copy it to any location you like.%@NL@% %@NL@% %@NL@% %@CR:MCVF2700@%%@3@%%@AB@%15.2.7 Moving Library Modules (Extracting)%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2701@%%@4@%Use the move c field to move an object module from the library file to an%@EH@% object file. This operation is equivalent to copying the module to an object file, then deleting the module from the library.%@NL@% %@NL@% %@NL@% %@CR:MCVF2800@%%@3@%%@AB@%15.2.8 Combining Libraries%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2801@%%@4@%You can add another library by using the add command symbol (%@AB@%+%@AE@%) with a%@EH@% library-file name instead of an object-file name in the %@AI@%commands%@AE@% field. In the %@AI@%commands%@AE@% field or at the %@AS@%Operations%@AE@% prompt, give the add command symbol (%@AB@%+%@AE@%) followed by the name of the library whose contents you wish to add to the library being changed. When you use this option, you must include the .LIB extension of the library-file name. Otherwise, LIB assumes that the file is an object file and looks for the file with an .OBJ extension.%@NL@% %@NL@% %@CR:MCVF2802@%%@4@%In addition to DOS libraries as input, LIB also accepts 286 XENIX archives%@EH@% and Intel-format libraries. Therefore, you can use LIB to convert libraries from either of these formats to the DOS format.%@NL@% %@NL@% %@CR:MCVF2803@%%@4@%LIB adds the modules of the library to the end of the library being changed.%@EH@% Note that the added library still exists as an independent library. LIB copies the modules without deleting them.%@NL@% %@NL@% %@CR:MCVF2804@%%@4@%Once you have added the contents of a library or libraries, you can save the%@EH@% new, combined library under a new name by giving a new name in the %@AI@%newlibrary%@AE@% field of the command line or at the %@AS@%Output library%@AE@% prompt. If you omit the %@AS@%Output library%@AE@% response, LIB saves the combined library under the name of the original library being changed. The original library is saved with the same base name and the extension .BAK.%@NL@% %@NL@% %@NL@% %@CR:MCVF2900@%%@3@%%@AB@%15.2.9 Creating a Cross-Reference-Listing File%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2901@%%@4@%Create a cross-reference-listing file by giving a name for the listing file%@EH@% in the %@AI@%listfile%@AE@% field of the command line or at the %@AS@%List file%@AE@% prompt. If you do not give a listing-file name, LIB uses the special file name NUL, which means no listing file is created.%@NL@% %@NL@% %@CR:MCVF2902@%%@4@%You can give the listing file any name and any extension. To cause the%@EH@% listing file to be created outside your current working directory, you can specify a full path name, including drive designation. LIB does not supply a default extension if you omit the extension.%@NL@% %@NL@% %@CR:MCVF2903@%%@4@%A cross-reference-listing file contains two lists. The first is an%@EH@% alphabetical listing of all public symbols in the library. Each symbol name is followed by the name of the module in which it is referenced.%@NL@% %@NL@% %@CR:MCVF2904@%%@4@%The second list is an alphabetical list of the modules in the library. Under%@EH@% each module name is an alphabetical listing of the public symbols referenced in that module.%@NL@% %@NL@% %@NL@% %@CR:MCVF2A00@%%@3@%%@AB@%15.2.10 Performing Consistency Checks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2A01@%%@4@%When you give only a library name followed by a semicolon in the %@AI@%oldlibrary%@AE@%%@EH@% field of the command line or at the %@AS@%Library name%@AE@% prompt, LIB performs a consistency check, displaying messages about any errors it finds. No changes are made to the library. It is not usually necessary to perform consistency checks since LIB automatically checks object files for consistency before adding them to the library.%@NL@% %@NL@% %@CR:MCVF2A02@%%@4@%To produce a cross-reference-listing file with a consistency check, invoke%@EH@% LIB, specify the library name followed by a semicolon, and give the name of the listing file. LIB then performs the consistency check and creates the cross-reference-listing file.%@NL@% %@NL@% %@NL@% %@CR:MCVF2B00@%%@3@%%@AB@%15.2.11 Setting the Library-Page Size%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVF2B01@%%@4@%You can set the library-page size while you are creating a library, and you%@EH@% can change the page size of an existing library by adding a page-size option after the library-file name in the LIB command line or after the new library-file name at the %@AS@%Library name%@AE@% prompt. The option has the following form:%@NL@% %@NL@% %@AB@%/PA%@AE@%«%@AB@%GESIZE%@AE@%» %@AB@%:%@AE@%%@AI@%number%@AE@%%@NL@% %@NL@% %@CR:MCVF2B02@%%@4@%The %@AI@%number%@AE@% specifies the new page size. It must be an integer value%@EH@% representing a power of 2 between the values 16 and 32,768.%@NL@% %@NL@% %@CR:MCVF2B03@%%@4@%The page size of a library affects the alignment of modules stored in the%@EH@% library. Modules in the library are always aligned to start at a position that is a multiple of the page size (in bytes) from the beginning of the file. The default page size is 16 bytes for a new library or the current page size for an existing library.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Because of the indexing technique used by %@AB@%LIB%@AE@%, a library with a large page%@NL@% size can hold more modules than a library with a smaller page size.%@NL@% However, for each module in the library, an average of %@AI@%pagesize%@AE@%/2 bytes%@NL@% of storage space is wasted. In most cases, a small page size is%@NL@% advantageous; you should use a small page size unless you need to put a%@NL@% very large number of modules in a library.%@NL@% %@NL@% Another consequence of this indexing technique is that the page size%@NL@% determines the maximum possible size of the %@AB@%.LIB%@AE@% file. Specifically,%@NL@% this limit is %@AI@%number%@AE@% %@AB@%*%@AE@% 65,536. For example, %@AS@%/P:16%@AE@% means that the %@AB@%.LIB%@AE@%%@NL@% file has to be smaller than 1 megabyte (16 %@AB@%*%@AE@% 65,536 bytes).%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVG0000@%%@1@%%@AB@%Chapter 16 NMAKE%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVG0001@%%@4@%The Microsoft Program-Maintenance Utility (NMAKE) can save you time by%@EH@% automating the process of updating project files. NMAKE compares the modification dates for one set of files, the target files, to those of another set of files, the dependent files. If any of the dependent files have changed more recently than the target files, NMAKE executes a specified series of commands.%@NL@% %@NL@% %@CR:MCVG0002@%%@4@%NMAKE is typically used by specifying a project's executable files as target%@EH@% files and the project's source files as the dependent files. If any of the source files have changed since the executable file was created, NMAKE can issue a command to assemble or compile the changed source files and link them into the executable file.%@NL@% %@NL@% %@CR:MCVG0003@%%@4@%NMAKE reads the target- and dependent-file specifications from a%@EH@% "description file," also called a "makefile." The description file comprises any number of description blocks. Each description block lists one or more targets and the dependent files related to those targets. The block also gives the commands that NMAKE must execute to bring the targets up to date. The description file may also contain macros, inference rules, and directives.%@NL@% %@NL@% %@NL@% %@CR:MCVG1000@%%@2@%%@AB@%16.1 Invoking NMAKE%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG1001@%%@4@%Two methods for invoking NMAKE are available:%@EH@%%@NL@% %@NL@% %@CR:MCVG1002@% 1. Specify options, macro definitions, and the names of targets to be%@NL@% built on the DOS command line.%@NL@% %@NL@% 2. Specify options, macro definitions, and the names of targets to be%@NL@% built in a command file, and give the file name on the DOS command%@NL@% line.%@NL@% %@NL@% %@NL@% %@CR:MCVG1100@%%@3@%%@AB@%16.1.1 Using a Command Line to Invoke NMAKE%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG1101@%%@4@%The syntax for invoking NMAKE from the command line is as follows:%@EH@%%@NL@% %@NL@% NMAKE «%@AI@%options%@AE@%» «%@AI@%macrodefinitions%@AE@%» «%@AI@%target...%@AE@%» «%@AI@%filename%@AE@%»%@NL@% %@NL@% %@CR:MCVG1102@%%@4@%The %@AI@%options%@AE@% field specifies options that modify the action of NMAKE.%@EH@% (Options are not required.) They are described in Section 16.2%@BO: adfed@%.%@NL@% %@NL@% %@CR:MCVG1103@%%@4@%The optional %@AI@%macrodefinitions%@AE@% field lists macro definitions for NMAKE to%@EH@% use. Macros provide a convenient method for replacing a string of text in the description file. Macro definitions that contain spaces must be enclosed by quotation marks. Macros are discussed in Section 16.3.2%@BO: b1bf8@%.%@NL@% %@NL@% %@CR:MCVG1104@%%@4@%The optional %@AI@%target...%@AE@% field specifies the name of one or more targets to%@EH@% build. If you do not list any targets, NMAKE builds the first target in the description file.%@NL@% %@NL@% %@CR:MCVG1105@%%@4@%The optional %@AI@%filename%@AE@% field gives the name of the description file from%@EH@% which NMAKE reads target- and dependent-file specifications and commands. A better way of designating the description file is to use the /F option (described in Section 16.2%@BO: adfed@%). By default, NMAKE looks for a file named MAKEFILE in the current directory. If MAKEFILE does not exist, NMAKE uses the %@AI@%filename%@AE@% field; it interprets the first string on the command line that is not an option or macro definition as the name of the description file, provided its file-name extension isn't listed in the .SUFFIXES list. (See Section 16.3.5%@BO: b8373@% for more information on the .SUFFIXES list.)%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Unless you use the /F option, NMAKE always searches for a file named%@NL@% MAKEFILE in the current directory.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVG1106@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% NMAKE /S "program = flash" sort.exe search.exe%@NL@% %@NL@% %@CR:MCVG1107@%%@4@%This example invokes NMAKE with the /S option, a macro assigning %@AS@%flash%@AE@% to%@EH@% %@AS@%program%@AE@%, and two targets, %@AS@%sort.exe%@AE@% and %@AS@%search.exe%@AE@%. By default, NMAKE uses the file named MAKEFILE as the description file.%@NL@% %@NL@% %@NL@% %@CR:MCVG1200@%%@3@%%@AB@%16.1.2 Using a Command File to Invoke NMAKE%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG1201@%%@4@%To invoke NMAKE with a command file, first create the command file, then%@EH@% issue a command with the following syntax:%@NL@% %@NL@% NMAKE @%@AI@%commandfile%@AE@%%@NL@% %@NL@% %@CR:MCVG1202@%%@4@%Here %@AI@%commandfile%@AE@% is the name of a file containing the same information that%@EH@% would be specified on the command line: options, macro definitions, and targets. The command file is not the same as the description file.%@NL@% %@NL@% %@CR:MCVG1203@%%@4@%A command file is useful for invoking NMAKE with a long string of%@EH@% command-line arguments, such as macro definitions, that might exceed the DOS limit of 128 characters. NMAKE treats line breaks that occur between arguments as spaces. Macro definitions can span multiple lines by ending each line except the last with a backslash ( \). Macro definitions that contain spaces must be enclosed by quotation marks, just as if they were entered directly on the command line.%@NL@% %@NL@% %@CR:MCVG1204@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% /S "program \%@NL@% = flash" sort.exe search.exe%@NL@% %@NL@% %@CR:MCVG1205@%%@4@%Assume a file named %@AS@%update%@AE@% contains the text above. The command below%@EH@% invokes NMAKE with the description file MAKEFILE, the /S option, the macro definition %@AS@%program = flash%@AE@%, and the targets %@AS@%sort.exe%@AE@% and %@AS@%search.exe%@AE@%. Note that the backslash ending the line allows the macro definition to span two lines.%@NL@% %@NL@% NMAKE @update%@NL@% %@NL@% %@NL@% %@CR:MCVG2000@%%@2@%%@AB@%16.2 NMAKE Options%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG2001@%%@4@%NMAKE accepts a number of command-line options, which are listed below. You%@EH@% may specify options in uppercase or lowercase and use either a slash or dash. For example, -B, /B, -b, and /b all represent the same option.%@NL@% %@CR:MCVG2002@%%@NL@% %@TH: 64 3395 2 27 49 @%%@CR:MCVG3252@%%@AB@%Option Action%@AE@%/A Executes commands to build all the targets requested even if they are not out of date./C Suppresses the NMAKE copyright message and prevents nonfatal error or warning messages from being displayed./D Displays the modification date of each file when the date is checked./E Causes environment variables to override macro definitions within description files./F %@AI@%filename%@AE@% Specifies %@AI@%filename%@AE@% as the name of the description file to use. If a dash (-) is entered instead of a file name, NMAKE accepts input from the standard input device instead of using a description file. If /F is not specified, NMAKE uses the file named MAKEFILE as the description file. If MAKEFILE does not exist, NMAKE uses the first string on the command line that is not an option or macro definition as the name of the file, provided the extension is not listed in the .SUFFIXES list (see Section 16.3.5%@BO: b8373@%)./I Ignores exit codes (also called return or "errorlevel" codes) returned by programs called from the NMAKE description file. NMAKE continues executing the rest of the description file despite the errors./N Displays the commands from the description file that NMAKE would execute but does not execute these commands. This option is useful for checking which targets are out of date and for debugging description files./P Prints all macro definitions and target descriptions./Q Returns a zero status code if the target is up to date and a nonzero status code if it is not. This option is useful when invoking NMAKE from within a batch file./R Ignores inference rules and macros contained in the TOOLS.INI file./S Does not display commands as they are executed./T Changes the modification dates for out-of-date target files to the current date. The file contents are not modified./X %@AI@%filename%@AE@% Sends all error output to %@AI@%filename%@AE@%, which can be either a file or a device. If a dash (-) is entered instead of a file name, the error output is sent to the standard output device.%@TE: 64 3395 2 27 49 @% %@NL@% %@CR:MCVG2003@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% NMAKE /f quick /c f1 f2%@NL@% %@NL@% %@CR:MCVG2004@%%@4@%The example above causes NMAKE to execute the commands in the description%@EH@% file %@AS@%quick%@AE@% to update the targets %@AS@%f1%@AE@% and %@AS@%f2%@AE@%. The /c option prevents NMAKE from displaying nonfatal error messages and warnings.%@NL@% %@NL@% NMAKE /D /N f1 f1.mak%@NL@% %@NL@% %@CR:MCVG2005@%%@4@%In the example above, NMAKE updates the target %@AS@%f1%@AE@%. If the current directory%@EH@% does not contain a file named MAKEFILE, NMAKE reads the file %@AS@%f1.mak%@AE@% as the description file. The /D option displays the modification date of each file and the /N option displays the commands without executing them.%@NL@% %@NL@% %@NL@% %@CR:MCVG3000@%%@2@%%@AB@%16.3 Description Files%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3001@%%@4@%NMAKE reads a description file to determine what to do. The description file%@EH@% may contain any number of description blocks, along with macros, inference rules, and directives. These can be in any order.%@NL@% %@NL@% %@CR:MCVG3002@%%@4@%When NMAKE runs, it builds the first target in the description file by%@EH@% default. You can override this default by specifying on the command line the names of the targets to build.%@NL@% %@NL@% %@CR:MCVG3003@%%@4@%The sections that follow describe the elements of a description file.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCVG3100@%%@3@%%@AB@%16.3.1 Description Blocks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3101@%%@4@%An NMAKE description file contains one or more description blocks. Each has%@EH@% the following form:%@NL@% %@NL@% %@CR:MCVG3102@%%@AI@%target... %@AB@%:%@AE@% «%@AI@%dependent%@AE@%...» «%@AB@%;%@AE@% %@AI@%command%@AE@%»«%@AB@%#%@AE@%%@AI@%comment%@AE@%»%@NL@% «%@AI@%command%@AE@%» «%@AB@%#%@AE@%%@AI@%comment%@AE@%» «%@AB@%#%@AE@%%@AI@%comment%@AE@%» | «%@AI@%command%@AE@%» . . .%@NL@% %@NL@% %@CR:MCVG3103@%%@4@%The file to be updated is target; %@AI@%dependent%@AE@% is a file upon which %@AI@%target%@AE@%%@EH@% depends; %@AI@%command%@AE@% target; and %@AI@%comment%@AE@% documents what is happening. The line containing %@AI@%target%@AE@% and %@AI@%dependent%@AE@% is called the dependency line because %@AI@%target%@AE@% depends on %@AI@%dependent%@AE@%.%@NL@% %@NL@% %@CR:MCVG3104@%%@4@%Each component of a description block is discussed below.%@EH@%%@NL@% %@NL@% %@CR:MCVG3110@%%@4@%%@AB@%The Target Field%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3111@%%@4@%The %@AI@%target%@AE@% field specifies the name of one or more files to update. If you%@EH@% specify more than one file, separate the file names by a space. The first target name must start in the first column of the line; it may not be preceded by any tabs or spaces. Note that the target need not be a file; it may be a pseudotarget, as described in Section 16.3.5%@BO: b8373@%. A target name can have a complete path specification, i.e., drive: path filename.ext. If a target name is a single letter, then a space must be inserted before the ":" to avoid confusion with a path name, such as "a:".%@NL@% %@NL@% %@CR:MCVG3120@%%@4@%%@AB@%The Dependent Field%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3121@%%@4@%The %@AI@%dependent%@AE@% field lists one or more files on which the target depends. If%@EH@% you specify more than one file, separate the file names by a space. You can specify directories for NMAKE to search for the dependent files by using the following form:%@NL@% %@NL@% %@AI@%target%@AE@% : {%@AI@%directory1%@AE@%;%@AI@%directory2...%@AE@%}%@AI@%dependent%@AE@%%@NL@% %@NL@% %@CR:MCVG3122@%%@4@%NMAKE searches the current directory first, then %@AI@%directory1%@AE@%, %@AI@%directory2%@AE@%, and%@EH@% so on. If %@AI@%dependent%@AE@% cannot be found in any of these directories, NMAKE looks for an inference rule to create the dependent in the current directory. See Section 16.3.3%@BO: b4fe0@% for more information on inference rules.%@NL@% %@NL@% %@CR:MCVG3123@%%@4@%In the following example, NMAKE first searches the current directory for%@EH@% %@AS@%pass.obj%@AE@%, then the %@AS@%\src\alpha%@AE@% directory, and finally the %@AS@%d:\proj%@AE@% directory:%@NL@% %@NL@% forward.exe : {\src\alpha;d:\proj}pass.obj%@NL@% %@NL@% %@CR:MCVG3130@%%@4@%%@AB@%TheCommand Field%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3131@%%@4@%The %@AI@%command%@AE@% is used to update the target. This can be any command that can%@EH@% be issued on the DOS command line. A semicolon must precede the command if it is given on the same line as the target and dependent files. Commands may be placed on separate lines following the dependency line, but each line must start with at least one space or tab character. Blank lines may be intermixed with commands. A long command may span several lines if each line ends with a backslash (\). If no commands are specified, NMAKE looks for an inference rule to build the target.%@NL@% %@NL@% %@CR:MCVG3140@%%@4@%%@AB@%The Comment Field%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3141@%%@4@%NMAKE considers any text between a number sign (#) and a new-line character%@EH@% to be a comment and ignores it. You may place a comment on a line by itself or at the end of any line except a command line. In the command section of the description file, comments must start in the first column.%@NL@% %@NL@% %@CR:MCVG3150@%%@4@%%@AB@%Wild-Card Characters%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3151@%%@4@%You can use the DOS wild-card characters (* and ?) when specifying target-%@EH@% and dependent-file names. NMAKE expands wild cards in target names when it reads the description file. It expands wild cards in the dependent names when it builds the target. For example, the following description block compiles all source files with the .C extension:%@NL@% %@NL@% astro.exe : *.c%@NL@% QCL *.c%@NL@% %@NL@% %@CR:MCVG3160@%%@4@%%@AB@%Escape Character%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3161@%%@4@%You can use a caret (^) to escape any DOS or OS/2 file-name character in a%@EH@% description file, so that the character takes on its literal meaning and does not have any special significance to NMAKE. Specifically, the caret escapes the following characters:%@NL@% %@NL@% %@CR:MCVG3162@%%@4@%# ( ) $ ^ \ { } ! @ -%@EH@%%@NL@% %@NL@% %@CR:MCVG3163@%%@4@%For example, NMAKE interprets the specification%@EH@%%@NL@% %@NL@% big^#.c%@NL@% %@NL@% %@CR:MCVG3164@%%@4@%as the file name%@EH@%%@NL@% %@NL@% big#.c%@NL@% %@NL@% %@CR:MCVG3165@%%@4@%Using the caret, you can include a literal new-line character in a%@EH@% description file. This capability is primarily useful in macro definitions, as in the following example:%@NL@% %@NL@% XYZ=abc^%@NL@% def%@NL@% %@NL@% %@CR:MCVG3166@%%@4@%NMAKE interprets this example as if you had assigned to the XYZ macro the%@EH@% C-style string %@AS@%abc\ndef%@AE@%. Note that this effect differs from the use of the backslash (\) to continue a line. A new-line character that follows a backslash is replaced with a space.%@NL@% %@NL@% %@CR:MCVG3167@%%@4@%NMAKE ignores a caret that is not followed by any of the characters%@EH@% mentioned above, as in the following:%@NL@% %@NL@% mno ^: def%@NL@% %@NL@% %@CR:MCVG3168@%%@4@%In this case, NMAKE ignores the caret and treats the line as%@EH@%%@NL@% %@NL@% mno : def%@NL@% %@NL@% %@CR:MCVG3169@%%@4@%Carets that appear within quotation marks are not treated as escape%@EH@% characters.%@NL@% %@NL@% %@CR:MCVG3170@%%@4@%%@AB@%16.3.1.2 Modifying Commands%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3171@%%@4@%Three different characters may be placed in front of a command to modify its%@EH@% effect. The character must be preceded by at least one space, and spaces may separate the character from the command. You may use more than one character to modify a single command. The characters are listed below.%@NL@% %@CR:MCVG3172@%%@NL@% %@TH: 42 2184 2 27 49 @%%@AB@%Character Action%@AE@%Dash (-) Turns off error checking for the command. If the dash is followed by a number, NMAKE halts only if the error level returned by the command is greater than the number. In the following example, if the program %@AS@%flash%@AE@% returned an error code NMAKE would not halt, but would continue to execute commands: %@AS@%light.lst:light.txt%@AE@% %@AS@% -flash light.txt%@AE@%At sign(@) Prevents NMAKE from displaying the command as it executes. In the example below, NMAKE does not display the ECHO command line: %@AS@%sort.exe:sort.obj%@AE@% %@AS@% @ECHO sorting%@AE@% The output of the ECHO command, however, appears as usual. (This modifier does not work with DOS 2.1.)Exclamation Causes the command to be executed for eachpoint (!) dependent file if the command uses one of the special macros $? or $**. The $? macro refers to all dependent files that are out of date with respect to the target, while $** refers to all dependent files in the description block. (See Section 16.3.2%@BO: b1bf8@% for more information on macros.) For example, %@AS@%print: hop.asm skip.bas jump.c%@AE@% %@AS@% !print $** lpt1:%@AE@% causes the following three commands to be generated: %@AS@%print hop.asm lpt1:%@AE@% %@AS@%print skip.bas lpt1:%@AE@% %@AS@%print jump.c lpt1:%@TE: 42 2184 2 27 49 @% %@NL@% %@CR:MCVG3180@%%@4@%%@AB@%16.3.1.3 Specifying a Target in Multiple Description Blocks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3181@%%@4@%You can specify more than one description block for the same target by using%@EH@% two colons (::) as the separator instead of one. For example:%@NL@% %@NL@% target.lib :: a.asm b.asm c.asm%@NL@% ML a.asm b.asm c.asm%@NL@% LIB target -+a.obj -+b.obj -+c.obj;%@NL@% target.lib :: d.c e.c%@NL@% QCL /c d.c e.c%@NL@% LIB target -+d.obj -+e.obj;%@NL@% %@NL@% %@CR:MCVG3182@%%@4@%These two description blocks both update the library named %@AS@%target.lib%@AE@%. If%@EH@% any of the assembly-language files have changed more recently than the library file, NMAKE executes the commands in the first block to assemble the source files and update the library. Similarly, if any of the C-language files have changed, NMAKE executes the second group of commands that compile the C files and then update the library.%@NL@% %@NL@% %@CR:MCVG3183@%%@4@%If you use a single colon in the above example, NMAKE issues an error%@EH@% message. It is legal, however, to use single colons if commands are listed in only one block. In this case, dependency lines are cumulative. For example,%@NL@% %@NL@% target: jump.bas%@NL@% target: up.c%@NL@% %@AI@%commands%@AE@%%@NL@% %@NL@% %@CR:MCVG3184@%%@4@%is equivalent to%@EH@%%@NL@% %@NL@% target: jump.bas up.c%@NL@% %@AI@%commands%@AE@%%@NL@% %@NL@% %@NL@% %@CR:MCVG3200@%%@3@%%@AB@%16.3.2 Macros%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3201@%%@4@%Macros provide a convenient way to replace a string in the description file%@EH@% with another string. The text is automatically replaced each time NMAKE is invoked. This feature makes it easy to change text used throughout the description file without having to edit every line that uses the text.%@NL@% %@NL@% %@CR:MCVG3202@%%@4@%Macros can be used in a variety of situations, including the following:%@EH@%%@NL@% %@NL@% %@CR:MCVG3203@% ■ To create a standard description file for several projects. The macro%@NL@% represents the file names used in commands. These file names are then%@NL@% defined when you run NMAKE. When you switch to a different project,%@NL@% changing the macro changes the file names NMAKE uses throughout the%@NL@% description file.%@NL@% %@NL@% ■ To control the options that NMAKE passes to the compiler, assembler, or%@NL@% linker. When you use a macro to specify the options, you can quickly%@NL@% change the options used throughout the description file in one easy%@NL@% step.%@NL@% %@NL@% %@CR:MCVG3210@%%@4@%%@AB@%16.3.2.1 Macro Definitions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3211@%%@4@%A macro definition uses the following form:%@EH@%%@NL@% %@NL@% %@AI@%macroname%@AE@% = %@AI@%string%@AE@%%@NL@% %@NL@% %@CR:MCVG3212@%%@4@%The %@AI@%macroname%@AE@% may be any combination of alphanumeric characters and the%@EH@% underscore (_) character. The %@AI@%string%@AE@% may be any valid string.%@NL@% %@NL@% %@CR:MCVG3213@%%@4@%You can define macros on the NMAKE command line or in the description file.%@EH@% Because of the way DOS parses command lines, the rules for the two methods are slightly different.%@NL@% %@NL@% %@CR:MCVG3220@%%@4@%%@AB@%Defining Macros in Description Files%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3221@%%@4@%In NMAKE description files, define each macro on a separate line. The first%@EH@% character of the macro name must be the first character on the line. NMAKE ignores spaces following %@AI@%macroname%@AE@% or preceding %@AI@%string%@AE@%. The %@AI@%string%@AE@% may be a null string and may contain embedded spaces. Do not enclose %@AI@%string%@AE@% in quotation marks; NMAKE will consider them part of the string.%@NL@% %@NL@% %@CR:MCVG3230@%%@4@%%@AB@%Defining Macros on the NMAKE Command Line%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3231@%%@4@%On the command line, no spaces may surround the equal sign. Spaces cause DOS%@EH@% to treat %@AI@%macroname%@AE@% and %@AI@%string%@AE@% as separate tokens. Strings that contain embedded spaces must be enclosed in double quotation marks. Alternatively, you can enclose the entire macro definition──%@AI@%macroname%@AE@% and %@AI@%string%@AE@%──in quotation marks. The %@AI@%string%@AE@% may be a null string. C command line macro definitions override definitions of the same macro in the description file.%@NL@% %@NL@% %@CR:MCVG3232@%%@4@%After you have defined a macro, use the following to include it in a%@EH@% dependency line or command:%@NL@% %@NL@% $(%@AI@%macroname%@AE@%)%@NL@% %@NL@% %@CR:MCVG3233@%%@4@%The parentheses are not required if %@AI@%macroname%@AE@% is only one character long. If%@EH@% you want to use a dollar sign ($) in the file but do not want to invoke a macro, enter two dollar signs ($$), or use the caret (^) as an escape character preceding the dollar sign.%@NL@% %@NL@% %@CR:MCVG3234@%%@4@%When NMAKE runs, it replaces all occurrences of $(%@AI@%macroname%@AE@%) with %@AI@%string%@AE@%. If%@EH@% the macro is undefined──that is, if its name does not appear to the left of an equal sign in the file or on the NMAKE command line, NMAKE treats it as a null string. Once a macro is defined, the only way to cancel its definition is to use the %@AB@%!UNDEF%@AE@% directive (see Section 16.3.4%@BO: b66d0@%).%@NL@% %@NL@% %@CR:MCVG3235@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3236@%%@4@%Assume the following text is in a file named MAKEFILE:%@EH@%%@NL@% %@NL@% program = flash%@NL@% c = LINK%@NL@% options =%@NL@% %@NL@% $(program).exe : $(program).obj%@NL@% $c $(options) $(program).obj;%@NL@% %@NL@% %@CR:MCVG3237@%%@4@%When you invoke NMAKE, it interprets the description block as the following:%@EH@%%@NL@% %@NL@% flash.exe : flash.obj%@NL@% LINK flash.obj;%@NL@% %@NL@% %@CR:MCVG3240@%%@4@%%@AB@%16.3.2.1 Macro Substitutions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3241@%%@4@%Just as macros allow you to substitute text in a description file, you can%@EH@% also substitute text within a macro itself. Use the following form:%@NL@% %@NL@% $(%@AI@%macroname%@AE@%:%@AI@%string1%@AE@% = %@AI@%string2%@AE@%)%@NL@% %@NL@% %@CR:MCVG3242@%%@4@%Every occurrence of %@AI@%string1%@AE@% is replaced by %@AI@%string2%@AE@% in the macro %@AI@%macroname%@AE@%.%@EH@% Spaces between the colon and %@AI@%string1%@AE@% are considered part of %@AI@%string1%@AE@%. Any spaces following %@AI@%string1%@AE@% or preceding %@AI@%string2%@AE@% are ignored. If %@AI@%string2%@AE@% is a null string, all occurrences of %@AI@%string1%@AE@% are deleted from the %@AI@%macroname%@AE@% macro.%@NL@% %@NL@% %@CR:MCVG3243@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% SRCS = prog.c sub1.c sub2.c%@NL@% %@NL@% DUP : $(SRCS)%@NL@% echo $(srcs)%@NL@% echo $(srcs:.c=.obj)%@NL@% %@NL@% %@CR:MCVG3244@%%@4@%Note that the special macro $** stands for the names of all the dependent%@EH@% files (see Section 16.3.2.3%@BO: b4c9e@%). If the description file above is invoked with a command line that specifies both targets, NMAKE will execute the following commands:%@NL@% %@NL@% echo prog.c sub1.c sub2.c%@NL@% prog.c sub1.c sub2.c%@NL@% echo prog.obj sub1.obj sub2.obj%@NL@% prog.obj sub1.obj sub2.obj%@NL@% %@NL@% %@CR:MCVG3245@%%@4@%The macro substitution does not alter the definition of the macro %@AS@%SRCS%@AE@%, but%@EH@% replaces the listed characters. When NMAKE builds the target %@AS@%prog.exe%@AE@%, it picks up the definition for the special macro $** (that is, the list of dependents) from the dependency line, which specifies the macro substitution in %@AS@%SRCS%@AE@%. The same is true for the second target, %@AS@%DUP%@AE@%. In this case, however, no macro substitution is requested, so %@AS@%SRCS%@AE@% retains its original value, and $** represents the names of the C source files.%@NL@% %@NL@% %@CR:MCVG3250@%%@4@%%@AB@%16.3.2.2 Special Macros%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3251@%%@4@%Several macros have special meaning. These macros are listed below with%@EH@% their values:%@NL@% %@NL@% %@TH: 46 2323 2 27 49 @%%@AB@%Macro Value%@AE@%$* The target name with the extension deleted.$@ The full name of the current target.$** The complete list of dependent files.$< The dependent file that is out of date with respect to the target (evaluated only for inference rules).$? The list of dependents that are out of date with respect to the target.$$@ The target NMAKE is currently evaluating. This is a dynamic dependency parameter that can be used only in dependency lines. See "Examples," below, for a typical use of this macro.$(CC) The command to invoke the C compiler. By default, NMAKE predefines this macro as %@AS@%CC = cl%@AE@%, which invokes the Microsoft C Optimizing Compiler. To redefine the macro to invoke the QuickC compiler, use %@AS@%CC = qcl%@AE@% You might want to place the above definition in your TOOLS.INI file to avoid having to redefine it for each description file.$(AS) The command that invokes the Microsoft Macro Assembler. NMAKE predefines this macro as %@AS@%AS = masm%@AE@%.$(MAKE) The name with which the NMAKE utility was invoked. This macro is used to invoke NMAKE recursively. It causes the line on which it appears to be executed even if the /N option is on. You may redefine this macro if you want to execute another program.$(MAKEFLAGS) The NMAKE options currently in effect. If you invoke NMAKE recursively, you should use the command: %@AS@%$(MAKE)%@AE@%. You cannot redefine this macro.%@TE: 46 2323 2 27 49 @% %@NL@% %@CR:MCVG3253@%%@4@%You can append characters to any of the first six macros in the above list%@EH@% to modify its meaning. Appending a D specifies the directory part of the file name only, an F specifies the file name, a B specifies just the base name, and an R specifies the complete file name without the extension. If you add one of these characters, you must enclose the macro name in parentheses. (The special macros $$@ and $** are the only exceptions to the rule that macro names more than one character long must be enclosed in parentheses.)%@NL@% %@NL@% %@CR:MCVG3254@%%@4@%For example, assume that $@ has the value %@AS@%C:\SOURCE\PROG\SORT.OBJ%@AE@%. The list%@EH@% below shows the effect the special characters have when combined with $@:%@NL@% %@NL@% %@CR:MCVG3255@%%@AB@%Macro Value%@AE@%%@NL@% %@NL@% $(@D) %@AS@%C:\SOURCE\PROG%@AE@%%@NL@% %@NL@% $(@F) %@AS@%SORT.OBJ%@AE@%%@NL@% %@NL@% $(@B) %@AS@%SORT%@AE@%%@NL@% %@NL@% $(@R) %@AS@%C:\SOURCE\PROG\SORT%@AE@%%@NL@% %@NL@% %@CR:MCVG3256@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% trig.lib : sin.obj cos.obj arctan.obj%@NL@% !LIB trig.lib -+$?;%@NL@% %@NL@% %@CR:MCVG3257@%%@4@%In the example above, the macro $? represents the names of all dependents%@EH@% that are more recent than the target. The exclamation point causes NMAKE to execute the LIB command once for each dependent in the list. As a result of this description, the LIB command is executed up to three times, each time replacing a module with a newer version.%@NL@% %@NL@% # Include files depend on versions in current directory%@NL@% DIR=c:\include%@NL@% $(DIR)\globals.h : globals.h%@NL@% COPY globals.h $@%@NL@% $(DIR)\types.h : types.h%@NL@% COPY types.h $@%@NL@% $(DIR)\macros.h : macros.h%@NL@% COPY macros.h $@%@NL@% %@NL@% %@CR:MCVG3258@%%@4@%This example shows the use of NMAKE to update a group of include files. In%@EH@% the description file above, each of the files %@AS@%globals.h%@AE@%, %@AS@%types.h%@AE@%, and %@AS@%macros.h%@AE@% in the directory %@AS@%c:\include%@AE@% depends on its counterpart in the current directory. If one of the include files is out of date, NMAKE replaces it with the file of the same name from the current directory.%@NL@% %@NL@% %@CR:MCVG3259@%%@4@%The description file below, which uses the special macro $$@, is equivalent.%@EH@%%@NL@% %@NL@% # Include files depend on versions in current directory%@NL@% DIR=c:\include%@NL@% $(DIR)\globals.h $(DIR)\types.h $(DIR)\macros.h: $$(@F)%@NL@% !COPY $? $@%@NL@% %@NL@% %@CR:MCVG325A@%%@4@%In this example, the special macro $$(@F) signifies the file name (without%@EH@% the directory) of the current target.%@NL@% %@NL@% %@CR:MCVG325B@%%@4@%When NMAKE executes the description, it evaluates the three targets, one at%@EH@% a time, with respect to their dependents. Thus, NMAKE first checks whether %@AS@%c:\include\globals.h%@AE@% is out of date compared with %@AS@%globals.h%@AE@% in the current directory. If so, it executes the command to copy the dependent file %@AS@%globals.h%@AE@% to the target. NMAKE repeats the procedure for the other two targets. Note that in the command line, the macro $? refers to the dependent for this target. The macro $@ means the full name of the target.%@NL@% %@NL@% %@CR:MCVG3260@%%@4@%%@AB@%16.3.2.3 Precedence of Macro Definitions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3261@%%@4@%If the same macro is defined in more than one place, the rule with the%@EH@% highest priority is used. The priority from highest to lowest is as follows:%@NL@% %@NL@% %@CR:MCVG3262@% 1. Definitions on the command line%@NL@% %@NL@% 2. Definitions in the description file or in an include file%@NL@% %@NL@% 3. Definitions by an environment variable%@NL@% %@NL@% 4. Definitions in the TOOLS.INI file%@NL@% %@NL@% 5. Predefined macros such as CC and AS%@NL@% %@NL@% %@CR:MCVG3263@%%@4@%If NMAKE is invoked with the /E option, which causes environment variables%@EH@% to override macro definitions, macros defined by environment variables take precedence over those defined in a description file.%@NL@% %@NL@% %@NL@% %@CR:MCVG3300@%%@3@%%@AB@%16.3.3 Inference Rules%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3301@%%@4@%Inference rules are templates that NMAKE uses to generate files with a given%@EH@% extension. When NMAKE encounters a description block with no commands, it looks for an inference rule that specifies how to create the target from the dependent files, given the two file extensions. Similarly, if a dependent file does not exist, NMAKE looks for an inference rule that specifies how to create the dependent from another file with the same base name.%@NL@% %@NL@% %@CR:MCVG3302@%%@4@%The use of inference rules eliminates the need to put the same commands in%@EH@% several description blocks. For example, you can use inference rules to specify a single QCL command that changes any C source file (which has an extension of .C) to an object file (which has an extension of .OBJ).%@NL@% %@NL@% %@CR:MCVG3303@%%@4@%Inference rules have the following form:%@EH@%%@NL@% %@NL@% .%@AI@%fromext%@AE@%.%@AI@%toext%@AE@%:%@NL@% %@AI@%command%@AE@%%@NL@% «%@AI@%command%@AE@%»%@NL@% .%@NL@% .%@NL@% .%@NL@% %@NL@% %@CR:MCVG3304@%%@4@%In this format, %@AI@%command%@AE@% specifies one of the commands involved in converting%@EH@% a file with the extension %@AI@%fromext%@AE@% to a file with the extension %@AI@%toext%@AE@%. Using the earlier example of converting C source files to object files, the inference rule looks as follows:%@NL@% %@NL@% .C.OBJ:%@NL@% QCL -c $<;%@NL@% %@NL@% %@CR:MCVG3305@%%@4@%The special macro $< represents the name of a dependent that is out of date%@EH@% relative to the target.%@NL@% %@NL@% %@CR:MCVG3310@%%@4@%%@AB@%Path Specifications%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3311@%%@4@%You can specify a single path for each of the extensions, using the%@EH@% following form:%@NL@% %@NL@% {%@AI@%frompath%@AE@%}.%@AI@%fromext%@AE@%{%@AI@%topath%@AE@%}.%@AI@%toext%@AE@%%@NL@% %@AI@%commands%@AE@%%@NL@% %@NL@% %@CR:MCVG3312@%%@4@%NMAKE takes the files with the %@AI@%fromext%@AE@% extension it finds in the directory%@EH@% specified by %@AI@%frompath%@AE@% and uses %@AI@%commands%@AE@% to create files with the %@AI@%toext%@AE@% extension in the directory specified by %@AI@%topath%@AE@%.%@NL@% %@NL@% %@CR:MCVG3313@%%@4@%If NMAKE finds a description block without commands, it looks for an%@EH@% inference rule that matches both extensions. NMAKE searches for inference rules in the following order:%@NL@% %@NL@% %@CR:MCVG3314@% 1. In the current description file.%@NL@% %@NL@% 2. In the tools-initialization file, TOOLS.INI. NMAKE first looks for the%@NL@% TOOLS.INI file in the current working directory and then in the%@NL@% directory indicated by the INIT environment variable. If it finds the%@NL@% file, NMAKE looks for the inference rules following the line that%@NL@% begins with the tag [nmake]. This begins a section that can contain all%@NL@% default macros, .SUFFIXES lists, and inference rules.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% NMAKE applies an inference rule only if the base name of the file it is%@NL@% trying to create matches the base name of a file that already exists.%@NL@% In effect, this means that inference rules are useful only when there is%@NL@% a one-to-one correspondence between the files with the "from" extension%@NL@% and the files with the "to" extension. You cannot, for example, define an%@NL@% inference rule that inserts a number of modules into a library.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVG3320@%%@4@%%@AB@%Predefined Inference Rules%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3321@%%@4@%NMAKE uses three predefined inference rules, summarized in Table 16.1. Note%@EH@% that these rules use the macro CC, which invokes the Microsoft C Optimizing Compiler by default. If you plan to rely on inference rules to build your targets, you should redefine CC to invoke the QuickC compiler, as shown in the list in Section 16.3.2.3%@BO: b4c9e@%.%@NL@% %@NL@% %@CR:MCVGT100@%%@4@%%@AB@%Table 16.1 Predefined Inference Rules%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%Inference Rule Command Default Action%@AE@%%@NL@% %@NL@% .c.obj $(CC) $(CFLAGS) %@AS@%/c $*.c CL /c $*.c%@AE@%%@NL@% .c.exe $(CC) $(CFLAGS) %@AS@%$*.c CL $*.c%@AE@%%@NL@% .asm.obj $(AS) $(AFLAGS) %@AS@%$*; masm $*;%@AE@%%@NL@% %@NL@% %@CR:MCVG3322@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% .OBJ.EXE:%@NL@% LINK $<;%@NL@% %@NL@% EXAMPLE1.EXE: EXAMPLE1.OBJ%@NL@% %@NL@% EXAMPLE2.EXE: EXAMPLE2.OBJ%@NL@% LINK /CO EXAMPLE2,,,LIBV3.LIB%@NL@% %@NL@% %@CR:MCVG3323@%%@4@%In the sample description file above, the first line defines an inference%@EH@% rule that executes the LINK command on the second line to create an executable file whenever a change is made in the corresponding object file. The file name in the inference rule is specified with the special macro $< so that the rule applies to any .OBJ file that has an out-of-date executable file.%@NL@% %@NL@% %@CR:MCVG3324@%%@4@%When NMAKE does not find any commands in the first description block, it%@EH@% checks for a rule that may apply and finds the rule defined on the first two lines of the description file. NMAKE applies the rule, replacing the $< macro with %@AS@%EXAMPLE1.OBJ%@AE@% when it executes the command, so that the LINK command becomes%@NL@% %@NL@% LINK EXAMPLE1.OBJ;%@NL@% %@NL@% %@CR:MCVG3325@%%@4@%NMAKE does not search for an inference rule when examining the second%@EH@% description block because a command is explicitly given.%@NL@% %@NL@% %@NL@% %@CR:MCVG3400@%%@3@%%@AB@%16.3.4 Directives%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3401@%%@4@%Using directives, you can construct description files that are similar to%@EH@% batch files. NMAKE provides directives that specify conditional execution of commands, display error messages, include the contents of other files, and turn on or off some of NMAKE's options.%@NL@% %@NL@% %@CR:MCVG3402@%%@4@%Each directive begins with an exclamation point (!) in the first column of%@EH@% the description file. Spaces can be placed between the exclamation point and the directive keyword. The list below describes the directives.%@NL@% %@NL@% %@CR:MCVG3403@%%@NL@% %@TH: 52 3548 2 27 49 @%%@AB@%Directive Description%@AE@%%@AB@%!IF%@AE@% %@AI@%expression%@AE@% Executes the statements between the %@AB@%!IF%@AE@% keyword and the next %@AB@%!ELSE%@AE@% or %@AB@%!ENDIF%@AE@% directive if %@AI@%constantexpression%@AE@% evaluates to a nonzero value.%@AB@%!ELSE%@AE@% Executes the statements between the%@AB@%!ELSE%@AE@% and %@AB@%!ENDIF%@AE@% directives if the statements preceding the%@AB@%!ELSE%@AE@% directive were not executed.%@AB@%!ENDIF%@AE@% Marks the end of the %@AB@%!IF%@AE@%, %@AB@%!IFDEF%@AE@%, or %@AB@%!IFNDEF%@AE@% block of statements.%@AB@%!IFDEF%@AE@% %@AI@%macroname%@AE@% Executes the statements between the%@AB@%!IFDEF%@AE@% keyword and the next%@AB@%!ELSE%@AE@% or %@AB@%!ENDIF%@AE@% directive if %@AI@%macroname%@AE@% is defined in the description file. NMAKE considers a macro with a null value to be defined.%@AB@%!IFNDEF%@AE@% %@AI@%macroname%@AE@% Executes the statements between the %@AB@%!IFNDEF%@AE@% keyword and the next %@AB@%!ELSE%@AE@% or %@AB@%!ENDIF%@AE@% directive if %@AI@%macroname%@AE@% is not defined in the description file.%@AB@%!UNDEF%@AE@% %@AI@%macroname%@AE@% Marks %@AI@%macroname%@AE@% as being undefined in NMAKE's symbol table.%@AB@%!ERROR%@AE@% %@AI@%text%@AE@% Causes %@AI@%text%@AE@% to be printed and then stops execution.!%@AB@%INCLUDE%@AE@% %@AI@%filename%@AE@% Reads and evaluates the file %@AI@%filename%@AE@% before continuing with the current description file. If %@AI@%filename%@AE@% is enclosed by angle brackets (< >), NMAKE searches for the file in the directories specified by the INCLUDE macro; otherwise it looks in the current directory only. The INCLUDE macro is initially set to the value of the INCLUDE environment variable.!%@AB@%CMDSWITCHES: {%@AE@%%@AB@%+%@AE@%|%@AB@%-%@AE@%}%@AI@%opt%@AE@%. Turns on or off one of four NMAKE options: /D, /I, /N, and /S. If no options are specified, the options are reset to the way they were when NMAKE was started. Turn an option on by preceding it with a plus sign (+), or turn it off by preceding it with a minus sign (-). Using this directive updates the MAKEFLAGS macro.%@TE: 52 3548 2 27 49 @% %@NL@% %@CR:MCVG3404@%%@4@%The %@AI@%constantexpression%@AE@% used with the !IF directive may consist of integer%@EH@% constants, string constants, or program invocations. Integer constants can use the C unary operators for numerical negation (-), one's complement (~), and logical negation (!). They may also use any of the C binary operators listed below:%@NL@% %@CR:MCVG3405@%%@NL@% %@TH: 37 1031 2 27 49 @%%@AB@%Operator Description%@AE@%%@AB@%+%@AE@% Addition%@AB@%-%@AE@% Subtraction%@AB@%*%@AE@% Multiplication%@AB@%/%@AE@% Division%@AB@%%%@AE@% Modulus%@AB@%&%@AE@% Bitwise AND%@AB@%|-%@AE@% Bitwise OR%@AB@%^^%@AE@% Bitwise XOR%@AB@%&&%@AE@% Logical AND%@AB@%%@AB@%|-|-%@AE@% Logical OR%@AB@%<<%@AE@% Left shift%@AB@%>>%@AE@% Right shift%@AB@%==%@AE@% Equality%@AB@%!=%@AE@% Inequality%@AB@%<%@AE@% Less than%@AB@%>%@AE@% Greater than%@AB@%<=%@AE@% Less than or equal to%@AB@%>=%@AE@% Greater than or equal to%@TE: 37 1031 2 27 49 @% %@NL@% %@CR:MCVG3406@%%@4@%You can use parentheses to group expressions. Values are assumed to be%@EH@% decimal values unless specified with a leading 0 (octal) or leading 0x (hexadecimal). Use the equality (%@AB@%==%@AE@%) operator to compare two strings for equality or the inequality (%@AB@%!=%@AE@%) operator to compare for inequality. Strings are enclosed by quotes. Program invocations must be in square brackets ([ ]).%@NL@% %@NL@% %@CR:MCVG3407@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% !INCLUDE <infrules.txt>%@NL@% !CMDSWITCHES +D%@NL@% winner.exe:winner.obj%@NL@% !IFDEF debug%@NL@% ! IF "$(debug)"=="y"%@NL@% LINK /CO winner.obj;%@NL@% ! ELSE%@NL@% LINK winner.obj;%@NL@% ! ENDIF%@NL@% !ELSE%@NL@% ! ERROR Macro named debug is not defined.%@NL@% !ENDIF%@NL@% %@NL@% %@CR:MCVG3408@%%@4@%The %@AB@%!INCLUDE%@AE@% directive causes the file %@AS@%INFRULES.TXT%@AE@% to be read and evaluated%@EH@% as if it were a part of the description file. The %@AB@%!CMDSWITCHES%@AE@% directive turns on the /D option, which displays the dates of the files as they are checked. If %@AS@%winner.exe%@AE@% is out of date with respect to %@AS@%winner.obj%@AE@%, the %@AB@%!IFDEF%@AE@% directive checks to see if the macro %@AS@%debug%@AE@% is defined. If it is defined, the %@AB@%!IF%@AE@% directive checks to see if it is set to %@AS@%y%@AE@%. If it is, then the linker is invoked with the /CO option; otherwise it is invoked without it. If the %@AS@%debug%@AE@% macro is not defined, the %@AB@%!ERROR%@AE@% directive prints the message and NMAKE stops executing.%@NL@% %@NL@% %@NL@% %@CR:MCVG3500@%%@3@%%@AB@%16.3.5 Pseudotargets%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG3501@%%@4@%A "pseudotarget" is a target that is not a file but instead is a name that%@EH@% serves as a "handle" for building a group of files or executing a group of commands. In the following example, %@AS@%UPDATE%@AE@% is a pseudotarget.%@NL@% %@NL@% UPDATE: *.*%@NL@% !copy $** a:\product%@NL@% %@NL@% %@CR:MCVG3502@%%@4@%When NMAKE evaluates a pseudotarget, it always considers the dependents out%@EH@% of date. In the description above, NMAKE copies each of the dependent files to the specified drive and directory.%@NL@% %@NL@% %@CR:MCVG3503@%%@4@%The NMAKE utility includes four predefined pseudotargets that provide%@EH@% special rules within a description file. The list below describes these pseudotargets.%@NL@% %@CR:MCVG3504@%%@NL@% %@TH: 50 2874 2 27 49 @%%@AB@%Pseudotarget Action%@AE@%.SILENT: Does not display lines as they are executed. Same effect as invoking NMAKE with the /S option..IGNORE: Ignores exit codes returned by programs called from the description file. Same effect as invoking NMAKE with the /I option..SUFFIXES:%@AI@%list%@AE@% Lists file suffixes for NMAKE to try if it needs to build a target file for which no dependents are specified. NMAKE searches the current directory for a file with the same name as the target file and a suffix from the list. If NMAKE finds such a file, and if an inference rule applies to the file, then NMAKE treats the file as a dependent of the target. The order of the suffixes in the list defines the order in which NMAKE searches for the files. The list is predefined as follows: %@AS@%.SUFFIXES: .obj .exe .c .asm%@AE@% To add suffixes to the list, specify .SUFFIXES: followed by the new suffixes. To clear the list, specify .SUFFIXES:PRECIOUS: %@AI@%target%@AE@%... Tells NMAKE not to delete %@AI@%target%@AE@% if the commands that build it are quit or interrupted. Using this pseudotarget overrides the NMAKE default. By default, NMAKE deletes the target if it cannot be sure the target was built successfully. For example: %@AS@%.PRECIOUS: tools.lib%@AE@% %@AS@%tools.lib : a2z.obj z2a.obj%@AE@% %@AS@% .%@AE@% %@AS@% .%@AE@% %@AS@% .%@AE@% If the commands (not shown here) to build %@AS@%tools.lib%@AE@% are interrupted, leaving an incomplete file, NMAKE does not delete the partially built %@AS@%tools.lib%@AE@% because it is listed with .PRECIOUS. Note, however, that .PRECIOUS is useful only in limited circumstances. Most professional development tools, including those provided by Microsoft, have their own interrupt handlers and "clean up" when errors occur.%@TE: 50 2874 2 27 49 @% %@NL@% %@CR:MCVG4000@%%@2@%%@AB@%16.4 Response-File Generation%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG4001@%%@4@%At times, you may need to issue a command in the description file that has a%@EH@% list of arguments that exceeds the DOS limit of 128 characters. NMAKE can generate response files for use with other programs.%@NL@% %@NL@% %@CR:MCVG4002@%%@4@%The syntax for creating a response file is%@EH@%%@NL@% %@NL@% %@AI@%target%@AE@% : %@AI@%dependents%@AE@%%@NL@% %@AI@%command%@AE@% @<< «%@AI@%filename%@AE@%»%@NL@% %@AI@%response-file-text%@AE@%%@NL@% <<%@AI@%%@NL@% %@NL@% %@CR:MCVG4003@%%@4@%All of the text between the two sets of double brackets (<<) is placed in a%@EH@% response file and given the name %@AI@%filename%@AE@%. The response file can be referred to at a later time using %@AI@%filename%@AE@%. If %@AI@%filename%@AE@% is not given, NMAKE gives the file a unique name in the directory specified by the TMP environment variable if it is defined; otherwise it creates it in the current directory. Note that the at sign (@) is not part of the NMAKE syntax but is the typical response-file character for utilities such as LIB and LINK.%@NL@% %@NL@% %@CR:MCVG4004@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% math.lib : add.obj sub.obj mul.obj div.obj%@NL@% LIB @<<%@NL@% math.lib%@NL@% -+add.obj-+sub.obj-+mul.obj-+div.obj%@NL@% listing%@NL@% <<%@NL@% %@NL@% %@CR:MCVG4005@%%@4@%The above example creates a response file and uses it to invoke the%@EH@% Microsoft Library Manager LIB. The response file specifies which library to use, the commands to execute, and the listing file to produce. The response file contains the following:%@NL@% %@NL@% math.lib%@NL@% -+add.obj-+sub.obj-+mul.obj-+div.obj%@NL@% listing%@NL@% %@NL@% %@NL@% %@CR:MCVG5000@%%@2@%%@AB@%16.5 Differences between NMAKE and MAKE%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVG5001@%%@4@%NMAKE differs from MAKE in the following ways:%@EH@%%@NL@% %@NL@% %@CR:MCVG5002@% ■ It accepts command-line arguments from a file.%@NL@% %@NL@% ■ It provides more command-line options.%@NL@% %@NL@% ■ It no longer evaluates targets sequentially. Instead, it updates the%@NL@% targets you specify when you invoke NMAKE, regardless of their%@NL@% positions in the description file. If no targets are specified, NMAKE%@NL@% updates the first target in the file.%@NL@% %@NL@% ■ It provides more special macros.%@NL@% %@NL@% ■ It permits substitutions within macros.%@NL@% %@NL@% ■ It supports directives placed in the description file.%@NL@% %@NL@% ■ It allows you to specify include files in the description file.%@NL@% %@NL@% %@CR:MCVG5003@%%@4@%MAKE assumed that all targets in the description file would be built.%@EH@% Because NMAKE builds the first target in the file unless you specify otherwise, you may need to change your old description files to work with the new utility.%@NL@% %@NL@% %@CR:MCVG5004@%%@4@%Description files written for use with MAKE typically list a series of%@EH@% subordinate targets followed by a higher-level target that depends on the subordinates. As MAKE executed, it would build the targets sequentially, creating the highest-level target at the end.%@NL@% %@NL@% %@CR:MCVG5005@%%@4@%The easiest way to convert these description files is to create a new%@EH@% description block at the top of the file. Give this block a pseudotarget named ALL and set its dependents to all of the other targets in the file. When NMAKE executes the description, it will assume you want to build the target ALL and consequently will build all targets in the file.%@NL@% %@NL@% %@CR:MCVG5006@%%@4@%Alternatively, if your description file already contains a block that builds%@EH@% a single, top-level target, you can simply make that block the first in the file.%@NL@% %@NL@% %@CR:MCVG5007@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% one.obj: one.c%@NL@% %@NL@% two.obj: two.c%@NL@% %@NL@% three.obj: three.c%@NL@% %@NL@% prog1.exe: one.obj two.obj three.obj%@NL@% link one two three, prog1;%@NL@% %@NL@% x.obj: x.c%@NL@% %@NL@% y.obj: y.c%@NL@% %@NL@% z.obj: z.c%@NL@% %@NL@% xyz.exe: x.obj y.obj z.obj%@NL@% link x y z, xyz;%@NL@% %@NL@% %@CR:MCVG5008@%%@4@%Assume the above is an old MAKE description file named MAKEFILE. Note that%@EH@% it builds two top-level targets, %@AS@%prog1.exe%@AE@% and %@AS@%xyz.exe%@AE@%. To use this file with the new NMAKE, insert the following as the first line in the file:%@NL@% %@NL@% ALL : prog1.exe xyz.exe%@NL@% %@NL@% %@CR:MCVG5009@%%@4@%With the addition of this line, %@AS@%ALL%@AE@% becomes the first target in the file.%@EH@% Since NMAKE, by default, builds the first target, you can invoke NMAKE with%@NL@% %@NL@% NMAKE%@NL@% %@NL@% %@CR:MCVG500A@%%@4@%and it will build both %@AS@%prog1.exe%@AE@% and %@AS@%xyz.exe%@AE@%.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCVH0000@%%@1@%%@AB@%Chapter 17 Using Other Utilities%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVH0001@%%@4@%The following utilities allow you to modify files and change the operating%@EH@% environment:%@NL@% %@NL@% %@CR:MCVH0002@% ■ Microsoft EXE File Header Utility (EXEMOD)%@NL@% %@NL@% Modifies header information in executable files.%@NL@% %@NL@% ■ Microsoft Environment Expansion Utility (SETENV)%@NL@% %@NL@% Enlarges the DOS environment table in IBM PC-DOS Versions 2.0, 2.1,%@NL@% 3.0, and 3.1. SETENV allows you to use more, larger environment%@NL@% variables.%@NL@% %@NL@% ■ Microsoft Debug Information Compactor Utility (CVPACK)%@NL@% %@NL@% Compresses executable files by reducing the size of CodeView debugging%@NL@% information within the files.%@NL@% %@NL@% %@CR:MCVH0003@%%@4@%The following sections explain how to use the EXEMOD, SETENV, and CVPACK%@EH@% utilities.%@NL@% %@NL@% %@NL@% %@CR:MCVH1000@%%@2@%%@AB@%17.1 Modifying Program Headers with the EXEMOD Utility%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVH1001@%%@4@%The EXEMOD utility allows you to modify fields in the header of an%@EH@% executable file. Some of the options available with EXEMOD are the same as LINK options, except that they work on files that have already been linked. Unlike the LINK options, the EXEMOD options require that values be specified as hexadecimal numbers.%@NL@% %@NL@% %@CR:MCVH1002@%%@4@%To display the current status of the header fields, type the following:%@EH@%%@NL@% %@NL@% EXEMOD %@AI@%executablefile%@AE@%%@NL@% %@NL@% %@CR:MCVH1003@%%@4@%To modify one or more of the fields in the file header, type the following:%@EH@%%@NL@% %@NL@% EXEMOD %@AI@%executablefile%@AE@% «%@AI@%options%@AE@%»%@NL@% %@NL@% %@CR:MCVH1004@%%@4@%EXEMOD expects %@AI@%executablefile%@AE@% to be the name of an existing file with the%@EH@% .EXE extension. If the file name is given without an extension, EXEMOD appends .EXE and searches for that file. If you supply a file with an extension other than .EXE, EXEMOD displays the following error message:%@NL@% %@NL@% %@AS@%exemod: file not .EXE%@AE@%%@NL@% %@NL@% %@CR:MCVH1005@%%@4@%The EXEMOD options are shown with the forward slash (%@AB@%/%@AE@%) designator, but a%@EH@% dash (%@AB@%-%@AE@%) may also be used. Options can be given in either uppercase or lowercase, but they cannot be abbreviated. The EXEMOD options and their effects are described in the following list:%@NL@% %@CR:MCVH1006@%%@NL@% %@TH: 30 1992 2 28 48 @%%@AB@%Option Effect%@AE@%%@AB@%/H%@AE@% Displays the current status of the DOS program header. Its effect is the same as entering EXEMOD with an %@AI@%executablefile%@AE@% specification but without options. The /H option should not be used with other options.%@AB@%/STACK%@AE@% %@AI@%hexnum%@AE@% Allows you to set the size of the stack (in bytes) for your program by setting the initial SP (stack pointer) value to %@AI@%hexnum%@AE@%. The minimum allocation value is adjusted upward, if necessary. This option has the same effect as the LINK /STACK option, except it works on files that are already linked.%@AB@%/MIN%@AE@% %@AI@%hexnum%@AE@% Sets the minimum allocation value (that is, the minimum number of 16-byte paragraphs needed by the program when it is loaded into memory) to %@AI@%hexnum%@AE@%. The actual value set may be different from the requested value if adjustments are necessary to accommodate the stack.%@AB@%/MAX%@AE@% %@AI@%hexnum%@AE@% Sets the maximum allocation value (that is, the maximum number of 16-byte paragraphs used by the program when it is loaded into memory) to %@AI@%hexnum%@AE@%. The maximum allocation value must be greater than or equal to the minimum allocation value. This option has the same effect as the LINK /CPARMAXALLOC option.%@TE: 30 1992 2 28 48 @% %@NL@% %@CR:MCVH1007@%%@4@%For each of the options listed above, %@AI@%hexnum%@AE@% is a number entered using%@EH@% hexadecimal digits (uppercase or lowercase); no prefix is needed.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% Use of the %@AB@%/STACK%@AE@% option on programs developed with other than Microsoft%@NL@% compilers or assemblers may cause the programs to fail, or %@AB@%EXEMOD%@AE@% may%@NL@% return an error message.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVH1008@%%@4@%EXEMOD works on packed files. When it recognizes a packed file, it prints%@EH@% the message%@NL@% %@NL@% %@AS@%packed file%@AE@%%@NL@% %@NL@% %@CR:MCVH1009@%then continues to modify the file header.%@NL@% %@NL@% %@CR:MCVH100A@%%@4@%When packed files are loaded, they are expanded to their unpacked state in%@EH@% memory. If the EXEMOD /STACK option is used on a packed file, the value changed is the value that SP has after expansion. If either the /MIN or the /STACK option is used, the value is corrected as necessary to accommodate unpacking of the modified stack. The /MAX option operates as it would for unpacked files.%@NL@% %@NL@% %@CR:MCVH100B@%%@4@%If the header of a packed file is displayed, the CS:IP and SS:SP values are%@EH@% displayed as they are after expansion. These values are not the same as the actual values in the header of the packed file.%@NL@% %@NL@% %@CR:MCVH100C@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% Microsoft (R) EXE File Header Utility Version 4.02%@NL@% Copyright (C) Microsoft Corp 1985. All rights reserved.%@NL@% %@NL@% TEST.EXE (hex) (dec)%@NL@% %@NL@% .EXE size (bytes) 439D 17309%@NL@% Minimum load size (bytes) 419D 16797%@NL@% Overlay number 0 0%@NL@% Initial CS:IP 0403:0000%@NL@% Initial SS:SP 0000:0000 0%@NL@% Minimum allocation (para) 0 0%@NL@% Maximum allocation (para) FFFF 65535%@NL@% Header size (para) 20 32%@NL@% Relocation table offset 1E 30%@NL@% Relocation entries 1 1%@NL@% %@NL@% %@CR:MCVH100D@%%@4@%The display above shows how EXEMOD would display the current file header for%@EH@% file %@AS@%TEST.EXE%@AE@%. Note that %@AS@%(para)%@AE@% refers to paragraphs, which are units of 16 bytes. To translate paragraphs to bytes, multiply by 16. The meaning of each field is given below.%@NL@% %@NL@% %@CR:MCVH100E@%%@4@%.EXE size is the size of the file as stored on disk. %@AS@%Minimum load size%@AE@% is%@EH@% the total amount of memory that DOS must provide in order for the program to execute.%@NL@% %@NL@% %@CR:MCVH100F@%%@4@%%@AS@%Overlay number%@AE@% is the ordinal number of the overlay as generated by LINK.%@EH@% (If the executable file does not use overlays, there is exactly one overlay module, the root.) Since EXEMOD looks only at the beginning of the file, the overlay number displayed is normally 0.%@NL@% %@NL@% %@CR:MCVH100G@%%@4@%%@AS@%Initial CS:IP%@AE@% and %@AS@%Initial SS:SP%@AE@% indicate the initial values of the%@EH@% instruction pointer and the stack pointer, respectively. The values of CS and SS are relative to the beginning of the load module and are changed once the file is actually loaded into memory. The offset address of the stack pointer (SP) indicates the amount of room available for the stack to grow downward before reaching SS. (Some of this room may be needed by other segments, however.) The initial value of SP can be changed with EXEMOD.%@NL@% %@NL@% %@CR:MCVH100H@%%@4@%%@AS@%Minimum allocation%@AE@% indicates the amount of memory that the file requires, in%@EH@% addition to the memory that DOS uses to load the file itself. If DOS is unable to allocate this amount of memory, it does not execute the file. This value can be changed with EXEMOD.%@NL@% %@NL@% %@CR:MCVH100I@%%@4@%%@AS@%Maximum allocation%@AE@% indicates the amount of memory the file requests, in%@EH@% addition to memory used to load the file itself. If the amount specified is not available, DOS allocates all available memory. This value can be changed with EXEMOD.%@NL@% %@NL@% %@CR:MCVH100J@%%@4@%%@AS@%Header size%@AE@% gives the size of all header information, including relocation%@EH@% entries.%@NL@% %@NL@% %@CR:MCVH100K@%%@4@%%@AS@%Relocation table offset%@AE@% indicates the number of bytes from the beginning of%@EH@% the file to the relocation entries.%@NL@% %@NL@% %@CR:MCVH100L@%%@4@%%@AS@%Relocation entries%@AE@% gives the number of relocation entries. Each of these%@EH@% entries is a piece of information used to adjust segment addresses in the load module (the portion of the file that is actually loaded into memory). DOS adds the load address to each segment address so that the segment address refers to a true location in physical memory.%@NL@% %@NL@% %@CR:MCVH100M@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >EXEMOD TEST.EXE%@NL@% %@NL@% %@CR:MCVH100N@%%@4@%The command in the above example generates the display in the previous%@EH@% example for the file %@AS@%TEST.EXE%@AE@%.%@NL@% %@NL@% EXEMOD TEST.EXE /STACK FF /MIN FF /MAX FFF%@NL@% %@NL@% %@CR:MCVH100O@%%@4@%The example above uses the EXEMOD command line to modify the header fields%@EH@% in %@AS@%TEST.EXE%@AE@%.%@NL@% %@NL@% >EXEMOD TEST.EXE%@NL@% %@NL@% Microsoft (R) EXE File Header Utility Version 4.02%@NL@% Copyright (C) Microsoft Corp 1985. All rights reserved.%@NL@% %@NL@% TEST.EXE (hex) (dec)%@NL@% %@NL@% .EXE size (bytes) 439D 17309%@NL@% Minimum load size (bytes) 528D 20877%@NL@% Overlay number 0 0%@NL@% Initial CS:IP 0403:0000%@NL@% Initial SS:SP 0000:00FF 256%@NL@% Minimum allocation (para) FF 256%@NL@% Maximum allocation (para) FFF 4095%@NL@% Header size (para) 20 32%@NL@% Relocation table offset 1E 30%@NL@% Relocation entries 1 1%@NL@% %@NL@% %@CR:MCVH100P@%%@4@%The last example shows the current status of the header for %@AS@%TEST.EXE%@AE@% after%@EH@% being altered by the previous example.%@NL@% %@NL@% %@NL@% %@CR:MCVH2000@%%@2@%%@AB@%17.2 Enlarging the DOS Environment with the SETENV Utility%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVH2001@%%@4@%The SETENV utility allows you to allocate more operating-environment space%@EH@% to DOS by modifying a copy of COMMAND.COM.%@NL@% %@NL@% %@CR:MCVH2002@%%@4@%Normally, DOS Versions 2.0 and later allocate 160 bytes (10 paragraphs) for%@EH@% the environment table. This may not be enough space if you want to set numerous environment variables using the SET or PATH command. For example, if you have a hard disk with several levels of subdirectories, a single environment variable might take 40 or 50 characters. Since each character uses 1 byte, you could easily require more than 160 bytes if you want to set several environment variables.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% %@AB@%SETENV%@AE@% works with most MS-DOS and PC-DOS operating systems, Versions 2.0 through 3.1. If the %@AB@%SETENV%@AE@% utility does not work with your version of %@AB@%COMMAND.COM%@AE@%, please contact Microsoft Technical Support. %@NL@% If you use DOS 3.2 or later, you can set the environment space with the DOS %@AB@%SHELL%@AE@% command. For example, the following command sets the environment size at 3000 bytes when placed in %@AB@%CONFIG.SYS%@AE@%: %@NL@% SHELL = COMMAND.COM /E:3000 /P%@NL@% %@NL@% See your DOS manual for further information.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% To enlarge the environment table, you can modify a copy of COMMAND.COM using SETENV. Make sure you work on a copy, and retain an unmodified version of COMMAND.COM for backup.%@NL@% %@NL@% %@CR:MCVH2003@%%@4@%The command line for modifying the environment table is as follows:%@EH@%%@NL@% %@NL@% SETENV %@AI@%filename%@AE@% «%@AI@%environmentsize%@AE@%»%@NL@% %@NL@% %@CR:MCVH2004@%%@4@%Normally, %@AI@%filename%@AE@% specifies COMMAND.COM. It must be a valid, unmodified%@EH@% copy of COMMAND.COM, though it can be renamed. The optional %@AI@%environmentsize%@AE@% is a decimal number specifying the size in bytes of the new allocation; %@AI@%environmentsize%@AE@% must be a number greater than or equal to 160 and less than or equal to 65,520. The specified %@AI@%environmentsize%@AE@% is rounded up to the nearest multiple of 16 (the size of a paragraph).%@NL@% %@NL@% %@CR:MCVH2005@%%@4@%If %@AI@%environmentsize%@AE@% is not given, SETENV reports the value currently%@EH@% allocated by the COMMAND.COM file.%@NL@% %@NL@% %@CR:MCVH2006@%%@4@%After modifying COMMAND.COM, you must reboot so that the environment table%@EH@% is set to the new size.%@NL@% %@NL@% %@CR:MCVH2007@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% >SETENV COMMAND.COM%@NL@% %@NL@% Microsoft (R) Environment Expansion Utility Version 2.10%@NL@% Copyright (C) Microsoft Corp 1985,1986. All rights reserved.%@NL@% %@NL@% command.com: Environment allocation = 160%@NL@% %@NL@% %@CR:MCVH2008@%%@4@%In the example above, no environment size is specified, so SETENV reports%@EH@% the current size of the environment table.%@NL@% %@NL@% >SETENV COMMAND.COM 605%@NL@% %@NL@% %@CR:MCVH2009@%%@4@%In the example above, an environment size of 605 bytes is requested. Since%@EH@% 605 bytes is not on a paragraph boundary (a multiple of 16), SETENV rounds the request up to 608 bytes. COMMAND.COM is modified so that it automatically sets an environment table of 608 bytes (38 paragraphs). You must reboot to set the new environment-table size.%@NL@% %@NL@% %@NL@% %@CR:MCVH3000@%%@2@%%@AB@%17.3 Saving Memory with the CVPACK Utility%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVH3001@%%@4@%After you compile and link a program with CodeView debugging information,%@EH@% you can use the Microsoft Debug Information Compactor Utility (CVPACK) to reduce the size of the executable file. CVPACK compresses information in the file, and allows the CodeView debugger to load larger programs without running out of memory.%@NL@% %@NL@% %@CR:MCVH3002@%%@4@%The CVPACK utility has the following command line:%@EH@%%@NL@% %@NL@% %@CR:MCVH3003@%CVPACK «/p» %@AI@%exefile%@AE@%%@NL@% %@NL@% %@CR:MCVH3004@%%@4@%The /p option results in the most effective possible packing but causes%@EH@% CVPACK to take longer to execute. When the /p option is specified, unused debugging information is discarded, and the packed information is sorted within the file. When the /p option is not specified, packed information is simply appended to the end of the file.%@NL@% %@NL@% %@CR:MCVH3005@%%@4@%To debug a file that has been altered with CVPACK, you must use Version 2.10%@EH@% or later of the CodeView debugger.%@NL@% %@NL@% %@NL@% %@CR:MCVI0000@%%@1@%%@AB@%Chapter 18 Linking for Windows and OS/2 Systems%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVI0001@%%@4@%This chapter covers concepts important to linking for Windows and OS/2%@EH@% systems, such as dynamic-linking and import libraries. Section 18.6%@BO: c0e10@% describes the IMPLIB utility for creating import libraries.%@NL@% %@NL@% %@CR:MCVI0002@%%@4@%In most respects, linking a program using the Microsoft Segmented-Executable%@EH@% Linker (LINK) for the OS/2 environment is similar to linking a program for the DOS 3.x environment. The principal difference is that most programs created for the DOS 3.x environment run as stand-alone applications, whereas programs that run under OS/2 protected mode generally call one or more "dynamic-link libraries."%@NL@% %@NL@% %@NL@% %@CR:MCVI1000@%%@2@%%@AB@%18.1 Dynamic-Link Libraries%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVI1001@%%@4@%A dynamic-link library contains executable code for common functions, just%@EH@% as an ordinary library does. Yet code for dynamic-link functions is not linked into the executable (.EXE) file. Instead, the library itself is loaded into memory at run time, along with the .EXE file.%@NL@% %@NL@% %@CR:MCVI1002@%%@4@%Each .DLL file (dynamic-link library) must use "export definitions" to make%@EH@% its functions directly available to other modules. At run time, functions not exported can only be called from within the same file. Each export definition specifies a function name.%@NL@% %@NL@% %@CR:MCVI1003@%%@4@%Conversely, the .EXE file must use "import definitions" that tell where each%@EH@% dynamic-link function can be found. Otherwise, OS/2 would not know what dynamic-link libraries to load when the program is run. Each import definition specifies a function name and the .DLL file where the function resides.%@NL@% %@NL@% %@CR:MCVI1004@%%@4@%Assume the simplest case, in which you create one application and one%@EH@% dynamic-link library. The linker requires export and import definitions for dynamic-link function calls. The OS/2 operating system provides two ways for you to supply these definitions:%@NL@% %@NL@% %@CR:MCVI1005@% ■ You create one module-definition file (.DEF extension) with export%@NL@% definitions for the .DLL file and another module-definition file with%@NL@% import definitions for the .EXE file. The module-definition files%@NL@% provide these definitions in an ASCII format.%@NL@% %@NL@% ■ You create one module-definition file (.DEF extension) for the .DLL%@NL@% file and then generate an import library to be linked to the .EXE file.%@NL@% %@NL@% %@CR:MCVI1006@%%@4@%The next two sections consider each of these methods in turn. Chapter 19%@BO: c14f2@%,%@EH@% "Using Module-Definition Files," gives a complete description of module-definition files.%@NL@% %@NL@% %@NL@% %@CR:MCVI2000@%%@2@%%@AB@%18.2 Linking without an Import Library%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVI2001@%%@4@%Figure 18.1%@FN@% Figure 18.1 is found on page 316 of the printed version.%@EF@% illustrates the first way to supply definitions for dynamic-link%@EH@% function calls, in which each of the two files──the .DLL file and the .EXE file──has a corresponding module-definition file. (A module-definition file has a .DEF default extension.)%@NL@% %@NL@% %@CR:MCVI2002@%%@4@%The two major steps are described below.%@EH@%%@NL@% %@NL@% %@CR:MCVI2003@% 1. Object files (and possibly standard-library files) are linked together%@NL@% with a module-definition file to create a dynamic-link library. A%@NL@% module-definition file for a dynamic-link library has at least two%@NL@% statements. The first is a %@AB@%LIBRARY%@AE@% statement, which directs the linker%@NL@% to create a .DLL rather than an .EXE file. The second statement is a%@NL@% list of export definitions.%@NL@% %@NL@% 2. Object files (and possibly standard-library files) are linked together%@NL@% with a module-definition file to create an application. The%@NL@% module-definition file for this application contains a list of import%@NL@% definitions. Each definition in this list contains both a function name%@NL@% and the name of a dynamic-link library.%@NL@% %@NL@% %@NL@% %@CR:MCVI3000@%%@2@%%@AB@%18.3 Linking with an Import Library%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVI3001@%%@4@%Figure 18.2%@FN@% Figure 18.2 is found on page 317 of the printed version.%@EF@% illustrates the second way to supply definitions for%@EH@% dynamic-link function calls, in which a module-definition file is supplied for the dynamic-link library and an import library is supplied for the application.%@NL@% %@NL@% %@CR:MCVI3002@%%@4@%The three major steps are explained below.%@EH@%%@NL@% %@NL@% %@CR:MCVI3003@% 1. Object files are linked to produce a .DLL file. This step is identical%@NL@% to the first step in the section above. Note that the module-definition%@NL@% file contains export definitions.%@NL@% %@NL@% 2. The IMPLIB utility is used to generate an import library. IMPLIB takes%@NL@% as input the same module-definition file used in the first step. IMPLIB%@NL@% knows the name of the library module (which by default has the same%@NL@% base name as the .DEF file), and it determines the name of each%@NL@% exported function by examining export definitions. For each export%@NL@% definition in the .DEF file, IMPLIB generates a corresponding import%@NL@% definition.%@NL@% %@NL@% 3. The .LIB file generated by IMPLIB is used as input to LINK, which%@NL@% creates an application. This .LIB file does not use the same file%@NL@% format as a .DEF file, but it fulfills the same purpose: to provide the%@NL@% linker with information about imported dynamic-link functions.%@NL@% %@NL@% %@CR:MCVI3004@%%@4@%The .LIB file generated by IMPLIB is called an import library. Import%@EH@% libraries are similar in most respects to ordinary libraries; you specify import libraries and ordinary libraries in the same command-line field of LINK, and you can append the two kinds of libraries together (by using the Library Manager). Furthermore, both kinds of libraries resolve external references at link time. The only difference is import libraries do not contain executable code, merely records that describe where the executable code can be found at run time.%@NL@% %@NL@% %@CR:MCVI3005@%%@4@%The cases considered in this section have been simple ones. Dynamic linking%@EH@% is flexible and supports more complicated cases. An application can make calls to more than one dynamic-link library. Furthermore, module-definition files for libraries can import functions as well as export them. It is possible for a .DLL file to call another .DLL file, and so on, to any level of complexity; the result may be a situation in which many files are loaded at run time.%@NL@% %@NL@% %@NL@% %@CR:MCVI4000@%%@2@%%@AB@%18.4 Why Use Import Libraries?%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVI4001@%%@4@%At first glance, it may seem easier to create programs without import%@EH@% libraries since import libraries add an extra step to the linking process. However, it is easier to use import libraries for two reasons.%@NL@% %@NL@% %@CR:MCVI4002@%%@4@%First, the IMPLIB utility automates much of the program-creation process for%@EH@% you. To run IMPLIB, you specify the .DEF file that you already created for the dynamic-link library. Operation of IMPLIB is simple. If you do not use an import library generated by IMPLIB, you must use an ASCII text editor to create a second .DEF file where you explicitly give all needed import definitions.%@NL@% %@NL@% %@CR:MCVI4003@%%@4@%Second, the first two steps in the linking process described above (creation%@EH@% of the .DLL file and creation of the import library) may be carried out only by the author of the dynamic-link library. The libraries may then be given to an applications programmer, who focuses on linking the application (third step). An applications programmer's task is simplified by linking with the import library because then it is not necessary to edit the .DEF file. The import library comes ready to link.%@NL@% %@NL@% %@CR:MCVI4004@%%@4@%A good example of a useful import library is the file DOSCALLS.LIB.%@EH@% Generally, protected-mode applications need to call one of the dynamic-link system libraries released with OS/2; the DOSCALLS.LIB file contains import definitions for all calls to these system libraries. It is much easier to link with DOSCALLS.LIB than to create a .DEF file for every OS/2 program you link.%@NL@% %@NL@% %@NL@% %@CR:MCVI5000@%%@2@%%@AB@%18.5 Advantages of Dynamic Linking%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVI5001@%%@4@%Why use dynamic-link libraries at all? Dynamic-link libraries serve much the%@EH@% same purpose that standard libraries do but they also give you the following advantages:%@NL@% %@NL@% %@CR:MCVI5002@% 1. Link applications faster.%@NL@% %@NL@% With dynamic linking, the executable code for a dynamic-link function%@NL@% is not copied into the application's .EXE file. Instead, only an import%@NL@% definition is copied.%@NL@% %@NL@% 2. Save significant disk space.%@NL@% %@NL@% Suppose you create a library function called %@AS@%printit%@AE@%, and this function%@NL@% is called by many different programs. If %@AS@%printit%@AE@% is in a standard%@NL@% library, the function's executable code must be linked into each .EXE%@NL@% file that calls the function. In other words, the same code resides on%@NL@% your disk in many different files. But if %@AS@%printit%@AE@% is stored in a%@NL@% dynamic-link library, the executable code resides in just one file──the%@NL@% library itself.%@NL@% %@NL@% 3. Make libraries and applications more independent.%@NL@% %@NL@% Dynamic-link libraries can be updated any number of times without%@NL@% relinking the applications that use them. If you are a user of%@NL@% third-party libraries, this is particularly convenient. You receive the%@NL@% updated .DLL file from the third-party developers, and you need only%@NL@% copy the new library onto your disk. At run time, your applications%@NL@% automatically call the updated library functions.%@NL@% %@NL@% 4. Utilize shared code and data segments.%@NL@% %@NL@% Code and data segments loaded in from a dynamic-link library can be%@NL@% shared. Without dynamic linking, this sharing is not possible because%@NL@% each file has its own copy of all the code and data it uses. By sharing%@NL@% segments with dynamic linking, you can use memory more efficiently.%@NL@% %@NL@% %@NL@% %@CR:MCVI6000@%%@2@%%@AB@%18.6 Creating Import Libraries with IMPLIB%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVI6001@%%@4@%This section summarizes the use of the Microsoft Import Library Manager%@EH@% (IMPLIB), and assumes you are familiar with the concepts of import libraries, dynamic linking, and module-definition files discussed in Section 18.2.%@BO: bef80@%%@NL@% %@NL@% %@CR:MCVI6002@%%@4@%You can create an import library for use by other programmers in resolving%@EH@% external references to your dynamic-link library. The IMPLIB command creates an import library, which is a file with a .LIB extension that can be read by the OS/2 linker. The .LIB file can be specified in the LINK command line with other libraries. Import libraries are recommended for all dynamic-link libraries. Without the use of import libraries, external references to dynamic-link routines must be declared in an %@AB@%IMPORTS%@AE@% statement in the module-definition file for the application being linked. IMPLIB is supported only in protected mode.%@NL@% %@NL@% %@CR:MCVI6003@%%@4@%The IMPLIB command-line format is as follows:%@EH@%%@NL@% %@NL@% IMPLIB %@AI@%implibname mod-def-file%@AE@% «%@AI@%mod-def-file%@AE@%...»%@NL@% %@NL@% %@CR:MCVI6004@%%@4@%The %@AI@%implibname%@AE@% is the name you wish the new import library to have.%@EH@%%@NL@% %@NL@% %@CR:MCVI6005@%%@4@%The %@AI@%mod-def-file%@AE@% is the name of a module-definition file for the%@EH@% dynamic-link module. You may enter more than one.%@NL@% %@NL@% %@CR:MCVI6006@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVI6007@%%@4@%The following command creates the import library named MYLIB.LIB from the%@EH@% module-definition file MYLIB.DEF:%@NL@% %@NL@% IMPLIB mylib.lib mylib.def%@NL@% %@NL@% %@NL@% %@CR:MCVJ0000@%%@1@%%@AB@%Chapter 19 Using Module-Definition Files%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVJ0001@%%@4@%A module-definition file describes the name, attributes, exports, imports,%@EH@% and other characteristics of an application or library for OS/2 or Microsoft Windows. This file is required for Windows applications and libraries and is also required for dynamic-link libraries that run under OS/2.%@NL@% %@NL@% %@NL@% %@CR:MCVJ1000@%%@2@%%@AB@%19.1 Module Statements%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ1001@%%@4@%A module-definition file contains one or more "module statements." Each%@EH@% module statement defines an attribute of the executable file, such as its module name, the attributes of program segments, and the number and names of exported and imported functions. The module statements and the attributes they define are listed below.%@NL@% %@CR:MCVJ1002@%%@NL@% %@TH: 37 1573 2 27 49 @%%@AB@%Module Statements Attribute Defined%@AE@%%@AB@%NAME%@AE@% Names application (no library created)%@AB@%LIBRARY%@AE@% Names dynamic-link library (no application created)%@AB@%DESCRIPTION%@AE@% Describes the module in one line%@AB@%CODE%@AE@% Gives default attributes for code segments%@AB@%DATA%@AE@% Gives default attributes for data segments%@AB@%SEGMENTS%@AE@% Gives attributes for specific segments%@AB@%STACKSIZE%@AE@% Specifies local-stack size in bytes%@AB@%EXPORTS%@AE@% Defines exported functions%@AB@%IMPORTS%@AE@% Defines imported functions%@AB@%STUB%@AE@% Adds a DOS 3.x executable file to the beginning of the module, usually to terminate the program when run in real mode%@AB@%HEAPSIZE%@AE@% Specifies local heap size in bytes%@AB@%PROTMODE%@AE@% Specifies that the module runs only in DOS protected mode%@AB@%OLD%@AE@% Preserves import information from a previous version of the library%@AB@%REALMODE%@AE@% Relaxes some restrictions that the linker imposes for protected-mode programs%@AB@%EXETYPE%@AE@% Identifies operating system%@TE: 37 1573 2 27 49 @% %@NL@% %@CR:MCVJ1003@%%@4@%The following rules govern the use of module statements in a%@EH@% module-definition file:%@NL@% %@NL@% %@CR:MCVJ1004@% ■ If you use either a %@AB@%NAME%@AE@% or a %@AB@%LIBRARY%@AE@% statement, it must precede all%@NL@% other statements in the module-definition file.%@NL@% %@NL@% ■ You can include source-level comments in the module-definition file by%@NL@% beginning a line with a semicolon (%@AB@%;%@AE@%). The OS/2 utilities ignore each%@NL@% such comment line.%@NL@% %@NL@% ■ All module-definition keywords (such as %@AB@%NAME%@AE@%, %@AB@%LIBRARY%@AE@%, and %@AB@%OLD%@AE@%) must be%@NL@% entered in uppercase letters.%@NL@% %@NL@% %@CR:MCVJ1005@%%@4@%The sample module-definition file below gives module definitions for a%@EH@% dynamic-link library. This sample file includes one source-level comment and five statements.%@NL@% %@NL@% %@AI@%; Sample module-definition file%@AE@%%@NL@% %@NL@% LIBRARY%@NL@% %@NL@% DESCRIPTION 'Sample .DEF file for a dynamic-link library'%@NL@% %@NL@% CODE PRELOAD%@NL@% %@NL@% STACKSIZE 1024%@NL@% %@NL@% EXPORTS%@NL@% Init @1%@NL@% Begin @2%@NL@% Finish @3%@NL@% Load @4%@NL@% Print @5%@NL@% %@NL@% %@CR:MCVJ1006@%%@4@%The sections below explain the meaning of these statements, as well as%@EH@% others, giving syntax and examples.%@NL@% %@NL@% %@NL@% %@CR:MCVJ2000@%%@2@%%@AB@%19.2 The NAME Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ2001@%%@4@%The %@AB@%NAME%@AE@% statement identifies the executable file as an application and%@EH@% optionally defines the name.%@NL@% %@NL@% %@CR:MCVJ2002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ2003@%%@AB@%NAME%@AE@% «%@AI@%appname%@AE@%» «%@AI@%apptype%@AE@%»%@NL@% %@NL@% %@CR:MCVJ2004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ2005@%%@4@%If %@AI@%appname%@AE@% is given, it becomes the name of the application as it is known%@EH@% by OS/2. This name can be any valid file name. If %@AI@%appname%@AE@% is not given, the name of the module-definition file──with the extension removed──becomes the name of the application.%@NL@% %@NL@% %@CR:MCVJ2006@%%@4@%The %@AI@%apptype%@AE@% field will be used by a future version of OS/2 and should be%@EH@% declared for compatibility with this future version.%@NL@% %@NL@% %@CR:MCVJ2007@%%@4@%If %@AI@%apptype%@AE@% is given, it defines the type of application being linked. This%@EH@% information is kept in the executable-file header. You do not need to use this field unless you may be using your application in a Windows environment. The %@AI@%apptype%@AE@% field may have one of the following values:%@NL@% %@NL@% %@CR:MCVJ2008@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%WINDOWAPI%@AE@% Real-mode Presentation Manager application. The%@NL@% application uses the API provided by the%@NL@% Presentation Manager and must be executed in the%@NL@% Presentation Manager environment.%@NL@% %@NL@% %@AB@%WINDOWCOMPAT%@AE@% Presentation Manager-compatible application. The%@NL@% application can run inside the Presentation%@NL@% Manager, or it can run in a separate screen%@NL@% group. An application can be of this type if it%@NL@% uses the proper subset of OS/2 video, keyboard,%@NL@% and mouse functions supported in the%@NL@% Presentation Manager applications.%@NL@% %@NL@% %@AB@%NOTWINDOWCOMPAT%@AE@% Application is not compatible with the%@NL@% Presentation Manager and must operate in a%@NL@% separate screen group from the Presentation%@NL@% Manager.%@NL@% %@NL@% %@CR:MCVJ2009@%%@4@%If the %@AB@%NAME%@AE@% statement is included in the module-definition file, the %@AB@%LIBRARY%@AE@%%@EH@% statement cannot appear. If neither a %@AB@%NAME%@AE@% statement nor a %@AB@%LIBRARY%@AE@% statement appears in a module-definition file, the default is %@AB@%NAME%@AE@%──that is, the linker acts as though a %@AB@%NAME%@AE@% statement were included, and thus creates an application rather than a library.%@NL@% %@NL@% %@CR:MCVJ200A@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ200B@%%@4@%The example below assigns the name %@AS@%calendar%@AE@% to the application being%@EH@% defined:%@NL@% %@NL@% NAME calendar WINDOWCOMPAT%@NL@% %@NL@% %@NL@% %@CR:MCVJ3000@%%@2@%%@AB@%19.3 The LIBRARY Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ3001@%%@4@%The %@AB@%LIBRARY%@AE@% statement identifies the executable file as a dynamic-link%@EH@% library and it can specify the name of the library or the type of library-module initialization required.%@NL@% %@NL@% %@CR:MCVJ3002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ3003@%%@AB@%LIBRARY%@AE@% «%@AI@%libraryname%@AE@%» «%@AI@%initialization%@AE@%»%@NL@% %@NL@% %@CR:MCVJ3004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ3005@%%@4@%If %@AI@%libraryname%@AE@% is given, it becomes the name of the library as it is known%@EH@% by OS/2. This name can be any valid file name. If %@AI@%libraryname%@AE@% is not given, the name of the module-definition file──with the extension removed──becomes the name of the library.%@NL@% %@NL@% %@CR:MCVJ3006@%%@4@%The %@AI@%initialization%@AE@% field is optional and can have one of the two values%@EH@% listed below. If neither is given, then the %@AI@%initialization%@AE@% default is %@AB@%INITGLOBAL%@AE@%.%@NL@% %@NL@% %@CR:MCVJ3007@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%INITGLOBAL%@AE@% The library-initialization routine is called%@NL@% only when the library module is initially loaded%@NL@% into memory%@NL@% %@NL@% %@AB@%INITINSTANCE%@AE@% The library-initialization routine is called%@NL@% each time a new process gains access to the%@NL@% library%@NL@% %@NL@% %@CR:MCVJ3008@%%@4@%If the %@AB@%LIBRARY%@AE@% statement is included in a module-definition file, %@AB@%NAME%@AE@%%@EH@% cannot appear. If no %@AB@%LIBRARY%@AE@% statement appears in a module-definition file, the linker assumes that the module-definition file is defining an application.%@NL@% %@NL@% %@CR:MCVJ3009@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ300A@%%@4@%The following example assigns the name %@AS@%calendar%@AE@% to the dynamic-link module%@EH@% being defined, and specifies that library initialization is performed each time a new process gains access to %@AS@%calendar%@AE@%:%@NL@% %@NL@% LIBRARY calendar INITINSTANCE%@NL@% %@NL@% %@NL@% %@CR:MCVJ4000@%%@2@%%@AB@%19.4 The DESCRIPTION Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ4001@%%@4@%The %@AB@%DESCRIPTION%@AE@% statement inserts the specified %@AI@%text%@AE@% into the application or%@EH@% library. This statement is useful for embedding source-control or copyright information into an application or library.%@NL@% %@NL@% %@CR:MCVJ4002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ4003@%%@AB@%DESCRIPTION%@AE@% %@AB@%'%@AE@%%@AI@%text%@AE@%%@AB@%'%@AE@%%@NL@% %@NL@% %@CR:MCVJ4004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ4005@%%@4@%The %@AI@%text%@AE@% is a one-line string enclosed in single quotation marks. Use of the%@EH@% %@AB@%DESCRIPTION%@AE@% statement is different from the inclusion of a comment because comments──lines that begin with a semicolon (;)──are not placed in the application or library.%@NL@% %@NL@% %@CR:MCVJ4006@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ4007@%%@4@%The following example inserts the text %@AS@%Template Program%@AE@% into the application%@EH@% or library being defined:%@NL@% %@NL@% DESCRIPTION 'Template Program'%@NL@% %@NL@% %@NL@% %@CR:MCVJ5000@%%@2@%%@AB@%19.5 The CODE Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ5001@%%@4@%The %@AB@%CODE%@AE@% statement defines the default attributes for code segments within%@EH@% the application or library.%@NL@% %@NL@% %@CR:MCVJ5002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ5003@%%@AB@%CODE%@AE@% «%@AI@%attribute%@AE@%...»%@NL@% %@NL@% %@CR:MCVJ5004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ5005@%%@4@%Each %@AI@%attribute%@AE@% must correspond to one of the following attribute fields.%@EH@% Each field can appear at most one time, and order is not significant. The attribute fields are presented below, along with legal values. In each case, the default value is listed last. The last three fields have no effect on OS/2 code segments and are included for use with Microsoft Windows.%@NL@% %@NL@% %@CR:MCVJ5006@%%@AB@%Field Values%@AE@%%@NL@% %@NL@% %@AI@%load%@AE@% %@AB@%PRELOAD%@AE@%, %@AB@%LOADONCALL%@AE@%%@NL@% %@NL@% %@AI@%executeonly%@AE@% %@AB@%EXECUTEONLY%@AE@%, %@AB@%EXECUTEREAD%@AE@%%@NL@% %@NL@% %@AI@%iopl%@AE@% %@AB@%IOPL%@AE@%, %@AB@%NOIOPL%@AE@%%@NL@% %@NL@% %@AI@%conforming%@AE@% %@AB@%CONFORMING%@AE@%, %@AB@%NONCONFORMING%@AE@%%@NL@% %@NL@% %@AI@%shared%@AE@% %@AB@%SHARED%@AE@%, %@AB@%NONSHARED%@AE@%%@NL@% %@NL@% %@AI@%movable%@AE@% %@AB@%MOVABLE%@AE@%, %@AB@%FIXED%@AE@%%@NL@% %@NL@% %@AI@%discard%@AE@% %@AB@%NONDISCARDABLE%@AE@%, %@AB@%DISCARDABLE%@AE@%%@NL@% %@NL@% %@CR:MCVJ5007@%%@4@%The %@AI@%load%@AE@% field determines when a code segment is to be loaded. This field%@EH@% contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ5008@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%PRELOAD%@AE@% The segment is loaded automatically at the%@NL@% beginning of the program%@NL@% %@NL@% %@AB@%LOADONCALL%@AE@% The segment is not loaded until accessed (the%@NL@% default)%@NL@% %@NL@% %@CR:MCVJ5009@%%@4@%The %@AI@%executeonly%@AE@% field determines whether a code segment can be read as well%@EH@% as executed. This field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ500A@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%EXECUTEONLY%@AE@% The segment can only be executed%@NL@% %@NL@% %@AB@%EXECUTEREAD%@AE@% The segment can be both executed and read (the%@NL@% default)%@NL@% %@NL@% %@CR:MCVJ500B@%%@4@%The %@AI@%iopl%@AE@% field determines whether or not a segment has I/O privilege (that%@EH@% is, whether it can access the hardware directly). This field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ500C@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%IOPL%@AE@% The code segment has I/O privilege%@NL@% %@NL@% %@AB@%NOIOPL%@AE@% The code segment does not have I/O privilege%@NL@% (the default)%@NL@% %@NL@% %@CR:MCVJ500D@%%@4@%The %@AI@%conforming%@AE@% field specifies whether a code segment is a 286 "conforming"%@EH@% segment. The concept of a conforming segment deals with privilege level (the range of instructions that the process can execute) and is relevant only to users writing device drivers and system-level code. A conforming segment can be called from either Ring 2 or Ring 3, and the segment executes at the caller's privilege level. This field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ500E@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%CONFORMING%@AE@% The segment is conforming%@NL@% %@NL@% %@AB@%NONCONFORMING%@AE@% The segment is nonconforming (the default)%@NL@% %@NL@% %@CR:MCVJ500F@%%@4@%The %@AI@%shared%@AE@% field determines whether all instances of the program can share a%@EH@% given code segment. This field is ignored by OS/2, but is provided for use with real-mode Windows. Under OS/2, all code segments are shared. The %@AI@%shared%@AE@% field contains one of the following keywords: %@AB@%SHARED%@AE@% or %@AB@%NONSHARED%@AE@% (the default for Windows).%@NL@% %@NL@% %@CR:MCVJ500G@%%@4@%The %@AI@%movable%@AE@% field determines whether a segment can be moved around in%@EH@% memory. This field is ignored by OS/2, but is provided for use with real-mode Windows. Under OS/2, all segments are movable. The %@AI@%movable%@AE@% field contains one of the following keywords: %@AB@%MOVABLE%@AE@% or %@AB@%FIXED%@AE@% (the default for Windows).%@NL@% %@NL@% %@CR:MCVJ500H@%%@4@%The %@AI@%discard%@AE@% field determines whether a segment can be swapped out to disk by%@EH@% the operating system when not currently needed. This attribute is ignored by OS/2, but is provided for use with real-mode Windows. Under OS/2 systems, all segments can be swapped as needed. The %@AI@%shared%@AE@% attribute contains one of the following keywords: %@AB@%DISCARDABLE%@AE@% or %@AB@%NONDISCARDABLE%@AE@% (the default for Windows).%@NL@% %@NL@% %@CR:MCVJ500I@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ500J@%%@4@%The following example sets defaults for the module's code segments so they%@EH@% are not loaded until accessed and have I/O hardware privilege:%@NL@% %@NL@% CODE LOADONCALL IOPL%@NL@% %@NL@% %@NL@% %@CR:MCVJ6000@%%@2@%%@AB@%19.6 The DATA Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ6001@%%@4@%The %@AB@%DATA%@AE@% statement defines the default attributes for the data segments%@EH@% within the application or module.%@NL@% %@NL@% %@CR:MCVJ6002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ6003@%%@AB@%DATA%@AE@% «%@AI@%attribute%@AE@%...»%@NL@% %@NL@% %@CR:MCVJ6004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ6005@%%@4@%Each %@AI@%attribute%@AE@% must correspond to one of the following attribute fields.%@EH@% Each field can appear at most one time, and order is not significant. The attribute fields are present below, along with legal values. In each case, the default value is listed last. The last two fields have no effect on OS/2 data segments, but are included for use with Microsoft Windows.%@NL@% %@NL@% %@CR:MCVJ6006@%%@AB@%Field Values%@AE@%%@NL@% %@NL@% %@AI@%load%@AE@% %@AB@%PRELOAD%@AE@%, %@AB@%LOADONCALL%@AE@%%@NL@% %@NL@% %@AI@%readonly%@AE@% %@AB@%READONLY%@AE@%, %@AB@%READWRITE%@AE@%%@NL@% %@NL@% %@AI@%instance%@AE@% %@AB@%NONE%@AE@%, %@AB@%SINGLE%@AE@%, %@AB@%MULTIPLE%@AE@%%@NL@% %@NL@% %@AI@%iopl%@AE@% %@AB@%IOPL%@AE@%, %@AB@%NOIOPL%@AE@%%@NL@% %@NL@% %@AI@%shared%@AE@% %@AB@%SHARED%@AE@%, %@AB@%NONSHARED%@AE@%%@NL@% %@NL@% %@AI@%movable%@AE@% %@AB@%MOVABLE%@AE@%, %@AB@%FIXED%@AE@%%@NL@% %@NL@% %@AI@%discard%@AE@% %@AB@%NONDISCARDABLE%@AE@%, %@AB@%DISCARDABLE%@AE@%%@NL@% %@NL@% %@CR:MCVJ6007@%%@4@%The %@AI@%load%@AE@% field determines when a segment will be loaded. This field contains%@EH@% one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ6008@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%PRELOAD%@AE@% The segment is loaded when the program begins%@NL@% execution%@NL@% %@NL@% %@AB@%LOADONCALL%@AE@% The segment is not loaded until it is accessed%@NL@% (the default)%@NL@% %@NL@% %@CR:MCVJ6009@%%@4@%The %@AI@%readonly%@AE@% field determines the access rights to a data segment. This%@EH@% field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ600A@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%READONLY%@AE@% The segment can only be read%@NL@% %@NL@% %@AB@%READWRITE%@AE@% The segment can be both read and written to (the%@NL@% default)%@NL@% %@NL@% %@CR:MCVJ600B@%%@4@%The %@AI@%instance%@AE@% field affects the sharing attributes of the automatic data%@EH@% segment, which is the physical segment represented by the group name DGROUP. (This segment group makes up the physical segment which contains the local stack and heap of the application.) The %@AI@%instance%@AE@% field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ600C@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%NONE%@AE@% No automatic data segment is created.%@NL@% %@NL@% %@AB@%SINGLE%@AE@% A single automatic data segment is shared by all%@NL@% instances of the module. In this case, the%@NL@% module is said to have "solo" data. This keyword%@NL@% is the default for dynamic-link libraries.%@NL@% %@NL@% %@AB@%MULTIPLE%@AE@% The automatic data segment is copied for each%@NL@% instance of the module. In this case, the module%@NL@% is said to have "instance" data. This keyword is%@NL@% the default for applications.%@NL@% %@NL@% %@CR:MCVJ600D@%%@4@%The %@AI@%iopl%@AE@% field determines whether or not data segments have I/O privilege%@EH@% (that is, whether or not they can access the hardware directly). This field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ600E@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%IOPL%@AE@% The data segments have I/O privilege%@NL@% %@NL@% %@AB@%NOIOPL%@AE@% The data segments do not have I/O privilege (the%@NL@% default)%@NL@% %@NL@% %@CR:MCVJ600F@%%@4@%The %@AI@%shared%@AE@% field determines whether all instances of the program can share a%@EH@% %@AB@%READWRITE%@AE@% data segment. Under OS/2, this field is ignored by the linker if the segment has the attribute %@AB@%READONLY%@AE@%, since %@AB@%READONLY%@AE@% data segments are always shared. The %@AI@%shared%@AE@% field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ600G@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%SHARED%@AE@% One copy of the data segment will be loaded and%@NL@% shared among all processes accessing the module.%@NL@% This keyword is the default for dynamic-link%@NL@% libraries%@NL@% %@NL@% %@AB@%NONSHARED%@AE@% The segment cannot be shared and must be loaded%@NL@% separately for each process. This keyword is the%@NL@% default for applications%@NL@% %@NL@% %@CR:MCVJ600H@%%@4@%The %@AI@%movable%@AE@% field determines whether a segment can be moved around in%@EH@% memory. This field is ignored by OS/2, but is provided for use with real-mode Windows. Under OS/2, all segments are movable. The %@AI@%movable%@AE@% field contains one of the following keywords: %@AB@%MOVABLE%@AE@% or %@AB@%FIXED%@AE@% (the default for Windows).%@NL@% %@NL@% %@CR:MCVJ600I@%%@4@%The optional %@AI@%discard%@AE@% field determines whether a segment can be swapped out%@EH@% to disk by the operating system when not currently needed. This attribute is ignored by OS/2, but is provided for use with real-mode Windows. Under OS/2 systems, all segments can be swapped as needed. The %@AI@%discard%@AE@% attribute contains one of the following keywords: %@AB@%DISCARDABLE%@AE@% or %@AB@%NONDISCARDABLE%@AE@% (the default for Windows).%@NL@% %@NL@% %@CR:MCVJ600J@%%@4@%Note that the linker makes the automatic-data-segment attribute (specified%@EH@% by an instance value of %@AB@%SINGLE%@AE@% or %@AB@%MULTIPLE%@AE@%) match the sharing attribute of the automatic data segment (specified by a shared value of %@AB@%SHARED%@AE@% or %@AB@%NONSHARED%@AE@%). Solo data (specified by %@AB@%SINGLE%@AE@%) force shared data segments by default. Instance data (specified by %@AB@%MULTIPLE%@AE@%) force nonshared data by default. Similarly, %@AB@%SHARED%@AE@% forces solo data, and %@AB@%NONSHARED%@AE@% forces instance data.%@NL@% %@NL@% %@CR:MCVJ600K@%%@4@%If you give a contradictory %@AB@%DATA%@AE@% statement such as %@AS@%DATA SINGLE NONSHARED%@AE@%,%@EH@% all segments in DGROUP are shared, and all other data segments are nonshared by default. If a segment that is a member of DGROUP is defined with a sharing attribute that conflicts with the automatic data type, a warning about the bad segment is issued, and the segment's flags are converted to a consistent sharing attribute. For example, the following%@NL@% %@NL@% DATA SINGLE%@NL@% SEGMENTS%@NL@% _DATA CLASS 'DATA' NONSHARED%@NL@% %@NL@% %@CR:MCVJ600L@%is converted to%@NL@% %@NL@% _DATA CLASS 'DATA' SHARED%@NL@% %@NL@% %@CR:MCVJ600M@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ600N@%%@4@%The example below defines the application's data segment so it is loaded%@EH@% only when it is accessed and cannot be shared by more than one copy of the program.%@NL@% %@NL@% DATA LOADONCALL NONSHARED%@NL@% %@NL@% %@CR:MCVJ600O@%%@4@%By default, the data segment can be read and written, the automatic-data%@EH@% segment is copied for each instance of the module, and the data segment has no I/O privilege.%@NL@% %@NL@% %@NL@% %@CR:MCVJ7000@%%@2@%%@AB@%19.7 The SEGMENTS Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ7001@%%@4@%The %@AB@%SEGMENTS%@AE@% statement defines the attributes of one or more segments in the%@EH@% application or library on a segment-by-segment basis. The attributes specified by this statement override defaults set in %@AB@%CODE%@AE@% and %@AB@%DATA%@AE@% statements.%@NL@% %@NL@% %@CR:MCVJ7002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ7003@%%@AB@%SEGMENTS%@AE@% %@AI@%segmentdefinitions%@AE@%%@NL@% %@NL@% %@CR:MCVJ7004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ7005@%%@4@%The %@AB@%SEGMENTS%@AE@% keyword marks the beginning of the segment definitions. This%@EH@% keyword can be followed by one or more segment definitions, each on a separate line (limited by the number set by the linker's /SEGMENTS option, or 128 if the option is not used). The syntax for each segment definition is as follows:%@NL@% %@NL@% %@CR:MCVJ7006@%«%@AB@%'%@AE@%»%@AI@%segmentname%@AE@%«%@AB@%'%@AE@%»«%@AB@%CLASS%@AE@%%@AB@%'%@AE@%%@AI@%classname%@AE@%%@AB@%'%@AE@%» «%@AI@%attribute%@AE@%... »%@NL@% %@NL@% %@CR:MCVJ7007@%%@4@%Each segment definition begins with a %@AI@%segmentname%@AE@%, which can be placed in%@EH@% optional single quotation marks (%@AB@%'%@AE@%). The quotation marks are required if %@AI@%segmentname%@AE@% conflicts with a module-definition keyword, such as %@AB@%CODE%@AE@% or %@AB@%DATA%@AE@%.%@NL@% %@NL@% %@CR:MCVJ7008@%%@4@%The %@AB@%CLASS%@AE@% keyword specifies the class of the segment. Single quotation marks%@EH@% (%@AB@%'%@AE@%) are required around %@AI@%classname%@AE@%. If you do not use the %@AB@%CLASS%@AE@% argument, the linker assumes that the class is %@AB@%CODE%@AE@%.%@NL@% %@NL@% %@CR:MCVJ7009@%%@4@%Each %@AI@%attribute%@AE@% must correspond to one of the following attribute fields.%@EH@% Each field can appear at most one time, and order is not significant. The attribute fields are presented below, along with legal values. In each case, the default value is listed last.%@NL@% %@NL@% %@CR:MCVJ700A@%%@AB@%Field Values%@AE@%%@NL@% %@NL@% %@AI@%load%@AE@% %@AB@%PRELOAD%@AE@%, %@AB@%LOADONCALL%@AE@%%@NL@% %@NL@% %@AI@%readonly%@AE@% %@AB@%READONLY%@AE@%, %@AB@%READWRITE%@AE@%%@NL@% %@NL@% %@AI@%executeonly%@AE@% %@AB@%EXECUTEONLY%@AE@%, %@AB@%EXECUTEREAD%@AE@%%@NL@% %@NL@% %@AI@%iopl%@AE@% %@AB@%IOPL%@AE@%, %@AB@%NOIOPL%@AE@%%@NL@% %@NL@% %@AI@%conforming%@AE@% %@AB@%CONFORMING%@AE@%, %@AB@%NONCONFORMING%@AE@%%@NL@% %@NL@% %@AI@%shared%@AE@% %@AB@%SHARED%@AE@%, %@AB@%NONSHARED%@AE@%%@NL@% %@NL@% %@AI@%movable%@AE@% %@AB@%MOVABLE%@AE@%, %@AB@%FIXED%@AE@%%@NL@% %@NL@% %@AI@%discard%@AE@% %@AB@%NONDISCARDABLE%@AE@%, %@AB@%DISCARDABLE%@AE@%%@NL@% %@NL@% %@CR:MCVJ700B@%%@4@%The %@AI@%load%@AE@% field determines when a segment is to be loaded. This field%@EH@% contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ700C@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%PRELOAD%@AE@% The segment is loaded automatically at the%@NL@% beginning of the program%@NL@% %@NL@% %@AB@%LOADONCALL%@AE@% The segment is not loaded until accessed (the%@NL@% default)%@NL@% %@NL@% %@CR:MCVJ700D@%%@4@%The %@AI@%readonly%@AE@% field determines the access rights to a data segment. This%@EH@% field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ700E@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%READONLY%@AE@% The segment can only be read%@NL@% %@NL@% %@AB@%READWRITE%@AE@% The segment can be both read and written to (the%@NL@% default)%@NL@% %@NL@% %@CR:MCVJ700F@%%@4@%The %@AI@%executeonly%@AE@% field determines whether a code segment can be read as well%@EH@% as executed. (The attribute has no effect on data segments.) This field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ700G@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%EXECUTEONLY%@AE@% The segment can only be executed%@NL@% %@NL@% %@AB@%EXECUTEREAD%@AE@% The segment can be both executed and read (the%@NL@% default)%@NL@% %@NL@% %@CR:MCVJ700H@%%@4@%The %@AI@%iopl%@AE@% field determines whether or not a segment has I/O privilege (that%@EH@% is, whether it can access the hardware directly). This field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ700I@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%IOPL%@AE@% The segments have I/O privilege%@NL@% %@NL@% %@AB@%NOIOPL%@AE@% The segments do not have I/O privilege (the%@NL@% default)%@NL@% %@NL@% %@CR:MCVJ700J@%%@4@%The %@AI@%conforming%@AE@% field specifies whether a code segment is a 286 "conforming"%@EH@% segment. The concept of a conforming segment deals with privilege level (the range of instructions that the process can execute) and is relevant only to users writing device drivers and system-level code. A conforming segment can be called from either Ring 2 or Ring 3, and the segment executes at the caller's privilege level. (The attribute has no effect on data segments.) This field contains one of the following keywords:%@NL@% %@NL@% %@CR:MCVJ700K@%%@AB@%Keyword Meaning%@AE@%%@NL@% %@NL@% %@AB@%CONFORMING%@AE@% The segment is conforming%@NL@% %@NL@% %@AB@%NONCONFORMING%@AE@% The segment is nonconforming (the default)%@NL@% %@NL@% %@CR:MCVJ700L@%%@4@%The %@AI@%shared%@AE@% field determines whether all instances of the program can share a%@EH@% %@AB@%READWRITE%@AE@% segment. For code segments and %@AB@%READONLY%@AE@% data segments, this field is ignored by OS/2, but is provided for use with real-mode Windows. Under OS/2, all code segments and all %@AB@%READONLY%@AE@% data segments are shared. The %@AI@%shared%@AE@% field contains one of the following keywords: %@AB@%SHARED%@AE@% or %@AB@%NONSHARED%@AE@% (the default).%@NL@% %@NL@% %@CR:MCVJ700M@%%@4@%The %@AI@%movable%@AE@% field determines whether a segment can be moved around in%@EH@% memory. This field is ignored by OS/2, but is provided for use with real-mode Windows. Under OS/2, all segments are movable. The %@AI@%movable%@AE@% field contains one of the following keywords: %@AB@%MOVABLE%@AE@% or %@AB@%FIXED%@AE@% (the default for Windows).%@NL@% %@NL@% %@CR:MCVJ700N@%%@4@%The optional %@AI@%discard%@AE@% field determines whether a segment can be swapped out%@EH@% to disk by the operating system, when not currently needed. This attribute is ignored by OS/2, but is provided for use with real-mode Windows. Under OS/2 systems, all segments can be swapped as needed. The %@AI@%shared%@AE@% attribute contains one of the following keywords: %@AB@%DISCARDABLE%@AE@% or %@AB@%NONDISCARDABLE%@AE@% (the default for Windows).%@NL@% %@NL@% %@CR:MCVJ700O@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ700P@%%@4@%The following example specifies segments named %@AS@%cseg1%@AE@%, %@AS@%cseg2%@AE@%, and %@AS@%dseg%@AE@%. The%@EH@% first segment is assigned class %@AS@%mycode%@AE@% and the second is assigned %@AB@%CODE%@AE@% by default. Each segment is given different attributes.%@AS@%%@NL@% %@NL@% SEGMENTS%@NL@% cseg1 CLASS 'mycode' IOPL%@NL@% cseg2 EXECUTEONLY PRELOAD CONFORMING%@NL@% dseg CLASS 'data' LOADONCALL READONLY%@NL@% %@NL@% %@NL@% %@CR:MCVJ8000@%%@2@%%@AB@%19.8 The STACKSIZE Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ8001@%%@4@%The %@AB@%STACKSIZE%@AE@% statement performs the same function as the /STACKSIZE linker%@EH@% option. It overrides the size of any stack segment defined in an application. (The %@AB@%STACKSIZE%@AE@% statement overrides the /STACKSIZE option).%@NL@% %@NL@% %@CR:MCVJ8002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ8003@%%@AB@%STACKSIZE%@AE@% %@AI@%number%@AE@%%@NL@% %@NL@% %@CR:MCVJ8004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ8005@%%@4@%The %@AI@%number%@AE@% must be an integer; it is considered to be in decimal format by%@EH@% default, but you can use C notation to specify hexadecimal or octal.%@NL@% %@NL@% %@CR:MCVJ8006@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ8007@%%@4@%The following example allocates 4,096 bytes of local-stack space:%@EH@%%@NL@% %@NL@% STACKSIZE 4096%@NL@% %@NL@% %@NL@% %@CR:MCVJ9000@%%@2@%%@AB@%19.9 The EXPORTS Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ9001@%%@4@%The %@AB@%EXPORTS%@AE@% statement defines the names and attributes of the functions%@EH@% exported to other modules and of the functions that run with I/O privilege. The term "export" refers to the process of making a function available to other run-time modules. By default, functions are hidden from other modules at run time.%@NL@% %@NL@% %@CR:MCVJ9002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ9003@%%@AB@%EXPORTS%@AE@% %@AI@%exportdefinitions%@AE@%%@NL@% %@NL@% %@CR:MCVJ9004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ9005@%%@4@%The %@AB@%EXPORTS%@AE@% keyword marks the beginning of the export definitions. It may be%@EH@% followed by up to 3,072 export definitions, each on a separate line. You need to give an export definition for each dynamic-link routine you want to make available to other modules. The syntax for an export definition is as follows:%@NL@% %@NL@% %@CR:MCVJ9006@%%@AI@%entryname%@AE@%«=%@AI@%internalname%@AE@%» «%@AB@%@%@AE@%%@AI@%ord%@AE@%«%@AB@%RESIDENTNAME%@AE@%»» «%@AI@%pwords%@AE@%» «%@AB@%NODATA%@AE@%»%@AB@%%@NL@% %@NL@% %@CR:MCVJ9007@%%@4@%The %@AI@%entryname%@AE@% specification defines the function name as it is known to%@EH@% other modules. The optional %@AI@%internalname%@AE@% defines the actual name of the export function as it appears within the module itself; by default, this name is the same as %@AI@%entryname%@AE@%.%@NL@% %@NL@% %@CR:MCVJ9008@%%@4@%The optional %@AI@%ord%@AE@% field defines the function's ordinal position within the%@EH@% module-definition table. If this field is used, the function's entry point can be invoked by name or by ordinal. Use of ordinal positions is faster and may save space.%@NL@% %@NL@% %@CR:MCVJ9009@%%@4@%The optional keyword %@AB@%RESIDENTNAME%@AE@% specifies that the function's name be kept%@EH@% resident in memory at all times. This keyword is applicable only if the %@AI@%ord%@AE@% option is used because if the %@AI@%ord%@AE@% option is not used, OS/2 automatically keeps the names of all exported functions resident in memory anyway.%@NL@% %@NL@% %@CR:MCVJ900A@%%@4@%The %@AI@%pwords%@AE@% field specifies the total size of the function's parameters, as%@EH@% meas-ured in words (the total number of bytes divided by two). This field is required only if the function executes with I/O privilege. When a function with I/O privilege is called, OS/2 consults the %@AI@%pwords%@AE@% field to determine how many words to copy from the caller's stack to the I/O-privileged function's stack.%@NL@% %@NL@% %@CR:MCVJ900B@%%@4@%The optional keyword %@AB@%NODATA%@AE@% is ignored by OS/2, but is provided for use by%@EH@% real-mode Windows.%@NL@% %@NL@% %@CR:MCVJ900C@%%@4@%Normally, the %@AB@%EXPORTS%@AE@% statement is only meaningful for functions within%@EH@% dynamic-link libraries and for functions that execute with I/O privilege.%@NL@% %@NL@% %@CR:MCVJ900D@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJ900E@%%@4@%The following %@AB@%EXPORTS%@AE@% statement defines the three export functions %@EH@% %@AS@%SampleRead%@AE@%, %@AS@%StringIn%@AE@%, and %@AS@%CharTest%@AE@%. The first two functions can be accessed either by their exported names or by an ordinal number. Note that in the module's own source code, these functions are defined as %@AS@%read2bin%@AE@% and %@AS@%str1%@AE@%, respectively. The last function runs with I/O privilege and therefore is given with the total size of the parameters: six words.%@NL@% %@NL@% EXPORTS%@NL@% SampleRead = read2bin @8%@NL@% StringIn = str1 @4 RESIDENTNAME%@NL@% CharTest 6%@NL@% %@NL@% %@NL@% %@CR:MCVJA000@%%@2@%%@AB@%19.10 The IMPORTS Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJA001@%%@4@%The %@AB@%IMPORTS%@AE@% statement defines the names of the functions that will be%@EH@% imported for the application or library. The term "import" refers to the process of declaring that a symbol is defined in another run-time module (a dynamic-link library). Typically, LINK uses an import library (created by the IMPLIB utility) to resolve external references to dynamic-link symbols. However, the %@AB@%IMPORTS%@AE@% statement provides an alternative for resolving these references within a module.%@NL@% %@NL@% %@CR:MCVJA002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJA003@%%@AB@%IMPORTS%@AE@% %@AI@%importdefinitions%@AE@%%@NL@% %@NL@% %@CR:MCVJA004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJA005@%%@4@%The %@AB@%IMPORTS%@AE@% keyword marks the beginning of the import definitions. This%@EH@% keyword is followed by one or more import definitions, each on a separate line. The only limit on the number of import definitions is that the total amount of space required for their names must be less than 64K. Each import definition corresponds to a particular function. The syntax for an import definition is as follows:%@AI@%%@NL@% %@NL@% %@CR:MCVJA006@%«%@AI@%internalname%@AE@%%@AB@%=%@AE@%»%@AI@%modulename%@AE@%%@AB@%.%@AE@%%@AI@%entry%@AE@%%@NL@% %@NL@% %@CR:MCVJA007@%%@4@%The %@AI@%internalname%@AE@% specifies the name that the importing module actually uses%@EH@% to call the function. Thus, %@AI@%internalname%@AE@% appears in the source code of the importing module, though the function may have a different name in the module where it is defined. By default, %@AI@%internalname%@AE@% is the same as the name given in %@AI@%entry%@AE@%.%@NL@% %@NL@% %@CR:MCVJA008@%%@4@%The %@AI@%modulename%@AE@% is the name of the application or library that contains the%@EH@% function.%@NL@% %@NL@% %@CR:MCVJA009@%%@4@%The %@AI@%entry%@AE@% field determines the function to be imported and can be a name or%@EH@% an ordinal value. (Ordinal values are set in an %@AB@%EXPORTS%@AE@% statement.) If an ordinal value is given, the %@AI@%internalname%@AE@% field is required.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% A given function has a name for each of three different contexts. The%@NL@% function has a name used by the exporting module (where it is defined), a%@NL@% name used as an entry point between modules, and a name as it is used by%@NL@% the importing module (where it is called). If neither module uses the%@NL@% optional %@AI@%internalname%@AE@% field, the function has the same name in all three%@NL@% contexts. If either of the modules use the %@AI@%internalname%@AE@% field, the%@NL@% function may have more than one distinct name.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVJA00A@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJA00B@%%@4@%The following %@AB@%IMPORTS%@AE@% statement defines three functions to be imported:%@EH@% %@AS@%SampleRead%@AE@%, %@AS@%SampleWrite%@AE@%, and a function that has been assigned an ordinal value of 1. The functions are found in the modules %@AS@%Sample%@AE@%, %@AS@%SampleA%@AE@%, and %@AS@%Read%@AE@%, respectively. The function from the %@AS@%Read%@AE@% module is referred to as %@AS@%ReadChar%@AE@% in the importing module; the original name of the function, as it is defined in the %@AS@%Read%@AE@% module, may or may not be known.%@NL@% %@NL@% IMPORTS%@NL@% Sample.SampleRead%@NL@% SampleA.SampleWrite%@NL@% ReadChar = Read.1%@NL@% %@NL@% %@NL@% %@CR:MCVJB000@%%@2@%%@AB@%19.11 The STUB Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJB001@%%@4@%The %@AB@%STUB%@AE@% statement adds a DOS 3.x executable file to the beginning of the%@EH@% application or library being created. The stub is invoked whenever the module is executed under DOS 2.x or DOS 3.x. Typically, the stub displays a message and terminates execution. (By default, the linker adds its own standard stub for this purpose.)%@NL@% %@NL@% %@CR:MCVJB002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJB003@%%@AB@%STUB%@AE@% %@AB@%'%@AE@%%@AI@%filename%@AE@%%@AB@%'%@AE@%%@NL@% %@NL@% %@CR:MCVJB004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJB005@%%@4@%The filename specifies the DOS executable file to be added. If the linker%@EH@% does not find %@AI@%filename%@AE@% in the current directory, it searches in the list of directories specified in the PATH environment variable.%@NL@% %@NL@% %@CR:MCVJB006@%%@4@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJB007@%%@4@%The following example appends the DOS executable file STOPIT.EXE to the%@EH@% beginning of the module:%@NL@% %@NL@% STUB 'STOPIT.EXE'%@NL@% %@NL@% %@CR:MCVJB008@%%@4@%The file STOPIT.EXE is executed when you attempt to run the module under%@EH@% DOS.%@NL@% %@NL@% %@NL@% %@CR:MCVJC000@%%@2@%%@AB@%19.12 The HEAPSIZE Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJC001@%%@4@%The %@AB@%HEAPSIZE%@AE@% statement defines the size of the application's local heap in%@EH@% bytes. This value affects the size of the automatic data segment.%@NL@% %@NL@% %@CR:MCVJC002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJC003@%%@AB@%HEAPSIZE%@AE@% %@AI@%bytes%@AE@% | %@AB@%MAXVAL%@AE@%%@NL@% %@NL@% %@CR:MCVJC004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJC005@%%@4@%The %@AI@%bytes%@AE@% field is an integer number considered decimal by default. However,%@EH@% hexadecimal and octal numbers can be entered by using C notation.%@NL@% %@NL@% %@CR:MCVJC006@%%@4@%%@AB@%MAXVAL%@AE@% is an optional keyword that may be substituted for %@AI@%bytes%@AE@% to set the%@EH@% field parameter. %@AB@%MAXVAL%@AE@% sets the heap size to the value of DGROUP-64K. DGROUP is the automatic or default data segment. The effect is that the loader allocates exactly 64K for DGROUP. This may be useful in bound applications in which you want to force a 64K requirement for DGROUP on the program in DOS. The bound program fails to load if 64K minus the size of DGROUP is less than zero.%@NL@% %@NL@% %@CR:MCVJC007@%%@4@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@NL@% HEAPSIZE 4000%@NL@% %@NL@% HEAPSIZE MAXVAL%@NL@% %@NL@% %@NL@% %@CR:MCVJD000@%%@2@%%@AB@%19.13 The PROTMODE Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJD001@%%@4@%The %@AB@%PROTMODE%@AE@% statement specifies that the module runs only in protected mode%@EH@% and not in Windows or dual mode. This statement is always optional, and permits a protected-mode-only application to omit some information from the executable-file header.%@NL@% %@NL@% %@CR:MCVJD002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJD003@%%@4@%%@AB@%PROTMODE%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJD004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJD005@%%@4@%If this statement is not included in the module-definition file, the linker%@EH@% assumes the application can be run in either real or protected mode.%@NL@% %@NL@% %@NL@% %@CR:MCVJE000@%%@2@%%@AB@%19.14 The OLD Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJE001@%%@4@%The %@AB@%OLD%@AE@% statement directs the linker to search another dynamic-link module%@EH@% for export ordinals. For more information on ordinals, see the sections above on the %@AB@%EXPORTS%@AE@% and %@AB@%IMPORTS%@AE@% statements. Exported names in the current module that match exported names in the %@AB@%OLD%@AE@% module are assigned ordinal values from that module unless one of the following conditions is in effect: the name in the %@AB@%OLD%@AE@% module has no ordinal value assigned, or an ordinal value is explicitly assigned in the current module.%@NL@% %@NL@% %@CR:MCVJE002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJE003@%%@AB@%OLD%@AE@% %@AB@%'%@AE@%%@AI@%filename%@AE@%%@AB@%'%@AE@%%@NL@% %@NL@% %@CR:MCVJE004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJE005@%%@4@%This statement is useful for preserving export ordinal values throughout%@EH@% successive versions of a dynamic-link module. The %@AB@%OLD%@AE@% has no effect on application modules.%@NL@% %@NL@% %@NL@% %@CR:MCVJF000@%%@2@%%@AB@%19.15 The REALMODE Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJF001@%%@4@%The %@AB@%REALMODE%@AE@% statement is analogous to the %@AB@%PROTMODE%@AE@% statement and is%@EH@% provided for use with real-mode Windows applications.%@NL@% %@NL@% %@CR:MCVJF002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJF003@%%@AB@%REALMODE%@AE@%%@NL@% %@NL@% %@CR:MCVJF004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJF005@%%@4@%%@AB@%REALMODE%@AE@% specifies that the application runs only in real mode. With this%@EH@% statement, the linker relaxes some of the restrictions that it imposes on programs running in protected mode.%@NL@% %@NL@% %@NL@% %@CR:MCVJG000@%%@2@%%@AB@%19.16 The EXETYPE Statement%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJG001@%%@4@%The %@AB@%EXETYPE%@AE@% statement specifies in which operating system the application%@EH@% (or dynamic-link library) is to run. This statement is optional and provides an additional degree of protection against the program being run in an incorrect operating system.%@NL@% %@NL@% %@CR:MCVJG002@%%@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJG003@%%@AB@%EXETYPE%@AE@% «%@AB@%OS2%@AE@% | %@AB@%WINDOWS%@AE@% | %@AB@%DOS4%@AE@%»%@NL@% %@NL@% %@CR:MCVJG004@%%@4@%%@AB@%Remarks%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVJG005@%%@4@%The %@AB@%EXETYPE%@AE@% keyword must be followed by a descriptor of the operating%@EH@% system, either %@AB@%OS2%@AE@% (for OS/2 applications and dynamic-link libraries), %@AB@%WINDOWS%@AE@%, or %@AB@%DOS4%@AE@%. If no %@AB@%EXETYPE%@AE@% statement is given, %@AB@%EXETYPE OS2%@AE@% is assumed by an operating system that is loading the program.%@NL@% %@NL@% %@CR:MCVJG006@%%@4@%The effect of %@AB@%EXETYPE%@AE@% is to set bits in the header which identify%@EH@% operating-system type. Operating-system loaders may check these bits.%@NL@% %@NL@% %@NL@% %@CR:MCVK0000@%%@1@%%@AB@%Chapter 20 Creating Dual-Mode Programs with BIND%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVK0001@%%@4@%The Microsoft Operating System/2 Bind (BIND) utility converts protected-mode%@EH@% programs so they can run in both real mode and protected mode. Not every protected-mode program can readily be converted. Programs you wish to convert should make no system calls other than calls to the functions listed in the Family API. (The Family API, see the %@AI@%Microsoft Operating System/2%@AE@% %@AI@%Programmer's Reference%@AE@%, is a subset of the API functions.)%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% The BIND utility will not work on BASIC programs.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVK0002@%%@4@%The BIND utility must "bind" dynamic-link functions──that is, the utility%@EH@% brings an application program together with libraries and links everything into a single stand-alone file that can run in real mode. The BIND utility also alters the executable-file format of the program so it is recognized as a standard executable file in both real mode and protected mode.%@NL@% %@NL@% %@CR:MCVK0003@%%@4@%If you are unable to create a bound version of your program, you can build a%@EH@% dual-mode version, as explained at the end of the chapter.%@NL@% %@NL@% %@CR:MCVK0004@%%@4@%There are three components to the BIND utility:%@EH@%%@NL@% %@NL@% %@CR:MCVK0005@% ■ BIND. This utility merges the executable file with the appropriate%@NL@% libraries as described above.%@NL@% %@NL@% ■ Loader. This tool loads the OS/2 executable file when running DOS 2.x%@NL@% or 3.x and simulates the OS/2 startup conditions in a DOS environment.%@NL@% The loader consists of code that is stored in BIND.EXE and copied into%@NL@% files as needed.%@NL@% %@NL@% ■ API.LIB. This library simulates the OS/2 API in a DOS environment.%@NL@% %@NL@% %@NL@% %@CR:MCVK1000@%%@2@%%@AB@%20.1 Binding Library Routines%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVK1001@%%@4@%The BIND utility replaces Family-API calls with simulator routines from the%@EH@% standard (object-code) library API.LIB. However, your program may also make dynamic-link calls to functions outside the API (that is, you can make dynamic-link calls that are not system calls). This section explains how BIND can accommodate these calls.%@NL@% %@NL@% %@CR:MCVK1002@%%@4@%If your program makes dynamic-link calls to functions outside the API, use%@EH@% the %@AI@%linklibs%@AE@% field described in Section 20.3%@BO: cddc2@%, "The BIND Command Line." BIND searches each of the libraries and files specified in %@AI@%linklibs%@AE@% for object code corresponding to the imported functions. In addition, if you are using import definitions with either the ordinal or the internal-name option, you need to specify import libraries so the functions you call can be identified correctly. (For a discussion of various options within import definitions, see Chapter 19%@BO: c14f2@%, "Using Module-Definition Files.")%@NL@% %@NL@% %@NL@% %@CR:MCVK2000@%%@2@%%@AB@%20.2 Binding Functions as Protected Mode Only%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVK2001@%%@4@%If your program freely makes non-Family-API calls without regard to which%@EH@% operating system is in use, the program cannot be converted for use in real mode. However, you may choose to write a program so it first checks the operating system and then restricts system calls (to the Family API) when running in real mode. The BIND utility supports conversion of these programs.%@NL@% %@NL@% %@CR:MCVK2002@%%@4@%By using the /n command-line option described below you can specify a list%@EH@% of functions supported in protected mode only. If your program ever attempts to call one of these functions when running in real mode, the BadDynLink system function is called and aborts your program. The advantage of this option is that it helps resolve external references, yet it remains the responsibility of your program to check the operating-system version and ensure that not one of these functions is ever called in real mode.%@NL@% %@NL@% %@CR:MCVK2003@%%@4@%If your program makes calls (either directly or indirectly) to%@EH@% non-Family-API system calls, but you do not use the /n option, then BIND fails to convert your program.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% %@AB@%BIND%@AE@% Version 1.0 does not work with files linked with the %@AB@%/EXEPACK%@AE@%%@NL@% option.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVK3000@%%@2@%%@AB@%20.3 The BIND Command Line%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVK3001@%%@4@%Invoke BIND with the following command line:%@EH@%%@NL@% %@NL@% %@CR:MCVK3002@%BIND %@AI@%infile%@AE@% «%@AI@%implibs%@AE@%» «%@AI@%linklibs%@AE@%» «/o %@AI@%outfile%@AE@%» «/n @%@AI@%file%@AE@%» «/n %@AI@%names%@AE@%» «/m %@AI@%mapfile%@AE@%»%@NL@% %@NL@% %@CR:MCVK3003@%%@CR:MCVK3004@%%@4@%The %@AI@%infile%@AE@% field contains the name of the OS/2 application. The file name%@EH@% may contain a complete path name. The file extension is optional; if you provide no extension, .EXE is assumed.%@NL@% %@NL@% %@CR:MCVK3005@%%@4@%The %@AI@%implibs%@AE@% field contains the name of one or more import libraries. As%@EH@% explained above, use this field if your program uses an import definition with either the %@AI@%ordinal%@AE@% or %@AI@%internalname%@AE@% fields.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% If you want to specify a 64K default data segment when running in real%@NL@% mode, specify the file APILMR.OBJ, which guarantees a 64K stack. The%@NL@% reason this object file may be necessary is that a protected-mode%@NL@% application is not automatically given a 64K default data segment; a%@NL@% protected-mode application is only allocated the space it specifically%@NL@% requests. If you do not specify the file APILMR.OBJ, you may not have the%@NL@% local heap area needed when you run in real mode.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVK3006@%%@4@%The %@AI@%linklibs%@AE@% field contains the name of one or more standard libraries and%@EH@% object files. Use this field to supply object code needed to resolve dynamic-link calls. Include DOSCALLS.LIB in this field. You must give the complete path name to DOSCALLS.LIB if it is not in the current directory. If you specify a second library, API.LIB, you need to give the complete path name for it also. If you do not specify API.LIB in this field, BIND automatically searches for API.LIB by looking in directories listed in the LIB environment variable. For example, the following command line successfully uses BIND if API.LIB is located in a directory listed in the LIB environment variable:%@NL@% %@NL@% BIND FOO.EXE \LIB\DOSCALLS.LIB%@NL@% %@NL@% %@CR:MCVK3007@%%@4@%The /o option specifies the name for the bound application, %@AI@%outfile%@AE@%, and may%@EH@% contain a full path name. The default value for this field is the name of the file that was given as %@AI@%infile%@AE@%.%@NL@% %@NL@% %@CR:MCVK3008@%%@4@%The /n option provides a way of listing functions that are supported in%@EH@% protected mode only. As explained above, if any of these functions are ever called in real mode, the BadDynLink function is called to abort the program. The /n option can be used either with a list of one or more %@AI@%names%@AE@% (separated by spaces), or Module Statements Attribute Defined with a %@AI@%file%@AE@% specification preceded by the %@AB@%@%@AE@% sign. The specified file should consist of a list of functions, one per line.%@NL@% %@NL@% %@CR:MCVK3009@%%@4@%The /m option causes a link map to be generated for the DOS 3.x environment%@EH@% of the .EXE file. The %@AI@%mapfile%@AE@% is the destination of the link map. If %@AI@%mapfile%@AE@% is not specified with the /m option, the destination of the link map is standard output.%@NL@% %@NL@% %@NL@% %@CR:MCVK4000@%%@2@%%@AB@%20.4 BIND Operation%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVK4001@%%@4@%BIND produces a single executable file that can run in either real mode or%@EH@% protected mode. To complete this task, BIND executes three major steps:%@NL@% %@NL@% %@CR:MCVK4002@% 1. Reads in the dynamic-link entry points (for imported functions) from%@NL@% the OS/2 executable file and outputs to a temporary object file the%@NL@% EXTDEF object records for each imported item. Each EXTDEF record tells%@NL@% the linker of an external reference that needs to be resolved through%@NL@% ordinary linking.%@NL@% %@NL@% 2. Invokes LINK, giving the executable file, the temporary object file,%@NL@% the API.LIB file, and any other libraries specified on the BIND command%@NL@% line. By linking in the loader and the API-simulator routines, LINK%@NL@% produces an executable file that can run in real mode.%@NL@% %@NL@% 3. Merges the protected-mode and real-mode executable files to produce a%@NL@% single file that can run in either mode.%@NL@% %@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@AI@%NOTE%@AE@%%@NL@% A dual-mode executable file produced with BIND can be run in both DOS 2.x%@NL@% and 3.x environments. However, if you change the name of an executable%@NL@% file produced by BIND, then it will not run under DOS 2.x.%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVK5000@%%@2@%%@AB@%20.5 Executable-File Layout%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVK5001@%%@4@%OS/2 executable files have two headers. The first header has a DOS 3.x%@EH@% format. The second header has the OS/2 format. When the executable file is run on an OS/2 system, it ignores the first header and uses the OS/2 format. When run under DOS 3.x, the old header is used to load the file. Figure 20.1%@FN@% Figure 20.1 is found on page 345 of the printed version.%@EF@% shows the arrangement of the merged headers.%@NL@% %@NL@% %@NL@% %@CR:MCVK6000@%%@2@%%@AB@%20.6 How to Build a Dual-Mode Application%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVK6001@%%@4@%If you cannot create a bound application out of your program, you may want%@EH@% to create a dual-mode executable (.EXE) file instead. A dual-mode .EXE file is similar to a bound file; both types of files run in either real mode or protected mode. However, the two types of files have a different internal structure.%@NL@% %@NL@% %@CR:MCVK6002@%%@4@%A bound file has common executable code that actually runs in both modes.%@EH@% System calls are specific to real mode or protected mode, but all system calls are modified at load time.%@NL@% %@NL@% %@CR:MCVK6003@%%@4@%In contrast, a dual-mode file has two separate programs contained in one%@EH@% file. One of these programs is real-mode-only and the other is protected-mode-only. All the code in a dual-mode executable file runs in either one mode or the other.%@NL@% %@NL@% %@CR:MCVK6004@%%@4@%To create a dual-mode application:%@EH@%%@NL@% %@NL@% %@CR:MCVK6005@% 1. Link a real-mode version of your program.%@NL@% %@NL@% 2. Create a module-definition file that contains the statement%@NL@% %@NL@% %@AS@%STUB 'PROGR.EXE'%@AE@%%@NL@% %@NL@% in which you substitute the name of your real-mode program for%@NL@% PROGR.EXE.%@NL@% %@NL@% 3. Link the protected-mode version of your program with this%@NL@% module-definition file. The protected-mode version and the real-mode%@NL@% version should have different names.%@NL@% %@NL@% %@NL@% %@CR:MCVL0000@%%@1@%%@AB@%Chapter 21 Using EXEHDR%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVL0001@%%@4@%The Microsoft Segmented-EXE Header Utility (EXEHDR) displays the contents of%@EH@% an executable-file header. You can use EXEHDR with OS/2 or Windows, and you can use it with an application or dynamic-link library. (With a Windows file, some of the meanings of the executable-file-header fields change; see your Windows documentation for more information.) The principal uses of EXEHDR include the following:%@NL@% %@NL@% %@CR:MCVL0002@% ■ Determining whether a file is an application or a dynamic-link library%@NL@% %@NL@% ■ Viewing the attributes set by the module-definition file%@NL@% %@NL@% ■ Viewing the number and size of code and data segments%@NL@% %@NL@% %@CR:MCVL0003@%%@4@%Except where noted otherwise, the special terms and keywords mentioned in%@EH@% this section are explained in Chapter 19%@BO: c14f2@%, "Using Module-Definition Files."%@NL@% %@NL@% %@NL@% %@CR:MCVL1000@%%@2@%%@AB@%21.1 The EXEHDR Command Line%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVL1001@%%@4@%To invoke the EXEHDR utility, use the syntax%@EH@%%@NL@% %@NL@% %@CR:MCVL1002@%EXEHDR «/v» %@AI@%file%@AE@%%@NL@% %@NL@% %@CR:MCVL1003@%in which %@AI@%file%@AE@% is an application or dynamic-link library for either the OS/2 or Windows environment. The /v option specifies output in verbose mode.%@NL@% %@NL@% %@CR:MCVL1004@%%@4@%Section 21.2%@BO: d003c@% presents sample output and explains the meaning of each field%@EH@% of the output. Section 21.3%@BO: d13d9@% describes additional output that EXEHDR produces when it is run in verbose mode.%@NL@% %@NL@% %@NL@% %@CR:MCVL2000@%%@2@%%@AB@%21.2 EXEHDR Output%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVL2001@%%@4@%This section discusses the meaning of each field in the output below──output%@EH@% produced when %@AS@%EXEHDR LINK.EXE%@AE@% is specified on the OS/2 command line. The first six fields list the contents of the segmented-executable-file header. The rest of the output lists each physical segment in the file. (The term "physical segment" is defined in Chapter 14, "Incremental Linking with ILINK.")%@NL@% %@NL@% Module: LINK%@NL@% Description: Microsoft Segmented-Executable Linker%@NL@% Data: NONSHARED%@NL@% Initial CS:IP: seg 2 offset 3d9c%@NL@% Initial SS:SP: seg 4 offset 8e40%@NL@% DGROUP: seg 4%@NL@% %@NL@% no. type address file mem flags%@NL@% 1 CODE 00003400 0f208 0f208%@NL@% 2 CODE 00012e00 05b04 05b04%@NL@% 3 DATA 00018c00 01c1f 01c1f%@NL@% 4 DATA 0001aa00 01b10 08e40%@NL@% %@NL@% %@CR:MCVL2002@%%@4@%The %@AS@%Module%@AE@% field is the name of the application as specified in the %@AB@%NAME%@AE@%%@EH@% statement of the module-definition file. If no module definition was used to create the executable file, this field displays the name assumed by default. If a module definition was used to create the file, but the %@AB@%LIBRARY%@AE@% statement appeared instead of the %@AB@%NAME%@AE@% statement (thus specifying a dynamic-link library), the name of the library is given and EXEHDR uses the word %@AS@%Library%@AE@% instead of %@AS@%Module.%@AE@%%@NL@% %@NL@% %@CR:MCVL2003@%%@4@%The %@AS@%Description%@AE@% field gives the contents, if any, of the %@AB@%DESCRIPTION%@AE@%%@EH@% statement of the module-definition file used to create the file being examined.%@NL@% %@NL@% %@CR:MCVL2004@%%@4@%The %@AS@%Data%@AE@% field indicates the type of the program's automatic data segment:%@EH@% %@AB@%SHARED%@AE@%, %@AB@%NONSHARED%@AE@%, or %@AB@%NONE%@AE@%. This type can be specified in a module-definition file, but by default is %@AB@%NONSHARED%@AE@% for applications and %@AB@%SHARED%@AE@% for dynamic-link libraries. In this context, %@AB@%SHARED%@AE@% and %@AB@%NONSHARED%@AE@% are equivalent to the %@AB@%SINGLE%@AE@% and %@AB@%MULTIPLE%@AE@% attributes listed in Section 19.6%@BO: c53df@%. (The "automatic data segment" is the physical segment corresponding to the group named DGROUP.)%@NL@% %@NL@% %@CR:MCVL2005@%%@4@%The %@AS@%Initial CS:IP%@AE@% field is the program starting address (if an application%@EH@% is being examined) or address of the initialization routine (if a dynamic-link library is being examined).%@NL@% %@NL@% %@CR:MCVL2006@%%@4@%The %@AS@%Initial SS:SP%@AE@% field gives the value of the initial stack pointer.%@EH@%%@NL@% %@NL@% %@CR:MCVL2007@%%@4@%The %@AS@%DGROUP%@AE@% field is the segment number of the automatic data segment. This%@EH@% segment corresponds to the group named DGROUP in the program's object modules. Note that segment numbers start with the number 1.%@NL@% %@NL@% %@CR:MCVL2008@%%@4@%After the contents of the OS/2 executable header are displayed, the contents%@EH@% of the segment table are listed. The following list describes the meaning of each heading in the table. Note that all values are given in hexadecimal radix except for the segment index number.%@NL@% %@CR:MCVL2009@%%@NL@% %@TH: 30 1578 2 20 56 @%%@AB@%Heading Meaning%@AE@%%@AS@%no.%@AE@% Segment index number, starting with 1, in decimal radix.%@AS@%type%@AE@% Identification of the segment as a code or data segment. A code segment is any segment with class name ending in %@AS@%'CODE'%@AE@%. All other segments are data segments.%@AS@%%@AS@%address%@AE@% Location, within the file, of the contents of the segment.%@AS@%file%@AE@% Size in bytes of the segment, as contained in the file.%@AS@%mem%@AE@% Size in bytes of the segment as it will be stored in memory. If the value of this field is greater than the value of the %@AS@%file%@AE@% field, OS/2 pads the additional space with zero values at load time.%@AS@%flags%@AE@% Segment attributes, as defined in Chapter 19, "Using Module-Definition Files." If the /v option is not used, only nondefault attributes are listed. Attributes are given in the form specified in Chapter 19%@BO: c14f2@%: %@AB@%READWRITE%@AE@%, %@AB@%PRELOAD%@AE@%, and so forth. Attributes that are meaningful to Windows but not to OS/2 are displayed as lowercase and in parentheses, [e.g., %@AS@%(movable)%@AE@%]%@TE: 30 1578 2 20 56 @% %@NL@% %@CR:MCVL3000@%%@2@%%@AB@%21.3 Output in Verbose Mode%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVL3001@%%@4@%When you specify the /v mode, the EXEHDR utility gives all the information%@EH@% discussed in Section 21.2%@BO: d003c@%, as well as some additional information. Specifically, when running in verbose mode, EXEHDR displays the following information in this order:%@NL@% %@NL@% %@CR:MCVL3002@% 1. DOS 3.x header information. All OS/2 executable files have a DOS 3.x%@NL@% header, whether bound or not. If the program is not bound, the DOS 3.x%@NL@% portion typically consists of a stub that terminates the program. For a%@NL@% de-scription of DOS executable-file-header fields, see the %@AI@%Microsoft%@AE@%%@NL@% %@AI@%MS-DOS Programmer's Reference%@AE@%, or see Chapter 17%@BO: ba564@% in this manual,%@NL@% "Using Other Utilities," for information on the Microsoft EXE File%@NL@% Header Utility (EXEMOD).%@NL@% %@NL@% 2. OS/2-specific header fields. This output includes the fields described%@NL@% in Section 21.2%@BO: d003c@% except for the segment table. (The segment-table%@NL@% display for verbose mode is described below.)%@NL@% %@NL@% 3. File addresses and lengths of the various tables in the executable%@NL@% file, as in the following example:%@NL@% %@NL@% Resource Table: 00003273 length 0000 (0)%@NL@% Resident Names Table: 00003273 length 0008 (8)%@NL@% Module Reference Table: 0000327b length 0006 (6)%@NL@% Imported Names Table: 00003281 length 0033 (51)%@NL@% Entry Table: 000032b4 length 0002 (2)%@NL@% Non-resident Names Table: 000032b6 length 0029 (41)%@NL@% Movable entry points: 0%@NL@% Segment sector size: 512%@NL@% %@NL@% The first field in each row gives the name of the table, the second%@NL@% field gives the address of the table within the file, the third field%@NL@% gives the length of the table in hexadecimal radix, and the last field%@NL@% gives the length of the table in decimal radix. See the %@AI@%Microsoft%@AE@%%@NL@% %@AI@%Operating System/2 Programmer's Reference%@AE@% for an explanation of each%@NL@% table.%@AI@%%@NL@% %@NL@% 4. Segment table with complete attributes, not just the nondefault%@NL@% attributes. In addition to the attributes described in Section 21.2%@BO: d003c@%,%@NL@% verbose mode also displays these two additional attributes:%@NL@% %@NL@% ■ The %@AS@%relocs%@AE@% attribute is displayed for each segment that has%@NL@% address relocations. Relocations occur in each segment that%@NL@% references objects in other segments or makes dynamic-link%@NL@% references.%@NL@% %@NL@% ■ The %@AS@%iterated%@AE@% attribute is displayed for each segment that has%@NL@% iterated data. Iterated data consist of a special code that packs%@NL@% repeated bytes; for example, OS/2 executables produced with the%@NL@% /EXEPACK option of LINK have iterated data.%@NL@% %@NL@% 5. Run-time relocations and fixups. See the object-module information in%@NL@% the %@AI@%Microsoft Operating System/2 Programmer's Reference%@AE@% for more%@NL@% information.%@NL@% %@NL@% 6. Finally, EXEHDR lists all exported entry points. Exports are discussed%@NL@% in Chapter 18%@BO: be41d@%, "Linking for Windows and OS/2 Systems," and in Section%@NL@% 19.9%@BO: c9500@%, "The EXPORTS Statement."%@NL@% %@NL@% %@NL@% %@CR:MCVa0000@%%@1@%%@AB@%Appendix A Regular Expressions%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVa0001@%%@4@%Regular expressions are used to specify text patterns in searches for%@EH@% variable text strings. Special characters can be used within regular expressions to specify groups of characters to be searched for.%@NL@% %@NL@% %@CR:MCVa0002@%%@4@%This appendix explains all of the special characters you can use to form%@EH@% regular expressions, but you do not need to learn them all to use the CodeView Search commands. The simplest form of regular expression is simply a text string. For example, if you want to search for all instances of the symbol %@AS@%COUNT%@AE@%, you can specify %@AS@%COUNT%@AE@% as the string to be found.%@NL@% %@NL@% %@CR:MCVa0003@%%@4@%If you want to search only for simple strings, you do not need to read this%@EH@% entire appendix, but you should know how to search for strings containing the special characters used in regular expressions. See Section A.2%@BO: d2e49@% for more information.%@NL@% %@NL@% %@NL@% %@CR:MCVa1000@%%@2@%%@AB@%A.1 Special Characters in Regular Expressions%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVa1001@%%@4@%The following characters have special meanings in regular expressions:%@EH@%%@NL@% %@NL@% %@CR:MCVa1002@%%@AB@%Character Purpose%@AE@%%@NL@% %@NL@% Asterisk (%@AB@%*%@AE@%) Matches any number of repetitions of the%@NL@% previous character.%@NL@% %@NL@% Backslash (%@AB@%\%@AE@%) Removes the special characteristics of the%@NL@% following characters: backslash (%@AB@%\%@AE@%), period (%@AB@%.%@AE@%),%@NL@% caret (%@AB@%^%@AE@%), dollar sign (%@AB@%$%@AE@%), asterisk (%@AB@%*%@AE@%), and%@NL@% left bracket (%@AB@%[%@AE@%).%@NL@% %@NL@% Brackets (%@AB@%[ ]%@AE@%) Matches characters specified within the%@NL@% brackets. The following special characters may%@NL@% be used:%@NL@% %@NL@% %@AB@%Character Purpose%@AE@%%@NL@% %@NL@% Caret (%@AB@%^%@AE@%) Reverses the function of the%@NL@% brackets. That is, the caret%@NL@% matches any character except%@NL@% those specified within the%@NL@% brackets.%@NL@% %@NL@% Dash (%@AB@%-%@AE@%) Matches characters in ASCII%@NL@% order between (inclusive of)%@NL@% the characters on either%@NL@% side of the dash.%@NL@% %@NL@% Caret (%@AB@%^%@AE@%) Matches beginning of line.%@NL@% %@NL@% Dollar sign (%@AB@%$%@AE@%) Matches end of line.%@NL@% %@NL@% Period (%@AB@%.%@AE@%) Matches any character.%@NL@% %@NL@% %@NL@% %@CR:MCVa2000@%%@2@%%@AB@%A.2 Searching for Special Characters%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVa2001@%%@4@%If you need to match one of the special characters used in regular%@EH@% expressions, precede it with a backslash when you specify a search string. The special charac-ters are the asterisk (%@AB@%*%@AE@%), backslash (%@AB@%\%@AE@%), left bracket (%@AB@%[%@AE@%), caret (%@AB@%^%@AE@%), dollar sign (%@AB@%$%@AE@%), and period (%@AB@%.%@AE@%).%@NL@% %@NL@% %@CR:MCVa2002@%%@4@%For example, the regular expression %@AS@%I*J%@AE@% matches such combinations as %@AS@%J,%@AE@% %@AS@%IJ,%@AE@%%@EH@% %@AS@%IIJ,%@AE@% and %@AS@%IIIJ%@AE@%. The regular expression %@AS@%I\*J%@AE@% matches only %@AS@%I*J%@AE@%. The backslash is necessary because the asterisk (%@AB@%*%@AE@%) is a special character in regular expressions.%@NL@% %@NL@% %@NL@% %@CR:MCVa3000@%%@2@%%@AB@%A.3 Using the Period%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVa3001@%%@4@%A period in a regular expression matches any single character. This%@EH@% corresponds to the question mark (%@AB@%?%@AE@%) used in specifying DOS file names.%@NL@% %@NL@% %@CR:MCVa3002@%%@4@%For example, you could use the regular expression %@AS@%AMAX.%@AE@% to search for either%@EH@% of the intrinsic functions%@AS@%AMAX0%@AE@% and %@AS@%AMAX1%@AE@%. You could use the expression %@AS@%X.Y%@AE@% to search for strings such as %@AS@%X+Y%@AE@%, %@AS@%X-Y%@AE@%, or %@AS@%X*Y%@AE@%. If your programming style is to put a space between variables and operators, you could use the regular expression %@AS@%X.Y%@AE@% for the same purpose.%@NL@% %@NL@% %@CR:MCVa3003@%%@4@%Note that when you use the period as a wild card, you will find the strings%@EH@% you are looking for, but you may also find other strings that you aren't interested in. You can use brackets to be more exact about the strings you want to find.%@NL@% %@NL@% %@NL@% %@CR:MCVa4000@%%@2@%%@AB@%A.4 Using Brackets%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVa4001@%%@4@%You can use brackets to specify a character or characters you want to match.%@EH@% Any of the characters listed within the brackets is an acceptable match. This method is more exact than using a period to match any character.%@NL@% %@NL@% %@CR:MCVa4002@%%@4@%For example, the regular expression %@AS@%x[-+/*]y%@AE@% matches %@AS@%x+y%@AE@%, %@AS@%x-y%@AE@%, %@AS@%x/y%@AE@%, or %@AS@%x*y%@AE@%,%@EH@% but not %@AS@%x=y%@AE@% or %@AS@%xzy%@AE@%. The regular expression %@AS@%COUNT[12]%@AE@% matches %@AS@%COUNT1%@AE@% and %@AS@%COUNT2%@AE@%, but not %@AS@%COUNT3%@AE@%.%@NL@% %@NL@% %@CR:MCVa4003@%%@4@%Most regular-expression special characters have no special meaning when used%@EH@% within brackets. The only special characters within brackets are the caret (%@AB@%^%@AE@%), dash (%@AB@%-%@AE@%), and right bracket (%@AB@%]%@AE@%). Even these characters only have special meanings in certain contexts, as explained in Sections A.4.1%@BO: d39c0@%-A.4.3.%@NL@% %@NL@% %@NL@% %@CR:MCVa4100@%%@3@%%@AB@%A.4.1 Using the Dash within Brackets%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVa4101@%%@4@%The dash (minus sign) can be used within brackets to specify a group of%@EH@% sequential ASCII characters. For example, the regular expression %@AS@%[0-9]%@AE@% matches any digit; it is equivalent to %@AS@%[0123456789]%@AE@%. Similarly, %@AS@%[a-z]%@AE@% matches any lowercase letter, and %@AS@%[A-Z]%@AE@% matches any uppercase letter.%@NL@% %@NL@% %@CR:MCVa4102@%%@4@%You can combine ASCII ranges of characters with other listed characters. For%@EH@% example, %@AS@%[A-Za-z ]%@AE@% matches any uppercase or lowercase letter or a space.%@NL@% %@NL@% %@CR:MCVa4103@%%@4@%The dash has this special meaning only if you use it to separate two ASCII%@EH@% characters. It has no special meaning if used directly after the starting bracket or directly before the ending bracket. This means you must be careful where you place the dash (minus sign) within brackets.%@NL@% %@NL@% %@CR:MCVa4104@%%@4@%For example, you might use the regular expression %@AS@%[+-/*]%@AE@% to match the%@EH@% characters %@AS@%+%@AE@%, %@AS@%-%@AE@%, %@AS@%/%@AE@%, and %@AS@%*%@AE@%. However, this does not give the intended result. Instead it matches the characters between %@AS@%+%@AE@% and %@AS@%/%@AE@% and also the character %@AS@%*%@AE@%. To specify the intended characters, put the dash first or last in the list: %@AS@%[-+/*]%@AE@% or %@AS@%[+/*-]%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVa4200@%%@3@%%@AB@%A.4.2 Using the Caret within Brackets%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVa4201@%%@4@%If used as the first character within brackets, the caret (%@AB@%^%@AE@%) reverses the%@EH@% meaning of the brackets. That is, any character except the ones in brackets is matched. For example, the regular expression %@AS@%[^0-9]%@AE@% matches any character that is not a digit. Specifying the characters to be excluded is often more concise than specifying the characters you want to match.%@NL@% %@NL@% %@CR:MCVa4202@%%@4@%If the caret is not in the first position within the brackets, it is treated%@EH@% as an ordinary character. For example, the expression %@AS@%[0-9^]%@AE@% matches any digit or a caret.%@NL@% %@NL@% %@NL@% %@CR:MCVa4300@%%@3@%%@AB@%A.4.3 Matching Brackets within Brackets%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVa4301@%%@4@%Sometimes you may want to specify the bracket characters as characters to be%@EH@% matched. This is no problem with the left bracket; it is treated as a normal character. However, the right bracket is interpreted as the end of the character list rather than as a character to be matched.%@NL@% %@NL@% %@CR:MCVa4302@%%@4@%If you want the right bracket to be matched, you must make it the first%@EH@% character after the initial left bracket. For example, the regular expression %@AS@%[]#![@%]%@AE@% matches either bracket character or any of the other characters listed within the brackets. However, if you changed the order of just one of the characters (to %@AS@%[#]![@%]%@AE@%), the meaning would be changed so that you would be specifying two groups of characters in brackets: %@AS@%[#]%@AE@% and %@AS@%[@%]%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVa5000@%%@2@%%@AB@%A.5 Using the Asterisk%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVa5001@%%@4@%The asterisk matches zero or more occurrences of the character preceding the%@EH@% asterisk.%@NL@% %@NL@% %@CR:MCVa5002@%%@4@%For example, the regular expression %@AS@%IF * TEST%@AE@% matches any number of%@EH@% repetitions of the space character that follow the word "%@AS@%if%@AE@%."%@NL@% %@NL@% IF TEST%@NL@% IF TEST%@NL@% IF TEST%@NL@% IFTEST%@NL@% %@NL@% %@CR:MCVa5003@%%@4@%Notice that the last example contains zero repetitions of the space%@EH@% character.%@NL@% %@NL@% %@CR:MCVa5004@%%@4@%The asterisk is convenient if the text you are searching for might contain%@EH@% some spaces, but you don't know the exact number. (Be careful in this situation: you can't be sure if the text contains a series of spaces or a tab.)%@NL@% %@NL@% %@CR:MCVa5005@%%@4@%You might also use the asterisk to search for a symbol when you aren't sure%@EH@% of the spelling. For example, you could use %@AS@%first*ime%@AE@% if you aren't sure if the identifier you are searching for is spelled %@AS@%firsttime%@AE@% or %@AS@%firstime%@AE@%.%@NL@% %@NL@% %@CR:MCVa5006@%%@4@%One particularly powerful use of the asterisk is to combine it with the%@EH@% period (%@AB@%.%@AE@%*). This combination searches for any group of characters. It is similar to the asterisk used in specifying DOS file names. For example, the expression %@AS@%(.*)%@AE@% matches %@AS@%(test)%@AE@%, %@AS@%(response .EQ. 'Y')%@AE@%, %@AS@%(x=0;x .LE. 20;x=x+1)%@AE@%, or any other string that starts with a left parenthesis and ends with a right parenthesis.%@NL@% %@NL@% %@CR:MCVa5007@%%@4@%You can use brackets with the asterisk to search for a sequence of repeated%@EH@% characters of a given type. For example, %@AS@%\[[0-9]*]%@AE@% matches number strings within brackets (%@AS@%[1353]%@AE@% or %@AS@%[3]%@AE@%), but does not match character strings within brackets (%@AS@%[count]%@AE@%). Empty brackets (%@AS@%[%@AE@%%@AS@%]%@AE@%) are also matched since the characters in the brackets are repeated zero times.%@AS@%%@NL@% %@NL@% %@NL@% %@CR:MCVa6000@%%@2@%%@AB@%A.6 Matching the Start or End of a Line%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVa6001@%%@4@%In regular expressions, the caret (%@AB@%^%@AE@%) matches the start of a line, and the%@EH@% dollar sign (%@AB@%$%@AE@%) matches the end of a line.%@NL@% %@NL@% %@CR:MCVa6002@%%@4@%For example, the regular expression %@AS@%^C%@AE@% matches any uppercase C that starts a%@EH@% line. Similarly, %@AS@%)$%@AE@% matches a right parenthesis at the end of a line, but not a right parenthesis within a line.%@NL@% %@NL@% %@CR:MCVa6003@%%@4@%You can combine both symbols to search for entire lines. For example, %@AS@%^{$%@AE@%%@EH@% matches any line consisting of only a left curly brace in the left margin and %@AS@%^$%@AE@% matches blank lines.%@NL@% %@NL@% %@NL@% %@CR:MCVb0000@%%@1@%%@AB@%Appendix B Using Exit Codes%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVb0001@%%@4@%Most utilities return an exit code (sometimes called an "errorlevel" code)%@EH@% used by DOS batch files or other programs. If the program finishes without errors, it returns an exit code 0. The code varies if the program encounters an error.%@NL@% %@NL@% %@NL@% %@CR:MCVb1000@%%@2@%%@AB@%B.1 Exit Codes with NMAKE%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVb1001@%%@4@%The NMAKE stops execution if a program executed by one of the commands in%@EH@% the NMAKE description file encounters an error. (Invoke NMAKE with the /I option to disable this behavior for the entire description file, or place a minus sign (-) in front of a command to disable it only for that command.) The exit code returned by the program is displayed as part of the error message.%@NL@% %@NL@% %@CR:MCVb1002@%%@4@%Assume the NMAKE description file %@AS@%TEST%@AE@% contains the following lines:%@EH@%%@NL@% %@NL@% TEST.OBJ : TEST.FOR%@NL@% FL /c TEST.FOR%@NL@% %@NL@% %@CR:MCVb1003@%%@4@%If the source code in %@AS@%TEST.FOR%@AE@% contains a program error (but not if it%@EH@% contains a warning error), you would see the following message the first time you use NMAKE with the NMAKE description file %@AS@%TEST%@AE@%:%@NL@% %@NL@% "nmake: CL /c TEST.FOR - error 2"%@NL@% %@NL@% %@CR:MCVb1004@%%@4@%This error message indicates that the command %@AS@%CL /c TEST.FOR%@AE@% in the NMAKE%@EH@% description file returned exit code 2.%@NL@% %@NL@% %@CR:MCVb1005@%%@4@%You can also test exit codes in NMAKE description files with the %@AB@%!IF%@AE@%%@EH@% directive.%@NL@% %@NL@% %@NL@% %@CR:MCVb2000@%%@2@%%@AB@%B.2 Exit Codes with DOS Batch Files%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVb2001@%%@4@%If you prefer to use DOS batch files instead of NMAKE description files, you%@EH@% can test the code returned with the IF command. The following sample batch file, called %@AS@%COMPILE.BAT%@AE@%, illustrates how to do this:%@NL@% %@NL@% CL /c %1%@NL@% IF NOT ERRORLEVEL 1 LINK %1;%@NL@% IF NOT ERRORLEVEL 1 %1%@NL@% %@NL@% %@CR:MCVb2002@%%@4@%You can execute this sample batch file with the following command:%@EH@%%@NL@% %@NL@% COMPILE TEST.C%@NL@% %@NL@% %@CR:MCVb2003@%%@4@%DOS then executes the first line of the batch file, substituting %@AS@%TEST.C%@AE@% for%@EH@% the parameter %@AS@%%1%@AE@%, as in the command line below.%@NL@% %@NL@% CL /c TEST.C%@NL@% %@NL@% %@CR:MCVb2004@%%@4@%It returns an exit code 0 if the compilation is successful or a higher code%@EH@% if the compiler encounters an error. In the second line, DOS tests to see if the code returned by the previous line is 1 or higher. If it is not (that is, if the code is 0), DOS executes the following command:%@NL@% %@NL@% LINK TEST;%@NL@% %@NL@% %@CR:MCVb2005@%%@4@%LINK also returns a code that is tested by the third line.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCVb3000@%%@2@%%@AB@%B.3 Exit Codes for Programs%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVb3001@%%@4@%An exit code 0 always indicates execution of the program with no fatal%@EH@% errors. Warning errors also return exit code 0. NMAKE can return several codes indica-ting different kinds of errors; other programs return only one code. The exit codes for each program are listed in Sections B.3.1%@BO: d5edc@%-B.3.4.%@NL@% %@NL@% %@NL@% %@CR:MCVb3100@%%@3@%%@AB@%B.3.1 LINK Exit Codes%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVb3101@%%@NL@%%@AU@%Code Meaning%@AE@%%@NL@% %@NL@% 0 No error.%@NL@% %@NL@% 2 Program error. Commands or files given as input%@NL@% to the linker produced the error.%@NL@% %@NL@% 4 System error. The linker encountered one of the%@NL@% following problems: 1) ran out of space on output%@NL@% files; 2) was unable to reopen the temporary%@NL@% file; 3) experienced an internal error; 4) was%@NL@% interrupted by the user.%@NL@% %@NL@% %@NL@% %@NL@% %@CR:MCVb3200@%%@3@%%@AB@%B.3.2 LIB Exit Codes%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVb3201@%%@AU@%Code Meaning%@AE@%%@NL@% %@NL@% 0 No error.%@NL@% %@NL@% 2 Program error. Commands or files given as input%@NL@% to the utility produced the error.%@NL@% %@NL@% 4 System error. The library manager encountered one%@NL@% of the following problems: 1) ran out of memory;%@NL@% 2) experienced an internal error; 3) was%@NL@% interrupted by the user.%@NL@% %@NL@% %@NL@% %@CR:MCVb3300@%%@3@%%@AB@%B.3.3 NMAKE Exit Codes%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVb3301@%%@AU@%Code Meaning%@AE@%%@NL@% %@NL@% 0 No error%@NL@% %@NL@% 2 Program error%@NL@% %@NL@% 4 System error──out of memory%@NL@% %@NL@% %@NL@% %@CR:MCVb3302@%%@4@%If a program called by a command in the NMAKE description file produces an%@EH@% error, the exit code is displayed in the NMAKE error message.%@NL@% %@NL@% %@NL@% %@CR:MCVb3400@%%@3@%%@AB@%B.3.4 EXEMOD and SETENV Exit Codes%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVb3401@%%@AU@%Code Meaning%@AE@%%@NL@% %@NL@% 0 No error.%@NL@% %@NL@% 2 Program error. Commands or files given as input%@NL@% to the utility produced the error.%@NL@% %@NL@% 4 System error. The utility encountered one of the%@NL@% following problems: 1) ran out of memory; 2)%@NL@% experienced an internal error; 3) was interrupted%@NL@% by the user.%@NL@% %@NL@% %@NL@% %@CR:MCVb3500@%%@3@%%@AB@%B.3.5 CVPACK Exit Codes%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVb3501@%%@AU@%Code Meaning%@AE@%%@NL@% %@NL@% 0 No error.%@NL@% %@NL@% 1 Program error. Commands or files given as%@NL@% input to the utility produced the error.%@NL@% %@NL@% %@CR:MCVc0000@%%@1@%%@AB@%Appendix C Error Messages%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@NL@% %@CR:MCVc1000@%%@2@%%@AB@%C.1 CodeView Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVc1001@%%@4@%The CodeView debugger displays an error message whenever it detects a%@EH@% command it cannot execute. Most errors (start-up errors are the exception) terminate the CodeView command under which the error occurred but do not terminate the debugger. You may see any of the following messages.%@NL@% %@NL@% %@CR:MCVcE001@%%@4@%%@AB@%? cannot display%@AE@%%@EH@%%@NL@% %@NL@% The Display Expression command (%@AB@%?%@AE@%) has been passed a valid symbol%@NL@% it cannot display. A variable with enumeration type cannot be%@NL@% displayed.%@NL@% %@NL@% %@CR:MCVcE002@%%@4@%%@AB@%Argument to IMAG/DIMAG must be simple type%@AE@%%@EH@%%@NL@% %@NL@% You specified an argument to an %@AB@%IMAG%@AE@% or %@AB@%DIMAG%@AE@% function not%@NL@% permitted, such as an array with no subscripts.%@NL@% %@NL@% %@CR:MCVcE003@%%@4@%%@AB@%Array must have subscript%@AE@%%@EH@%%@NL@% %@NL@% You specified an array without any subscripts in an expression,%@NL@% such as %@AS@%IARRAY+2%@AE@%. A correct example would be %@AS@%IARRAY[1]+2%@AE@%.%@NL@% %@NL@% %@CR:MCVcE004@%%@4@%%@AB@%Bad address%@AE@%%@EH@%%@NL@% %@NL@% You specified an address in an invalid form.%@NL@% %@NL@% For instance, you may have entered an address containing%@NL@% hexadecimal characters when the radix is decimal.%@NL@% %@NL@% %@CR:MCVcE005@%%@4@%%@AB@%Bad breakpoint command%@AE@%%@EH@%%@NL@% %@NL@% You typed an invalid breakpoint number with the Breakpoint Clear,%@NL@% Breakpoint Disable, or Breakpoint Enable command.%@NL@% %@NL@% The number must be in the range 0 to 19.%@NL@% %@NL@% %@CR:MCVcE006@%%@4@%%@AB@%Bad emulator info%@AE@%%@EH@%%@NL@% %@NL@% The CodeView debugger cannot read data from the floating-point%@NL@% emulator.%@NL@% %@NL@% %@CR:MCVcE007@%%@4@%%@AB@%Bad flag%@AE@%%@EH@%%@NL@% %@NL@% You specified an invalid flag mnemonic with the Register dialog%@NL@% command (%@AB@%R%@AE@%).%@NL@% %@NL@% Use one of the mnemonics displayed when you enter the command %@AB@%RF%@AE@%.%@NL@% %@NL@% %@CR:MCVcE008@%%@4@%%@AB@%Bad format string%@AE@%%@EH@%%@NL@% %@NL@% You used an invalid format specifier following an expression.%@NL@% %@NL@% Expressions used with the Display Expression, Watch, Watchpoint,%@NL@% and Tracepoint commands can have CodeView format specifiers set%@NL@% off from the expression by a comma. The valid format specifiers%@NL@% are %@AB@%c%@AE@%, %@AB@%d%@AE@%, %@AB@%e%@AE@%, %@AB@%E%@AE@%, %@AB@%f%@AE@%, %@AB@%g%@AE@%, %@AB@%G%@AE@%, %@AB@%i%@AE@%, %@AB@%o%@AE@%, %@AB@%s%@AE@%, %@AB@%u%@AE@%, %@AB@%x%@AE@%, %@AB@%X%@AE@%. Some format specifiers%@NL@% can be preceded by the prefix %@AB@%h%@AE@% or %@AB@%l%@AE@%. See the Display Expression%@NL@% command for more information about format specifiers.%@NL@% %@NL@% %@CR:MCVcE009@%%@4@%%@AB@%Bad integer or real constant%@AE@%%@EH@%%@NL@% %@NL@% You specified an illegal numeric constant in an expression.%@NL@% %@NL@% %@CR:MCVcE010@%%@4@%%@AB@%Bad intrinsic function%@AE@%%@EH@%%@NL@% %@NL@% You specified an illegal intrinsic function name in an expression.%@NL@% %@NL@% %@CR:MCVcE011@%%@4@%%@AB@%Bad radix (use 8, 10, or 16)%@AE@%%@EH@%%@NL@% %@NL@% With the %@AB@%N%@AE@% command, you can use only octal, decimal, and%@NL@% hexadecimal radixes.%@NL@% %@NL@% %@CR:MCVcE012@%%@4@%%@AB@%Bad register%@AE@%%@EH@%%@NL@% %@NL@% You typed the Register command (%@AB@%R%@AE@%) with an invalid register name.%@NL@% %@NL@% Use %@AB@%AX%@AE@%, %@AB@%BX%@AE@%, %@AB@%CX%@AE@%, %@AB@%DX%@AE@%, %@AB@%SP%@AE@%, %@AB@%BP%@AE@%, %@AB@%SI%@AE@%, %@AB@%DI%@AE@%, %@AB@%DS%@AE@%, %@AB@%ES%@AE@%, %@AB@%SS%@AE@%, %@AB@%CS%@AE@%, %@AB@%IP%@AE@%, or %@AB@%F%@AE@%.%@NL@% %@NL@% %@CR:MCVcE013@%%@4@%%@AB@%Bad subscript%@AE@%%@EH@%%@NL@% %@NL@% You entered an illegal subscript expression for an array, such as%@NL@% %@AS@%IARRAY(3.3)%@AE@% or %@AS@%IARRAY((3,3))%@AE@%. The correct expression for this%@NL@% example (in BASIC or FORTRAN) is %@AS@%IARRAY(3,3)%@AE@%.%@NL@% %@NL@% %@CR:MCVcE014@%%@4@%%@AB@%Bad type case%@AE@%%@EH@%%@NL@% %@NL@% The types of the operands in an expression are incompatible.%@NL@% %@NL@% %@CR:MCVcE015@%%@4@%%@AB@%Bad type (use one of 'ABDILSTUW')%@AE@%%@EH@%%@NL@% %@NL@% The valid dump types are ASCII (%@AB@%A%@AE@%), Byte (%@AB@%B%@AE@%), Double Word (%@AB@%D%@AE@%),%@NL@% Integer (%@AB@%I%@AE@%), Long Real (%@AB@%L%@AE@%), Short Real (%@AB@%S%@AE@%), 10-Byte Real (%@AB@%T%@AE@%),%@NL@% Unsigned (%@AB@%U%@AE@%), and Word (%@AB@%W%@AE@%).%@NL@% %@NL@% %@CR:MCVcE016@%%@4@%%@AB@%Badly formed type%@AE@%%@EH@%%@NL@% %@NL@% The type information in the symbol table of the file you are%@NL@% debugging is incorrect.%@NL@% %@NL@% If the message occurs, please note the circumstances of the error%@NL@% and inform Microsoft Corporation by following the directions in%@NL@% the Microsoft Product Assistance Request form at the back of one%@NL@% of your manuals.%@NL@% %@NL@% %@CR:MCVcE017@%%@4@%%@AB@%Breakpoint # or '*' expected%@AE@%%@EH@%%@NL@% %@NL@% You entered the Breakpoint Clear (%@AB@%BC%@AE@%), Breakpoint Disable (%@AB@%BD%@AE@%), or%@NL@% Breakpoint Enable (%@AB@%BE%@AE@%) command with no argument.%@NL@% %@NL@% These commands require that you specify the number of the%@NL@% breakpoint to be acted on, or that you specify the asterisk (%@AB@%*%@AE@%)%@NL@% indicating that all breakpoints are to be acted on.%@NL@% %@NL@% %@CR:MCVcE018@%%@4@%%@AB@%Cannot use struct or union as scalar%@AE@%%@EH@%%@NL@% %@NL@% A struct or union variable cannot be used as a scalar value in a C%@NL@% expression.%@NL@% %@NL@% Such variables must be followed by a file separator or preceded by%@NL@% the address of operator.%@NL@% %@NL@% %@CR:MCVcE019@%%@4@%%@AB@%Cannot cast complex constant component into REAL%@AE@%%@EH@%%@NL@% %@NL@% Both the real and imaginary components of a %@AB@%COMPLEX%@AE@% constant must%@NL@% be compatible with the type %@AB@%REAL%@AE@%.%@NL@% %@NL@% %@CR:MCVcE020@%%@4@%%@AB@%Cannot cast IMAG/DIMAG argument to COMPLEX%@AE@%%@EH@%%@NL@% %@NL@% Arguments to %@AB@%IMAG%@AE@% and %@AB@%DIMAG%@AE@% must be simple numeric types.%@NL@% %@NL@% %@CR:MCVcE021@%%@4@%%@AB@%Cannot find%@AE@% %@AI@%filename%@AE@%%@EH@%%@NL@% %@NL@% The CodeView debugger could not find the executable file you%@NL@% specified when you started.%@NL@% %@NL@% You may have misspelled the file name, or the file is in a%@NL@% different directory.%@NL@% %@NL@% %@CR:MCVcE022@%%@4@%%@AB@%Character constant too long%@AE@%%@EH@%%@NL@% %@NL@% You specified a character constant too long for the FORTRAN%@NL@% expression evaluator (the limit is 126 bytes).%@NL@% %@NL@% %@CR:MCVcE023@%%@4@%%@AB@%Character too big for current radix%@AE@%%@EH@%%@NL@% %@NL@% In a constant, you specified a radix that is larger than the%@NL@% current CodeView radix.%@NL@% %@NL@% Use the %@AB@%N%@AE@% command to change the radix.%@NL@% %@NL@% %@CR:MCVcE024@%%@4@%%@AB@%Constant too big%@AE@%%@EH@%%@NL@% %@NL@% The CodeView debugger cannot accept an unsigned constant number%@NL@% larger than 4,294,967,295 (16#FFFFFFFF).%@NL@% %@NL@% %@CR:MCVcE025@%%@4@%%@AB@%CPU not an 80386%@AE@%%@EH@%%@NL@% %@NL@% The 386 option cannot be selected if you are using a machine%@NL@% without an 80386 processor.%@NL@% %@NL@% %@CR:MCVcE026@%%@4@%%@AB@%Divide by zero%@AE@%%@EH@%%@NL@% %@NL@% An expression in an argument of a dialog command attempts to%@NL@% divide by zero.%@NL@% %@NL@% %@CR:MCVcE027@%%@4@%%@AB@%EMM error%@AE@%%@EH@%%@NL@% %@NL@% The debugger is failing to use EMM correctly. Please contact%@NL@% Microsoft Corporation by following the directions in the Microsoft%@NL@% Product Assistance Request form at the back of one of your%@NL@% manuals.%@NL@% %@NL@% %@CR:MCVcE028@%%@4@%%@AB@%EMM hardware error%@AE@%%@EH@%%@NL@% %@NL@% The Expanded Memory routines report a hardware error. Your%@NL@% expanded memory board may need replacement.%@NL@% %@NL@% %@CR:MCVcE029@%%@4@%%@AB@%EMM memory not found%@AE@%%@EH@%%@NL@% %@NL@% You tried to use the %@AB@%/E%@AE@% option without having installed expanded%@NL@% memory. You must make this installation with software that%@NL@% accesses the memory according to the Lotus/Intel/Microsoft EMS%@NL@% specification.%@NL@% %@NL@% %@CR:MCVcE030@%%@4@%%@AB@%EMM software error%@AE@%%@EH@%%@NL@% %@NL@% The Expanded Memory routines report a software error. Reinstall%@NL@% EMM software.%@NL@% %@NL@% %@CR:MCVcE031@%%@4@%%@AB@%Expression not a memory address%@AE@%%@EH@%%@NL@% %@NL@% A Tracepoint command was given without a symbol that evaluates to%@NL@% a single memory address.%@NL@% %@NL@% For example, the commands %@AS@%TP?1%@AE@% and %@AS@%TP?a+b%@AE@% each produce this error%@NL@% message. The proper way to put a tracepoint on the word at address%@NL@% 1 is with the command %@AS@%TPW 1%@AE@%.%@NL@% %@NL@% %@CR:MCVcE032@%%@4@%%@AB@%Expression too complex%@AE@%%@EH@%%@NL@% %@NL@% An expression given as a dialog-command argument is too complex.%@NL@% %@NL@% Try simplifying the expression.%@NL@% %@NL@% %@CR:MCVcE033@%%@4@%%@AB@%Extra input ignored%@AE@%%@EH@%%@NL@% %@NL@% You specified too many arguments to a command.%@NL@% %@NL@% The CodeView debugger evaluates the valid arguments and ignores%@NL@% the rest. Often in this situation the debugger does not evaluate%@NL@% the arguments in the way you intended.%@NL@% %@NL@% %@CR:MCVcE034@%%@4@%%@AB@%Flip/Swap option off - application output lost%@AE@%%@EH@%%@NL@% %@NL@% The program you are debugging is writing to the screen, but the%@NL@% output cannot be displayed because you have turned off the%@NL@% flip/swap option.%@NL@% %@NL@% %@CR:MCVcE035@%%@4@%%@AB@%Floating point error%@AE@%%@EH@%%@NL@% %@NL@% This message should not occur, but if it does, please note the%@NL@% circumstances of the error and inform Microsoft Corporation by%@NL@% following the directions in the Microsoft Product Assistance%@NL@% Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE036@%%@4@%%@AB@%Floating point not loaded%@AE@%%@EH@%%@NL@% %@NL@% This message occurs when the current thread has not initialized%@NL@% its own emulator. Each thread has its own floating-point emulator.%@NL@% %@NL@% %@CR:MCVcE037@%%@4@%%@AB@%Function call before 'main'%@AE@%%@EH@%%@NL@% %@NL@% This message occurs when you attempt to evaluate a program-defined%@NL@% function before you have entered the main function.%@NL@% %@NL@% Execute at least to the beginning of the main function before%@NL@% attempting to evaluate program-defined functions.%@NL@% %@NL@% %@CR:MCVcE038@%%@4@%%@AB@%Illegal instruction%@AE@%%@EH@%%@NL@% %@NL@% This message usually indicates that a divide-by-zero machine%@NL@% instruction was attempted.%@NL@% %@NL@% %@CR:MCVcE039@%%@4@%%@AB@%Index out of bound%@AE@%%@EH@%%@NL@% %@NL@% You specified a subscript value outside the bounds declared for%@NL@% the array.%@NL@% %@NL@% %@CR:MCVcE040@%%@4@%%@AB@%Insufficient EMM memory%@AE@%%@EH@%%@NL@% %@NL@% Not enough expanded memory is available to hold the program's%@NL@% symbol table.%@NL@% %@NL@% %@CR:MCVcE041@%%@4@%%@AB@%Internal debugger error%@AE@%%@EH@%%@NL@% %@NL@% If this message occurs, please note the circumstances of the error%@NL@% and notify Microsoft Corporation by following the directions in%@NL@% the Microsoft Product Assistance Request form at the back of one%@NL@% of your manuals.%@NL@% %@NL@% %@CR:MCVcE042@%%@4@%%@AB@%Invalid argument%@AE@%%@EH@%%@NL@% %@NL@% One of the arguments you specified is not a valid CodeView%@NL@% expression.%@NL@% %@NL@% %@CR:MCVcE043@%%@4@%%@AB@%Invalid executable file format - please relink%@AE@%%@EH@%%@NL@% %@NL@% The executable file was not linked with the version of the linker%@NL@% released with this version of the CodeView debugger. Relink with%@NL@% the more current version of the linker.%@NL@% %@NL@% %@CR:MCVcE044@%%@4@%%@AB@%Invalid option%@AE@%%@EH@%%@NL@% %@NL@% The option specified cannot be used with the CodeView Option%@NL@% command.%@NL@% %@NL@% %@CR:MCVcE045@%%@4@%%@AB@%Missing '"'%@AE@%%@EH@%%@NL@% %@NL@% You specified a string as an argument to a dialog command, but you%@NL@% did not supply a closing double quotation mark.%@NL@% %@NL@% %@CR:MCVcE046@%%@4@%%@AB@%Missing '('%@AE@%%@EH@%%@NL@% %@NL@% An argument to a dialog command was specified as an expression%@NL@% containing a right parenthesis, but no left parenthesis.%@NL@% %@NL@% %@CR:MCVcE047@%%@4@%%@AB@%Missing ')'%@AE@%%@EH@%%@NL@% %@NL@% An argument to a dialog command was specified as an expression%@NL@% containing a left parenthesis, but no right parenthesis.%@NL@% %@NL@% %@CR:MCVcE048@%%@4@%%@AB@%Missing ']'%@AE@%%@EH@%%@NL@% %@NL@% An argument to a dialog command was specified as an expression%@NL@% containing a left bracket, but no right bracket.%@NL@% %@NL@% This error message can also occur if a regular expression is%@NL@% specified with a right bracket but no left bracket.%@NL@% %@NL@% %@CR:MCVcE049@%%@4@%%@AB@%Missing '(' in complex constant%@AE@%%@EH@%%@NL@% %@NL@% The debugger is expecting an opening parenthesis of a complex%@NL@% constant in an expression, but it is missing.%@NL@% %@NL@% %@CR:MCVcE050@%%@4@%%@AB@%Missing ')' in complex constant%@AE@%%@EH@%%@NL@% %@NL@% The debugger expects a closing parenthesis of a complex constant%@NL@% in an expression.%@NL@% %@NL@% %@CR:MCVcE051@%%@4@%%@AB@%Missing ')' in substring%@AE@%%@EH@%%@NL@% %@NL@% The debugger expects a closing parenthesis of a substring%@NL@% expression.%@NL@% %@NL@% %@CR:MCVcE052@%%@4@%%@AB@%Missing '(' to intrinsic%@AE@%%@EH@%%@NL@% %@NL@% The debugger expects an opening parenthesis for an intrinsic%@NL@% function.%@NL@% %@NL@% %@CR:MCVcE053@%%@4@%%@AB@%Missing ')' to intrinsic%@AE@%%@EH@%%@NL@% %@NL@% The debugger expects a closing parenthesis for an intrinsic%@NL@% function.%@NL@% %@NL@% %@CR:MCVcE054@%%@4@%%@AB@%No closing single quote%@AE@%%@EH@%%@NL@% %@NL@% You specified a character in an expression used as a%@NL@% dialog-command argument, but the closing single quotation mark is%@NL@% missing.%@NL@% %@NL@% %@CR:MCVcE055@%%@4@%%@AB@%No code at this line number%@AE@%%@EH@%%@NL@% %@NL@% You tried to set a breakpoint on a source line that does not%@NL@% correspond to machine code. (In other words, the source line does%@NL@% not contain an executable statement.)%@NL@% %@NL@% For instance, the line may be a data declaration or a comment.%@NL@% %@NL@% %@CR:MCVcE056@%%@4@%%@AB@%No free EMM memory handles%@AE@%%@EH@%%@NL@% %@NL@% The debugger cannot find an available handle. EMM software%@NL@% allocates a fixed number of memory handles (usually 256) to be%@NL@% used for specific tasks.%@NL@% %@NL@% %@CR:MCVcE057@%%@4@%%@AB@%No match of regular expression%@AE@%%@EH@%%@NL@% %@NL@% No match was found for the regular expression you specified with%@NL@% the Search command or with the Find selection from the Search%@NL@% menu.%@NL@% %@NL@% %@CR:MCVcE058@%%@4@%%@AB@%No previous regular expression%@AE@%%@EH@%%@NL@% %@NL@% You selected Previous from the Search menu, but there was no%@NL@% previous match for the last regular expression specified.%@NL@% %@NL@% %@CR:MCVcE059@%%@4@%%@AB@%No source lines at this address%@AE@%%@EH@%%@NL@% %@NL@% The address you specified as an argument for the View command (%@AB@%V%@AE@%)%@NL@% does not have any source lines.%@NL@% %@NL@% For instance, it could be an address in a library routine or an%@NL@% assembly-language module.%@NL@% %@NL@% %@CR:MCVcE060@%%@4@%%@AB@%No such file/directory%@AE@%%@EH@%%@NL@% %@NL@% A file specified in a command argument or in response to a prompt%@NL@% does not exist.%@NL@% %@NL@% For instance, the message appears when you select Load from the%@NL@% File menu and then enter the name of a nonexistent file.%@NL@% %@NL@% %@CR:MCVcE061@%%@4@%%@AB@%No symbolic information = CV options not used or wrong LINK version%@AE@%%@EH@%%@NL@% %@NL@% The program file you specified is not in the CodeView format.%@NL@% %@NL@% You cannot debug in source mode unless you recreate the file in%@NL@% CodeView format. However, you can debug in assembly mode.%@NL@% %@NL@% %@CR:MCVcE062@%%@4@%%@AB@%Not a text file%@AE@%%@EH@%%@NL@% %@NL@% You attempted to load a file by using the Load selection from the%@NL@% File menu or using the View command, but the file is not a text%@NL@% file.%@NL@% %@NL@% The CodeView debugger determines if a file is a text file by%@NL@% checking the first 128 bytes for characters that are not in the%@NL@% ASCII ranges 9 to 13 and 20 to 126.%@NL@% %@NL@% %@CR:MCVcE063@%%@4@%%@AB@%Not an executable file%@AE@%%@EH@%%@NL@% %@NL@% The file you specified to be debugged when you started the%@NL@% CodeView debugger is not an executable file having the extension%@NL@% %@AB@%.EXE%@AE@% or %@AB@%.COM%@AE@%.%@NL@% %@NL@% %@CR:MCVcE064@%%@4@%%@AB@%Not enough space%@AE@%%@EH@%%@NL@% %@NL@% You typed the Shell Escape command (%@AB@%!%@AE@%) or selected Shell from the%@NL@% File menu, but there is not enough free memory to execute%@NL@% %@AB@%COMMAND.COM%@AE@%.%@NL@% %@NL@% Since memory is released by code in the FORTRAN start-up routines,%@NL@% this error always occurs if you try to use the Shell Escape%@NL@% command before you have executed any code. Use any of the%@NL@% code-execution commands (Trace, Program Step, or Go) to execute%@NL@% the FORTRAN start-up code, then try the Shell Escape command%@NL@% again. The message also occurs with assembly-language programs%@NL@% that do not specifically release memory.%@NL@% %@NL@% %@CR:MCVcE065@%%@4@%%@AB@%Object too big%@AE@%%@EH@%%@NL@% %@NL@% You entered a Tracepoint command with a data object (such as an%@NL@% array) larger than 128 bytes.%@NL@% %@NL@% %@CR:MCVcE066@%%@4@%%@AB@%Operand types incorrect for this operation%@AE@%%@EH@%%@NL@% %@NL@% An operand in a FORTRAN expression had a type incompatible with%@NL@% the operation applied to it.%@NL@% %@NL@% For example, if %@AS@%P%@AE@% is declared as %@AS@%CHARACTER P(10)%@AE@%, the %@AS@%? P+5%@AE@% would%@NL@% produce this error, since a character array cannot be an operand%@NL@% of an arithmetic operator.%@NL@% %@NL@% %@CR:MCVcE067@%%@4@%%@AB@%Operator must have a struct\union type%@AE@%%@EH@%%@NL@% %@NL@% You have used one of the C member-selection operators (-, >, or .)%@NL@% in an expression that does not reference an element of a structure%@NL@% or union.%@NL@% %@NL@% %@CR:MCVcE068@%%@4@%%@AB@%Operator needs lvalue%@AE@%%@EH@%%@NL@% %@NL@% You specified an expression that does not evaluate to a memory%@NL@% location in an operation that requires one. (An lvalue is an%@NL@% expression that refers to a memory location.)%@NL@% %@NL@% For example, %@AS@%buffer(count)%@AE@% is correct because it represents a%@NL@% symbol in memory. However, %@AS@%I .EQV. 10%@AE@% is invalid because it%@NL@% evaluates to TRUE or FALSE instead of to a single memory location.%@NL@% %@NL@% %@CR:MCVcE069@%%@4@%%@AB@%Overlay not resident%@AE@%%@EH@%%@NL@% %@NL@% You tried to unassemble machine code from a function that is%@NL@% currently not in memory.%@NL@% %@NL@% %@CR:MCVcE070@%%@4@%%@AB@%Program terminated normally (%@AE@%%@AI@%number%@AE@%%@AB@%)%@AE@%%@EH@%%@NL@% %@NL@% You executed your program to the end. The number displayed in%@NL@% parentheses is the exit code returned to DOS by your program.%@NL@% %@NL@% You must use the Restart command (or the Start menu selection) to%@NL@% start the program before executing more code.%@NL@% %@NL@% %@CR:MCVcE071@%%@4@%%@AB@%Radix must be between 2 and 36 inclusive%@AE@%%@EH@%%@NL@% %@NL@% You specified a radix outside the allowable range.%@NL@% %@NL@% %@CR:MCVcE072@%%@4@%%@AB@%Register variable out of scope%@AE@%%@EH@%%@NL@% %@NL@% You tried to specify a register variable by using the period (%@AB@%.%@AE@%)%@NL@% operator and a routine name.%@NL@% %@NL@% For example, if you are in a third-level routine, you can display%@NL@% the value of a local variable called %@AS@%local%@AE@% in a second-level%@NL@% routine called %@AS@%parent%@AE@% with the following command:%@NL@% %@NL@% ? parent.local%@NL@% %@NL@% However, this command will not work if %@AS@%local%@AE@% is declared as a%@NL@% register variable.%@NL@% %@NL@% %@CR:MCVcE073@%%@4@%%@AB@%Regular expression too complex%@AE@%%@EH@%%@NL@% %@NL@% The regular expression specified is too complex for the CodeView%@NL@% debugger to evaluate.%@NL@% %@NL@% %@CR:MCVcE074@%%@4@%%@AB@%Regular expression too long%@AE@%%@EH@%%@NL@% %@NL@% The regular expression specified is too long for the CodeView%@NL@% debugger to evaluate.%@NL@% %@NL@% %@CR:MCVcE075@%%@4@%%@AB@%Restart program to debug%@AE@%%@EH@%%@NL@% %@NL@% You have executed to the end of the program you are debugging.%@NL@% %@NL@% %@CR:MCVcE076@%%@4@%%@AB@%Simple variable cannot have argument%@AE@%%@EH@%%@NL@% %@NL@% In an expression, you specified an argument to a simple variable.%@NL@% %@NL@% For example, given the declaration %@AS@%INTEGER NUM%@AE@%, the expression%@NL@% %@AS@%NUM(I)%@AE@% is not allowed.%@NL@% %@NL@% %@CR:MCVcE077@%%@4@%%@AB@%Substring range out of bound%@AE@%%@EH@%%@NL@% %@NL@% A character expression exceeds the length specified in the%@NL@% %@AB@%CHARACTER%@AE@% statement.%@NL@% %@NL@% %@CR:MCVcE078@%%@4@%%@AB@%Syntax error%@AE@%%@EH@%%@NL@% %@NL@% You specified an invalid command line for a dialog command.%@NL@% %@NL@% Check for an invalid command letter. This message also appears if%@NL@% you enter an invalid assembly-language instruction using the%@NL@% Assembly command. The error is preceded by a caret that points to%@NL@% the first character the CodeView debugger could not interpret.%@NL@% %@NL@% %@CR:MCVcE079@%%@4@%%@AB@%Too few array bounds given%@AE@%%@EH@%%@NL@% %@NL@% The bounds that you specified in an array subscript do not match%@NL@% the array declaration.%@NL@% %@NL@% For example, given the array declaration %@AS@%INTEGER IARRAY(3,4)%@AE@%, the%@NL@% expression %@AS@%IARRAY(I)%@AE@% would produce this error message.%@NL@% %@NL@% %@CR:MCVcE080@%%@4@%%@AB@%Too many array bounds given%@AE@%%@EH@%%@NL@% %@NL@% The bounds that you specified in an array subscript do not match%@NL@% the array declaration.%@NL@% %@NL@% For example, given the array declaration %@AS@%INTEGER IARRAY(3,4)%@AE@%, the%@NL@% expression %@AS@%IARRAY(I,3,J)%@AE@% would produce this error message.%@NL@% %@NL@% %@CR:MCVcE081@%%@4@%%@AB@%Too many breakpoints%@AE@%%@EH@%%@NL@% %@NL@% You tried to specify a 21st breakpoint; the CodeView debugger%@NL@% permits only 20.%@NL@% %@NL@% %@CR:MCVcE082@%%@4@%%@AB@%Too many open files%@AE@%%@EH@%%@NL@% %@NL@% You do not have enough file handles for the CodeView debugger to%@NL@% operate correctly.%@NL@% %@NL@% You must specify more files in your %@AB@%CONFIG.SYS%@AE@% file. See the DOS%@NL@% user's guide for information on using the %@AB@%CONFIG.SYS%@AE@% file.%@NL@% %@NL@% %@CR:MCVcE083@%%@4@%%@AB@%Type clash in function argument%@AE@%%@EH@%%@NL@% %@NL@% The type of an actual parameter does not match the corresponding%@NL@% formal parameter.%@NL@% %@NL@% This message also appears when a subroutine that uses alternate%@NL@% returns is called and the values of the return labels in the%@NL@% actual parameter list are not 0.%@NL@% %@NL@% %@CR:MCVcE084@%%@4@%%@AB@%Type conversion too complex%@AE@%%@EH@%%@NL@% %@NL@% You tried to type cast an element of an expression in a type other%@NL@% than the simple types or with more than one level of indirection.%@NL@% %@NL@% An example of a complex type would be type casting to a struct or%@NL@% union type. An example of two levels of indirection is %@AS@%char **%@AE@%.%@NL@% %@NL@% %@CR:MCVcE085@%%@4@%%@AB@%Unable to open file%@AE@%%@EH@%%@NL@% %@NL@% A file you specified in a command argument or in response to a%@NL@% prompt cannot be opened.%@NL@% %@NL@% For instance, this message appears when you select Load from the%@NL@% File menu, and then enter the name of a file that is corrupted or%@NL@% has its file attributes set so that it cannot be opened.%@NL@% %@NL@% %@CR:MCVcE086@%%@4@%%@AB@%Unknown symbol%@AE@%%@EH@%%@NL@% %@NL@% You specified an identifier not in the CodeView debugger's symbol%@NL@% table.%@NL@% %@NL@% Check for a misspelling. This message may also occur if you try to%@NL@% use a local variable in an argument when you are not in the%@NL@% routine where the variable is defined. The message also occurs%@NL@% when a subroutine that uses alternate returns is called and the%@NL@% values of the return labels in the actual parameter list are not 0.%@NL@% %@NL@% %@CR:MCVcE087@%%@4@%%@AB@%Unrecognized option%@AE@% %@AI@%option%@AE@%%@EH@%%@NL@% %@AB@%Valid options: /B /C<%@AE@%%@AI@%command%@AE@%%@AB@%> /D /F /I /M /S /T /W /43 /2%@AE@%%@NL@% %@NL@% You entered an invalid option when starting the CodeView debugger.%@NL@% %@NL@% Try retyping the command line.%@NL@% %@NL@% %@CR:MCVcE088@%%@4@%%@AB@%Usage cv [%@AE@%%@AI@%options%@AE@%%@AB@%] file [%@AE@%%@AI@%arguments%@AE@%%@AB@%]%@AE@%%@EH@%%@NL@% %@NL@% You failed to specify an executable file when you started%@NL@% CodeView.%@NL@% %@NL@% Try again with the syntax shown in the message.%@NL@% %@NL@% %@CR:MCVcE089@%%@4@%%@AB@%Video mode changed without the /S option%@AE@%%@EH@%%@NL@% %@NL@% The program changed video modes (either to or from graphics modes)%@NL@% when screen swapping was not specified.%@NL@% %@NL@% You must use the %@AB@%/S%@AE@% option to specify screen swapping when%@NL@% debugging graphics programs. You can continue debugging when you%@NL@% get this message, but the output screen of the debugged program%@NL@% may be damaged.%@NL@% %@NL@% %@CR:MCVcE090@%%@4@%%@AB@%Warning: packed file%@AE@%%@EH@%%@NL@% %@NL@% You started the CodeView debugger with a packed file as the%@NL@% executable file.%@NL@% %@NL@% You can attempt to debug the program in assembly mode, but the%@NL@% packing routines at the start of the program may make this%@NL@% difficult. You cannot debug in source mode because all symbolic%@NL@% information is stripped from a file when it is packed with the%@NL@% %@AB@%/EXEPACK%@AE@% linker option.%@NL@% %@NL@% %@CR:MCVcE091@%%@4@%%@AB@%Wrong number of function arguments%@AE@%%@EH@%%@NL@% %@NL@% You specified an incorrect number of arguments when you tried to%@NL@% evaluate a function in a CodeView expression.%@NL@% %@NL@% %@NL@% %@CR:MCVc2000@%%@2@%%@AB@%C.2 LINK Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVc2001@%%@4@%This section lists and describes error messages generated by the Microsoft%@EH@% Segmented-Executable Linker, %@AB@%LINK%@AE@%.%@NL@% %@NL@% %@CR:MCVc2002@%%@4@%%@AB@%Fatal errors%@AE@% cause the linker to stop execution. Fatal error messages have%@EH@% the following format:%@NL@% %@NL@% %@AI@%location%@AE@%%@AS@%: error L1%@AE@%%@AI@%xxx%@AE@%%@AS@%:%@AE@%%@AI@% messagetext%@AE@%%@NL@% %@NL@% %@CR:MCVc2003@%%@4@%%@AB@%Nonfatal errors%@AE@% indicate problems in the executable file. LINK produces the%@EH@% executable file. Nonfatal error messages have the following format:%@NL@% %@NL@% %@AI@%location%@AE@% %@AS@%: error L2%@AE@%%@AI@%xxx%@AE@%%@AS@%:%@AE@%%@AI@%messagetext%@AE@%%@NL@% %@NL@% %@CR:MCVc2004@%%@4@%%@AB@%Warnings%@AE@% indicate possible problems in the executable file. LINK produces%@EH@% the executable file. Warnings have the following format:%@NL@% %@NL@% %@AI@%location%@AE@%%@AS@% : warning L4%@AE@%%@AI@%xxx%@AE@%%@AS@%:%@AE@%%@AI@%messagetext%@AE@%%@NL@% %@NL@% %@CR:MCVc2005@%%@4@%In all three kinds of messages, location is the input file associated with%@EH@% the error, or %@AS@%LINK%@AE@% if there is no input file. If the input file is an %@AB@%.OBJ%@AE@% or %@AB@%.LIB%@AE@% file and has a module name, the module name is enclosed in parentheses, as shown below.%@NL@% %@NL@% SLIBC.LIB(_file)%@NL@% MAIN.OBJ(main.c)%@NL@% TEXT.OBJ%@NL@% %@NL@% %@CR:MCVc2006@%%@4@%The following error messages may appear when you link object files with the%@EH@% Microsoft Segmented-Executable Linker, %@AB@%LINK%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVc2100@%%@3@%%@AB@%C.3.1 LINK Fatal Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE092@%%@4@%%@AB@%L1001%@AE@% %@AI@%option%@AE@%%@AB@% : option name ambiguous%@AE@%%@EH@%%@NL@% %@NL@% A unique option name did not appear after the option indicator%@NL@% (%@AB@%/%@AE@%). For example, the command%@NL@% %@NL@% LINK /N main;%@NL@% %@NL@% generates this error, since %@AB@%LINK%@AE@% cannot tell which of the options%@NL@% beginning with the letter "N" was intended.%@NL@% %@NL@% %@CR:MCVcE093@%%@4@%%@AB@%L1002%@AE@% %@AI@%option%@AE@%%@AB@% : unrecognized option name%@AE@%%@EH@%%@NL@% %@NL@% An unrecognized character followed the option indicator (%@AB@%/%@AE@%), as%@NL@% shown below.%@NL@% %@NL@% LINK /ABCDEF main;%@NL@% %@NL@% %@CR:MCVcE094@%%@4@%%@AB@%L1003 /QUICKLIB, /EXEPACK incompatible%@AE@%%@EH@%%@NL@% %@NL@% You cannot link with both the %@AB@%/QU%@AE@% option and the %@AB@%/E%@AE@% option.%@NL@% %@NL@% %@CR:MCVcE095@%%@4@%%@AB@%L1004%@AE@% %@AI@%option%@AE@%%@AB@% : invalid numeric value%@AE@%%@EH@%%@NL@% %@NL@% An incorrect value appeared for one of the linker options. For%@NL@% example, a character string was given for an option that requires%@NL@% a numeric value.%@NL@% %@NL@% %@CR:MCVcE096@%%@4@%%@AB@%L1005 /PACKCODE : packing limit exceeds 65536 bytes%@AE@%%@EH@%%@NL@% %@NL@% The value supplied with the %@AB@%/PACKCODE%@AE@% option exceeds the limit of%@NL@% 65,536 bytes.%@NL@% %@NL@% %@CR:MCVcE097@%%@4@%%@AB@%%@AB@%L1006%@AE@% %@AI@%option-text%@AE@%%@AB@% : stack size exceeds 65535 bytes%@AE@%%@EH@%%@NL@% %@NL@% The value given as a parameter to the %@AB@%/STACKSIZE%@AE@% option exceeds%@NL@% the maximum allowed.%@NL@% %@NL@% %@CR:MCVcE098@%%@4@%%@AB@%L1007%@AE@% %@AI@%option%@AE@%%@AB@% : interrupt number exceeds 255%@AE@%%@EH@%%@NL@% %@NL@% A number greater than 255 was given as the /OVERLAYINTERRUPT%@NL@% option value.%@NL@% %@NL@% %@CR:MCVcE099@%%@4@%%@AB@%L1008%@AE@% %@AI@%option%@AE@%%@AB@% : segment limit set too high%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%/SEGMENTS%@AE@% option specified a limit on the number of segments%@NL@% allowed greater than 3,072.%@NL@% %@NL@% %@CR:MCVcE100@%%@4@%%@AB@%L1009%@AE@% %@AI@%number%@AE@%%@AB@% : CPARMAXALLOC : illegal value%@AE@%%@EH@%%@NL@% %@NL@% The number specified in the %@AB@%/CPARMAXALLOC%@AE@% option was not in the%@NL@% range 1- 65,535.%@NL@% %@NL@% %@CR:MCVcE101@%%@4@%%@AB@%L1020 no object modules specified%@AE@%%@EH@%%@NL@% %@NL@% No object-file names were specified to the linker.%@NL@% %@NL@% %@CR:MCVcE102@%%@4@%%@AB@%L1021 cannot nest response files%@AE@%%@EH@%%@NL@% %@NL@% A response file occurred within a response file.%@NL@% %@NL@% %@CR:MCVcE103@%%@4@%%@AB@%L1022 response line too long%@AE@%%@EH@%%@NL@% %@NL@% A line in a response file was longer than 127 characters.%@NL@% %@NL@% %@CR:MCVcE104@%%@4@%%@AB@%L1023 terminated by user%@AE@%%@EH@%%@NL@% %@NL@% You entered CTRL+C.%@NL@% %@NL@% %@CR:MCVcE105@%%@4@%%@AB@%L1024 nested right parentheses%@AE@%%@EH@%%@NL@% %@NL@% The contents of an overlay were typed incorrectly on the command%@NL@% line.%@NL@% %@NL@% %@CR:MCVcE106@%%@4@%%@AB@%L1025 nested left parentheses%@AE@%%@EH@%%@NL@% %@NL@% The contents of an overlay were typed incorrectly on the command%@NL@% line.%@NL@% %@NL@% %@CR:MCVcE107@%%@4@%%@AB@%L1026 unmatched right parenthesis%@AE@%%@EH@%%@NL@% %@NL@% A right parenthesis was missing from the contents specification of%@NL@% an overlay on the command line.%@NL@% %@NL@% %@CR:MCVcE108@%%@4@%%@AB@%L1027 unmatched left parenthesis%@AE@%%@EH@%%@NL@% %@NL@% A left parenthesis was missing from the contents specification of%@NL@% an overlay on the command line.%@NL@% %@NL@% %@CR:MCVcE109@%%@4@%%@AB@%L1030 missing internal name%@AE@%%@EH@%%@NL@% %@NL@% An %@AB@%IMPORT%@AE@% statement specified an ordinal in the module-definition%@NL@% file without including the internal name of the routine. The name%@NL@% must be given if the import is by ordinal.%@NL@% %@NL@% %@CR:MCVcE110@%%@4@%%@AB@%L1031 module description redefined%@AE@%%@EH@%%@NL@% %@NL@% A %@AB@%DESCRIPTION%@AE@% statement in the module-definition file was%@NL@% specified more than once, a procedure that is not allowed.%@NL@% %@NL@% %@CR:MCVcE111@%%@4@%%@AB@%L1032 module name redefined%@AE@%%@EH@%%@NL@% %@NL@% The module name was specified more than once (via a %@AB@%NAME%@AE@% or%@NL@% %@AB@%LIBRARY%@AE@% statement), a procedure that is not allowed.%@NL@% %@NL@% %@CR:MCVcE112@%%@4@%%@AB@%L1040 too many exported entries%@AE@%%@EH@%%@NL@% %@NL@% The module-definition file exceeded the limit of 3,072 exported%@NL@% names.%@NL@% %@NL@% %@CR:MCVcE113@%%@4@%%@AB@%L1041 resident-name table overflow%@AE@%%@EH@%%@NL@% %@NL@% The size of the resident-name table exceeds 65,534 bytes. (An%@NL@% entry in the resident-name table is made for each exported routine%@NL@% designated %@AB@%RESIDENTNAME%@AE@%, and consists of the name plus three bytes%@NL@% of information. The first entry is the module name.)%@NL@% %@NL@% Reduce the number of exported routines or change some to%@NL@% nonresident status.%@NL@% %@NL@% %@CR:MCVcE114@%%@4@%%@AB@%L1042 nonresident-name table overflow%@AE@%%@EH@%%@NL@% %@NL@% The size of the nonresident-name table exceeds 65,534 bytes. (An%@NL@% entry in the nonresident-name table is made for each exported%@NL@% routine not designated %@AB@%RESIDENT-NAME%@AE@%, and consists of the name%@NL@% plus three bytes of information. The first entry is the%@NL@% %@AB@%DESCRIPTION%@AE@% statement.)%@NL@% %@NL@% Reduce the number of exported routines or change some to resident%@NL@% status.%@NL@% %@NL@% %@CR:MCVcE115@%%@4@%%@AB@%L1043 relocation table overflow%@AE@%%@EH@%%@NL@% %@NL@% More than 32,768 long calls, long jumps, or other long pointers%@NL@% appeared in the program.%@NL@% %@NL@% Try replacing long references with short references where%@NL@% possible, and recreate the object module.%@NL@% %@NL@% %@CR:MCVcE116@%%@4@%%@AB@%L1044 imported-name table overflow%@AE@%%@EH@%%@NL@% %@NL@% The size of the imported-names table exceeds 65,534 bytes. (An%@NL@% entry in the imported-names table is made for each new name given%@NL@% in the %@AB@%IMPORTS%@AE@% section──including the module names──and consists%@NL@% of the name plus one byte.)%@NL@% %@NL@% Reduce the number of imports.%@NL@% %@NL@% %@CR:MCVcE117@%%@4@%%@AB@%L1045 too many TYPDEF records%@AE@%%@EH@%%@NL@% %@NL@% An object module contained more than 255 %@AB@%TYPDEF%@AE@% records. These%@NL@% records describe communal variables. This error can appear only%@NL@% with programs produced by the Microsoft FORTRAN Compiler or other%@NL@% compilers that support communal variables. (%@AB@%TYPDEF%@AE@% is a DOS term.%@NL@% It is explained in the %@AI@%Microsoft MS-DOS Programmer's Reference%@AE@% and%@NL@% in other reference books on DOS.)%@NL@% %@NL@% %@CR:MCVcE118@%%@4@%%@AB@%L1046 too many external symbols in one module%@AE@%%@EH@%%@NL@% %@NL@% An object module specified more than the limit of 1,023 external%@NL@% symbols.%@NL@% %@NL@% Break the module into smaller parts.%@NL@% %@NL@% %@CR:MCVcE119@%%@4@%%@AB@%L1047 too many group, segment, and class names in one module%@AE@%%@EH@%%@NL@% %@NL@% The program contained too many group, segment, and class names.%@NL@% %@NL@% Reduce the number of groups, segments, or classes, and recreate%@NL@% the object file.%@NL@% %@NL@% %@CR:MCVcE120@%%@4@%%@AB@%L1048 too many segments in one module%@AE@%%@EH@%%@NL@% %@NL@% An object module had more than 255 segments.%@NL@% %@NL@% Split the module or combine segments.%@NL@% %@NL@% %@CR:MCVcE121@%%@4@%%@AB@%L1049 too many segments%@AE@%%@EH@%%@NL@% %@NL@% The program had more than the maximum number of segments. (The%@NL@% %@AB@%/SEGMENTS%@AE@% option specifies the maximum legal number; the default%@NL@% is 128.)%@NL@% %@NL@% Relink by using the %@AB@%/SEGMENTS%@AE@% option with an appropriate number of%@NL@% segments.%@NL@% %@NL@% %@CR:MCVcE122@%%@4@%%@AB@%L1050 too many groups in one module%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%LINK%@AE@% encountered more than 21 group definitions (%@AB@%GRPDEF%@AE@%) in a%@NL@% single module.%@NL@% %@NL@% Reduce the number of group definitions or split the module. (Group%@NL@% definitions are explained in the %@AI@%Microsoft MS-DOS Programmer's%@AE@%%@NL@% %@AI@%Reference%@AE@% and in other reference books on DOS.)%@NL@% %@NL@% %@CR:MCVcE123@%%@4@%%@AB@%L1051 too many groups%@AE@%%@EH@%%@NL@% %@NL@% The program defined more than 20 groups, not counting %@AB@%DGROUP%@AE@%.%@NL@% %@NL@% Reduce the number of groups.%@NL@% %@NL@% %@CR:MCVcE124@%%@4@%%@AB@%L1052 too many libraries%@AE@%%@EH@%%@NL@% %@NL@% An attempt was made to link with more than 32 libraries.%@NL@% %@NL@% Combine libraries, or use modules that require fewer libraries.%@NL@% %@NL@% %@CR:MCVcE125@%%@4@%%@AB@%L1053 out of memory for symbol table%@AE@%%@EH@%%@NL@% %@NL@% The program had more symbolic information (such as public,%@NL@% external, segment, group, class, and file names) than could fit in%@NL@% available memory.%@NL@% %@NL@% Try freeing memory by linking from the DOS command level instead%@NL@% of from a %@AB@%MAKE%@AE@% file or an editor. Otherwise, combine modules or%@NL@% segments and try to eliminate as many public symbols as possible.%@NL@% %@NL@% %@CR:MCVcE126@%%@4@%%@AB@%L1054 requested segment limit too high%@AE@%%@EH@%%@NL@% %@NL@% The linker did not have enough memory to allocate tables%@NL@% describing the num-ber of segments requested. (The default is 128%@NL@% or the value specified with the %@AB@%/SEGMENTS%@AE@% option.)%@NL@% %@NL@% Try linking again by using the %@AB@%/SEGMENTS%@AE@% option to select a%@NL@% smaller number of segments (for example, use 64 if the default was%@NL@% used previously), or free some memory by eliminating resident%@NL@% programs or shells.%@NL@% %@NL@% %@CR:MCVcE127@%%@4@%%@AB@%L1056 too many overlays%@AE@%%@EH@%%@NL@% %@NL@% The program defined more than 63 overlays.%@NL@% %@NL@% %@CR:MCVcE128@%%@4@%%@AB@%L1057 data record too large%@AE@%%@EH@%%@NL@% %@NL@% A %@AB@%LEDATA%@AE@% record (in an object module) contained more than 1,024%@NL@% bytes of data. This is a translator error. (%@AB@%LEDATA%@AE@% is a DOS term%@NL@% that is explained in the %@AI@%Microsoft MS-DOS Programmer's Reference%@AE@%%@NL@% and in other DOS reference books.)%@NL@% %@NL@% Note which translator (compiler or assembler) produced the%@NL@% incorrect object module and the circumstances. Please report this%@NL@% error to Microsoft Corporation by following the directions in the%@NL@% Microsoft Product Assistance Request form at the back of one of%@NL@% your manuals.%@NL@% %@NL@% %@CR:MCVcE129@%%@4@%%@AB@%L1061 out of memory for/INCREMENTAL%@AE@%%@EH@%%@NL@% %@NL@% The linker ran out of memory when trying to process the additional%@NL@% information required for %@AB@%ILINK%@AE@% support.%@NL@% %@NL@% Disable incremental linking.%@NL@% %@NL@% %@CR:MCVcE130@%%@4@%%@AB@%L1062 too many symbols for/INCREMENTAL%@AE@%%@EH@%%@NL@% %@NL@% The program had more symbols than can be stored in the %@AB@%.SYM%@AE@% file.%@NL@% %@NL@% Reduce the number of symbols or disable incremental linking.%@NL@% %@NL@% %@CR:MCVcE131@%%@4@%%@AB@%L1063 out of memory for CodeView information%@AE@%%@EH@%%@NL@% %@NL@% The linker was given too many object files with debug information,%@NL@% and the linker ran out of space to store it.%@NL@% %@NL@% Reduce the number of object files that have debug information.%@NL@% %@NL@% %@CR:MCVcE132@%%@4@%%@AB@%L1064 out of memory%@AE@%%@EH@%%@NL@% %@NL@% The linker was not able to allocate enough memory from the%@NL@% operating system to link the program. On OS/2, try increasing the%@NL@% swap space. Otherwise, reduce the size of the program in terms of%@NL@% code, data, and symbols. On OS/2, consider splitting the program%@NL@% into dynlink libraries.%@NL@% %@NL@% %@CR:MCVcE133@%%@4@%%@AB@%L1070%@AE@% %@AI@%name%@AE@%%@AB@% : segment size exceeds 64K%@AE@%%@EH@%%@NL@% %@NL@% A single segment contained more than 64K of code or data.%@NL@% %@NL@% Try compiling and linking using the large model.%@NL@% %@NL@% %@CR:MCVcE134@%%@4@%%@AB@%L1071 segment _TEXT larger than 65520 bytes%@AE@%%@EH@%%@NL@% %@NL@% This error is likely to occur only in small-model C programs, but%@NL@% it can occur when any program with a segment named %@AB@%_TEXT%@AE@% is linked%@NL@% using the %@AB@%/DOSSEG%@AE@% option of the %@AB@%LINK%@AE@% command. Small-model C%@NL@% programs must reserve code addresses 0 and 1; this range is%@NL@% increased to 16 for alignment purposes.%@NL@% %@NL@% Try compiling and linking using the large model.%@NL@% %@NL@% %@CR:MCVcE135@%%@4@%%@AB@%L1072 common area longer than 65536 bytes%@AE@%%@EH@%%@NL@% %@NL@% The program had more than 64K of communal variables. This error%@NL@% cannot appear with object files generated by the Microsoft Macro%@NL@% Assembler, %@AB@%MASM%@AE@%. It occurs only with programs produced by the%@NL@% Microsoft FORTRAN Compiler or other compilers that support%@NL@% communal variables.%@NL@% %@NL@% %@CR:MCVcE136@%%@4@%%@AB@%L1073 file segment limit exceeded%@AE@%%@EH@%%@NL@% %@NL@% The number of physical or file segments exceeds the limit of 254%@NL@% imposed by OS/2 protected mode and by Windows for each application%@NL@% or dynamic-link library. (A file segment is created for each group%@NL@% definition, nonpacked logical segment, and set of packed%@NL@% segments.)%@NL@% %@NL@% Reduce the number of segments or put more information into each%@NL@% segment. Make sure that the %@AB@%/PACKCODE%@AE@% and/or the %@AB@%/PACKDATA%@AE@% options%@NL@% are on.%@NL@% %@NL@% %@CR:MCVcE137@%%@4@%%@AB@%L1074%@AE@% %@AI@%name%@AE@%%@AB@% : group larger than 64K bytes%@AE@%%@EH@%%@NL@% %@NL@% The given group exceeds the limit of 65,536 bytes.%@NL@% %@NL@% Reduce the size of the group, or remove any unneeded segments from%@NL@% the group (refer to the map file for a listing of segments).%@NL@% %@NL@% %@CR:MCVcE138@%%@4@%%@AB@%L1075 entry table larger than 65535 bytes%@AE@%%@EH@%%@NL@% %@NL@% The entry table exceeds the limit of 65,535 bytes. (There is an%@NL@% entry in this table for each exported routine for each address%@NL@% that is the target of a far relocation, and for one of the%@NL@% following conditions when true: the target segment is%@NL@% designated %@AB@%IOPL%@AE@%; or %@AB@%PROTMODE%@AE@% is not enabled and the target segment%@NL@% is designated %@AB@%MOVABLE%@AE@%.)%@NL@% %@NL@% Declare %@AB@%PROTMODE%@AE@% if applicable, or reduce the number of exported%@NL@% routines, or make some segments %@AB@%FIXED%@AE@% or %@AB@%NOIOPL%@AE@% if possible.%@NL@% %@NL@% %@CR:MCVcE139@%%@4@%%@AB@%L1078 file segment alignment too small%@AE@%%@EH@%%@NL@% %@NL@% The segment-alignment size given with the %@AB@%/ALIGN:%@AE@%%@AI@%number%@AE@% option was%@NL@% too small. Try increasing %@AI@%number%@AE@%.%@NL@% %@NL@% %@CR:MCVcE140@%%@4@%%@AB@%L1080 cannot open list file%@AE@%%@EH@%%@NL@% %@NL@% The disk or the root directory was full.%@NL@% %@NL@% Delete or move files to make space.%@NL@% %@NL@% %@CR:MCVcE141@%%@4@%%@AB@%L1081 out of space for run file%@AE@%%@EH@%%@NL@% %@NL@% The disk on which the %@AB@%.EXE%@AE@% file was being written was full.%@NL@% %@NL@% Free more space on the disk and restart the linker.%@NL@% %@NL@% %@CR:MCVcE142@%%@4@%%@AB@%L1082%@AE@% %@AI@%name%@AE@%%@AB@% : stub file not found%@AE@%%@EH@%%@NL@% %@NL@% The linker could not open the file given in the %@AB@%STUB%@AE@% statement in%@NL@% the module-definition file.%@NL@% %@NL@% %@CR:MCVcE143@%%@4@%%@AB@%L1083 cannot open run file%@AE@%%@EH@%%@NL@% %@NL@% The disk or the root directory was full.%@NL@% %@NL@% Delete or move files to make space.%@NL@% %@NL@% %@CR:MCVcE144@%%@4@%%@AB@%L1084 cannot create temporary file%@AE@%%@EH@%%@NL@% %@NL@% The disk or root directory was full.%@NL@% %@NL@% Free more space in the directory and restart the linker.%@NL@% %@NL@% %@CR:MCVcE145@%%@4@%%@AB@%L1085 cannot open temporary file%@AE@%%@EH@%%@NL@% %@NL@% The disk or the root directory was full.%@NL@% %@NL@% Delete or move files to make space.%@NL@% %@NL@% %@CR:MCVcE146@%%@4@%%@AB@%L1086 scratch file missing%@AE@%%@EH@%%@NL@% %@NL@% An internal error has occurred.%@NL@% %@NL@% Note the circumstances of the problem and contact Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE147@%%@4@%%@AB@%L1087 unexpected end-of-file on scratch file%@AE@%%@EH@%%@NL@% %@NL@% The disk with the temporary linker-output file was removed.%@NL@% %@NL@% %@CR:MCVcE148@%%@4@%%@AB@%L1088 out of space for list file%@AE@%%@EH@%%@NL@% %@NL@% The disk (where the listing file was being written) is full.%@NL@% %@NL@% Free more space on the disk and restart the linker.%@NL@% %@NL@% %@CR:MCVcE149@%%@4@%%@AB@%L1089%@AE@% %@AI@%filename%@AE@%%@AB@% : cannot open response file%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%LINK%@AE@% could not find the specified response file.%@NL@% %@NL@% This usually indicates a typing error.%@NL@% %@NL@% %@CR:MCVcE150@%%@4@%%@AB@%L1090 cannot reopen list file%@AE@%%@EH@%%@NL@% %@NL@% The original disk was not replaced at the prompt.%@NL@% %@NL@% Restart the linker.%@NL@% %@NL@% %@CR:MCVcE151@%%@4@%%@AB@%L1091 unexpected end-of-file on library%@AE@%%@EH@%%@NL@% %@NL@% The disk containing the library was probably removed.%@NL@% %@NL@% Replace the disk containing the library and run the linker again.%@NL@% %@NL@% %@CR:MCVcE152@%%@4@%%@AB@%L1092 cannot open module-definitions file%@AE@%%@EH@%%@NL@% %@NL@% The linker could not open the module-definition file specified on%@NL@% the command line or in the response file.%@NL@% %@NL@% %@CR:MCVcE153@%%@4@%%@AB@%L1093%@AE@% %@AI@%filename%@AE@%%@AB@% : object not found%@AE@%%@EH@%%@NL@% %@NL@% One of the object files specified in the linker input was not%@NL@% found.%@NL@% %@NL@% Restart the linker and specify the object file.%@NL@% %@NL@% %@CR:MCVcE154@%%@4@%%@AB@%L1094%@AE@% %@AI@%file%@AE@%%@AB@% : cannot open file for writing%@AE@%%@EH@%%@NL@% %@NL@% The linker was unable to open the file with write permission.%@NL@% %@NL@% Check file permissions.%@NL@% %@NL@% %@CR:MCVcE155@%%@4@%%@AB@%L1095%@AE@% %@AI@%file%@AE@%%@AB@% : out of space on file%@AE@%%@EH@%%@NL@% %@NL@% The linker ran out of disk space for the specified output file.%@NL@% %@NL@% Delete or move files to make space.%@NL@% %@NL@% %@CR:MCVcE156@%%@4@%%@AB@%L1100 stub.EXE file invalid%@AE@%%@EH@%%@NL@% %@NL@% The file specified in the %@AB@%STUB%@AE@% statement is not a valid real-mode%@NL@% executable file.%@NL@% %@NL@% %@CR:MCVcE157@%%@4@%%@AB@%L1101 invalid object module%@AE@%%@EH@%%@NL@% %@NL@% One of the object modules was invalid.%@NL@% %@NL@% If the error persists after recompiling, please contact Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE158@%%@4@%%@AB@%L1102 unexpected end-of-file%@AE@%%@EH@%%@NL@% %@NL@% An invalid format for a library was encountered.%@NL@% %@NL@% %@CR:MCVcE159@%%@4@%%@AB@%L1103 attempt to access data outside segment bounds%@AE@%%@EH@%%@NL@% %@NL@% A data record in an object module specified data extending beyond%@NL@% the end of a segment. This is a translator error.%@NL@% %@NL@% Note which translator (compiler or assembler) produced the%@NL@% incorrect object module and the circumstances in which it was%@NL@% produced. Please report this error to Microsoft Corporation by%@NL@% following the directions in the Microsoft Product Assistance%@NL@% Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE160@%%@4@%%@AB@%L1104%@AE@% %@AI@%filename%@AE@%%@AB@% : not valid library%@AE@%%@EH@%%@NL@% %@NL@% The specified file was not a valid library file. This error causes%@NL@% %@AB@%LINK%@AE@% to abort.%@NL@% %@NL@% %@CR:MCVcE161@%%@4@%%@AB@%L1105 invalid object due to aborted incremental compile%@AE@%%@EH@%%@NL@% %@NL@% Delete the object file, recompile the program, and relink.%@NL@% %@NL@% %@CR:MCVcE162@%%@4@%%@AB@%L1113 unresolved COMDEF; internal error%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the error and contact Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE163@%%@4@%%@AB@%L1114 file not suitable for /EXEPACK; relink without%@AE@%%@EH@%%@NL@% %@NL@% For the linked program, the size of the packed load image plus%@NL@% packing overhead was larger than that of the unpacked load image.%@NL@% %@NL@% Relink without the %@AB@%/EXEPACK%@AE@% option.%@NL@% %@NL@% %@CR:MCVcE164@%%@4@%%@AB@%L1115%@AE@% %@AI@%option%@AE@%%@AB@%: option incompatible with overlays%@AE@%%@EH@%%@NL@% %@NL@% The given option is not compatible with overlays. Remove the%@NL@% option or else do not use overlaid modules.%@NL@% %@NL@% %@CR:MCVcE165@%%@4@%%@AB@%L1123%@AE@% %@AI@%name%@AE@%%@AB@% : segment defined for both 16- and 32-bit.%@AE@%%@EH@%%@NL@% %@NL@% Define the segment as either 16-bit or 32-bit.%@NL@% %@NL@% %@CR:MCVcE166@%%@4@%%@AB@%L1126 conflicting iopl-parameter-words value%@AE@%%@EH@%%@NL@% %@NL@% An exported name was specified in the module-definition file with%@NL@% an %@AB@%IOPL%@AE@%-parameter-words value, and the same name was specified as%@NL@% an export by the Microsoft C export pragma with a different%@NL@% parameter-words value.%@NL@% %@NL@% %@CR:MCVcE167@%%@4@%%@AB@%L1127 far segment references not allowed with /BINARY%@AE@%%@EH@%%@NL@% %@NL@% You used the %@AB@%/BINARY%@AE@% option (causing the linker to produce a .COM%@NL@% file) with modules that have a far segment reference. Far segment%@NL@% references are not compatible with the %@AB@%.COM%@AE@% file format.%@NL@% High-level-language modules cause this error message (unless the%@NL@% language supports tiny memory model). Assembly code that%@NL@% references a segment address also produces this error message. For%@NL@% example:%@NL@% %@NL@% mov ax, seg mydata%@NL@% %@NL@% %@NL@% %@CR:MCVc2200@%%@3@%%@AB@%C.2.2 LINK Nonfatal Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE168@%%@4@%%@AB@%L2000 imported starting address%@AE@%%@EH@%%@NL@% %@NL@% The program starting address as specified in the %@AB@%END%@AE@% statement in%@NL@% a %@AB@%MASM%@AE@% file is an imported routine. This is not supported by OS/2%@NL@% or Windows.%@NL@% %@NL@% %@CR:MCVcE169@%%@4@%%@AB@%L2001 fixup(s) without data%@AE@%%@EH@%%@NL@% %@NL@% A %@AB@%FIXUPP%@AE@% record occurred without a data record immediately%@NL@% preceding it. This is probably a compiler error. (See the%@NL@% %@AI@%Microsoft MS-DOS %@AE@%%@AI@%Programmer's Reference%@AE@% for more information on%@NL@% %@AB@%FIXUPP%@AE@%.)%@NL@% %@NL@% If the error persists after recompiling, please contact Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one or your manuals.%@NL@% %@NL@% %@CR:MCVcE170@%%@4@%%@AB@%L2002 fixup overflow at %@AI@%number%@AE@%%@AB@% in segment%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@% %@NL@% This error message will be followed by one of the following:%@NL@% %@NL@% %@CR:MCVc2201@%1. "Target external '%@AI@%name%@AE@%.'"%@NL@% %@NL@% 2. frm seg %@AI@%name1%@AE@%, tgt seg %@AI@%name2%@AE@%, tgt offset %@AI@%number%@AE@%.%@NL@% %@NL@% %@CR:MCVc2202@%%@4@%A fixup overflow is essentially an attempted reference to code or data that%@EH@% is impossible because the source location, i.e., where the reference is made "from," and the target address, i.e., where the reference is made "to," are too far apart. A close look at the source location is often all you need to correct the problem.%@NL@% %@NL@% %@CR:MCVc2203@%%@4@%Revise the source file and recreate the object file. (For information about%@EH@% frame and target segments, see the %@AI@%Microsoft MS-DOS Programmer's Reference%@AE@%.)%@NL@% %@NL@% %@CR:MCVcE171@%%@4@%%@AB@%L2003 intersegment self-relative fixup at%@AE@% %@AI@%number%@AE@%%@AB@% in segment name%@AE@%%@EH@%%@NL@% %@NL@% The program issued a near call or jump to a label in a different%@NL@% segment. This error most often occurs when you specifically%@NL@% declare an external procedure to be near and it should be declared%@NL@% as far.%@NL@% %@NL@% %@CR:MCVcE172@%%@4@%%@AB@%L2004 LOBYTE-type fixup overflow%@AE@%%@EH@%%@NL@% %@NL@% A %@AB@%LOBYTE%@AE@% fixup generated an address overflow. (See the %@AI@%Microsoft%@AE@%%@NL@% %@AI@%MS-DOS Programmer's Reference%@AE@% for more information.)%@NL@% %@NL@% %@CR:MCVcE173@%%@4@%%@AB@%L2005 fixup type unsupported%@AE@%%@EH@%%@NL@% %@NL@% A fixup type occurred that is not supported by the Microsoft%@NL@% linker. This is probably a compiler error.%@NL@% %@NL@% Note the circumstances of the failure and contact Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE174@%%@4@%%@AB@%L2010 too many fixups in LIDATA record%@AE@%%@EH@%%@NL@% %@NL@% The number of far relocations (pointer- or base-type) in a LIDATA%@NL@% record ex- ceeds the limit imposed by the linker. This is%@NL@% typically produced by the %@AB@%DUP%@AE@% statement in an %@AB@%.ASM%@AE@% file. The limit%@NL@% is dynamic: a 1,024-byte buffer is shared by relocations and the%@NL@% contents of the %@AB@%LIDATA%@AE@% record; there are eight bytes per%@NL@% relocation.%@NL@% %@NL@% Reduce the number of far relocations in the %@AB@%DUP%@AE@% statement.%@NL@% %@NL@% %@CR:MCVcE175@%%@4@%%@AB@%L2011%@AE@% %@AI@%name%@AE@%%@AB@% : NEAR/HUGE conflict%@AE@%%@EH@%%@NL@% %@NL@% Conflicting %@AB@%NEAR%@AE@% and %@AB@%HUGE%@AE@% attributes were given for a communal%@NL@% variable. This error can occur only with programs produced by the%@NL@% Microsoft FORTRAN Compiler or other compilers that support%@NL@% communal variables.%@NL@% %@NL@% %@CR:MCVcE176@%%@4@%%@AB@%L2012%@AE@% %@AI@%name%@AE@%%@AB@% : array-element size mismatch%@AE@%%@EH@%%@NL@% %@NL@% A far communal array was declared with two or more different%@NL@% array-element sizes (for instance, an array was declared once as%@NL@% an array of characters and once as an array of real numbers). This%@NL@% error cannot occur with object files produced by the Microsoft%@NL@% Macro Assembler. It occurs only with the Microsoft FORTRAN%@NL@% Compiler and any other compiler that supports far communal arrays.%@NL@% %@NL@% %@CR:MCVcE177@%%@4@%%@AB@%L2013 LIDATA record too large%@AE@%%@EH@%%@NL@% %@NL@% A %@AB@%LIDATA%@AE@% record contained more than 512 bytes. This is probably a%@NL@% compiler error.%@NL@% %@NL@% Note the circumstances of the failure and contact Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE178@%%@4@%%@AB@%L2022%@AE@% %@AI@%name%@AE@%%@AB@% (alias%@AE@% %@AI@%internalname%@AE@%%@AB@%) : export undefined%@AE@%%@EH@%%@NL@% %@NL@% The internal name of the given exported routine is undefined.%@NL@% %@NL@% Number LINK Error Message%@NL@% %@NL@% %@CR:MCVcE179@%%@4@%%@AB@%L2023%@AE@% %@AI@%name%@AE@%%@AB@% (alias%@AE@% %@AI@%internalname%@AE@%%@AB@%) : export imported%@AE@%%@EH@%%@NL@% %@NL@% The internal name of the given exported routine conflicts with the%@NL@% internal name of a previously imported routine. The set of%@NL@% imported and exported names cannot overlap.%@NL@% %@NL@% %@CR:MCVcE180@%%@4@%%@AB@%L2024%@AE@% %@AI@%name%@AE@%%@AB@% : special symbol already defined%@AE@%%@EH@%%@NL@% %@NL@% Your program defined a symbol name already used by the linker for%@NL@% one of its own low-level symbols. (For example, the linker%@NL@% generates special symbols used in overlay support and other%@NL@% operations.)%@NL@% %@NL@% Choose another name for the symbol in order to avoid conflict.%@NL@% %@NL@% %@CR:MCVcE181@%%@4@%%@AB@%L2025%@AE@% %@AI@%name%@AE@%%@AB@% : symbol defined more than once.%@AE@%%@EH@%%@NL@% %@NL@% The same symbol has been found in two different object files.%@NL@% %@NL@% %@CR:MCVcE182@%%@4@%%@AB@%L2026 entry ordinal%@AE@% %@AI@%number%@AE@%%@AB@%, name%@AE@% %@AI@%name%@AE@%%@AB@% : multiple definitions for the%@AE@%%@EH@%%@NL@% %@AB@%same ordinal%@AE@%%@NL@% %@NL@% The given exported name with the given ordinal number conflicted%@NL@% with a different exported name previously assigned to the same%@NL@% ordinal. Only one name can be associated with a particular%@NL@% ordinal.%@NL@% %@NL@% %@CR:MCVcE183@%%@4@%%@AB@%L2027%@AE@% %@AI@%name%@AE@%%@AB@% : ordinal too large for export%@AE@%%@EH@%%@NL@% %@NL@% The given exported name was assigned an ordinal that exceeded the%@NL@% limit of 3,072.%@NL@% %@NL@% %@CR:MCVcE184@%%@4@%%@AB@%L2028 automatic data segment plus heap exceed 64K%@AE@%%@EH@%%@NL@% %@NL@% The total size of data declared in %@AB@%DGROUP%@AE@%, plus the value given in%@NL@% %@AB@%HEAPSIZE%@AE@% in the module-definition file, plus the stack size given%@NL@% by the %@AB@%/STACKSIZE%@AE@% option or %@AB@%STACKSIZE%@AE@% module-definition file%@NL@% statement, exceeds 64K. Reduce near-data allocation, %@AB@%HEAPSIZE%@AE@%, or%@NL@% stack.%@NL@% %@NL@% %@CR:MCVcE185@%%@4@%%@AB@%L2029%@AE@% %@AI@%name%@AE@%%@AB@% : unresolved external%@AE@%%@EH@%%@NL@% %@NL@% The name that comes before %@AS@%in file(s)%@AE@% is the unresolved external%@NL@% symbol. On the next line is a list of object modules that have%@NL@% made references to this symbol. This message and the list are also%@NL@% written to the map file, if one exists.%@NL@% %@NL@% %@CR:MCVcE186@%%@4@%%@AB@%L2030 starting address not code (use class 'CODE')%@AE@%%@EH@%%@NL@% %@NL@% The program starting address, as specified in the %@AB@%END%@AE@% statement of%@NL@% an %@AB@%.ASM%@AE@% file, should be in a code segment. (Code segments are%@NL@% recognized if their class name ends in %@AS@%'CODE'%@AE@%.) This is an error%@NL@% in OS/2 protected mode.%@NL@% %@NL@% The error message may be disabled by including the %@AB@%REALMODE%@AE@%%@NL@% statement in the module-definition file.%@NL@% %@NL@% %@CR:MCVcE187@%%@4@%%@AB@%L2041 stack plus data exceed 64K%@AE@%%@EH@%%@NL@% %@NL@% If the total of near data and requested stack size exceeds 64K,%@NL@% the program will not run correctly. The linker checks for this%@NL@% condition only when %@AB@%/DOSSEG%@AE@% is enabled, which is the case in the%@NL@% library startup module.%@NL@% %@NL@% Reduce the stack size.%@NL@% %@NL@% %@CR:MCVcE188@%%@4@%%@AB@%L2043 Quick Library support module missing%@AE@%%@EH@%%@NL@% %@NL@% You did not link with the required %@AB@%QUICKLIB.OBJ%@AE@% module when%@NL@% creating a Quick library.%@NL@% %@NL@% %@CR:MCVcE189@%%@4@%%@AB@%L2044%@AE@% %@AI@%name%@AE@%%@AB@% : symbol multiply defined, use/NOE%@AE@%%@EH@%%@NL@% %@NL@% The linker found what it interprets as a public-symbol%@NL@% redefinition, probably because you have redefined a symbol defined%@NL@% in a library. Relink with the %@AB@%/NOEXTDICTIONARY%@AE@% (%@AB@%NOE%@AE@%) option. If%@NL@% error L2025 results for the same symbol, then you have a genuine%@NL@% symbol-redefinition error.%@NL@% %@NL@% %@CR:MCVcE190@%%@4@%%@AB@%L2045%@AE@% %@AI@%segmentname%@AE@%%@AB@% : segment with > 1 class name not allowed with/INC%@AE@%%@EH@%%@NL@% %@NL@% Your program defined a segment more than once, giving the segment%@NL@% different class names. Different class names for the same segment%@NL@% are not allowed when you link with the %@AB@%/INCREMENTAL%@AE@% option.%@NL@% Normally, this error should never appear unless you are%@NL@% programming with %@AB@%MASM%@AE@%. For example, if you give the two MASM%@NL@% statements%@NL@% %@NL@% %@AS@%_BSS segment%@AE@%%@NL@% %@AS@%'BSS'_BSS segment 'DATA'%@AE@%%@NL@% %@NL@% then the statements have the effect of defining two distinct%@NL@% segments with the same name but different classes. This situation%@NL@% is incompatible with the %@AB@%/INCREMENTAL%@AE@% option.%@NL@% %@NL@% %@CR:MCVcE191@%%@4@%%@AB@%L2047 IOPL attribute conflict - segment:%@AE@% %@AI@%segname%@AE@%%@AB@% in group:%@AE@% %@AI@%grpname%@AE@%%@EH@%%@NL@% %@NL@% The segment %@AI@%segname%@AE@% is the a member of the group %@AI@%grpname%@AE@%, but has%@NL@% a different %@AB@%IOPL%@AE@% attribute from other segments in the group.%@NL@% %@NL@% %@NL@% %@CR:MCVc2300@%%@3@%%@AB@%C.2.3 LINK Warning Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE192@%%@4@%%@AB@%L4000 seg disp. included near offset in segment%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@% %@NL@% This is the warning generated by the %@AB@%/WARNFIXUP%@AE@% option. See%@NL@% Section 13.3.31%@BO: 99af7@%, "Issuing Fixup Warnings," for more information%@NL@% on that option.%@NL@% %@NL@% %@CR:MCVcE193@%%@4@%%@AB@%L4001 frame-relative fixup, frame ignored near%@AE@% %@AI@%offset%@AE@%%@AB@% in segment%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@% %@NL@% A reference is made relative to a segment that is different from%@NL@% the target segment of the reference. For example, if %@AS@%_foo%@AE@% is%@NL@% defined in segment %@AS@%_TEXT%@AE@%, the instruction %@AS@%call DGROUP:_foo%@AE@%%@NL@% produces this warning. The frame %@AB@%DGROUP%@AE@% is ignored, so the linker%@NL@% treats the call as if it were %@AS@%call _TEXT:_foo%@AE@%.%@NL@% %@NL@% %@CR:MCVcE194@%%@4@%%@AB@%L4002 frame-relative absolute fixup near%@AE@% %@AI@%offset%@AE@%%@AB@% in segment%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@% %@NL@% A reference is made similar to the type described in L4001, but%@NL@% both segments are absolute (defined with %@AB@%AT%@AE@%). The linker treats%@NL@% the executable file as if the file were to run in real mode only.%@NL@% %@NL@% %@CR:MCVcE195@%%@4@%%@AB@%L4003 intersegment self-relative fixup at%@AE@% %@AI@%offset%@AE@%%@AB@% in segment%@AE@% %@AI@%name%@AE@%%@AB@% pos:%@AE@%%@EH@%%@NL@% %@AI@%offset%@AE@% %@AB@%target external%@AE@% '%@AI@%name%@AE@%'%@NL@% %@NL@% The linker found an intersegment self-relative fixup. This error%@NL@% may be caused by compiling a small-model program with the %@AB@%/NT%@AE@%%@NL@% option.%@NL@% %@NL@% %@CR:MCVcE196@%%@4@%%@AB@%L4010 invalid alignment specification%@AE@%%@EH@%%@NL@% %@NL@% The number specified in the %@AB@%/ALIGNMENT%@AE@% option must be a power of 2%@NL@% in the range 2-32,768, inclusive.%@NL@% %@NL@% %@CR:MCVcE197@%%@4@%%@AB@%L4011 PACKCODE value exceeding 65500 unreliable%@AE@%%@EH@%%@NL@% %@NL@% The packing limit specified with the %@AB@%/PACKCODE%@AE@% option was between%@NL@% 65,500 and 65,536. Code segments with a size in this range are%@NL@% unreliable on some steppings of the 80286 processor.%@NL@% %@NL@% %@CR:MCVcE198@%%@4@%%@AB@%L4012 load-high disables EXEPACK%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%/HIGH%@AE@% and %@AB@%/EXEPACK%@AE@% options cannot be used at the same time.%@NL@% %@NL@% %@CR:MCVcE199@%%@4@%%@AB@%L4013 invalid option for new-format executable file ignored%@AE@%%@EH@%%@NL@% %@NL@% The use of overlays with the options %@AB@%/CPARMAXALLOC%@AE@%, %@AB@%/DSALLOCATE%@AE@%,%@NL@% and %@AB@%/NOGROUPASSOCIATION%@AE@% is not allowed with either OS/2%@NL@% protected-mode or Windows executable files.%@NL@% %@NL@% %@CR:MCVcE200@%%@4@%%@AB@%L4014%@AE@% %@AI@%option%@AE@%%@AB@% : invalid option for old-format executable file ignored%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%/ALIGNMENT%@AE@% option is invalid for real-mode executables.%@NL@% %@NL@% %@CR:MCVcE201@%%@4@%%@AB@%L4015 /CODEVIEW disables /DSALLOCATE%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%/CODEVIEW%@AE@% and %@AB@%/DSALLOCATE%@AE@% options cannot be used at the same%@NL@% time.%@NL@% %@NL@% %@CR:MCVcE202@%%@4@%%@AB@%L4016 /CODEVIEW disables/EXEPACK%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%/CODEVIEW%@AE@% and %@AB@%/EXEPACK%@AE@% options cannot be used at the same%@NL@% time.%@NL@% %@NL@% %@CR:MCVcE203@%%@4@%%@AB@%L4020%@AE@% %@AI@%name%@AE@%%@AB@% : code-segment size exceeds 65500%@AE@%%@EH@%%@NL@% %@NL@% Code segments of 65,501-65,536 bytes in length may be unreliable%@NL@% on the Intel 80286 processor.%@NL@% %@NL@% %@CR:MCVcE204@%%@4@%%@AB@%L4021 no stack segment%@AE@%%@EH@%%@NL@% %@NL@% The program did not contain a stack segment defined with %@AB@%STACK%@AE@%%@NL@% combine type. This message should not appear for modules compiled%@NL@% with the Microsoft FORTRAN Compiler, but it could appear for an%@NL@% assembly-language module.%@NL@% %@NL@% Normally, every program should have a stack segment with the%@NL@% combine type specified as %@AB@%STACK%@AE@%. You may ignore this message if%@NL@% you have a specific reason for not defining a stack or for%@NL@% defining one without the %@AB@%STACK%@AE@% combine type. Linking with versions%@NL@% of %@AB@%LINK%@AE@% earlier than Version 2.40 might cause this message since%@NL@% these linkers search libraries only once.%@NL@% %@NL@% %@CR:MCVcE205@%%@4@%%@AB@%L4022%@AE@% %@AI@%group1%@AE@%%@AB@%,%@AE@% %@AI@%group2%@AE@%%@AB@% : groups overlap%@AE@%%@EH@%%@NL@% %@NL@% The named groups overlap. Since a group is assigned to a physical%@NL@% segment, groups cannot overlap with either OS/2 protected-mode or%@NL@% Windows executable files.%@NL@% %@NL@% Reorganize segments and group definitions so the groups do not%@NL@% overlap. Refer to the map file.%@NL@% %@NL@% %@CR:MCVcE206@%%@4@%%@AB@%L4023%@AE@% %@AI@%name%@AE@%%@AB@% (%@AE@%%@AI@%internal name%@AE@%%@AB@%) : export internal name conflict%@AE@%%@EH@%%@NL@% %@NL@% The internal name of the given exported routine conflicted with%@NL@% the internal name of a previous import definition or export%@NL@% definition.%@NL@% %@NL@% %@CR:MCVcE207@%%@4@%%@AB@%L4024%@AE@% %@AI@%name%@AE@%%@AB@% : multiple definitions for export name%@AE@%%@EH@%%@NL@% %@NL@% The given name was exported more than once, an action that is not%@NL@% allowed.%@NL@% %@NL@% %@CR:MCVcE208@%%@4@%%@AB@%L4025%@AE@% %@AI@%name%@AE@%%@AB@% : import internal name conflict%@AE@%%@EH@%%@NL@% %@NL@% The internal name of the given imported routine (import is either%@NL@% a name or a number) conflicted with the internal name of a%@NL@% previous export or import.%@NL@% %@NL@% %@CR:MCVcE209@%%@4@%%@AB@%L4026%@AE@% %@AI@%dynlib.import (name)%@AE@%%@AB@% : self-imported%@AE@%%@EH@%%@NL@% %@NL@% The given imported routine was imported from the module being%@NL@% linked. This is not supported on some systems.%@NL@% %@NL@% %@CR:MCVcE210@%%@4@%%@AB@%L4027%@AE@% %@AI@%name%@AE@%%@AB@% : multiple definitions for import internal-name%@AE@%%@EH@%%@NL@% %@NL@% The given internal name was imported more than once. Previous%@NL@% import definitions are ignored.%@NL@% %@NL@% %@CR:MCVcE211@%%@4@%%@AB@%L4028%@AE@% %@AI@%name%@AE@%%@AB@% : segment already defined%@AE@%%@EH@%%@NL@% %@NL@% The given segment was defined more than once in the %@AB@%SEGMENTS%@AE@%%@NL@% statement of the module-definition file.%@NL@% %@NL@% %@CR:MCVcE212@%%@4@%%@AB@%L4029%@AE@% %@AI@%name%@AE@%%@AB@% : DGROUP segment converted to type data%@AE@%%@EH@%%@NL@% %@NL@% The given logical segment in the group %@AB@%DGROUP%@AE@% was defined as a%@NL@% code segment. (%@AB@%DGROUP%@AE@% cannot contain code segments because the%@NL@% linker always considers %@AB@%DGROUP%@AE@% to be a data segment. The name%@NL@% %@AB@%DGROUP%@AE@% is predefined as the automatic data segment.) The linker%@NL@% converts the named segment to type "data."%@NL@% %@NL@% %@CR:MCVcE213@%%@4@%%@AB@%L4030%@AE@% %@AI@%name%@AE@%%@AB@% : segment attributes changed to conform with automatic data%@AE@%%@EH@%%@NL@% segment%@NL@% %@NL@% The given logical segment in the group %@AB@%DGROUP%@AE@% was given sharing%@NL@% attributes (%@AB@%SHARED/NONSHARED%@AE@%) that differed from the automatic%@NL@% data attributes as declared by the %@AB@%DATA%@AE@% %@AI@%instance%@AE@% specification%@NL@% (%@AB@%SINGLE/MULTIPLE%@AE@%). The attributes are converted to conform to%@NL@% those of %@AB@%DGROUP%@AE@%. Refer to Error L4029 for more information on%@NL@% %@AB@%DGROUP%@AE@%.%@NL@% %@NL@% %@CR:MCVcE214@%%@4@%%@AB@%L4031%@AE@% %@AI@%name%@AE@%%@AB@% : segment declared in more than one group%@AE@%%@EH@%%@NL@% %@NL@% A segment was declared to be a member of two different groups.%@NL@% %@NL@% Correct the source file and recreate the object files.%@NL@% %@NL@% %@CR:MCVcE215@%%@4@%%@AB@%L4032%@AE@% %@AI@%name%@AE@%%@AB@% : code-group size exceeds 65500 bytes%@AE@%%@EH@%%@NL@% %@NL@% The given code group has a size between 65,500 and 65,536 bytes, a%@NL@% size that is unreliable on some steppings of the 80286 processor.%@NL@% %@NL@% %@CR:MCVcE216@%%@4@%%@AB@%L4034 more than 239 overlay segments; extra put in root%@AE@%%@EH@%%@NL@% %@NL@% Your program designated more than the limit of 239 segments to go%@NL@% in overlays. Starting with the 234th segment, they are assigned to%@NL@% the root (that is, the permanently resident portion of the%@NL@% program).%@NL@% %@NL@% %@CR:MCVcE217@%%@4@%%@AB@%L4036 no automatic data segment%@AE@%%@EH@%%@NL@% %@NL@% The application did not define a group named %@AB@%DGROUP%@AE@%. %@AB@%DGROUP%@AE@% has%@NL@% special meaning to the linker, which uses it to identify the%@NL@% automatic or default data segment used by the operating system.%@NL@% Most OS/2 protected-mode and Windows applications require %@AB@%DGROUP%@AE@%.%@NL@% This warning will not be issued if %@AB@%DATA%@AE@% %@AB@%NONE%@AE@% is declared or if the%@NL@% executable file is a dynamic-link library.%@NL@% %@NL@% %@CR:MCVcE218@%%@4@%%@AB@%L4038 program has no starting address%@AE@%%@EH@%%@NL@% %@NL@% Your OS/2 or Windows application had no starting address, which%@NL@% usually will cause the program to fail. Higher-level languages%@NL@% automatically specify a starting address. If you are writing an%@NL@% assembly-language program, specify a starting address with the %@AB@%END%@AE@%%@NL@% statement.%@NL@% %@NL@% Real-mode programs and dynamic-link libraries should never receive%@NL@% this message, regardless whether or not they have starting%@NL@% addresses.%@NL@% %@NL@% %@CR:MCVcE219@%%@4@%%@AB@%L4042 cannot open old version%@AE@%%@EH@%%@NL@% %@NL@% The file specified in the %@AB@%OLD%@AE@% statement in the module-definition%@NL@% file could not be opened.%@NL@% %@NL@% %@CR:MCVcE220@%%@4@%%@AB@%L4043 old version not segmented-executable format%@AE@%%@EH@%%@NL@% %@NL@% The file specified in the %@AB@%OLD%@AE@% statement in the module-definition%@NL@% file was not a valid OS/2 protected-mode or Windows executable%@NL@% file.%@NL@% %@NL@% %@CR:MCVcE221@%%@4@%%@AB@%L4045 name of output file is%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@% %@NL@% The prompt for the run-file field gave an inaccurate default%@NL@% because %@AB@%/QUICKLIB%@AE@% option was not used early enough. The output%@NL@% will be a Quick library with the name given in the error message.%@NL@% %@NL@% %@CR:MCVcE222@%%@4@%%@AB@%L4046 module name different from output file name%@AE@%%@EH@%%@NL@% %@NL@% The name of the executable file as specified in the %@AB@%NAME%@AE@% or%@NL@% %@AB@%LIBRARY%@AE@% statement is different from the output file name. This may%@NL@% cause problems; consult the documentation for your operating%@NL@% system.%@NL@% %@NL@% %@CR:MCVcE223@%%@4@%%@AB@%L4050 too many public symbols for sorting%@AE@%%@EH@%%@NL@% %@NL@% The linker uses the stack and all available memory in the near%@NL@% heap to sort public symbols for the %@AB@%/MAP%@AE@% option. If the number of%@NL@% public symbols exceeds the space available for them, this warning%@NL@% is issued and the symbols are not sorted in the map file but%@NL@% listed in an arbitrary order.%@NL@% %@NL@% Reduce the number of symbols.%@NL@% %@NL@% %@CR:MCVcE224@%%@4@%%@AB@%L4051%@AE@% %@AI@%filename%@AE@%%@AB@% : cannot find library%@AE@%%@EH@%%@NL@% %@NL@% The linker could not find the specified file.%@NL@% %@NL@% Enter a new file name, a new path specification, or both.%@NL@% %@NL@% %@CR:MCVcE225@%%@4@%%@AB@%L4053 VM.TMP : illegal file name; ignored%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%VM.TMP%@AE@% appeared as an object-file name.%@NL@% %@NL@% Rename the file and rerun the linker.%@NL@% %@NL@% %@CR:MCVcE226@%%@4@%%@AB@%L4054%@AE@% %@AI@%filename%@AE@%%@AB@% : cannot find file%@AE@%%@EH@%%@NL@% %@NL@% The linker could not find the specified file.%@NL@% %@NL@% Enter a new file name, a new path specification, or both.%@NL@% %@NL@% %@CR:MCVcE227@%%@4@%%@AB@%L4067 ignoring start address not equal to 0x100 for /TINY%@AE@%%@EH@%%@NL@% %@NL@% The code specified a starting address other than the assumed%@NL@% address of 100 hex for a %@AB@%.COM%@AE@% file created with the %@AB@%/TINY%@AE@% option.%@NL@% The linker is proceeding to start the %@AB@%.COM%@AE@% file at 100 hex,%@NL@% regardless of the specified address.%@NL@% %@NL@% Present only in the DOS-only 3.xx linkers and the executable 5.xx%@NL@% linkers.%@NL@% %@NL@% %@NL@% %@CR:MCVc3000@%%@2@%%@AB@%C.3 ILINK Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVc3001@%%@4@%This section lists and describes error messages generated by the Microsoft%@EH@% Incremental Linker, %@AB@%ILINK%@AE@%.%@NL@% %@NL@% %@CR:MCVc3002@%%@4@%%@AB@%Fatal errors%@AE@% cause the linker to end the linking session. Fatal error%@EH@% messages have the following format:%@NL@% %@NL@% %@CR:MCVc3003@%%@AI@%location%@AE@% : %@AS@%error L1%@AE@%%@AI@%xxx%@AE@%: %@AI@%messagetext%@AE@%%@NL@% %@NL@% %@CR:MCVc3004@%%@4@%%@AB@%Incremental violations%@AE@% cause %@AB@%ILINK%@AE@% to end the linking session and carry out%@EH@% the command specified by the /e option. Incremental violations messages have the following format:%@NL@% %@NL@% %@CR:MCVc3005@%%@AI@%location%@AE@% : %@AS@%error L2%@AE@%%@AI@%xxx%@AE@%: %@AI@%messagetext%@AE@%%@NL@% %@NL@% %@CR:MCVc3006@%%@4@%%@AB@%Warnings%@AE@% give notice of certain conditions without ending the operation of%@EH@% ILINK. Warnings have the following format:%@NL@% %@NL@% %@CR:MCVc3007@%%@AI@%location%@AE@% : %@AS@%warning L4%@AE@%%@AI@%xxx%@AE@%: %@AI@%messagetext%@AE@%%@NL@% %@NL@% %@CR:MCVc3008@%%@4@%In all three kinds of messages, location is the input file associated with%@EH@% the error. If the input file is an %@AB@%.OBJ%@AE@% or %@AB@%.LIB%@AE@% file and has a module name, the module name is enclosed in parentheses, as shown in the following examples:%@NL@% %@NL@% SLIBC.LIB (_file)%@NL@% MAIN.OBJ (main.c)%@NL@% TEXT.OBJ%@NL@% %@NL@% %@CR:MCVc3009@%%@4@%The following error messages may appear when you link object files with the%@EH@% Microsoft Incremental Linker, %@AB@%ILINK%@AE@%.%@NL@% %@NL@% %@NL@% %@CR:MCVc3100@%%@3@%%@AB@%C.3.1 ILINK Fatal Errors%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE228@%%@4@%%@AB@%L1105 invalid object due to aborted incremental compile%@AE@%%@EH@%%@NL@% %@NL@% Delete the object file, recompile the program, and relink.%@NL@% %@NL@% %@CR:MCVcE229@%%@4@%%@AB@%L1200 .SYM seek error%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.SYM%@AE@% file could not be properly read. Try redoing a full link%@NL@% with the %@AB@%/INCREMENTAL%@AE@% option.%@NL@% %@NL@% %@CR:MCVcE230@%%@4@%%@AB@%L1201 .SYM read error%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.SYM%@AE@% file could not be properly read. Try redoing a full link%@NL@% with the %@AB@%/INCREMENTAL%@AE@% option.%@NL@% %@NL@% %@CR:MCVcE231@%%@4@%%@AB@%L1202 .SYM write error%@AE@%%@EH@%%@NL@% %@NL@% The disk is full or the %@AB@%.SYM%@AE@% file already exists and has the%@NL@% %@AB@%READONLY%@AE@% attribute.%@NL@% %@NL@% %@CR:MCVcE232@%%@4@%%@AB@%L1203 map for segment%@AE@% %@AI@%name%@AE@%%@AB@% exceeds 64K%@AE@%%@EH@%%@NL@% %@NL@% The symbolic information associated with the given segment exceeds%@NL@% 64K bytes, an amount more than %@AB@%ILINK%@AE@% can handle.%@NL@% %@NL@% %@CR:MCVcE233@%%@4@%%@AB@%L1204 .ILK write error%@AE@%%@EH@%%@NL@% %@NL@% The disk is full or the %@AB@%.SYM%@AE@% file already exists and has the%@NL@% %@AB@%READONLY%@AE@% attribute.%@NL@% %@NL@% %@CR:MCVcE234@%%@4@%%@AB@%L1205 fixup overflow at%@AE@% %@AI@%address%@AE@%%@AB@% in segment%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@% %@NL@% A %@AB@%FIXUPP%@AE@% object record with the given location referred to a%@NL@% target too far away to be correctly processed. This messages%@NL@% indicates an error in translation by the compiler or assembler.%@NL@% %@NL@% %@CR:MCVcE235@%%@4@%%@AB@%L1206 .ILK seek error%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.ILK%@AE@% file is corrupted. Do a full link. If the error%@NL@% persists, note the circumstance of the error and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE236@%%@4@%%@AB@%L1207 .ILK file too large%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.ILK%@AE@% file is too large for %@AB@%ILINK%@AE@% to process. Do a full link.%@NL@% %@NL@% %@CR:MCVcE237@%%@4@%%@AB@%L1208 invalid .SYM file%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.SYM%@AE@% file is invalid; delete the file and do a full link. If%@NL@% the problem persists, contact Microsoft Product Support.%@NL@% %@NL@% %@CR:MCVcE238@%%@4@%%@AB@%L1209 .OBJ close error%@AE@%%@EH@%%@NL@% %@NL@% The operating system returned an error when %@AB@%ILINK%@AE@% attempted to%@NL@% close one of the %@AB@%.OBJ%@AE@% files.%@NL@% %@NL@% %@CR:MCVcE239@%%@4@%%@AB@%L1210 .OBJ read error%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.OBJ%@AE@% file has an unreadable structure. Try rebuilding the .OBJ%@NL@% file and doing a full link. This message indicates an error in%@NL@% translation by the compiler or assembler.%@NL@% %@NL@% %@CR:MCVcE240@%%@4@%%@AB@%L1211 too many LNAMES%@AE@%%@EH@%%@NL@% %@NL@% An object module has more than 255 %@AB@%LNAME%@AE@% records.%@NL@% %@NL@% %@CR:MCVcE241@%%@4@%%@AB@%L1212 too many SEGDEFs%@AE@%%@EH@%%@NL@% %@NL@% The given object module has more than 100 %@AB@%SEGDEF%@AE@% records. A SEGDEF%@NL@% record defines logical segments.%@NL@% %@NL@% %@CR:MCVcE242@%%@4@%%@AB@%L1213 too many GRPDEFs%@AE@%%@EH@%%@NL@% %@NL@% The given object module has more than 10 %@AB@%GRPDEF%@AE@% records. A GRPDEF%@NL@% record defines physical segments.%@NL@% %@NL@% %@CR:MCVcE243@%%@4@%%@AB@%L1214 too many COMDEFs%@AE@%%@EH@%%@NL@% %@NL@% The total number of %@AB@%COMDEF%@AE@% and %@AB@%EXTDEF%@AE@% records exceeded the limit.%@NL@% The limit on the total of %@AB@%COMDEF%@AE@% records (communal data variables)%@NL@% and %@AB@%EXTDEF%@AE@% records (external references) is 1,023. Use fewer%@NL@% communal or external variables in your program.%@NL@% %@NL@% %@CR:MCVcE244@%%@4@%%@AB@%L1215 too many EXTDEFs%@AE@%%@EH@%%@NL@% %@NL@% The total number of %@AB@%COMDEF%@AE@% and %@AB@%EXTDEF%@AE@% records exceeded the limit.%@NL@% The limit on the total of %@AB@%COMDEF%@AE@% records (communal data variables)%@NL@% and %@AB@%EXTDEF%@AE@% records (external references) is 1,023. Use fewer%@NL@% communal or external variables in your program.%@NL@% %@NL@% %@CR:MCVcE245@%%@4@%%@AB@%L1216 symbol%@AE@% %@AI@%name%@AE@%%@AB@% multiply defined%@AE@%%@EH@%%@NL@% %@NL@% The given symbol is defined more than once.%@NL@% %@NL@% %@CR:MCVcE246@%%@4@%%@AB@%L1217 internal error #3%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstance of the error and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE247@%%@4@%%@AB@%L1218 .EXE file too big, change alignment%@AE@%%@EH@%%@NL@% %@NL@% The segment-sector alignment value in the %@AB@%.EXE%@AE@% file is too small%@NL@% to express the size of one of the segments. Do a full link and%@NL@% increase the alignment value with the %@AB@%/ALIGNMENT%@AE@% option to %@AB@%LINK%@AE@%.%@NL@% %@NL@% %@CR:MCVcE248@%%@4@%%@AB@%L1219 too many library files%@AE@%%@EH@%%@NL@% %@NL@% The number of libraries exceeded %@AB@%ILINK%@AE@%'s limit of 32 libraries%@NL@% (%@AB@%.LIB%@AE@% files). Reduce the number of libraries.%@NL@% %@NL@% %@CR:MCVcE249@%%@4@%%@AB@%L1220 seek error on library%@AE@%%@EH@%%@NL@% %@NL@% A library (%@AB@%.LIB%@AE@% file) is corrupted. Do a full link and check your%@NL@% %@AB@%.LIB%@AE@% files.%@NL@% %@NL@% %@CR:MCVcE250@%%@4@%%@AB@%L1221 library close error%@AE@%%@EH@%%@NL@% %@NL@% The operating system returned an error when %@AB@%ILINK%@AE@% attempted to%@NL@% close one of the libraries (%@AB@%.LIB%@AE@% files). Do a full link. If the%@NL@% error persists, note the circumstances of the error and notify%@NL@% Microsoft Corporation by following the directions in the Microsoft%@NL@% Product Assistance Request form at the back of one of your%@NL@% manuals.%@NL@% %@NL@% %@CR:MCVcE251@%%@4@%%@AB@%L1222 error closing .EXE file%@AE@%%@EH@%%@NL@% %@NL@% The operating system returned an error when %@AB@%ILINK%@AE@% attempted to%@NL@% close the executable file. Do a full link. If the error persists,%@NL@% contact Microsoft Product Support.%@NL@% %@NL@% %@CR:MCVcE252@%%@4@%%@AB@%L1223 could not update time on%@AE@% %@AI@%file%@AE@%%@EH@%%@NL@% %@NL@% The operating system returned an error when %@AB@%ILINK%@AE@% attempted to%@NL@% update the time on the given file. Possibly the file had the%@NL@% %@AB@%READONLY%@AE@% attribute set.%@NL@% %@NL@% %@CR:MCVcE253@%%@4@%%@AB@%L1224 invalid flag%@AE@% %@AI@%character%@AE@%%@EH@%%@NL@% %@NL@% You used incorrect syntax on the %@AB@%ILINK%@AE@% command line.%@NL@% %@NL@% %@CR:MCVcE254@%%@4@%%@AB@%L1225 only one -e command allowed%@AE@%%@EH@%%@NL@% %@NL@% You used incorrect syntax on the %@AB@%ILINK%@AE@% command line.%@NL@% %@NL@% %@CR:MCVcE255@%%@4@%%@AB@%L1226 terminated by user%@AE@%%@EH@%%@NL@% %@NL@% You pressed CTRL+C or CTRL+BREAK, an action that interrupts and%@NL@% terminates %@AB@%ILINK%@AE@%.%@NL@% %@NL@% %@CR:MCVcE256@%%@4@%%@AB@%L1227 file%@AE@% %@AI@%name%@AE@%%@AB@% write protected%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.EXE%@AE@%, %@AB@%.ILK%@AE@%, or %@AB@%.SYM%@AE@% file that %@AB@%ILINK%@AE@% attempted to update has%@NL@% the %@AB@%READONLY%@AE@% attribute.%@NL@% %@NL@% %@CR:MCVcE257@%%@4@%%@AB@%L1228 file%@AE@% %@AI@%name%@AE@%%@AB@% missing%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ILINK%@AE@% could not find one of the %@AB@%.OBJ%@AE@% files specified on the%@NL@% command line.%@NL@% %@NL@% %@CR:MCVcE258@%%@4@%%@AB@%L1229 invalid.OBJ format%@AE@%%@EH@%%@NL@% %@NL@% There may be one of several problems: error in compiler%@NL@% translation, corrupted object file, invalid object file (possibly%@NL@% text file), or object file could not be read or found.%@NL@% %@NL@% %@CR:MCVcE259@%%@4@%%@AB@%L1230 invalid%@AE@% %@AI@%file%@AE@%%@AB@% record: position =%@AE@% %@AI@%address%@AE@%%@EH@%%@NL@% %@NL@% The given %@AB@%.OBJ%@AE@% file has an invalid format or one unrecognized by%@NL@% %@AB@%ILINK%@AE@%. This message may indicate an error in translation by the%@NL@% compiler or assembler.%@NL@% %@NL@% %@CR:MCVcE260@%%@4@%%@AB@%L1231 file%@AE@% %@AI@%name%@AE@%%@AB@% was not full linked%@AE@%%@EH@%%@NL@% %@NL@% You specified an %@AB@%.OBJ%@AE@% file in the %@AB@%ILINK%@AE@% command line that was not%@NL@% in the list of files in the most recent full link.%@NL@% %@NL@% %@CR:MCVcE261@%%@4@%%@AB@%L1232 cannot run%@AE@% %@AI@%program%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ILINK%@AE@% is unable to execute a program specified for execution with%@NL@% the %@AB@%\e%@AE@% command-line option. Make sure the program is in the search%@NL@% path and is an %@AB@%.EXE%@AE@% or %@AB@%.COM%@AE@% file.%@NL@% %@NL@% %@CR:MCVcE262@%%@4@%%@AB@%L1233%@AE@% %@AI@%program%@AE@%%@AB@% returned%@AE@% %@AI@%return-code%@AE@%%@EH@%%@NL@% %@NL@% The given program was specified with the %@AB@%\e%@AE@% option. When ILINK%@NL@% executed this program, it terminated with the given nonzero return%@NL@% code. %@AB@%ILINK%@AE@% cannot continue to the next commands, if any.%@NL@% %@NL@% %@CR:MCVcE263@%%@4@%%@AB@%L1234 error creating%@AE@% %@AI@%file%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ILINK%@AE@% was unable to create the batch file for executing the %@AB@%\e%@AE@%%@NL@% commands. Make sure the directory given in %@AB@%TMP%@AE@% or %@AB@%TEMP%@AE@%, or the%@NL@% current directory, exists and can be written to.%@NL@% %@NL@% %@CR:MCVcE264@%%@4@%%@AB@%L1235 error writing to%@AE@% %@AI@%file%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ILINK%@AE@% experienced an error while writing the batch file for%@NL@% executing the %@AB@%\e%@AE@% commands. Make sure the drive for %@AB@%TMP%@AE@% or %@AB@%TEMP%@AE@% or%@NL@% the current drive has enough free space.%@NL@% %@NL@% %@CR:MCVcE265@%%@4@%%@AB@%L1240 far references in STRUC fields not supported%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ILINK%@AE@% currently does not support %@AB@%STRUC%@AE@% definitions like this:%@NL@% %@NL@% extrn func:FAR%@NL@% rek STRUC%@NL@% far_adr DD func ; %@AI@%Initialized far address%@AE@%%@NL@% ; %@AI@%within a STRUC%@AE@%%@NL@% rek ENDS%@NL@% %@NL@% To use %@AB@%ILINK%@AE@%, change your code to get rid of the far address%@NL@% within the %@AB@%STRUC%@AE@%.%@NL@% %@NL@% %@CR:MCVcE266@%%@4@%%@AB@%L1241 too many defined segments%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ILINK%@AE@% has a limit of 255 physical segments (that is, segments%@NL@% defined in the object module as opposed to groups or logical%@NL@% segments). To use %@AB@%ILINK%@AE@%, reduce the number of segments.%@NL@% %@NL@% %@CR:MCVcE267@%%@4@%%@AB@%L1242 too many modules%@AE@%%@EH@%%@NL@% %@NL@% The program exceeds %@AB@%ILINK%@AE@%'s limit of 1,204 modules. Reduce the%@NL@% number of modules.%@NL@% %@NL@% %@CR:MCVcE268@%%@4@%%@AB@%L1243 cannot link 64K-length segments%@AE@%%@EH@%%@NL@% %@NL@% The program has a segment larger than 65,535 bytes.%@NL@% %@NL@% %@CR:MCVcE269@%%@4@%%@AB@%L1244 cannot link iterated segments%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ILINK%@AE@% cannot handle programs linked with the %@AB@%/EXEPACK%@AE@% linker%@NL@% option.%@NL@% %@NL@% %@NL@% %@CR:MCVc3200@%%@3@%%@AB@%C.3.2 Incremental Violations%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE270@%%@4@%%@AB@%L1250%@AE@% %@AI@%number%@AE@%%@AB@% undefined symbols%@AE@%%@EH@%%@NL@% %@NL@% A number of symbols were referred to in fixups but never publicly%@NL@% defined in the program. The given number indicates how many of%@NL@% these undefined symbols were found.%@NL@% %@NL@% %@CR:MCVcE271@%%@4@%%@AB@%L1251 invalid module reference%@AE@% %@AI@%library%@AE@%%@EH@%%@NL@% %@NL@% The program makes a dynamic-link reference to a dynamic-link%@NL@% library that is not recognized or declared by the %@AB@%.EXE%@AE@% file.%@NL@% %@NL@% %@CR:MCVcE272@%%@4@%%@AB@%L1252 file%@AE@% %@AI@%name%@AE@%%@AB@% does not exist%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ILINK%@AE@% could not find the given file required for %@AB@%ILINK%@AE@% operation.%@NL@% %@NL@% %@CR:MCVcE273@%%@4@%%@AB@%L1253 symbol%@AE@% %@AI@%name%@AE@%%@AB@% deleted%@AE@%%@EH@%%@NL@% %@NL@% A symbol was deleted from an incrementally linked module.%@NL@% %@NL@% %@CR:MCVcE274@%%@4@%%@AB@%L1254 new segment definition%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@% %@NL@% A segment was added to the program.%@NL@% %@NL@% %@CR:MCVcE275@%%@4@%%@AB@%L1255 changed segment definition%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@% %@NL@% The segment contribution changed for the given module; it%@NL@% contributed to a segment it did not previously contribute to, or a%@NL@% segment contribution was removed.%@NL@% %@NL@% %@CR:MCVcE276@%%@4@%%@AB@%L1256 segment%@AE@% %@AI@%name%@AE@%%@AB@% grew too big%@AE@%%@EH@%%@NL@% %@NL@% The given segment grew beyond the padding for the given module.%@NL@% %@NL@% %@CR:MCVcE277@%%@4@%%@AB@%L1257 new group definition%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@% %@NL@% A new group was defined via the %@AB@%GROUP%@AE@% directive in assembly%@NL@% language or via the %@AB@%\ND%@AE@% C compiler option.%@NL@% %@NL@% %@CR:MCVcE278@%%@4@%%@AB@%L1258 group%@AE@% %@AI@%name%@AE@%%@AB@% changed to include%@AE@% %@AI@%segment%@AE@%%@EH@%%@NL@% %@NL@% The list of segments included in the given group changed.%@NL@% %@NL@% %@CR:MCVcE279@%%@4@%%@AB@%L1259 symbol%@AE@% %@AI@%name%@AE@%%@AB@% changed%@AE@%%@EH@%%@NL@% %@NL@% The given data symbol moved (is now at a new address).%@NL@% %@NL@% %@CR:MCVcE280@%%@4@%%@AB@%L1260 cannot add new communal data symbol%@AE@% %@AI@%name%@AE@%%@EH@%%@NL@% %@NL@% A new communal data symbol was added as an uninitialized variable%@NL@% in C or with the %@AB@%COMM%@AE@% feature in %@AB@%MASM%@AE@%.%@NL@% %@NL@% %@CR:MCVcE281@%%@4@%%@AB@%L1261 communal variable%@AE@% %@AI@%name%@AE@%%@AB@% grew too big%@AE@%%@EH@%%@NL@% %@NL@% The given communal variable changed size too much.%@NL@% %@NL@% %@CR:MCVcE282@%%@4@%%@AB@%L1262 invalid symbol type for%@AE@% %@AI@%symbol%@AE@%%@EH@%%@NL@% %@NL@% A symbol which was previously a code symbol became a data symbol%@NL@% or vice versa.%@NL@% %@NL@% %@CR:MCVcE283@%%@4@%%@AB@%L1263 new Codeview symbolic info%@AE@%%@EH@%%@NL@% %@NL@% A module previously compiled without %@AB@%\Zi%@AE@% was compiled with %@AB@%\Zi%@AE@%.%@NL@% %@NL@% %@CR:MCVcE284@%%@4@%%@AB@%L1264 new line-number info%@AE@%%@EH@%%@NL@% %@NL@% A module previously compiled without %@AB@%\Zi%@AE@% or %@AB@%\Zd%@AE@% was compiled with%@NL@% %@AB@%\Zi%@AE@% or %@AB@%\Zd%@AE@%.%@NL@% %@NL@% %@CR:MCVcE285@%%@4@%%@AB@%L1265 new public CodeView info%@AE@%%@EH@%%@NL@% %@NL@% New information on public symbol addresses was added.%@NL@% %@NL@% %@CR:MCVcE286@%%@4@%%@AB@%L1266 invalid .EXE file%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.EXE%@AE@% file is invalid. Make sure you are using an up-to-date%@NL@% linker. If the error persists, note the circumstances of the error%@NL@% and notify Microsoft Corporation by following the directions in%@NL@% the Microsoft Product Assistance Request form at the back of one%@NL@% of your manuals.%@NL@% %@NL@% %@CR:MCVcE287@%%@4@%%@AB@%L1267 invalid .ILK file%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.ILK%@AE@% file is invalid. Make sure you are using an up-to-date%@NL@% linker. If the error persists, notify Microsoft Corporation by%@NL@% following the directions in the Microsoft Product Assistance%@NL@% Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE288@%%@4@%%@AB@%L1268 .SYM/.ILK mismatch%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.SYM%@AE@% and %@AB@%.ILK%@AE@% files are out of sync. Make sure you are using%@NL@% an up-to-date linker. If the error persists, note the%@NL@% circumstances of the error and notify Microsoft Corporation by%@NL@% following the directions in the Microsoft Product Assistance%@NL@% Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE289@%%@4@%%@AB@%L1269 library%@AE@% %@AI@%name%@AE@%%@AB@% has changed%@AE@%%@EH@%%@NL@% %@NL@% The given library has changed.%@NL@% %@NL@% %@CR:MCVcE290@%%@4@%%@AB@%L1270 entry table expansion not implemented%@AE@%%@EH@%%@NL@% %@NL@% The program call tree changed in such a way that %@AB@%ILINK%@AE@% could not%@NL@% process it correctly. This problem is caused by new calls to a%@NL@% routine from another routine that did not call it before. Do a%@NL@% full link.%@NL@% %@NL@% %@CR:MCVcE291@%%@4@%%@AB@%L1271 segment%@AE@% %@AI@%index%@AE@%%@AB@% with relocs exceeds 64K; cannot move%@AE@%%@EH@%%@NL@% %@NL@% The given segment, referred to by its index within the program's%@NL@% segment table, is too big along with its runtime relocations for%@NL@% %@AB@%ILINK%@AE@% to process the segment correctly.%@NL@% %@NL@% %@CR:MCVcE292@%%@4@%%@AB@%L1272 .ILK read error%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.ILK%@AE@% file does not exist or was not in the expected format.%@NL@% %@NL@% %@CR:MCVcE293@%%@4@%%@AB@%L1273 out of memory%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%ILINK%@AE@% ran out of memory for processing the input. If you are%@NL@% running %@AB@%ILINK%@AE@% while using the %@AB@%NMAKE%@AE@% utility, try running ILINK%@NL@% from the shell (that is, directly from the operating-system%@NL@% prompt). Otherwise, do a full link.%@NL@% %@NL@% %@NL@% %@CR:MCVc3300@%%@3@%%@AB@%C.3.3 ILINK Warning Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE294@%%@4@%%@AB@%L4201 fixup frame relative to an (as yet) undefined symbol - assuming%@AE@%%@EH@%%@NL@% %@AB@%ok%@AE@%%@NL@% %@NL@% See documentation for %@AB@%LINK%@AE@% error messages L4001 and L4002.%@NL@% %@NL@% %@CR:MCVcE295@%%@4@%%@AB@%L4202 module contains TYPEDEFs - ignored%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.OBJ%@AE@% file contains type definitions. %@AB@%ILINK%@AE@% ignores these%@NL@% records.%@NL@% %@NL@% %@CR:MCVcE296@%%@4@%%@AB@%L4203 module contains BLKDEFs - ignored%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%.OBJ%@AE@% file contains records no longer supported by Microsoft%@NL@% language compilers.%@NL@% %@NL@% %@CR:MCVcE297@%%@4@%%@AB@%L4204 old .EXE free information lost%@AE@%%@EH@%%@NL@% %@NL@% The free list in the %@AB@%.EXE%@AE@% file has been corrupted. The free list%@NL@% represents "holes" in the %@AB@%EXE%@AE@% file made available when segments%@NL@% moved to new locations.%@NL@% %@NL@% %@CR:MCVcE298@%%@4@%%@AB@%L4205 file%@AE@% %@AI@%name%@AE@%%@AB@% has no useful contribution%@AE@%%@EH@%%@NL@% %@NL@% The given module makes no contribution to any segment.%@NL@% %@NL@% %@CR:MCVcE299@%%@4@%%@AB@%L4206 main entry point moved%@AE@%%@EH@%%@NL@% %@NL@% The program starting address changed. You may want to consider%@NL@% doing a full link.%@NL@% %@NL@% %@NL@% %@CR:MCVc4000@%%@2@%%@AB@%C.4 LIB Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVc4001@%%@4@%Error messages generated by the Microsoft Library Manager, LIB, have one of%@EH@% the following formats:%@NL@% %@NL@% {%@AI@%filename%@AE@%| %@AS@%LIB%@AE@%} : %@AS@%fatal error U1%@AE@%%@AI@%xxx%@AE@%: %@AI@%messagetext%@AE@%%@NL@% {%@AI@%filename%@AE@%| %@AS@%LIB%@AE@%} : %@AS@%nonfatal error U2%@AE@%%@AI@%xxx%@AE@%: %@AI@%messagetext%@AE@%%@NL@% {%@AI@%filename%@AE@%| %@AS@%LIB%@AE@%} : %@AS@%warning U4%@AE@%%@AI@%xxx%@AE@%: %@AI@%messagetext%@AE@%%@NL@% %@NL@% %@CR:MCVc4002@%%@4@%The message begins with the input-file name (%@AI@%filename%@AE@%), if one exists, or%@EH@% with the name of the utility. If possible, %@AB@%LIB%@AE@% prints a warning and continues operation. In some cases errors are fatal, and %@AB@%LIB%@AE@% terminates processing. %@AB@%LIB%@AE@% may display the following error messages.%@NL@% %@NL@% %@NL@% %@CR:MCVc4100@%%@3@%%@AB@%C.4.1 Fatal LIB Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE300@%%@4@%%@AB@%U1150 page size too small%@AE@%%@EH@%%@NL@% %@NL@% The page size of an input library was too small, indicating an%@NL@% invalid input %@AB@%.LIB%@AE@% file.%@NL@% %@NL@% %@CR:MCVcE301@%%@4@%%@AB@%U1151 syntax error : illegal file specification%@AE@%%@EH@%%@NL@% %@NL@% A command operator such as a minus sign (%@AB@%-%@AE@%) was given without a%@NL@% following module name.%@NL@% %@NL@% %@CR:MCVcE302@%%@4@%%@AB@%U1152 syntax error : option name missing%@AE@%%@EH@%%@NL@% %@NL@% A forward slash (%@AB@%/%@AE@%) was given without an option after it.%@NL@% %@NL@% %@CR:MCVcE303@%%@4@%%@AB@%U1153 syntax error : option value missing%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%/PAGESIZE%@AE@% option was given without a value following it.%@NL@% %@NL@% %@CR:MCVcE304@%%@4@%%@AB@%U1154 option unknown%@AE@%%@EH@%%@NL@% %@NL@% An unknown option was given. Currently, %@AB@%LIB%@AE@% recognizes the%@NL@% %@AB@%/PAGESIZE%@AE@%, %@AB@%/NOIGNORECASE%@AE@%, and %@AB@%/IGNORECASE%@AE@% options.%@NL@% %@NL@% %@CR:MCVcE305@%%@4@%%@AB@%U1155 syntax error : illegal input%@AE@%%@EH@%%@NL@% %@NL@% The given command did not follow correct %@AB@%LIB%@AE@% syntax as specified%@NL@% in Chapter 15%@BO: a2cc3@%, "Managing Libraries with LIB."%@NL@% %@NL@% %@CR:MCVcE306@%%@4@%%@AB@%U1156 syntax error%@AE@%%@EH@%%@NL@% %@NL@% The given command did not follow the correct %@AB@%LIB%@AE@% syntax as%@NL@% specified in Chapter 15%@BO: a2cc3@%, "Managing Libraries with LIB."%@NL@% %@NL@% %@CR:MCVcE307@%%@4@%%@AB@%U1157 comma or new line missing%@AE@%%@EH@%%@NL@% %@NL@% A comma or carriage return was expected in the command line but%@NL@% did not appear. This may indicate an incorrectly placed comma, as%@NL@% in the following line:%@NL@% %@NL@% LIB math.lib,-mod1+mod2;%@NL@% %@NL@% The line should have been entered as follows:%@NL@% %@NL@% LIB math.lib -mod1+mod2;%@NL@% %@NL@% %@CR:MCVcE308@%%@4@%%@AB@%U1158 terminator missing%@AE@%%@EH@%%@NL@% %@NL@% Either the response to the %@AS@%Output library%@AE@% prompt or the last line%@NL@% of the response file used to start %@AB@%LIB%@AE@% did not end with a carriage%@NL@% return.%@NL@% %@NL@% %@CR:MCVcE309@%%@4@%%@AB@%U1161 cannot rename old library%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%LIB%@AE@% could not rename the old library to have a %@AB@%.BAK%@AE@% extension%@NL@% because the %@AB@%.BAK%@AE@% version already existed with read only%@NL@% protection.%@NL@% %@NL@% Change the protection on the old %@AB@%.BAK%@AE@% version.%@NL@% %@NL@% %@CR:MCVcE310@%%@4@%%@AB@%U1162 cannot reopen library%@AE@%%@EH@%%@NL@% %@NL@% The old library could not be reopened after it was renamed to have%@NL@% a %@AB@%.BAK%@AE@% extension.%@NL@% %@NL@% %@CR:MCVcE311@%%@4@%%@AB@%U1163 error writing to cross-reference file%@AE@%%@EH@%%@NL@% %@NL@% The disk or root directory was full.%@NL@% %@NL@% Delete or move files to make space.%@NL@% %@NL@% %@CR:MCVcE312@%%@4@%%@AB@%U1170 too many symbols%@AE@%%@EH@%%@NL@% %@NL@% More than 4,609 symbols appeared in the library file.%@NL@% %@NL@% %@CR:MCVcE313@%%@4@%%@AB@%U1171 insufficient memory%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%LIB%@AE@% did not have enough memory to run.%@NL@% %@NL@% Remove any shells or resident programs and try again, or add more%@NL@% memory.%@NL@% %@NL@% %@CR:MCVcE314@%%@4@%%@AB@%U1172 no more virtual memory%@AE@%%@EH@%%@NL@% %@NL@% Try using the %@AB@%/NOEXTDICTIONARY%@AE@%. The current library exceeds the%@NL@% 512K byte limit imposed by %@AB@%LIB%@AE@% option. Try using the%@NL@% %@AB@%/NOEXITDICTIONARY%@AE@% or reduce the number of object modules.%@NL@% %@NL@% %@CR:MCVcE315@%%@4@%%@AB@%U1173 internal failure%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the failure and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE316@%%@4@%%@AB@%U1174 mark: not allocated%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the failure and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE317@%%@4@%%@AB@%U1175 free: not allocated%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the error and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE318@%%@4@%%@AB@%U1180 write to extract file failed%@AE@%%@EH@%%@NL@% %@NL@% The disk or root directory was full.%@NL@% %@NL@% Delete or move files to make space.%@NL@% %@NL@% %@CR:MCVcE319@%%@4@%%@AB@%U1181 write to library file failed%@AE@%%@EH@%%@NL@% %@NL@% The disk or root directory was full.%@NL@% %@NL@% Delete or move files to make space.%@NL@% %@NL@% %@CR:MCVcE320@%%@4@%%@AB@%U1182%@AE@% %@AI@%filename%@AE@%%@AB@% : cannot create extract file%@AE@%%@EH@%%@NL@% %@NL@% The disk or root directory was full, or the specified extract file%@NL@% already existed with read-only protection.%@NL@% %@NL@% Make space on the disk or change the protection of the extract%@NL@% file.%@NL@% %@NL@% %@CR:MCVcE321@%%@4@%%@AB@%U1183 cannot open response file%@AE@%%@EH@%%@NL@% %@NL@% The response file was not found.%@NL@% %@NL@% %@CR:MCVcE322@%%@4@%%@AB@%U1184 unexpected end-of-file on command input%@AE@%%@EH@%%@NL@% %@NL@% An end-of-file character was received prematurely in response to a%@NL@% prompt.%@NL@% %@NL@% %@CR:MCVcE323@%%@4@%%@AB@%U1185 cannot create new library%@AE@%%@EH@%%@NL@% %@NL@% The disk or root directory was full, or the library file already%@NL@% existed with read-only protection.%@NL@% %@NL@% Make space on the disk or change the protection of the library%@NL@% file.%@NL@% %@NL@% %@CR:MCVcE324@%%@4@%%@AB@%U1186 error writing to new library%@AE@%%@EH@%%@NL@% %@NL@% The disk or root directory was full.%@NL@% %@NL@% Delete or move files to make space.%@NL@% %@NL@% %@CR:MCVcE325@%%@4@%%@AB@%U1187 cannot open VM.TMP%@AE@%%@EH@%%@NL@% %@NL@% The disk or root directory was full.%@NL@% %@NL@% Delete or move files to make space.%@NL@% %@NL@% %@CR:MCVcE326@%%@4@%%@AB@%U1188 cannot write to VM%@AE@%%@EH@%%@NL@% %@NL@% The library manager cannot write to the virtual memory. Note the%@NL@% circumstances of the failure and notify Microsoft Corporation by%@NL@% following the directions in the Microsoft Product Assistance%@NL@% Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE327@%%@4@%%@AB@%U1189 cannot read from VM%@AE@%%@EH@%%@NL@% %@NL@% The library manager cannot read the virtual memory. Note the%@NL@% circumstances of the error and notify Microsoft Corporation by%@NL@% following the directions in the Microsoft Product Assistance%@NL@% Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE328@%%@4@%%@AB@%U1190 interrupted by user%@AE@%%@EH@%%@NL@% %@NL@% You interrupted %@AB@%LIB%@AE@% during its operation, with CTRL+C or%@NL@% CTRL+BREAK.%@NL@% %@NL@% %@CR:MCVcE329@%%@4@%%@AB@%U1200%@AE@% %@AI@%name%@AE@%%@AB@% : invalid library header%@AE@%%@EH@%%@NL@% %@NL@% The input library file had an invalid format. It was either not a%@NL@% library file or it had been corrupted.%@NL@% %@NL@% %@CR:MCVcE330@%%@4@%%@AB@%U1203%@AE@% %@AI@%name%@AE@%%@AB@% : invalid object module near%@AE@% %@AI@%location%@AE@%%@EH@%%@NL@% %@NL@% The module specified by %@AI@%name%@AE@% was not a valid object module.%@NL@% %@NL@% %@NL@% %@CR:MCVc4200@%%@3@%%@AB@%C.4.2 Nonfatal LIB Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE331@%%@4@%%@AB@%U2152%@AE@% %@AI@%filename%@AE@%%@AB@% : cannot create listing%@AE@%%@EH@%%@NL@% %@NL@% The directory or disk was full, or the cross-reference-listing%@NL@% file already existed with read-only protection.%@NL@% %@NL@% Make space on the disk or change the protection of the%@NL@% cross-reference-listing file.%@NL@% %@NL@% %@CR:MCVcE332@%%@4@%%@AB@%U2155%@AE@% %@AI@%modulename%@AE@%%@AB@% : module not in library; ignored%@AE@%%@EH@%%@NL@% %@NL@% The specified module was not found in the input library.%@NL@% %@NL@% %@CR:MCVcE333@%%@4@%%@AB@%U2157%@AE@% %@AI@%filename%@AE@%%@AB@% : cannot access file%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%LIB%@AE@% was unable to open the specified file.%@NL@% %@NL@% %@CR:MCVcE334@%%@4@%%@AB@%U2158%@AE@% %@AI@%libraryname%@AE@%%@AB@% : invalid library header; file ignored%@AE@%%@EH@%%@NL@% %@NL@% The input library had an incorrect format.%@NL@% %@NL@% %@CR:MCVcE335@%%@4@%%@AB@%U2159%@AE@% %@AI@%filename%@AE@%%@AB@% : invalid format%@AE@% %@AI@%hexnumber%@AE@%%@AB@%; file ignored%@AE@%%@EH@%%@NL@% %@NL@% The signature byte or word hexnumber of the given file was not one%@NL@% of the following recognized types: Microsoft library, Intel%@NL@% library, Microsoft object, or Xenix archive.%@NL@% %@NL@% %@NL@% %@CR:MCVc4300@%%@3@%%@AB@%C.5.3 Warning LIB Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE336@%%@4@%%@AB@%U4150%@AE@% %@AI@%modulename%@AE@%%@AB@% : module redefinition ignored%@AE@%%@EH@%%@NL@% %@NL@% A module was specified to be added to a library but a module with%@NL@% the same name was already in the library, or a module with the%@NL@% same name was found more than once in the library.%@NL@% %@NL@% %@CR:MCVcE337@%%@4@%%@AB@%U4151%@AE@% %@AI@%name%@AE@%%@AB@% : symbol defined in%@AE@% %@AI@%modulename%@AE@%%@AB@%, redefinition ignored%@AE@%%@EH@%%@NL@% %@NL@% The specified symbol was defined in more than one module.%@NL@% %@NL@% %@CR:MCVcE338@%%@4@%%@AB@%U4153%@AE@% %@AI@%number%@AE@%%@AB@% : page size too small; ignored%@AE@%%@EH@%%@NL@% %@NL@% The value specified in the %@AB@%/PAGESIZE%@AE@% option was less than 16.%@NL@% %@NL@% %@CR:MCVcE339@%%@4@%%@AB@%U4155%@AE@% %@AI@%modulename%@AE@%%@AB@% : module not in library%@AE@%%@EH@%%@NL@% %@NL@% A module specified to be replaced does not already exist in the%@NL@% library. %@AB@%LIB%@AE@% adds the module anyway.%@NL@% %@NL@% %@CR:MCVcE340@%%@4@%%@AB@%U4156%@AE@% %@AI@%libraryname%@AE@%%@AB@% : output-library specification ignored%@AE@%%@EH@%%@NL@% %@NL@% An output library was specified in addition to a new library name.%@NL@% For example, specifying%@NL@% %@NL@% LIB new.lib+one.obj,new.lst,new.lib%@NL@% %@NL@% where %@AS@%new.lib%@AE@% does not already exist, causes this error.%@NL@% %@NL@% %@CR:MCVcE341@%%@4@%%@AB@%U4157 insufficient memory, extended dictionary not created%@AE@%%@EH@%%@NL@% %@NL@% Insufficient memory prevented %@AB@%LIB%@AE@% from creating an extended%@NL@% dictionary. The library is still valid, but the linker will not be%@NL@% able to take advantage of the extended dictionary to speed%@NL@% linking.%@NL@% %@NL@% %@CR:MCVcE342@%%@4@%%@AB@%U4158 internal error, extended dictionary not created%@AE@%%@EH@%%@NL@% %@NL@% An internal error prevented %@AB@%LIB%@AE@% from creating an extended%@NL@% dictionary. The library is still valid, but the linker will not be%@NL@% able to take advantage of the extended dictionary to speed%@NL@% linking.%@NL@% %@NL@% %@NL@% %@CR:MCVc5000@%%@2@%%@AB@%C.5 NMAKE Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVc5001@%%@4@%Error messages from the NMAKE utility have one of the following formats:%@EH@%%@NL@% %@NL@% {%@AI@%filename%@AE@% | %@AS@%NMAKE%@AE@%} : %@AS@%fatal error U1%@AE@%%@AI@%xxx%@AE@%: %@AI@%messagetext%@AE@%%@NL@% {%@AI@%filename%@AE@% | %@AS@%NMAKE%@AE@%} : %@AS@%warning U4%@AE@%%@AI@%xxx%@AE@%: %@AI@%messagetext%@AE@%%@NL@% %@NL@% %@CR:MCVc5002@%%@4@%The message begins with the input-file name (%@AI@%filename%@AE@%) and line number, if%@EH@% one exists, or with the name of the utility.%@NL@% %@NL@% %@CR:MCVc5003@%%@4@%NMAKE generates the following error messages.%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCVc5100@%%@3@%%@AB@%C.5.1 Fatal NMAKE Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE343@%%@4@%%@AB@%U1000 syntax error: ')' missing in macro invocation%@AE@%%@EH@%%@NL@% %@NL@% A left parenthesis (%@AS@%(%@AE@%) appeared without a matching right%@NL@% parenthesis (%@AS@%)%@AE@%) in a macro invocation. The correct form is%@NL@% $(%@AI@%name%@AE@%), or $%@AI@%n%@AE@% for one-character names.%@NL@% %@NL@% %@CR:MCVcE344@%%@4@%%@AB@%U1001 syntax error : illegal character '%@AE@%%@AI@%character%@AE@%%@AB@%' in macro%@AE@%%@EH@%%@NL@% %@NL@% A nonalphanumeric character other than an underscore (%@AB@%_%@AE@%) appeared%@NL@% in a macro.%@NL@% %@NL@% %@CR:MCVcE345@%%@4@%%@AB@%U1002 syntax error : bad macro invocation '$'%@AE@%%@EH@%%@NL@% %@NL@% A single dollar sign (%@AB@%$%@AE@%) appeared without a macro name associated%@NL@% with it. The correct form is $(%@AI@%name%@AE@%). To use a dollar sign in the%@NL@% file, type it twice or precede it with a caret (%@AB@%^%@AE@%).%@NL@% %@NL@% %@CR:MCVcE346@%%@4@%%@AB@%U1003 syntax error : '=' missing in macro%@AE@%%@EH@%%@NL@% %@NL@% The equal sign (%@AB@%=%@AE@%) was missing in a macro definition. The correct%@NL@% form is '%@AI@%name%@AE@% = %@AI@%value%@AE@%'.%@NL@% %@NL@% %@CR:MCVcE347@%%@4@%%@AB@%U1004 syntax error : macro name missing%@AE@%%@EH@%%@NL@% %@NL@% A macro invocation appeared without a name. The correct form is%@NL@% $(%@AI@%name%@AE@%).%@NL@% %@NL@% %@CR:MCVcE348@%%@4@%%@AB@%U1005 syntax error : text must follow ':' in macro%@AE@%%@EH@%%@NL@% %@NL@% A string substitution was specified for a macro, but the string to%@NL@% be changed in the macro was not specified.%@NL@% %@NL@% %@CR:MCVcE349@%%@4@%%@AB@%U1016 syntax error : closing '"' missing%@AE@%%@EH@%%@NL@% %@NL@% An opening double quotation mark (%@AB@%"%@AE@%) appeared without a closing%@NL@% double quotation mark.%@NL@% %@NL@% %@CR:MCVcE350@%%@4@%%@AB@%U1017 unknown directive '%@AE@%%@AI@%directive%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% The directive specified is not one of the recognized directives.%@NL@% %@NL@% %@CR:MCVcE351@%%@4@%%@AB@%U1018 directive and/or expression part missing%@AE@%%@EH@%%@NL@% %@NL@% The directive is incompletely specified. The expression part is%@NL@% required.%@NL@% %@NL@% %@CR:MCVcE352@%%@4@%%@AB@%U1019 too many nested if blocks%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the failure and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE353@%%@4@%%@AB@%U1020 EOF found before next directive%@AE@%%@EH@%%@NL@% %@NL@% A directive, such as %@AB@%!ENDIF%@AE@%, was missing.%@NL@% %@NL@% %@CR:MCVcE354@%%@4@%%@AB@%U1021 syntax error : else unexpected%@AE@%%@EH@%%@NL@% %@NL@% An %@AB@%!ELSE%@AE@% directive was found that was not preceded by %@AB@%!IF%@AE@%, %@AB@%!IFDEF%@AE@%,%@NL@% or %@AB@%!IFNDEF%@AE@%, or was placed in a syntactically incorrect place.%@NL@% %@NL@% %@CR:MCVcE355@%%@4@%%@AB@%U1022 Missing terminating char for string/program invocation :%@AE@%%@EH@%%@NL@% '%@AI@%character%@AE@%'%@NL@% %@NL@% The closing double quotation mark (%@AB@%"%@AE@%) in a string comparison in a%@NL@% directive was missing, or the closing bracket (%@AB@%]%@AE@%) in a program%@NL@% invocation in a directive was missing.%@NL@% %@NL@% %@CR:MCVcE356@%%@4@%%@AB@%U1023 syntax error present in expression%@AE@%%@EH@%%@NL@% %@NL@% An expression is invalid. Check the allowed operators and operator%@NL@% precedence.%@NL@% %@NL@% %@CR:MCVcE357@%%@4@%%@AB@%U1024 illegal argument to !CMDSWITCHES%@AE@%%@EH@%%@NL@% %@NL@% An unrecognized command switch was specified.%@NL@% %@NL@% %@CR:MCVcE358@%%@4@%%@AB@%U1031 file name missing%@AE@%%@EH@%%@NL@% %@NL@% An include directive was found, but the name of the file to%@NL@% include was missing.%@NL@% %@NL@% %@CR:MCVcE359@%%@4@%%@AB@%U1033 syntax error : '%@AE@%%@AI@%string%@AE@%%@AB@%' unexpected%@AE@%%@EH@%%@NL@% %@NL@% The specified string is not part of the valid syntax for a%@NL@% makefile.%@NL@% %@NL@% %@CR:MCVcE360@%%@4@%%@AB@%U1034 syntax error : separator missing%@AE@%%@EH@%%@NL@% %@NL@% The colon (%@AB@%:%@AE@%) that separates target(s) and dependent(s) is%@NL@% missing.%@NL@% %@NL@% %@CR:MCVcE361@%%@4@%%@AB@%U1035 syntax error : expected separator or '='%@AE@%%@EH@%%@NL@% %@NL@% Either a colon (%@AB@%:%@AE@%), implying a dependency line, or an equal sign%@NL@% (%@AB@%=%@AE@%), implying a macro definition, was expected.%@NL@% %@NL@% %@CR:MCVcE362@%%@4@%%@AB@%U1036 syntax error : too many names to left of '='%@AE@%%@EH@%%@NL@% %@NL@% Only one string is allowed to the left of a macro definition.%@NL@% %@NL@% %@CR:MCVcE363@%%@4@%%@AB@%U1037 syntax error : target name missing%@AE@%%@EH@%%@NL@% %@NL@% A colon (%@AB@%:%@AE@%) was found before a target name was found. At least one%@NL@% target is required.%@NL@% %@NL@% %@CR:MCVcE364@%%@4@%%@AB@%U1038 internal error : lexer%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the failure and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE365@%%@4@%%@AB@%U1039 internal error : parser%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the failure and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE366@%%@4@%%@AB@%U1040 internal error : macro-expansion%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the failure and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE367@%%@4@%%@AB@%U1041 internal error : target building%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the failure and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE368@%%@4@%%@AB@%U1042 internal error : expression stack overflow%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the failure and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE369@%%@4@%%@AB@%U1043 internal error : temp file limit exceeded%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the failure and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE370@%%@4@%%@AB@%U1044 internal error : too many levels of recursion building a target%@AE@%%@EH@%%@NL@% %@NL@% Note the circumstances of the failure and notify Microsoft%@NL@% Corporation by following the directions in the Microsoft Product%@NL@% Assistance Request form at the back of one of your manuals.%@NL@% %@NL@% %@CR:MCVcE371@%%@4@%%@AB@%U1050%@AE@% %@AI@%user-specified text%@AE@%%@EH@%%@NL@% %@NL@% The message specified with the %@AB@%!ERROR%@AE@% directive is displayed.%@NL@% %@NL@% %@CR:MCVcE372@%%@4@%%@AB@%U1051 '%@AE@%%@AI@%progname%@AE@%%@AB@%' usage : [-acdeinpqrst -f makefile -x stderrfile]%@AE@%%@EH@%%@NL@% %@AB@%[macrodefs] [targets]%@AE@%%@NL@% %@NL@% An error was made trying to invoke %@AB@%NMAKE%@AE@%.%@NL@% %@NL@% Use the specified form.%@NL@% %@NL@% %@CR:MCVcE373@%%@4@%%@AB@%U1052 out of memory%@AE@%%@EH@%%@NL@% %@NL@% The program ran out of space in the far heap. Split the%@NL@% description into smaller and simpler pieces.%@NL@% %@NL@% %@CR:MCVcE374@%%@4@%%@AB@%U1053 file '%@AE@%%@AI@%filename%@AE@%%@AB@%' not found%@AE@%%@EH@%%@NL@% %@NL@% The file was not found. The file name might not be properly%@NL@% specified in the makefile.%@NL@% %@NL@% %@CR:MCVcE375@%%@4@%%@AB@%U1054 file '%@AE@%%@AI@%filename%@AE@%%@AB@%' unreadable%@AE@%%@EH@%%@NL@% %@NL@% The file cannot be read. The file might not have the appropriate%@NL@% attributes for reading.%@NL@% %@NL@% %@CR:MCVcE376@%%@4@%%@AB@%U1055 can't create response file '%@AE@%%@AI@%filename%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% The response file cannot be created.%@NL@% %@NL@% %@CR:MCVcE377@%%@4@%%@AB@%U1056 out of environment space%@AE@%%@EH@%%@NL@% %@NL@% The environment space limit was reached.%@NL@% %@NL@% Restart the program with a larger environment space.%@NL@% %@NL@% %@CR:MCVcE378@%%@4@%%@AB@%U1057 can't find command.com%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%COMMAND.COM%@AE@% file could not be found.%@NL@% %@NL@% %@CR:MCVcE379@%%@4@%%@AB@%U1058 unlink of file '%@AE@%%@AI@%filename%@AE@%%@AB@%' failed%@AE@%%@EH@%%@NL@% %@NL@% Unlink of the temporary response file failed.%@NL@% %@NL@% %@CR:MCVcE380@%%@4@%%@AB@%U1059 terminated by user%@AE@%%@EH@%%@NL@% %@NL@% Execution of %@AB@%NMAKE%@AE@% aborted because you typed CTRL+C or CTRL+BREAK.%@NL@% %@NL@% %@CR:MCVcE381@%%@4@%%@AB@%U1070 cycle in macro definition '%@AE@%%@AI@%macroname%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% A circular definition was detected in the macro definition%@NL@% specified. This is an invalid definition.%@NL@% %@NL@% %@CR:MCVcE382@%%@4@%%@AB@%U1071 cycle in dependency tree for target '%@AE@%%@AI@%targetname%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% A circular dependency was detected in the dependency tree for the%@NL@% specified target. This is invalid.%@NL@% %@NL@% %@CR:MCVcE383@%%@4@%%@AB@%U1072 cycle in include files%@AE@% %@AI@%filenames%@AE@%%@EH@%%@NL@% %@NL@% A circular inclusion was detected in the include files specified.%@NL@% That is, each file includes the other.%@NL@% %@NL@% %@CR:MCVcE384@%%@4@%%@AB@%U1073 don't know how to make '%@AE@%%@AI@%targetname%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% The specified target does not exist and there are no commands to%@NL@% execute or inference rules given for it. Hence it cannot be built.%@NL@% %@NL@% %@CR:MCVcE385@%%@4@%%@AB@%U1074 macro definition too long%@AE@%%@EH@%%@NL@% %@NL@% The macro definition is too long.%@NL@% %@NL@% %@CR:MCVcE386@%%@4@%%@AB@%U1075 string too long%@AE@%%@EH@%%@NL@% %@NL@% The text string would overflow an internal buffer.%@NL@% %@NL@% %@CR:MCVcE387@%%@4@%%@AB@%U1076 name too long%@AE@%%@EH@%%@NL@% %@NL@% The macro name, target name, or build-command name would overflow%@NL@% an internal buffer. Macro names may be at most 128 characters.%@NL@% %@NL@% %@CR:MCVcE388@%%@4@%%@AB@%U1077 '%@AE@%%@AI@%program%@AE@%%@AB@%' : return code%@AE@% %@AI@%value%@AE@%%@EH@%%@NL@% %@NL@% The given program invoked from %@AB@%NMAKE%@AE@% failed, returning the error%@NL@% code %@AI@%value%@AE@%.%@NL@% %@NL@% %@CR:MCVcE389@%%@4@%%@AB@%U1078 constant overflow at '%@AE@%%@AI@%directive%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% A constant in %@AI@%directive%@AE@%'s expression was too big.%@NL@% %@NL@% %@CR:MCVcE390@%%@4@%%@AB@%U1079 illegal expression: divide by zero present%@AE@%%@EH@%%@NL@% %@NL@% An expression tries to divide by zero.%@NL@% %@NL@% %@CR:MCVcE391@%%@4@%%@AB@%U1080 operator and/or operand out of place: usage illegal%@AE@%%@EH@%%@NL@% %@NL@% The expression incorrectly uses an operator or operand.%@NL@% %@NL@% Check the allowed set of operators and their precedence.%@NL@% %@NL@% %@CR:MCVcE392@%%@4@%%@AB@%U1081 '%@AE@%%@AI@%program%@AE@%%@AB@%' : program not found%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%NMAKE%@AE@% could not find the given program in order to run it.%@NL@% %@NL@% Make sure that the program is in the current path and has the%@NL@% correct extension.%@NL@% %@NL@% %@CR:MCVcE393@%%@4@%%@AB@%U1082%@AE@% %@AI@%command%@AE@%%@AB@% cannot execute command: out of memory%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%NMAKE%@AE@% cannot execute the given command because there is not enough%@NL@% memory. Free memory and run %@AB@%NMAKE%@AE@% again.%@NL@% %@NL@% %@CR:MCVcE394@%%@4@%%@AB@%U1085 can't mix implicit and explicit rules%@AE@%%@EH@%%@NL@% %@NL@% A regular target was specified along with the target for a rule%@NL@% (which has the form .%@AI@%fromext%@AE@%.%@AI@%toext%@AE@%). This is invalid.%@NL@% %@NL@% %@CR:MCVcE395@%%@4@%%@AB@%U1086 inference rule can't have dependents%@AE@%%@EH@%%@NL@% %@NL@% Dependents are not allowed when an inference rule is being%@NL@% defined.%@NL@% %@NL@% %@CR:MCVcE396@%%@4@%%@AB@%U1087 can't have : and :: dependents for same target%@AE@%%@EH@%%@NL@% %@NL@% A target cannot have both a single-colon (%@AB@%:%@AE@%) and a double-colon%@NL@% (%@AB@%::%@AE@%) dependency.%@NL@% %@NL@% %@CR:MCVcE397@%%@4@%%@AB@%U1088 invalid separator on inference rules: '::'%@AE@%%@EH@%%@NL@% %@NL@% Inference rules can use only a single-colon (%@AB@%:%@AE@%) separator.%@NL@% %@NL@% %@CR:MCVcE398@%%@4@%%@AB@%U1089 can't have build commands for pseudotarget '%@AE@%%@AI@%targetname%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% Pseudotargets (for example, %@AB@%.PRECIOUS%@AE@%, .SUFFIXES) cannot have%@NL@% build commands specified.%@NL@% %@NL@% %@CR:MCVcE399@%%@4@%%@AB@%U1090 can't have dependents for pseudotarget '%@AE@%%@AI@%targetname%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% The specified pseudotarget (for example, %@AB@%.SILENT%@AE@%, %@AB@%.IGNORE%@AE@%) cannot%@NL@% have a dependent.%@NL@% %@NL@% %@CR:MCVcE400@%%@4@%%@AB@%U1091 invalid suffixes in inference rule%@AE@%%@EH@%%@NL@% %@NL@% The suffixes being used in the inference rule are invalid.%@NL@% %@NL@% %@CR:MCVcE401@%%@4@%%@AB@%U1092 too many names in rule%@AE@%%@EH@%%@NL@% %@NL@% An inference rule cannot have more than one pair of extensions%@NL@% (.%@AI@%fromext%@AE@%.%@AI@%toext%@AE@%) as a target.%@NL@% %@NL@% %@CR:MCVcE402@%%@4@%%@AB@%U1093 can't mix special pseudotargets%@AE@%%@EH@%%@NL@% %@NL@% It is illegal to list two or more pseudotargets together.%@NL@% %@NL@% %@NL@% %@CR:MCVc5200@%%@3@%%@AB@%C.5.2 Warning NMAKE Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE403@%%@4@%%@AB@%U4011 command file can only be invoked from command line%@AE@%%@EH@%%@NL@% %@NL@% A command file cannot be invoked from within another command file.%@NL@% Such an invocation is ignored.%@NL@% %@NL@% %@CR:MCVcE404@%%@4@%%@AB@%U4012 resetting value of special macro '%@AE@%%@AI@%macroname%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% The value of a macro such as $(%@AB@%MAKE%@AE@%) was changed within a%@NL@% description file.%@NL@% %@NL@% The name by which this program was invoked is not a tagged section%@NL@% in the %@AB@%TOOLS.INI%@AE@% file.%@NL@% %@NL@% %@CR:MCVcE405@%%@4@%%@AB@%U4015 no match found for wildcard '%@AE@%%@AI@%filename%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% There are no file names that match the specified target or%@NL@% dependent file with the wild-card characters asterisk (%@AB@%*%@AE@%) and%@NL@% question mark (%@AB@%?%@AE@%).%@NL@% %@NL@% %@CR:MCVcE406@%%@4@%%@AB@%U4016 too many rules for target '%@AE@%%@AI@%targetname%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% Multiple blocks of build commands are specified for a target using%@NL@% single colons (%@AB@%:%@AE@%) as separators.%@NL@% %@NL@% %@CR:MCVcE407@%%@4@%%@AB@%U4017 ignoring rule%@AE@% %@AI@%rule%@AE@%%@AB@% (extension not in .SUFFIXES)%@AE@%%@EH@%%@NL@% %@NL@% The rule was ignored because the suffix(es) in the rule are not%@NL@% listed in the %@AB@%.SUFFIXES%@AE@% list.%@NL@% %@NL@% %@CR:MCVcE408@%%@4@%%@AB@%U4018 special macro undefined '%@AE@%%@AI@%macroname%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% The special macro %@AI@%macroname%@AE@% is undefined.%@NL@% %@NL@% %@CR:MCVcE409@%%@4@%%@AB@%U4019 Filename '%@AE@%%@AI@%filename%@AE@%%@AB@%' too long; truncating to 8.3%@AE@%%@EH@%%@NL@% %@NL@% The base name of the file has more than eight characters or the%@NL@% extension has more than three characters. %@AB@%NMAKE%@AE@% truncates the name%@NL@% to an eight-character base and a three-character extension.%@NL@% %@NL@% %@CR:MCVcE410@%%@4@%%@AB@%U4020 removed target '%@AE@%%@AI@%target%@AE@%%@AB@%'%@AE@%%@EH@%%@NL@% %@NL@% Execution of %@AB@%NMAKE%@AE@% was interrupted while it was trying to build%@NL@% the given target, and therefore the target was incomplete. Because%@NL@% the target was not specified in the %@AB@%.PRECIOUS%@AE@% list, %@AB@%NMAKE%@AE@% has%@NL@% deleted it.%@NL@% %@NL@% %@NL@% %@CR:MCVc6000@%%@2@%%@AB@%C.6 EXEMOD Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVc6001@%%@4@%Error messages from the Microsoft EXE File Header Utility, EXEMOD, have one%@EH@% of the following formats:%@NL@% %@NL@% {%@AI@%filename%@AE@%| %@AS@%EXEMOD%@AE@%} : %@AS@%fatal error U1%@AE@%%@AI@%xxx%@AE@%:%@AI@%messagetext%@AE@%%@NL@% {%@AI@%filename%@AE@%| %@AS@%EXEMOD%@AE@%} : %@AS@%warning U4%@AE@%%@AI@%xxx%@AE@%:%@AI@% messagetext%@AE@%%@NL@% %@NL@% %@CR:MCVc6002@%%@4@%The message begins with the input-file name (%@AI@%filename%@AE@%), if one exists, or%@EH@% with the name of the utility. If possible, %@AB@%EXEMOD%@AE@% prints a warning and continues operation. In some cases errors are fatal and %@AB@%EXEMOD%@AE@% terminates processing.%@NL@% %@NL@% %@CR:MCVc6003@%%@4@%EXEMOD generates the following error messages:%@EH@%%@NL@% %@NL@% %@NL@% %@CR:MCVc6100@%%@3@%%@AB@%C.6.1 Fatal EXEMOD Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE411@%%@4@%%@AB@%U1050 usage : exemod file [-/h] [-/stack n] [-/max n] [-/min n]%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%EXEMOD%@AE@% command line was not specified properly.%@NL@% %@NL@% Try again using the syntax shown. Note that the option indicator%@NL@% can be either a slash (%@AB@%/%@AE@%) or a hyphen (%@AB@%-%@AE@%). The single brackets%@NL@% (%@AB@%[ ]%@AE@%) in the error message indicate that your choice of the item%@NL@% within them is optional.%@NL@% %@NL@% %@CR:MCVcE412@%%@4@%%@AB@%U1051 invalid .EXE file : bad header%@AE@%%@EH@%%@NL@% %@NL@% The specified input file is not an executable file or it has an%@NL@% invalid file header.%@NL@% %@NL@% %@CR:MCVcE413@%%@4@%%@AB@%U1052 invalid .EXE file : actual length less than reported%@AE@%%@EH@%%@NL@% %@NL@% The second and third fields in the input-file header indicate a%@NL@% file size greater than the actual size.%@NL@% %@NL@% %@CR:MCVcE414@%%@4@%%@AB@%U1053 cannot change load-high program%@AE@%%@EH@%%@NL@% %@NL@% When the minimum allocation value and the maximum allocation value%@NL@% are both 0, the file cannot be modified.%@NL@% %@NL@% %@CR:MCVcE415@%%@4@%%@AB@%U1054 file not .EXE%@AE@%%@EH@%%@NL@% %@NL@% %@AB@%EXEMOD%@AE@% automatically appends the %@AB@%.EXE%@AE@% extension to any file name%@NL@% without an extension; in this case, no file with the given name%@NL@% and an %@AB@%.EXE%@AE@% extension could be found.%@NL@% %@NL@% %@CR:MCVcE416@%%@4@%%@AB@%U1055%@AE@% %@AI@%filename%@AE@%%@AB@% : cannot find file%@AE@%%@EH@%%@NL@% %@NL@% The file specified by %@AI@%filename%@AE@% could not be found.%@NL@% %@NL@% %@CR:MCVcE417@%%@4@%%@AB@%U1056%@AE@% %@AI@%filename%@AE@%%@AB@% : permission denied%@AE@%%@EH@%%@NL@% %@NL@% The file specified by %@AI@%filename%@AE@% was a read only file.%@NL@% %@NL@% %@NL@% %@CR:MCVc6200@%%@3@%%@AB@%C.6.2 Warning EXEMOD Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVcE418@%%@4@%%@AB@%U4050 packed file%@AE@%%@EH@%%@NL@% %@NL@% The given file was a packed file. This is a warning only.%@NL@% %@NL@% %@CR:MCVcE419@%%@4@%%@AB@%U4051 minimum allocation less than stack; correcting minimum%@AE@%%@EH@%%@NL@% %@NL@% If the minimum allocation value is not enough to accommodate the%@NL@% stack (either the original stack request or the modified request),%@NL@% the minimum allocation value is adjusted. This is a warning%@NL@% message only; the modification is still performed.%@NL@% %@NL@% %@CR:MCVcE420@%%@4@%%@AB@%U4052 minimum allocation greater than maximum; correcting maximum%@AE@%%@EH@%%@NL@% %@NL@% If the minimum allocation value is greater than the maximum%@NL@% allocation value, the maximum allocation value is adjusted. This%@NL@% is a warning message only; %@AB@%EXEMOD%@AE@% will still modify the file. The%@NL@% values shown if you ask for a display of DOS header values will be%@NL@% the values after the packed file is expanded.%@NL@% %@NL@% %@NL@% %@CR:MCVc7000@%%@2@%%@AB@%C.7 SETENV Error Messages%@AE@%%@EH@%%@NL@% %@NL@% %@CR:MCVc7001@%%@4@%Messages generated by the Microsoft Environment Expansion Utility, SETENV,%@EH@% have the following format:%@NL@% %@NL@% {%@AI@%filename%@AE@% | %@AS@%SETENV%@AE@%} :%@AS@%fatal error U1%@AE@%%@AI@%xxx%@AE@%%@AS@%:%@AE@%%@AI@%messagetext%@AE@%%@NL@% %@NL@% %@CR:MCVc7002@%%@4@%The message begins with the input-file name (%@AI@%filename%@AE@%), if one exists, or%@EH@% with the name of the utility.%@NL@% %@NL@% %@CR:MCVc7003@%%@4@%SETENV generates the following fatal error messages:%@EH@%%@NL@% %@NL@% %@CR:MCVcE421@%%@4@%%@AB@%U1080 usage : setenv <command.com> [envsize]%@AE@%%@EH@%%@NL@% %@NL@% The command line was not specified properly. This usually%@NL@% indicates that the wrong number of arguments was given.%@NL@% %@NL@% Try again with the syntax shown in the message.%@NL@% %@NL@% %@CR:MCVcE422@%%@4@%%@AB@%U1081 unrecognizable COMMAND.COM%@AE@%%@EH@%%@NL@% %@NL@% The %@AB@%COMMAND.COM%@AE@% file was not one of the accepted versions (DOS%@NL@% Versions 2.0, 2.1, 2.11, 3.0, and 3.1).%@NL@% %@NL@% %@CR:MCVcE423@%%@4@%%@AB@%U1082 maximum for Version 3.1 : 992%@AE@%%@EH@%%@NL@% %@NL@% You specified a file recognized as %@AB@%COMMAND.COM%@AE@% for IBM PC-DOS,%@NL@% Version 3.1, and gave an environment size greater than 992 bytes,%@NL@% the maximum allowed for that version.%@NL@% %@NL@% %@CR:MCVcE424@%%@4@%%@AB@%U1083 maximum environment size : 65520%@AE@%%@EH@%%@NL@% %@NL@% The environment size specified was greater than 65,520 bytes, the%@NL@% maximum size allowed.%@NL@% %@NL@% %@CR:MCVcE425@%%@4@%%@AB@%U1084 minimum environment size : 160%@AE@%%@EH@%%@NL@% %@NL@% The environment size specified was less than 160 bytes, the%@NL@% minimum size allowed.%@NL@% %@NL@% %@CR:MCVcE426@%%@4@%%@AB@%U1085%@AE@% %@AI@%filename%@AE@%%@AB@% : cannot find file%@AE@%%@EH@%%@NL@% %@NL@% The specified file was not found, perhaps because it was a%@NL@% directory or some other special file.%@NL@% %@NL@% %@CR:MCVcE427@%%@4@%%@AB@%U1086%@AE@% %@AI@%filename%@AE@%%@AB@% : permission denied%@AE@%%@EH@%%@NL@% %@NL@% The specified file was a read only file.%@NL@% %@NL@% %@CR:MCVcE428@%%@4@%%@AB@%U1087%@AE@% %@AI@%filename%@AE@%%@AB@% : unknown error%@AE@%%@EH@%%@NL@% %@NL@% An unknown system error occurred while the specified file was%@NL@% being read or written.%@NL@% %@NL@% %@NL@% %@CR:MCVg0000@%%@1@%%@AB@%Glossary%@AE@%%@EH@%%@NL@% ───────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@CR:MCVgD001@%%@4@%%@AB@%8087 or 80287 coprocessor%@AE@%%@EH@%%@NL@% Intel hardware products that perform much faster math calculations than the main processor.%@NL@% %@NL@% %@CR:MCVgD002@%%@4@%%@AB@%adapter%@AE@%%@EH@%%@NL@% A term sometimes used to refer to printed-circuit cards that plug into a computer and control a device, such as a video display or a printer.%@NL@% %@NL@% %@CR:MCVgD003@%%@4@%%@AB@%address%@AE@%%@EH@%%@NL@% An expression that evaluates to a location in memory. Addresses can be given in the segment offset format. If the segment is not given, the default segment is assumed. The default segment is CS for commands related to code and DS for commands related to data.%@NL@% %@NL@% %@CR:MCVgD004@%%@4@%%@AB@%address range%@AE@%%@EH@%%@NL@% A range of memory bounded by two addresses. The range can be specified in the normal format by giving the starting and ending addresses (inclusive), or it can be specified in the object-range format by specifying the starting address followed first by the letter (uppercase or lowercase) and then by the number of objects in the range (0x100 L 10, for example, specifies the range from 0x100 to 0x109, inclusive).%@NL@% %@NL@% %@CR:MCVgD005@%%@4@%%@AB@%Applications Program Interface (API)%@AE@%%@EH@%%@NL@% The set of calls a program uses to obtain services from the operating system. The term API denotes a service interface, whatever its form. Generally used to refer to OS/2 system calls.%@NL@% %@NL@% %@CR:MCVgD006@%%@4@%%@AB@%argc%@AE@%%@EH@%%@NL@% The conventional name for the first argument to the main function in a C source program (an integer specifying how many arguments are passed to the program from the command line).%@NL@% %@NL@% %@CR:MCVgD007@%%@4@%%@AB@%argument%@AE@%%@EH@%%@NL@% A value passed to a function.%@NL@% %@NL@% %@CR:MCVgD008@%%@4@%%@AB@%argv%@AE@%%@EH@%%@NL@% The conventional name for the second argument to the main function in a C source program (a pointer to an array of strings). The first string is the program name and each following string is an argument passed to the program from the command line.%@NL@% %@NL@% %@CR:MCVgD009@%%@4@%%@AB@%array%@AE@%%@EH@%%@NL@% A set of elements with the same type.%@NL@% %@NL@% %@CR:MCVgD010@%%@4@%%@AB@%ASCII (American Standard Code for Information Interchange)%@AE@%%@EH@%%@NL@% A set of 256 codes that many computers use to represent letters, digits, special characters, and other symbols. Only the first 128 of these codes are standardized; the remaining 128 are special characters defined by the computer manufacturer.%@NL@% %@NL@% %@CR:MCVgD011@%%@4@%%@AB@%assembly mode%@AE@%%@EH@%%@NL@% The mode in which the CodeView debugger displays assembly-language- instruction mnemonics to represent the code being executed.%@NL@% %@NL@% %@CR:MCVgD012@%%@4@%%@AB@%base name%@AE@%%@EH@%%@NL@% The part of a file name before the extension. For example, SAMPLE is the base name of the file SAMPLE.BAS.%@NL@% %@NL@% %@CR:MCVgD013@%%@4@%%@AB@%BASIC%@AE@%%@EH@%%@NL@% A programming language included with versions of DOS. BASIC is an acronym for Beginner's All-purpose Symbolic Instruction Code.%@NL@% %@NL@% %@CR:MCVgD014@%%@4@%%@AB@%Basic Input/Output System (BIOS)%@AE@%%@EH@%%@NL@% The code built into system memory that provides hardware interface routines for programs. You can trace into the BIOS with the CodeView debugger, using assembly mode.%@NL@% %@NL@% %@CR:MCVgD015@%%@4@%%@AB@%batch file%@AE@%%@EH@%%@NL@% A text file containing MS-DOS commands that can be invoked from the MS-DOS command line.%@NL@% %@NL@% %@CR:MCVgD016@%%@4@%%@AB@%breakpoint%@AE@%%@EH@%%@NL@% A specified address where program execution will be halted. The CodeView debugger interrupts execution whenever the program reaches an address where a breakpoint has been set. See also "watchpoint" and "tracepoint" for a description of conditional breakpoints.%@NL@% %@NL@% %@CR:MCVgD017@%%@4@%%@AB@%buffer%@AE@%%@EH@%%@NL@% An area in memory in which a copy of the file is kept and changed as you edit. This buffer is copied to disk when you do a save operation.%@NL@% %@NL@% %@CR:MCVgD018@%%@4@%%@AB@%call gate%@AE@%%@EH@%%@NL@% A special LDT or GDT entry that describes a subroutine entry point rather than a memory segment. A far call to a call gate selector will cause a transfer to the entry point specified in the call gate. This is a feature of the 80286/80386 hardware and is normally used to provide a transition from a lower privilege state to a higher one.%@NL@% %@NL@% %@CR:MCVgD019@%%@4@%%@AB@%CGA%@AE@%%@EH@%%@NL@% IBM's Color Graphics Adapter.%@NL@% %@NL@% %@CR:MCVgD020@%%@4@%%@AB@%character string%@AE@%%@EH@%%@NL@% A sequence of bytes treated as a set of ASCII letters or numbers.%@NL@% %@NL@% %@CR:MCVgD021@%%@4@%%@AB@%Child process%@AE@%%@EH@%%@NL@% A process created by another process (its parent process).%@NL@% %@NL@% %@CR:MCVgD022@%%@4@%%@AB@%click%@AE@%%@EH@%%@NL@% To press and release one of the mouse buttons while pointing the mouse at an object on the screen.%@NL@% %@NL@% %@CR:MCVgD023@%%@4@%%@AB@%Color Graphics Adapter (CGA)%@AE@%%@EH@%%@NL@% A video adapter capable of displaying text characters or graphics pixels. Color can also be displayed with the appropriate display monitor.%@NL@% %@NL@% %@CR:MCVgD024@%%@4@%%@AB@%command%@AE@%%@EH@%%@NL@% An instruction you use to control a computer program, such as DOS or an application program.%@NL@% %@NL@% %@CR:MCVgD025@%%@4@%%@AB@%command file%@AE@%%@EH@%%@NL@% A file that contains the program or instructions required to carry out a command. If the file's extension is COM or EXE, the command file contains machine instructions; if its extension is BAT, the command file is a batch file and contains DOS commands; if its extension is CMD, the command file contains OS/2 commands.%@NL@% %@NL@% %@CR:MCVgD026@%%@4@%%@AB@%compile%@AE@%%@EH@%%@NL@% The action performed to translate programming language statements to a form that can be executed by the computer.%@NL@% %@NL@% %@CR:MCVgD027@%%@4@%%@AB@%constant%@AE@%%@EH@%%@NL@% A value that does not change during program execution. A variable, on the other hand, is a value that can──and usually does──change during program execution.%@NL@% %@NL@% %@CR:MCVgD028@%%@4@%%@AB@%constant expression%@AE@%%@EH@%%@NL@% Any expression that evaluates to a constant and may involve integer constants, character constants, floating-point constants, enumeration constants, type casts to integral and floating-point types, and other constant expressions.%@NL@% %@NL@% %@CR:MCVgD029@%%@4@%%@AB@%CPU%@AE@%%@EH@%%@NL@% Central Processing Unit, or the main processor in a computer. For example, the CPU is an Intel 8088 in PCs and an 80286 in PC/ATs.%@NL@% %@NL@% %@CR:MCVgD030@%%@4@%%@AB@%Ctrl-C%@AE@%%@EH@%%@NL@% Same as CTRL-BREAK.%@NL@% %@NL@% %@CR:MCVgD031@%%@4@%%@AB@%Ctrl-S%@AE@%%@EH@%%@NL@% Same as CTRL-NUM LOCK.%@NL@% %@NL@% %@CR:MCVgD032@%%@4@%%@AB@%cursor%@AE@%%@EH@%%@NL@% The thin blinking line that represents the current location where the next character you type appears. The cursor automatically moves to the dialog window when you start entering a command.%@NL@% %@NL@% %@CR:MCVgD033@%%@4@%%@AB@%debugger%@AE@%%@EH@%%@NL@% A program that helps the programmer locate the source of problems found during runtime testing of a program.%@NL@% %@NL@% %@CR:MCVgD034@%%@4@%%@AB@%dialog box%@AE@%%@EH@%%@NL@% A box that appears when you choose a menu command that requires additional information.%@NL@% %@NL@% %@CR:MCVgD035@%%@4@%%@AB@%dialog commands%@AE@%%@EH@%%@NL@% Commands entered in the dialog window in window mode, or any command in sequential mode. Dialog commands consist of one- or two-character commands that can usually be followed by arguments.%@NL@% %@NL@% %@CR:MCVgD036@%%@4@%%@AB@%dialog window%@AE@%%@EH@%%@NL@% The window at the bottom of the CodeView screen where dialog commands can be entered and previously entered dialog commands can be reviewed.%@NL@% %@NL@% %@CR:MCVgD037@%%@4@%%@AB@%double precision%@AE@%%@EH@%%@NL@% A real (floating-point) value that occupies eight bytes of memory. Double-precision values are accurate to 15 or 16 digits.%@NL@% %@NL@% %@CR:MCVgD038@%%@4@%%@AB@%drag%@AE@%%@EH@%%@NL@% To point the mouse at an object on the screen, press a mouse button, and then move the mouse while holding the button down.%@NL@% %@NL@% %@CR:MCVgD039@%%@4@%%@AB@%dump%@AE@%%@EH@%%@NL@% Contents of memory displayed at a specified memory location. In the CodeView debugger, the size of the object to be displayed is specified with a type character from the following list: %@AB@%A%@AE@% (ASCII), %@AB@%B%@AE@% (Byte), %@AB@%I%@AE@% (Integer), %@AB@%U%@AE@% (Unsigned Integer), %@AB@%W%@AE@% (Word), %@AB@%D%@AE@% (Double Word), %@AB@%SP%@AE@% (Short Real), %@AB@%L%@AE@% (Long Real), or %@AB@%T%@AE@% (10-Byte Real).%@NL@% %@NL@% %@CR:MCVgD040@%%@4@%%@AB@%dynamic link%@AE@%%@EH@%%@NL@% A method of postponing the resolution of external references until loadtime or runtime. A dynamic link allows the called subroutines to be packaged, distributed, and maintained independently of their callers. OS/2 extends the dynamic link mechanism to serve as the primary method by which all system and nonsystem services are obtained.%@NL@% %@NL@% %@CR:MCVgD041@%%@4@%%@AB@%dynamic-link library%@AE@%%@EH@%%@NL@% A file, in a special format, that contains the binary code for a group of dynamically linked subroutines.%@NL@% %@NL@% %@CR:MCVgD042@%%@4@%%@AB@%dynamic-link routine%@AE@%%@EH@%%@NL@% See "dynamic link."%@NL@% %@NL@% %@CR:MCVgD043@%%@4@%%@AB@%Enhanced graphics adapter (EGA)%@AE@%%@EH@%%@NL@% A video adapter capable of displaying in all the modes of the color graphics adapter (CGA) plus additional modes. The CodeView 43 option displays in the EGA's 43-line text mode.%@NL@% %@NL@% %@CR:MCVgD044@%%@4@%%@AB@%environment strings%@AE@%%@EH@%%@NL@% A series of user-definable and program-definable strings associated with each process. The initial values of environment strings are established by a process's parent.%@NL@% %@NL@% %@CR:MCVgD045@%%@4@%%@AB@%environment table%@AE@%%@EH@%%@NL@% The part of MS-DOS that stores environment variables and their values.%@NL@% %@NL@% %@CR:MCVgD046@%%@4@%%@AB@%environment variable%@AE@%%@EH@%%@NL@% A variable stored in the environment table that provides MS-DOS with information (where to find executable files and library files, where to create temporary files, etc.).%@NL@% %@NL@% %@CR:MCVgD047@%%@4@%%@AB@%Esc%@AE@%%@EH@%%@NL@% Escape key.%@NL@% %@NL@% %@CR:MCVgD048@%%@4@%%@AB@%escape sequence%@AE@%%@EH@%%@NL@% A specific combination of a backslash (\) followed by a letter or combination of digits. The combination represents white-space and nongraphic characters within strings and character constants.%@NL@% %@NL@% %@CR:MCVgD049@%%@4@%%@AB@%executable file%@AE@%%@EH@%%@NL@% A file with an extension of .EXE, .COM, .BAT, or .CMD. Executable files can be run by typing the file name at the system prompt.%@NL@% %@NL@% %@CR:MCVgD050@%%@4@%%@AB@%executable program%@AE@%%@EH@%%@NL@% A file that contains executable program code. When the name of the file is typed at the system prompt, the statements in the file are executed.%@NL@% %@NL@% %@CR:MCVgD051@%%@4@%%@AB@%exit code%@AE@%%@EH@%%@NL@% A code returned by a program to MS-DOS indicating whether the program ran successfully.%@NL@% %@NL@% %@CR:MCVgD052@%%@4@%%@AB@%expression%@AE@%%@EH@%%@NL@% A combination of operands and operators that yields a single value.%@NL@% %@NL@% %@CR:MCVgD053@%%@4@%%@AB@%Family Applications Program Interface (Family API)%@AE@%%@EH@%%@NL@% A standard execution environment under MS-DOS versions 2.x and 3.x and OS/2. The programmer can use the Family API to create an application that uses a subset of OS/2 functions (but a superset of MS-DOS 3.x functions) and that runs in a binary-compatible fashion under MS-DOS versions 2.x and 3.x and OS/2.%@NL@% %@NL@% %@CR:MCVgD054@%%@4@%%@AB@%far address%@AE@%%@EH@%%@NL@% A memory location specified by using a segment (location of a 64K block) and an offset from the beginning of the segment. Far addresses require four bytes──two for the segment and two for the offset. A far address is also known as a segmented address. See "near address."%@NL@% %@NL@% %@CR:MCVgD055@%%@4@%%@AB@%file%@AE@%%@EH@%%@NL@% A named collection of information stored on a disk. The file usually contains either data or a program.%@NL@% %@NL@% %@CR:MCVgD056@%%@4@%%@AB@%flags%@AE@%%@EH@%%@NL@% A register that contains individual bits, each of which signals a condition that can be tested by a machine-level instruction. In other registers, the contents of the register are considered as a whole, while in the flags register only the individual bits have meaning. In the CodeView debugger, the current values of the most commonly used bits of the flags register are shown at the bottom of the register window. See "registers."%@NL@% %@NL@% %@CR:MCVgD057@%%@4@%%@AB@%flipping%@AE@%%@EH@%%@NL@% A screen-exchange method that uses the video pages of the CGA or EGA to store both the debugging and output screens. Video pages are areas of memory reserved for screen storage. When you request the other screen, the two video pages are exchanged. This method is faster than swapping──the other screen-exchange method──but it does not work with the MA or with programs that do graphics or use the video pages. See also "screen exchange" and "swapping."%@NL@% %@NL@% %@CR:MCVgD058@%%@4@%%@AB@%function%@AE@%%@EH@%%@NL@% A subroutine or procedure that returns a value.%@NL@% %@NL@% %@CR:MCVgD059@%%@4@%%@AB@%function call%@AE@%%@EH@%%@NL@% A call to a a subroutine that performs a specific action. In C (source mode), subroutines are called functions. In assembly language (assembly mode), subroutines are called procedures.%@NL@% %@NL@% %@CR:MCVgD060@%%@4@%%@AB@%global symbol%@AE@%%@EH@%%@NL@% A symbol that is available throughout the entire program. In the CodeView debugger, function names are always global symbols. See also "local symbol."%@NL@% %@NL@% %@CR:MCVgD061@%%@4@%%@AB@%global variable%@AE@%%@EH@%%@NL@% A variable that is available throughout a module.%@NL@% %@NL@% %@CR:MCVgD062@%%@4@%%@AB@%grandparent process%@AE@%%@EH@%%@NL@% The parent process of a process that created a process.%@NL@% %@NL@% %@CR:MCVgD063@%%@4@%%@AB@%hexadecimal%@AE@%%@EH@%%@NL@% The base-16 numbering system whose digits are 0 through F (the letters A through F represent the decimal numbers 10 through 15). Hexadecimal is often used in computer programming because it is easily converted to and from binary, the base-2 numbering system the computer itself uses.%@NL@% %@NL@% %@CR:MCVgD064@%%@4@%%@AB@%highlight%@AE@%%@EH@%%@NL@% A reverse-video area in a text box, window, or menu marking the current command chosen or text that has been selected for copying or deleting.%@NL@% %@NL@% %@CR:MCVgD065@%%@4@%%@AB@%I/O privilege mechanism%@AE@%%@EH@%%@NL@% A facility that allows a process to ask a device driver for direct access to the device's I/O ports and any dedicated or mapped memory locations it has. The I/O privilege mechanism can be used directly by an application or indirectly by a dynamic-link package.%@NL@% %@NL@% %@CR:MCVgD066@%%@4@%%@AB@%identifier%@AE@%%@EH@%%@NL@% A name that identifies a register or a location in memory. The terms identifier and symbol are used synonymously in CodeView documentation.%@NL@% %@NL@% %@CR:MCVgD067@%%@4@%%@AB@%IEEE format (Institute for Electrical and Electronic Engineers, Inc.)%@AE@%%@EH@%%@NL@% A method of representing floating-point numbers internally.%@NL@% %@NL@% %@CR:MCVgD068@%%@4@%%@AB@%include file%@AE@%%@EH@%%@NL@% A source file that is merged into a program with the %@AB@%$INCLUDE%@AE@% metacommand or the C %@AB@%#include%@AE@% directive.%@NL@% %@NL@% %@CR:MCVgD069@%%@4@%%@AB@%integer%@AE@%%@EH@%%@NL@% A whole number represented inside the machine as a 16-bit two's complement binary number. An integer has a range of -32,768 to +32,767. See "long integer."%@NL@% %@NL@% %@CR:MCVgD070@%%@4@%%@AB@%interrupt call%@AE@%%@EH@%%@NL@% A machine-level procedure that can be called to execute a BIOS, MS-DOS, or other function. You can trace into BIOS interrupts with the CodeView debugger, but not into the MS-DOS interrupt (0x21).%@NL@% %@NL@% %@CR:MCVgD071@%%@4@%%@AB@%label%@AE@%%@EH@%%@NL@% A symbol (identifier) representing an address in the code segment (CS) register. Labels in C programs can be either function names or labels for goto statements.%@NL@% %@NL@% %@CR:MCVgD072@%%@4@%%@AB@%link%@AE@%%@EH@%%@NL@% The step that the linker performs to produce an executable file. The link step resolves references to procedures or variables in other modules and creates a complete program ready for execution.%@NL@% %@NL@% %@CR:MCVgD073@%%@4@%%@AB@%linking%@AE@%%@EH@%%@NL@% The process in which the linker loads modules into memory, computes absolute offset addresses for routines and variables in relocatable modules, and resolves all external references by searching the run-time library. After loading and linking, the linker saves the modules it has loaded into memory as a single executable file.%@NL@% %@NL@% %@CR:MCVgD074@%%@4@%%@AB@%local symbol%@AE@%%@EH@%%@NL@% A symbol that only has value within a particular function. A function argument or a variable declared as auto or static within a function can be a local symbol. See "global symbol."%@NL@% %@NL@% %@CR:MCVgD075@%%@4@%%@AB@%local variable%@AE@%%@EH@%%@NL@% A variable whose scope is confined to a particular unit of code, such as the module-level code, or a procedure within a module.%@NL@% %@NL@% %@CR:MCVgD076@%%@4@%%@AB@%long integer%@AE@%%@EH@%%@NL@% A whole number represented inside the machine by a 32-bit two's complement value. Long integers have a range of -2,147,483,648 to +2,147,483,647. See "integer."%@NL@% %@NL@% %@CR:MCVgD077@%%@4@%%@AB@%lvalue%@AE@%%@EH@%%@NL@% An expression (such as a variable name) that refers to a single memory location and is required as the left-hand operand of an assignment operation or the single operand of a unary operator. For example, %@AS@%X1%@AE@% is an lvalue, but %@AS@%X1+X2%@AE@% is not.%@NL@% %@NL@% %@CR:MCVgD078@%%@4@%%@AB@%machine code%@AE@%%@EH@%%@NL@% A series of binary numbers that a microprocessor executes as program instructions.%@NL@% %@NL@% %@CR:MCVgD079@%%@4@%%@AB@%macro%@AE@%%@EH@%%@NL@% A method for representing a long series of characters or statements with a symbol. The macro is expanded by the C or MASM preprocessor. C and MASM each have their own conventions for defining macros.%@NL@% %@NL@% %@CR:MCVgD080@%%@4@%%@AB@%math coprocessor%@AE@%%@EH@%%@NL@% An optional hardware component, such as an 8087 or 80287 chip, that improves the speed of arithmetic involving floating-point numbers.%@NL@% %@NL@% %@CR:MCVgD081@%%@4@%%@AB@%menu bar%@AE@%%@EH@%%@NL@% The bar at the top of the CodeView display containing menu titles and the titles Trace and Go.%@NL@% %@NL@% %@CR:MCVgD082@%%@4@%%@AB@%Microsoft binary format%@AE@%%@EH@%%@NL@% A method of representing floating-point numbers internally.%@NL@% %@NL@% %@CR:MCVgD083@%%@4@%%@AB@%module%@AE@%%@EH@%%@NL@% A discrete group of statements. Every program has at least one module (the main module). In most cases, each module corresponds to one source file. When you save a program containing multiple modules, each module is saved in a separate disk file.%@NL@% %@NL@% %@CR:MCVgD084@%%@4@%%@AB@%Monochrome Adapter (MA)%@AE@%%@EH@%%@NL@% A video adapter capable of displaying only in black and white. Most monochrome adapters display text only; individual graphics pixels cannot be displayed. The CodeView debugger recognizes monochrome adapters and automatically selects swapping as the screen-exchange mode.%@NL@% %@NL@% %@CR:MCVgD085@%%@4@%%@AB@%mouse%@AE@%%@EH@%%@NL@% A pointing device that fits under your hand and rolls in any direction on a flat surface. By moving the mouse, you can move the mouse pointer in a corresponding direction on the screen. See "pointer."%@NL@% %@NL@% %@CR:MCVgD086@%%@4@%%@AB@%mouse pointer%@AE@%%@EH@%%@NL@% The reverse-video square that moves to indicate the current position of the mouse. The mouse pointer only appears if a mouse is installed. To select an item with the mouse, move the mouse until the pointer rests on the item.%@NL@% %@NL@% %@CR:MCVgD087@%%@4@%%@AB@%multitasking operating system%@AE@%%@EH@%%@NL@% An operating system in which two or more programs/threads can execute simultaneously.%@NL@% %@NL@% %@CR:MCVgD088@%%@4@%%@AB@%NAN%@AE@%%@EH@%%@NL@% An acronym that stands for "not a number." The 8087 or 80287 coprocessor generates NANs when the result of an operation cannot be represented in the IEEE format. For example, if you try to add two positive numbers whose sum is larger than the maximum value supported by the data type, the coprocessor returns a NAN instead of the sum.%@NL@% %@NL@% %@CR:MCVgD089@%%@4@%%@AB@%near address%@AE@%%@EH@%%@NL@% A memory location specified by using only the offset from the start of the segment. A near address requires only two bytes. See "far address."%@NL@% %@NL@% %@CR:MCVgD090@%%@4@%%@AB@%null pointer%@AE@%%@EH@%%@NL@% A pointer to nothing, expressed as the integer value 0.%@NL@% %@NL@% %@CR:MCVgD091@%%@4@%%@AB@%object file%@AE@%%@EH@%%@NL@% A file (with the extension .OBJ) containing relocatable machine code produced by compiling a program and used by the linker to form an executable file.%@NL@% %@NL@% %@CR:MCVgD092@%%@4@%%@AB@%object module%@AE@%%@EH@%%@NL@% The contents of an object file after the file has been made part of a stand-alone library.%@NL@% %@NL@% %@CR:MCVgD093@%%@4@%%@AB@%object range%@AE@%%@EH@%%@NL@% See "address range."%@NL@% %@NL@% %@CR:MCVgD094@%%@4@%%@AB@%offset%@AE@%%@EH@%%@NL@% The number of bytes from the beginning of a segment in memory to a particular byte in that segment.%@NL@% %@NL@% %@CR:MCVgD095@%%@4@%%@AB@%output screen%@AE@%%@EH@%%@NL@% The screen where program output is shown. The Screen Exchange command (\), Output from the View menu, and the F4 key can be used to switch to this screen. The output screen is the same as it would be if you ran the debugged program outside of the CodeView debugger.%@NL@% %@NL@% %@CR:MCVgD096@%%@4@%%@AB@%parent process%@AE@%%@EH@%%@NL@% A process that creates another process, called the child process.%@NL@% %@NL@% %@CR:MCVgD097@%%@4@%%@AB@%PID (Process Identification Number)%@AE@%%@EH@%%@NL@% A unique code that OS/2 assigns to a process when the process is created. The PID may be any value except 0.%@NL@% %@NL@% %@CR:MCVgD098@%%@4@%%@AB@%pointer%@AE@%%@EH@%%@NL@% A variable containing the address of another variable. See "mouse pointer."%@NL@% %@NL@% %@CR:MCVgD099@%%@4@%%@AB@%popup menu%@AE@%%@EH@%%@NL@% A menu that pops up when you point the mouse cursor to the menu title and press a mouse button. In the CodeView debugger, popup menus also pop up when you press the ALT key and the first letter of the menu title at the same time. You can make a selection from the menu by dragging the highlight up or down with the mouse, by pressing the UP or DOWN direction key to move the highlight, or by pressing the ALT key and the first letter of the selection title at the same time.%@NL@% %@NL@% %@CR:MCVgD100@%%@4@%%@AB@%port%@AE@%%@EH@%%@NL@% The electrical connection through which the computer sends and receives data to and from devices or other computers.%@NL@% %@NL@% %@CR:MCVgD101@%%@4@%%@AB@%precedence%@AE@%%@EH@%%@NL@% The relative position of an operator in the hierarchy that determines the order in which expressions are evaluated.%@NL@% %@NL@% %@CR:MCVgD102@%%@4@%%@AB@%printf%@AE@%%@EH@%%@NL@% A function in the C standard library that prints formatted output according to instructions supplied with a type-specifier argument. The CodeView debugger uses a subset of the %@AB@%printf%@AE@% type specifiers to format expression values.%@NL@% %@NL@% %@CR:MCVgD103@%%@4@%%@AB@%privilege mode%@AE@%%@EH@%%@NL@% A special execution mode (also known as ring 0) supported by the 80286/80386 hardware. Code executing in this mode can execute restricted instructions that are used to manipulate key system structures and tables. Only the OS/2 kernel and device drivers run in this mode.%@NL@% %@NL@% %@CR:MCVgD104@%%@4@%%@AB@%procedure%@AE@%%@EH@%%@NL@% A general term for a SUB or FUNCTION.%@NL@% %@NL@% %@CR:MCVgD105@%%@4@%%@AB@%procedure call%@AE@%%@EH@%%@NL@% A call to a subroutine that performs a specific action. In assembly language (assembly mode), subroutines are called procedures. In C (source mode), subroutines are called functions.%@NL@% %@NL@% %@CR:MCVgD106@%%@4@%%@AB@%process%@AE@%%@EH@%%@NL@% The executing instance of a binary file. In OS/2, the terms task and process are used interchangeably. A process is the unit of ownership, and processes own resources such as memory, open files, dynlink libraries, and semaphores.%@NL@% %@NL@% %@CR:MCVgD107@%%@4@%%@AB@%processor%@AE@%%@EH@%%@NL@% See "CPU."%@NL@% %@NL@% %@CR:MCVgD108@%%@4@%%@AB@%program step%@AE@%%@EH@%%@NL@% To trace the next source line in source mode or the next instruction in assembly mode. If the source line or instruction contains a function, procedure, or interrupt call, the call is executed to the end and the CodeView debugger is ready to execute the instruction after the call. See "trace."%@NL@% %@NL@% %@CR:MCVgD109@%%@4@%%@AB@%protected mode%@AE@%%@EH@%%@NL@% The operating mode of the 80286 or 80386 microprocessor that allows the operating system to use features that protect one application from another (also called protect mode). Protected mode in OS/2 supports multitasking and a whole range of special services not supported in DOS.%@NL@% %@NL@% %@CR:MCVgD110@%%@4@%%@AB@%radix%@AE@%%@EH@%%@NL@% The number system in which numbers are specified. In the CodeView debugger, numbers can be entered in three radixes: 8 (octal), 10 (decimal), or 16 (hexadecimal). The default radix is 10.%@NL@% %@NL@% %@CR:MCVgD111@%%@4@%%@AB@%real mode%@AE@%%@EH@%%@NL@% The operating mode of the 80286 or 80386 microprocessor that runs programs designed for the 8086/8088 microprocessor. All programs for the DOS environment run in real mode.%@NL@% %@NL@% %@CR:MCVgD112@%%@4@%%@AB@%redirection%@AE@%%@EH@%%@NL@% To specify the device from which a program will receive input or to which it will send output. Normally program input comes from the keyboard, and program output goes to the screen. Redirection involves specifying a device (or file) other than the default device. In the MS-DOS operating system, input is redirected with the less-than symbol (<) and output is redirected with the greater-than symbol (>). The same symbols are used in the CodeView debugger to redirect input or output of the debugging session. In addition, the equal sign (=) can be used to redirect both input and output.%@NL@% %@NL@% %@CR:MCVgD113@%%@4@%%@AB@%register window%@AE@%%@EH@%%@NL@% The optional window in which the central processing unit (CPU) registers and the bits of the flag register are displayed.%@NL@% %@NL@% %@CR:MCVgD114@%%@4@%%@AB@%registers%@AE@%%@EH@%%@NL@% Special memory within the processor, where byte- or word-sized data can be stored during m 
