Microsoft Programmer's Library 1.3

home *** CD-ROM | disk | FTP | other *** search

/ Microsoft Programmer's Library 1.3 / Microsoft-Programers-Library-v1.3.iso / books / wsptools.db < prev next >

Wrap

Text File | 1991-03-01 | 851.9 KB | 16,680 lines

%@1@%%@AB@%Microsoft Windows Software Development Kit - Tools%@AE@%%@EH@%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@AB@%Microsoft (R) Windows (tm) Software Development Kit - Tools%@AE@%%@NL@% %@AB@%development tools for building Microsoft (R) Windows applications %@AB@%VERSION 3.0%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% for the MS-DOS (R) and PC-DOS Operating Systems%@NL@% Microsoft Corporation%@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. U.S. Government Restricted Rights The SOFTWARE and documentation are provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c) (1) and (2) of the Commercial Computer Software ─ Restricted Rights at 48 CFR 52.227-19, as applicable. Contractor/manufacturer is Microsoft Corporation/One Microsoft Way/Redmond, WA 98052-6399.%@NL@% (C) Copyright Microsoft Corporation, 1990. All rights reserved. Simultaneously published in the U.S. and Canada.%@NL@% Printed and bound in the United States of America.%@NL@% Microsoft, MS, MS-DOS, GW-BASIC, QuickC, CodeView, and XENIX are registered trademarks and Windows is a trademark of Microsoft Corporation.%@NL@% AT&T is a registered trademark of American Telephone and Telegraph Company.%@NL@% Aldus is a registered trademark of Aldus Corporation.%@NL@% COMPAQ is a registered trademark of Compaq Computer Corporation.%@NL@% IBM is a registered trademark of International Business Machines Corporation.%@NL@% Intel is a registered trademark of Intel Corporation.%@NL@% Lotus and 1-2-3 are registered trademarks of Lotus Development Corporation.%@NL@% Mac and Macintosh are registered trademarks of Apple Computer, Inc.%@NL@% Olivetti is a registered trademark of Ing. C. Olivetti.%@NL@% Paintbrush is a registered trademark of Zsoft Corporation.%@NL@% The Symbol fonts provided with Windows 3.0 are based on the CG Times font, a product of AGFA Compugraphic Division of Agfa Corporation.%@NL@% Tandy is a registered trademark of Tandy Corporation.%@NL@% Document No. SY0314b-300-R00-1089%@NL@% %@NL@% %@1@%%@AB@%Table of Contents%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%Introduction%@AE@%%@BO: 77a0@% Organization of This Manual%@BO: 7af8@% Building a Windows Application%@BO: 8c03@% Document Conventions%@BO: 9832@% Summary%@BO: b7ea@% %@AB@%PART I%@AE@%%@BO: b940@% %@AB@%Compilers and Linkers%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%Chapter 1%@AE@%%@BO: bb10@% %@AB@%Compiling Applications: The C Compiler%@AE@% 1.1%@BO: be7f@% Compiling C-Language Windows Applications 1.2%@BO: d751@% Compiler Options 1.2.1%@BO: da21@% Memory-Model Options 1.2.2%@BO: e215@% Application Development Options 1.2.3%@BO: eb33@% Dynamic-Link Library Options 1.3%@BO: f5a6@% Summary %@AB@%Chapter 2%@AE@%%@BO: f687@% %@AB@%Linking Applications: The Linker%@AE@% 2.1%@BO: fe3b@% Creating Module-Definition Files 2.1.1%@BO: 11377@% Creating Module Definitions for Applications 2.1.2%@BO: 1203f@% Creating Module Definitions for Libraries 2.2%@BO: 12c0d@% Importing Dynamic-Link Libraries 2.3%@BO: 13651@% Linking an Application 2.3.1%@BO: 1388e@% Using the LINK Command 2.3.2%@BO: 142e3@% Specifying LINK Command Options 2.3.3%@BO: 164be@% Specifying Libraries on the LINK Command Line 2.4%@BO: 1727f@% Examining Executable File Headers 2.5%@BO: 176b0@% Summary %@AB@%Chapter 3%@AE@%%@BO: 179b3@% %@AB@%Compiling Resources: The Resource Compiler%@AE@% 3.1%@BO: 17d69@% Including Resources in an Application 3.2%@BO: 182a7@% Creating a Resource Script File 3.3%@BO: 1a5ac@% Using the Resource Compiler 3.3.1%@BO: 1cf59@% Compiling Resources Separately 3.3.2%@BO: 1d3a9@% Defining Names for the Preprocessor 3.3.3%@BO: 1d891@% Renaming the Compiled Resource File 3.3.4%@BO: 1dc8a@% Controlling the Directories that RC Searches 3.3.5%@BO: 1e58d@% Displaying Progress Messages 3.4%@BO: 1e7ca@% Summary %@AB@%PART II%@AE@%%@BO: 1ee02@% %@AB@%Resource Editors%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%Chapter 4%@AE@%%@BO: 1f053@% %@AB@%Designing Images: SDKPaint%@AE@% 4.1%@BO: 1f513@% How SDKPaint Works with Files 4.1.1%@BO: 1f815@% File Types 4.1.2%@BO: 1fbb6@% Icon and Cursor Data: The SDKPAINT.DAT File 4.2%@BO: 206c5@% The SDKPaint Window 4.3%@BO: 2162d@% Opening Files and Images 4.3.1%@BO: 2172c@% Converting Files to 3.0 Format 4.3.2%@BO: 21833@% Opening Bitmaps 4.3.3%@BO: 21dfe@% Opening Icons and Cursors 4.4%@BO: 22b9c@% Drawing with SDKPaint Tools 4.5%@BO: 238c2@% Using the SDKPaint Palette 4.5.1%@BO: 241b9@% Working with Opaque, Screen, and Inverse Colors 4.6%@BO: 251d5@% Customizing the Palette 4.6.1%@BO: 253be@% Editing Colors 4.6.2%@BO: 25727@% Saving a Palette 4.6.3%@BO: 258bf@% Loading a Customized Palette 4.7%@BO: 25acf@% Defining the Cursor Hotspot 4.8%@BO: 25e38@% Using the Clipboard 4.9%@BO: 2678f@% Using ZoomIn to Examine Images 4.10%@BO: 26c43@% Summary %@AB@%Chapter 5%@AE@%%@BO: 27084@% %@AB@%Designing Dialog Boxes: The Dialog Editor%@AE@% 5.1%@BO: 27697@% How the Dialog Editor Works with Files 5.1.1%@BO: 27c93@% The Dialog Script 5.1.2%@BO: 28574@% The Resource File 5.1.3%@BO: 28b9a@% The Include File 5.2%@BO: 29600@% Installing and Removing Custom Controls 5.2.1%@BO: 29adc@% Installing a Custom Control 5.2.2%@BO: 29d97@% Removing a Custom Control 5.3%@BO: 29eca@% Viewing a Dialog Box: The Dialog Editor Window 5.3.1%@BO: 2afad@% The Mode Display 5.3.2%@BO: 2b33f@% The Toolbox 5.3.3%@BO: 2b4fd@% The Selected Item Status Window 5.4%@BO: 2bdd7@% Opening Files and Dialog Boxes 5.4.1%@BO: 2bf8d@% Opening a Resource File 5.4.2%@BO: 2c0e6@% Opening an Include File 5.4.3%@BO: 2c30c@% Opening a Dialog Box 5.5%@BO: 2c6ba@% Editing Dialog Box Controls 5.5.1%@BO: 2de79@% Adding Controls 5.5.2%@BO: 2e690@% Working with Individual Controls 5.6%@BO: 2fb32@% Working with Groups of Controls 5.6.1%@BO: 2fc38@% Moving Groups of Controls 5.6.2%@BO: 30088@% Defining Input Focus Sequence 5.7%@BO: 30dc5@% Working with a Dialog Box 5.7.1%@BO: 30f44@% Resizing a Dialog Box 5.7.2%@BO: 31164@% Renaming a Dialog Box 5.7.3%@BO: 31271@% Defining Styles 5.7.4%@BO: 313cb@% Setting Memory Flags 5.7.5%@BO: 31744@% Canceling Edits 5.8%@BO: 318cf@% Moving a Dialog Box Between Resources 5.9%@BO: 31cdb@% Working with Include Files 5.9.1%@BO: 32539@% Creating New Include Files 5.9.2%@BO: 329d4@% Loading Existing Include Files 5.9.3%@BO: 32ddd@% Editing Include Files 5.9.4%@BO: 335c3@% Saving Include Files 5.10%@BO: 33757@% Summary %@AB@%Chapter 6%@AE@%%@BO: 33cf8@% %@AB@%Designing Fonts: The Font Editor%@AE@% 6.1%@BO: 342ca@% Opening a Font 6.2%@BO: 34ca3@% Editing Characters 6.2.1%@BO: 35091@% Turning Pixels On or Off 6.2.2%@BO: 35220@% Changing Rows and Columns of Pixels 6.2.3%@BO: 35c37@% Modifying Blocks of Pixels 6.2.4%@BO: 365e5@% Changing Character Width 6.2.5%@BO: 36d22@% Storing Changes to a Character 6.2.6%@BO: 36f9e@% Canceling Changes to a Character 6.3%@BO: 37419@% Editing a Font 6.4%@BO: 3818c@% Changing Font File Header Information 6.5%@BO: 39c7a@% Summary %@AB@%PART III%@AE@%%@BO: 39d91@% %@AB@%Debugging and Optimization Tools%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%Chapter 7%@AE@%%@BO: 3a335@% %@AB@%Debugging in Protected Mode: CodeView for Windows%@AE@% 7.1%@BO: 3acad@% Requirements for Use 7.2%@BO: 3b253@% Comparing %@AB@%CVW%@AE@% with Other Microsoft Debuggers 7.2.1%@BO: 3b461@% Differences between CVW and SYMDEB 7.2.2%@BO: 3bc05@% Differences between CVW and CodeView for DOS 7.3%@BO: 3c7e7@% Preparing to Run CVW 7.3.1%@BO: 3ca33@% Setting Up a Secondary Monitor 7.3.2%@BO: 3d1c0@% Setting Up the Debugging Version of Windows 7.3.3%@BO: 3dc1d@% Preparing Windows Applications for Debugging 7.4%@BO: 3e208@% Starting a Debugging Session 7.4.1%@BO: 3e5aa@% Starting a Debugging Session for a Single Application 7.4.2%@BO: 3ed39@% Starting a Debugging Session for Multiple Instances of an Application 7.4.3%@BO: 3f295@% Starting a Debugging Session for Multiple Applications 7.4.4%@BO: 3f9ce@% Starting a Debugging Session for DLLs 7.4.5%@BO: 40849@% Using CVW File Run Options 7.5%@BO: 41ef7@% Saving Session Information 7.6%@BO: 42570@% Working with the CVW Screen 7.6.1%@BO: 42713@% Using CVW Display Windows 7.6.2%@BO: 43d21@% Using the CVW Menu Bar 7.7%@BO: 45c88@% Getting On-line Help in %@AB@%CVW%@AE@% 7.8%@BO: 45e67@% Displaying Program Data 7.8.1%@BO: 46119@% Displaying Variables 7.8.2%@BO: 46d22@% Displaying Expressions 7.8.3%@BO: 4716f@% Displaying Arrays and Structures 7.8.4%@BO: 485b5@% Using the Quick Watch Command 7.8.5%@BO: 48afc@% Tracing Windows Messages 7.8.6%@BO: 491e4@% Displaying Memory 7.8.7%@BO: 4b845@% Displaying the Contents of Registers 7.8.8%@BO: 4bd76@% Displaying Windows Modules 7.9%@BO: 4bed4@% Modifying Program Data 7.10%@BO: 4c716@% Controlling Program Execution 7.10.1%@BO: 4cbf5@% Continuous Execution 7.10.2%@BO: 4f4a1@% Single-Step Execution 7.10.3%@BO: 4fc5f@% Jumping to a Particular Location 7.10.4%@BO: 502fa@% Interrupting Your Program 7.11%@BO: 51117@% Handling Abnormal Termination of the Application 7.11.1%@BO: 5145f@% Handling a Fatal Exit 7.11.2%@BO: 5220f@% Handling a GP Fault 7.12%@BO: 52587@% Ending a CVW Session 7.13%@BO: 5267d@% Restarting a %@AB@%CVW%@AE@% Debugging Session 7.14%@BO: 52a52@% Advanced %@AB@%CVW%@AE@% Techniques 7.14.1%@BO: 52c37@% Using Multiple Source Windows 7.14.2%@BO: 52e37@% Calling Functions 7.14.3%@BO: 53286@% Checking for Undefined Pointers 7.14.4%@BO: 53804@% Handling Register Variables 7.14.5%@BO: 53c7d@% Redirecting %@AB@%CVW%@AE@% Input and Output 7.15%@BO: 54118@% Customizing CVW with the TOOLS.INI File 7.16%@BO: 5446a@% A Sample Session in %@AB@%CVW%@AE@% 7.17%@BO: 56924@% Summary %@AB@%Chapter 8%@AE@%%@BO: 56cd9@% %@AB@%Debugging in Real Mode: Symbolic Debugger%@AE@% 8.1%@BO: 575ef@% Preparing Symbol Files 8.1.1%@BO: 57827@% MAPSYM Program 8.1.2%@BO: 58494@% The Incremental Linker 8.1.3%@BO: 5868a@% Symbols with C-Language Applications 8.1.4%@BO: 58b5c@% Symbols with Assembly-Language Applications 8.2%@BO: 59092@% Setting Up the Debugging Terminal 8.2.1%@BO: 59247@% Setting Up a Remote Terminal 8.2.2%@BO: 59702@% Setting Up a Secondary Monitor 8.3%@BO: 59bfb@% Starting SYMDEB with Windows 8.3.1%@BO: 5a251@% Specifying SYMDEB Options 8.3.2%@BO: 5c64c@% Specifying Symbol Files 8.3.3%@BO: 5cd9b@% Passing the Application to Windows 8.3.4%@BO: 5d09c@% Using SYMDEB Keys 8.4%@BO: 5d7aa@% Working with Symbol Maps 8.4.1%@BO: 5dc42@% Listing the Symbol Maps 8.4.2%@BO: 5e4ee@% Opening a Symbol Map 8.4.3%@BO: 5e71d@% Displaying Symbols 8.5%@BO: 5ecd4@% Starting the Application 8.6%@BO: 5ef91@% Displaying Allocation Messages 8.6.1%@BO: 5f80a@% Setting Breakpoints with Symbols 8.6.2%@BO: 5fdd4@% Displaying Variables 8.6.3%@BO: 603d4@% Displaying Application Source Statements 8.7%@BO: 60938@% Quitting SYMDEB 8.8%@BO: 60dad@% SYMDEB Command Overview and Tables 8.8.1%@BO: 62bfa@% Command Arguments 8.8.2%@BO: 65499@% Address Arguments 8.8.3%@BO: 66503@% Expressions 8.9%@BO: 66e66@% SYMDEB Commands a ─ Assemble%@BO: 670b1@% ba ─ Breakpoint Address%@BO: 6783c@% bc ─ Breakpoint Clear%@BO: 68271@% bd ─ Breakpoint Disable%@BO: 684c3@% be ─ Breakpoint Enable%@BO: 68713@% bl ─ Breakpoint List%@BO: 68987@% bp ─ Breakpoint Set%@BO: 68c25@% c ─ Compare%@BO: 691ac@% d ─ Dump%@BO: 6943b@% da ─ Dump ASCII%@BO: 69704@% db ─ Dump Bytes%@BO: 69961@% dd ─ Dump Doublewords%@BO: 69c49@% df ─ Display Global Free List%@BO: 69e58@% dg ─ Display Global Heap%@BO: 6a132@% dh ─ Display Local Heap%@BO: 6ac49@% dl ─ Dump Long Reals%@BO: 6b07e@% dm ─ Display Global Module List%@BO: 6b2c7@% dq ─ Dump Task Queue%@BO: 6b601@% ds ─ Dump Short Reals%@BO: 6ba78@% dt ─ Dump Ten-Byte Reals%@BO: 6bcbf@% du ─ Display Global LRU List%@BO: 6bef1@% dw ─ Dump Words%@BO: 6c793@% e ─ Enter%@BO: 6c976@% ea ─ Enter Address%@BO: 6ccc9@% eb ─ Enter Bytes%@BO: 6cf2c@% ed ─ Enter Doublewords%@BO: 6d222@% el ─ Enter Long Reals%@BO: 6d4ef@% es ─ Enter Short Reals%@BO: 6d765@% et ─ Enter Ten-Byte Reals%@BO: 6d9e0@% ew ─ Enter Words%@BO: 6dc55@% f ─ Fill%@BO: 6de8f@% g ─ Go%@BO: 6e0ec@% h ─ Hex%@BO: 6e471@% i ─ Input%@BO: 6e5df@% k ─ Backtrace Stack%@BO: 6e788@% kt ─ Backtrace Task Stack%@BO: 6eadf@% kv ─ Verbose Backtrace Stack%@BO: 6ee2a@% l ─ Load%@BO: 6efe0@% m ─ Move%@BO: 6f5e1@% m%@AI@%id%@AE@%%@AB@%%@AE@%─ Macro%@BO: 6f7a2@% n ─ Name%@BO: 6fb3f@% o ─ Output%@BO: 6ff21@% p ─ Program Step%@BO: 700c1@% q ─ Quit%@BO: 7043c@% r ─ Register%@BO: 705a1@% s ─ Search%@BO: 708e5@% Set Source Mode%@BO: 70a89@% t ─ Trace%@BO: 70efd@% u ─ Unassemble%@BO: 71280@% v ─ View%@BO: 71532@% w ─ Write%@BO: 716a0@% x ─ Examine Symbol Map%@BO: 71b29@% xo ─ Open Symbol Map%@BO: 722ba@% z ─ Set Symbol Value%@BO: 72566@% ? ─ Display Help%@BO: 726a5@% ? ─ Display Expression%@BO: 727e7@% . ─ Source-Line Display%@BO: 72a6f@% Redirect Input%@BO: 72b9a@% Redirect Output%@BO: 72d9b@% Redirect Input and Output%@BO: 72f78@% ! ─ Shell Escape%@BO: 73188@% * ─ Comment%@BO: 7342a@% %@AB@%Chapter 9%@AE@%%@BO: 73575@% %@AB@%Advanced Debugging in Protected Mode: 80386 Debugger%@AE@% 9.1%@BO: 73af4@% Preparing Symbol Files for the 80386 Debugger 9.2%@BO: 73dd5@% Starting the Debugger 9.3%@BO: 74653@% When an Application Fails 9.4%@BO: 74ce9@% Debugger Command Format 9.4.1%@BO: 74ebc@% Command Keys 9.4.2%@BO: 750c9@% Command Parameters 9.4.3%@BO: 76c60@% Binary and Unary Operators 9.5%@BO: 7763a@% Common Command Directory ? ─ Display Expression%@BO: 782f8@% ? ─ Display Help Menu%@BO: 79359@% .? ─ Display External Commands%@BO: 7949d@% .b ─ Set COM Port Baud Rate%@BO: 7963e@% .df ─ Display Global Free List%@BO: 79c60@% .dg ─ Display Global Heap%@BO: 7a0c0@% .dh ─ Display Local Heap%@BO: 7aea7@% .dm ─ Display Global Module List%@BO: 7b2f8@% .dq ─ Dump Task Queue%@BO: 7b643@% .du ─ Display Global LRU List%@BO: 7bacb@% .reboot ─ Reboot Target System%@BO: 7c430@% bc ─ Clear Breakpoints%@BO: 7c56a@% bd ─ Disable Breakpoints%@BO: 7c975@% be ─ Enable Breakpoints%@BO: 7ce01@% bl ─ List Breakpoints%@BO: 7d268@% bp ─ Set Breakpoints%@BO: 7d81f@% c ─ Compare Memory%@BO: 7e3ab@% d ─ Display Memory%@BO: 7ea53@% db ─ Display Bytes%@BO: 7f13f@% dd ─ Display Doublewords%@BO: 7f799@% dg ─ Display GDT%@BO: 7ff2f@% di ─ Display IDT%@BO: 806b2@% dl ─ Display LDT%@BO: 80ed0@% dt ─ Display TSS%@BO: 8190e@% dw ─ Display Words%@BO: 81e26@% e ─ Enter Byte%@BO: 8252a@% f ─ Fill Memory%@BO: 8301d@% g ─ Go%@BO: 83742@% h ─ Hexadecimal Arithmetic%@BO: 842e4@% i ─ Input Byte%@BO: 8472d@% j ─ Conditional Execute%@BO: 849d4@% k ─ Backtrace Stack%@BO: 85209@% ka ─ Set Backtrace Arguments%@BO: 856b6@% kt ─ Backtrace Task Stack%@BO: 859f3@% kv ─ Verbose Backtrace Stack%@BO: 85ffa@% la ─ List Absolute Symbols%@BO: 861b7@% lg ─ List Groups%@BO: 862f7@% lm ─ List Map%@BO: 86662@% ln ─ List Near%@BO: 868dd@% ls ─ List Symbols%@BO: 86d08@% m ─ Move Memory%@BO: 873c5@% o ─ Output to Port%@BO: 87b9e@% p ─ Program Trace%@BO: 87e9f@% r ─ Display Registers%@BO: 889a5@% s ─ Search Bytes%@BO: 89d82@% t ─ Trace Instructions%@BO: 8a3ff@% u ─ Unassemble Bytes%@BO: 8ada1@% v ─ Set Interrupt Vector Trapping%@BO: 8b5ed@% vl ─ Display Interrupt Trapping Information%@BO: 8bcf1@% w ─ Change Map%@BO: 8bf38@% y ─ Debugger Option Command%@BO: 8c621@% z ─ Zap Embedded INT 1 and INT 3 Instructions%@BO: 8ce3e@% zd ─ Execute Default Command String%@BO: 8d048@% zl ─ Display Default Command String%@BO: 8d356@% zs ─ Change Default Command String%@BO: 8d50c@% 9.6 386 Enhanced Windows Environment Commands%@BO: 8dbb2@% 9.7 Summary%@BO: 904b0@% %@AB@%Chapter 10%@AE@%%@BO: 9079e@% %@AB@%Monitoring Messages: Spy%@AE@% 10.1%@BO: 90bc5@% Displaying Messages 10.2%@BO: 90f08@% Choosing Options 10.2.1%@BO: 910cb@% Choosing Messages 10.2.2%@BO: 917e0@% Choosing the Output Device 10.2.3%@BO: 91bb1@% Choosing Frequency of Output 10.3%@BO: 91e50@% Choosing a Window: The Window Menu 10.4%@BO: 92730@% Turning Spy On and Off: The Spy Menu 10.5%@BO: 92a4a@% Summary %@AB@%Chapter 11%@AE@%%@BO: 92cf7@% %@AB@%Viewing the Heap: Heap Walker%@AE@% 11.1%@BO: 92fec@% How Heap Walker Views Memory 11.1.1%@BO: 93107@% Viewing the Heap in Protected Mode 11.1.2%@BO: 932ad@% Viewing the Heap in Real Mode 11.2%@BO: 93561@% The Heap Walker Window 11.3%@BO: 93a55@% Using Heap Walker Commands 11.3.1%@BO: 93c03@% Performing File Operations: The File Menu 11.3.2%@BO: 9427e@% Walking the Heap: The Walk and EmsWalk Menus 11.3.3%@BO: 95063@% Sorting Memory Objects: The Sort Menu 11.3.4%@BO: 95400@% Displaying Memory Objects: The Object Menu 11.3.5%@BO: 962ec@% Allocating Memory: The Alloc Menu 11.3.6%@BO: 96c22@% Determining Memory Size: The Add! Menu 11.4%@BO: 96dc5@% Suggestions for Using Heap Walker 11.5%@BO: 977d9@% Summary %@AB@%Chapter 12%@AE@%%@BO: 97904@% %@AB@%Moving Memory: Shaker%@AE@% 12.1%@BO: 97bb6@% Using Shaker 12.2%@BO: 98622@% Summary %@AB@%Chapter 13%@AE@%%@BO: 98768@% %@AB@%Analyzing CPU Time: Profiler%@AE@% 13.1%@BO: 98bc7@% Overview of Profiler 13.2%@BO: 9936c@% Preparing to Run Profiler 13.3%@BO: 998e1@% Using Profiler Functions 13.3.1%@BO: 99d26@% Starting and Stopping Sampling: The ProfStart and ProfStop Functions 13.3.2%@BO: 9a38f@% Checking if Profiler Is Installed: The ProfInsChk Function 13.3.3%@BO: 9a621@% Setting the Sampling Rate: The ProfSampRate Function 13.3.4%@BO: 9af87@% Managing Output: The ProfClear, ProfFlush, and ProfSetup Functions 13.3.5%@BO: 9bbd2@% Stopping Profiler: The ProfFinish Function 13.4%@BO: 9be9e@% Sampling Code 13.4.1%@BO: 9c496@% Sampling Applications in Windows Real Mode 13.4.2%@BO: 9cf81@% Sampling Applications in Windows 386 Enhanced Mode 13.5%@BO: 9d309@% Displaying Samples: SHOWHITS.EXE 13.6%@BO: 9ebf9@% Summary %@AB@%Chapter 14%@AE@%%@BO: 9ed31@% %@AB@%Analyzing Swaps: Swap%@AE@% 14.1%@BO: 9f0b2@% Preparing to Run Swap 14.1.1%@BO: 9f1bd@% Files You Need to Run Swap 14.1.2%@BO: 9f5c1@% Using the SwapRecording Function 14.2%@BO: 9f9d0@% Running Swap 14.2.1%@BO: a0052@% Specifying a Symbol-File Path 14.2.2%@BO: a0259@% Specifying a Pathname for the Data Collection File 14.2.3%@BO: a0440@% Specifying a Module and Segment 14.3%@BO: a0768@% Displaying Output 14.4%@BO: a15fb@% Summary %@AB@%PART IV%@AE@%%@BO: a1750@% %@AB@%Help Tools%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%Chapter 15%@AE@%%@BO: a1a76@% %@AB@%Providing Help: The Help System%@AE@% 15.1%@BO: a1efb@% Creating a Help System: The Development Cycle 15.2%@BO: a25a6@% How Help Appears to the User 15.3%@BO: a2a32@% How Help Appears to the Help Writer 15.4%@BO: a2e0e@% How Help Appears to the Help Programmer 15.5%@BO: a3015@% Summary %@AB@%Chapter 16%@AE@%%@BO: a3307@% %@AB@%Planning the Help System%@AE@% 16.1%@BO: a3529@% Developing a Plan 16.1.1%@BO: a3847@% Defining the Audience 16.1.2%@BO: a3da2@% Planning the Content of the Help System 16.1.3%@BO: a42e0@% Planning the Structure of Help Topics 16.1.4%@BO: a4d6a@% Displaying Context-Sensitive Help Topics 16.2%@BO: a571a@% Determining the Topic File Structure 16.2.1%@BO: a5985@% Choosing a File Structure for Your Application 16.3%@BO: a5f48@% Designing the Appearance of Help Topics 16.3.1%@BO: a612e@% Layout of the Help Text 16.3.2%@BO: a76d9@% Type Fonts and Sizes 16.3.3%@BO: a7cb9@% Graphic Images 16.4%@BO: a8119@% Summary %@AB@%Chapter 17%@AE@%%@BO: a8875@% %@AB@%Creating the Help Topic Files%@AE@% 17.1%@BO: a8c68@% Choosing an Authoring Tool 17.2%@BO: a9015@% Structuring Help Topic Files 17.3%@BO: a9424@% Coding Help Topic Files 17.3.1%@BO: aa061@% Assigning Build Tags 17.3.2%@BO: aaca1@% Assigning Context Strings 17.3.3%@BO: ab556@% Assigning Titles 17.3.4%@BO: abd90@% Assigning Key Words 17.3.5%@BO: ad08c@% Assigning Browse Sequence Numbers 17.3.6%@BO: ae5d1@% Creating Cross-References Between Topics 17.3.7%@BO: aeb5f@% Defining Terms 17.4%@BO: af620@% Inserting Graphic Images 17.4.1%@BO: af8d0@% Creating and Capturing Bitmaps 17.4.2%@BO: aff35@% Placing Bitmaps Using a Graphical Word Processor 17.4.3%@BO: b019e@% Placing Bitmaps by Reference 17.5%@BO: b0c62@% Managing Topic Files 17.5.1%@BO: b0f4c@% Keeping Track of Files and Topics 17.5.2%@BO: b12dc@% Creating a Help Tracker 17.6%@BO: b1b0f@% Summary %@AB@%Chapter 18%@AE@%%@BO: b1c01@% %@AB@%Building the Help File%@AE@% 18.1%@BO: b201c@% Creating the Help Project File 18.2%@BO: b29aa@% Specifying Topic Files: The Files Section 18.3%@BO: b2fdf@% Specifying Build Tags: The BuildTags Section 18.4%@BO: b3425@% Specifying Options: The Options Section 18.4.1%@BO: b3b4f@% Specifying Error Reporting: The Warning Option 18.4.2%@BO: b426e@% Specifying Build Topics: The Build Option 18.4.3%@BO: b4d85@% Specifying the Root Directory: The Root Option 18.4.4%@BO: b5232@% Specifying the Index: The Index Option 18.4.5%@BO: b5760@% Assigning a Title to the Help System: The Title Option 18.4.6%@BO: b5a93@% Converting Fonts: The Forcefont Option 18.4.7%@BO: b608e@% Changing Font Sizes : The Mapfontsize Option 18.4.8%@BO: b6889@% Multiple Key-Word Tables: The Multikey Option 18.4.9%@BO: b6e82@% Compressing the File: The Compress Option 18.5%@BO: b74ed@% Specifying Alternate Context Strings: The Alias Section 18.6%@BO: b7ed7@% Mapping Context-Sensitive Topics: The Map Section 18.7%@BO: b8ddd@% Including Bitmaps by Reference: The Bitmaps Section 18.8%@BO: b90e9@% Compiling Help Files 18.8.1%@BO: b9b13@% Using the Help Compiler 18.9%@BO: b9f8d@% Programming the Application to Access Help 18.9.1%@BO: ba1b0@% Calling WinHelp from an Application 18.9.2%@BO: bb31b@% Getting Context-Sensitive Help 18.9.3%@BO: bd387@% Getting Help on an Item Listed on the Help Menu 18.9.4%@BO: bd6c6@% Accessing Additional Key-Word Tables 18.9.5%@BO: bdf91@% Canceling Help 18.10%@BO: be805@% Summary %@AB@%Chapter 19%@AE@%%@BO: beaa9@% %@AB@%Help Examples and Compiler Error Messages%@AE@% 19.1%@BO: bef59@% Help Topic Examples 19.2%@BO: bf6ba@% Help Compiler Error Messages 19.2.1%@BO: c01ca@% Errors During Processing of Project File 19.2.2%@BO: c3d6c@% Errors During Processing of RTF Topic Files %@AB@%Index%@AE@%%@BO: c8c74@% %@CR:C6A-Intro @%%@1@%%@AB@%Introduction%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% The %@AI@%Microsoft(R) Windows(tm) Software Development Kit Tools%@AE@% manual explains how to use the programming tools that come with the Microsoft Windows Software Development Kit (SDK). This manual also explains how to use some additional tools, such as the C Compiler and linker, that don't come with the SDK but which you will need in order to create Windows applications.%@NL@% This introductory chapter describes the following topics: %@NL@% ■ The general organization of %@AI@%Tools%@AE@%%@NL@% ■ An overview of the steps involved in creating a Windows application%@NL@% ■ The notational conventions used throughout the manual%@NL@% ■ Related documentation %@NL@% %@2@%%@CR:C6A00000001 @%%@AB@%Organization of This Manual%@AE@%%@EH@%%@NL@% This manual is divided into four parts, each of which contains several chapters. %@NL@% Part 1, "Compilers and Linkers," explains how to compile and link your source files. Part 1 consists of the following chapters.%@CR:C6A00000002 @%%@CR:C6A00000003 @%%@CR:C6A00000004 @%%@CR:C6A00000005 @%%@CR:C6A00000006 @%%@NL@% ■ Chapter 1, "Compiling Applications: The C Compiler," explains how to use the C Compiler (%@AB@%CL%@AE@%) to compile C-language source files for Windows applications.%@NL@% ■ Chapter 2, "Linking Applications: The Linker," explains how to use the linker (%@AB@%LINK%@AE@%) to link compiled source files into an executable Windows application.%@NL@% ■ Chapter 3, "Compiling Resources: The Resource Compiler," explains how to use the Resource Compiler (%@AB@%RC%@AE@%) to compile application resources and add them to an executable Windows application.%@NL@% Part 2, "Resource Editors," explains how to create and maintain Windows program resources, such as icons and bitmaps, using the tools that come with the SDK. Part 2 consists of the following chapters: %@NL@% ■ Chapter 4, "Designing Images: SDKPaint," explains how to use SDKPaint (%@AB@%SDKPAINT%@AE@%) to create and edit icons, cursors, and bitmaps for Windows applications. %@NL@% ■ Chapter 5, "Designing Dialog Boxes: The Dialog Editor," explains how to use the Dialog Editor (%@AB@%DIALOG%@AE@%) to create and edit dialogs for Windows applications.%@NL@% ■ Chapter 6, "Designing Fonts: The Font Editor," explains how to use the Font Editor (%@AB@%FONTEDIT%@AE@%) to create and edit font files for Windows applications.%@NL@% Part 3, "Debugging and Optimization Tools," explains how to use the debugging and testing tools that come with the SDK. Part 3 consists of the following chapters:%@AB@% %@AE@%%@NL@% ■ Chapter 7, "Debugging in Protected Mode: CodeView for Windows," explains how to use CodeView(R) for Windows (%@AB@%CVW%@AE@%) to debug Windows applications that run in protected mode.%@NL@% ■ Chapter 8, "Debugging in Real Mode: Symbolic Debugger," explains how to use the Symbolic Debugger (%@AB@%SYMDEB%@AE@%) to debug Windows applications that run in real mode.%@NL@% ■ Chapter 9, "Advanced Debugging in Protected Mode: 80386 Debugger," explains how to use the 80386 Debugger (%@AB@%WDEB386%@AE@%) to debug Windows applications that run in protected mode.%@NL@% ■ Chapter 10, "Monitoring Messages: Spy," explains how to use Spy (%@AB@%SPY%@AE@%) to monitor a window receiving system messages. %@NL@% ■ Chapter 11, "Viewing the Heap: Heap Walker," explains how to use Heap Walker (%@AB@%HEAPWALK%@AE@%) to open and examine the global heap.%@NL@% ■ Chapter 12, "Moving Memory: Shaker," explains how to use Shaker (%@AB@%SHAKER%@AE@%) to see the effect of memory movement on applications.%@NL@% ■ Chapter 13, "Analyzing CPU Time: Profiler," explains how to use Profiler (%@AB@%PROFILER%@AE@%) to analyze and optimize the performance of moveable code.%@NL@% ■ Chapter 14, "Analyzing Swaps: Swap," explains how to use Swap (%@AB@%SWAP%@AE@%) to analyze and optimize your application's swapping behavior.%@NL@% Part 4, "Help Tools," explains how to plan, write, and compile a Windows Help system. Part 4 consists of the following chapters:%@AB@% %@AE@%%@NL@% ■ Chapter 15, "Providing Help: The Help System," gives an overview of the Help system from the point of view of the user, the Help writer, and the Help programmer.%@NL@% ■ Chapter 16, "Planning the Help System," explains what considerations the Help writer should keep in mind when planning a Help system.%@NL@% ■ Chapter 17, "Creating the Help Topic Files," explains how to write and code Help text files.%@NL@% ■ Chapter 18, "Building the Help File," explains how to build a Help resource file.%@NL@% ■ Chapter 19, "Help Examples and Compiler Error Messages," shows example topic files in several word processors, together with their corresponding Help display. The chapter also includes a listing of Help compiler error messages.%@NL@% %@2@%%@CR:C6A00000007 @%%@AB@%Building a Windows Application%@AE@%%@EH@%%@NL@% You can build a Windows application using any ASCII text editor and the tools described in this manual. This section briefly explains the process involved in creating a Windows application, and highlights the role that the development tools play in this process. %@NL@% To build a Windows application, do the following:%@CR:C6A00000008 @%%@CR:C6A00000009 @%%@CR:C6A00000010 @%%@NL@% 1. Using a text editor, create C-language or assembly-language source files that contain the WinMain function, window functions, and other application code.%@CR:C6A00000011 @%%@NL@% 2. Create any cursor, icon, bitmap, dialog, and font resources the application will need with the resource editors (%@AB@%SDKPAINT%@AE@%, %@AB@%DIALOG%@AE@%, and %@AB@%FONTEDIT%@AE@%).%@NL@% 3. Produce a resource script (.RC) file that defines all of the application's resources. The script file, which you create with a text editor, lists and names the resources you created in the preceding step. It also defines menus, dialog boxes, and other resources, such as string tables and application-defined resources.%@CR:C6A00000012 @%%@NL@% 4. Use the Resource Compiler with the %@AB@%-r%@AE@% switch to compile the resource script (.RC) file into a binary resource (.RES) file. %@CR:C6A00000013 @%%@NL@% 5. Use a text editor to create the module-definition (.DEF) file. %@CR:C6A00000014 @%%@NL@% 6. Compile all C-language sources with the C Compiler. Use the Microsoft Macro Assembler (%@AB@%MASM%@AE@%) to assemble all assembly-language sources.%@CR:C6A00000015 @%%@NL@% 7. Using %@AB@%LINK%@AE@%, link the compiled and/or assembled source files with your Windows and C run-time libraries. This produces a file with the .EXE extension; however, you cannot execute such a file, because it does not yet include the compiled resources.%@NL@% 8. Use %@AB@%RC%@AE@% without the %@AB@%-r%@AE@% switch to add the binary resource (.RES) file to the .EXE file. This produces an executable Windows application.%@NL@% 9. Track down program errors and other problems with the Windows debuggers: CodeView for Windows and the Symbolic Debugger. The Spy program is useful for monitoring the Windows messages your program receives. The Shaker program lets you simulate memory movements that occur in the Windows multitasking environment.%@NL@% 10. Fine-tune your program with Windows optimization tools, Profiler and Swap, so that it runs faster and uses memory more efficiently. %@NL@% 11. Build your program's help system with the Windows Help tools. This step can take place during, rather than after, the application-development process.%@NL@% The following figure shows the steps required to build a Windows application. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% The figure "Building a Windows Application" does not include the debugging, optimization, or Help tools. %@NL@% %@2@%%@CR:C6A00000016 @%%@AB@%Document Conventions%@AE@%%@EH@%%@NL@% Throughout this manual, the term "DOS" refers to both MS-DOS(R) and PC-DOS, except when noting features that are unique to one or the other.%@CR:C6A00000017 @%%@NL@% The following document conventions are used throughout this manual: %@NL@% %@TH: 75 5380 02 34 42 @%Convention Description of Convention%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%Bold text%@AE@% Bold text indicates a specific term or punctuation mark intended to be used literally: language key words or functions (such as %@AB@%EXETYPE%@AE@% or %@AB@%%@AE@% %@AB@%CreateWindow%@AE@%), DOS commands, and command-line options (such as %@AB@%/Zi%@AE@%). You must type these terms and punctuation marks exactly as shown. However, the use of uppercase or lowercase letters is not always significant. For instance, you can invoke the linker by typing either %@AB@%%@AE@% %@AB@%LINK%@AE@%, %@AB@%link%@AE@%, or %@AB@%Link%@AE@% at the DOS prompt. %@CR:C6A00000018 @% %@CR:C6A00000019 @%( ) In syntax statements, parentheses enclose one or more parameters that you pass to a function. %@CR:C6A00000020 @% %@CR:C6A00000021 @% %@CR:C6A00000022 @% %@AI@%Italic text%@AE@% Italic text indicates a placeholder; you are expected to provide the actual value. For example, the following syntax for the %@AB@%Set-%@AE@% %@AB@%CursorPos%@AE@% function indicates that you must substitute values for the %@AI@%X%@AE@% and %@AI@%Y%@AE@% coordinates, separated by a comma: %@AB@%%@AE@% %@AB@%SetCursorPos(%@AE@%%@AI@%X, Y%@AE@%%@AB@%)%@AE@% %@CR:C6A00000023 @% %@CR:C6A00000024 @% %@AS@%Monospaced type%@AE@% Code examples are displayed in a nonproportional typeface. %@CR:C6A00000025 @% %@CR:C6A00000026 @% %@AS@%BEGIN%@RR@% .%@RR@% .%@RR@% .%@RR@%END%@AE@% A vertical ellipsis in a program example indicates that a portion of the program is omitted. %@CR:C6A00000027 @% %@CR:C6A00000028 @%. . . An ellipsis following an item indicates that more items having the same form may appear. In the following example, the horizontal ellipsis indicates that you can specify more than one %@AI@%breakaddress%@AE@% value for the %@AB@%g%@AE@% command: %@AB@%g%@AE@% «=%@AI@%startaddress%@AE@%» «%@AI@%breakaddress%@AE@%»...%@CR:C6A00000029 @%%@CR:C6A00000030 @%%@CR:C6A00000031 @%« » Double brackets enclose optional fields or parameters in command lines and syntax statements. In the following example, %@AI@%option%@AE@% and %@AI@%executable-file%@AE@% are optional parameters of the %@AB@%RC%@AE@% command: %@CR:C6A00000032 @% %@CR:C6A00000033 @% %@CR:C6A00000034 @% %@CR:C6A00000035 @% %@AB@%RC%@AE@% «%@AI@%option%@AE@%» %@AI@%filename%@AE@% «%@AI@%executable-file%@AE@%»| A 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: %@CR:C6A00000036 @% %@CR:C6A00000037 @% %@CR:C6A00000038 @%%@AB@%%@AE@% %@AB@%DB%@AE@% «%@AI@%address%@AE@% | %@AI@%range%@AE@%» The bar indicates that following the %@AB@%%@AE@% %@AB@%Dump Bytes%@AE@% command (%@AB@%DB%@AE@%), you can specify either an %@AI@%address%@AE@% or a %@AI@%range%@AE@%. " " Quotation marks set off terms defined in the text. %@CR:C6A00000039 @% %@CR:C6A00000040 @% %@CR:C6A00000041 @%{ } Curly braces indicate that you must specify one of the enclosed items.%@CR:C6A00000042 @% %@CR:C6A00000043 @% %@CR:C6A00000044 @% %@CR:C6A00000045 @%SMALL CAPITAL LETTERS Small capital letters indicate the names of keys and key sequences, such as: ALT + SPACEBAR %@CR:C6A00000046 @% %@CR:C6A00000047 @% %@CR:C6A00000048 @% %@CR:C6A00000049 @%%@TE: 75 5380 02 34 42 @% %@4@%%@AB@%Microsoft Windows Software Development Kit Documentation Set%@AE@%%@EH@%%@NL@% Throughout this documentation set "SDK" refers specifically to the Microsoft Windows Software Development Kit and its contents. The SDK includes the following manuals: %@NL@% %@AB@%Title%@AE@% %@AB@%Contents%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AI@%Installation and%@AE@% Provides an orientation to the SDK, %@AI@%Update Guide %@AE@% explains how to install the SDK software, and highlights the changes for version 3.0.%@AI@%%@AE@% %@AI@%Guide to Programming%@AE@% Explains how to write Windows applications, and provides sample applications that you can use as templates for writing your own programs. The %@AI@%Guide to Programming%@AE@% also addresses some advanced Windows programming topics. %@AI@%Tools%@AE@% Explains how to use the software-development tools you'll need to build Windows applications, such as debuggers and specialized SDK editors. %@AI@%Reference%@AE@% Is a comprehensive guide to all the details of the Microsoft Windows application program interface (API). The %@AI@%Reference%@AE@% lists in alphabetical order all the current functions, messages, and data structures of the API, and provides extensive overviews on how to use the API. %@AI@%System Application Architecture,%@AE@% Provides guidelines and recommendations %@AI@%Common User Access: Advanced %@AE@% for writing programs that appear and act %@AI@%Interface Design Guide%@AE@% consistently like other Microsoft Windows applications. %@2@%%@CR:C6A00000050 @%%@AB@%Summary%@AE@%%@EH@%%@NL@% This introductory chapter explained the organization of %@AI@%Tools%@AE@%, and briefly described the tools and processes you use to build Windows applications. %@NL@% For more information about building Windows applications, see %@AI@%Guide to %@AI@%Programming%@AE@%. %@NL@% %@CR:C6A-Part 01 @%%@1@%%@AB@%PART I Compilers and Linkers%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Part 1 describes how to use the C Compiler to compile your C-language source code modules, the linker to link your compiled or assembled source files with your Microsoft Windows and C run-time libraries, and the Resource Compiler to produce an executable Windows application. %@NL@% %@CR:C6A00010001 @%%@1@%%@AB@%Chapter 1 Compiling Applications: The C Compiler%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Many Microsoft Windows applications are written in the C programming language and are compiled using the Microsoft C Compiler (%@AB@%CL%@AE@%). This chapter describes the following topics: %@NL@% ■ A brief overview of how to write C-language Windows applications%@NL@% ■ How to use the Microsoft C Compiler to compile C-language Windows applications%@NL@% This chapter deals only with the special compilation requirements of C-language Windows applications. For complete information on using the C Compiler, see the Microsoft C documentation. For information on writing Windows applications using the C language, see the %@AI@%Guide to Programming%@AE@%. %@NL@% %@2@%%@CR:C6A00010002 @%%@AB@%1.1 Compiling C-Language Windows Applications%@AE@%%@EH@%%@NL@% To compile a C-language Windows application, use the Microsoft C Compiler. The compiler comes with Microsoft C; it is not included in the Microsoft Windows Software Development Kit (SDK). Microsoft Windows requires version 5.1 or later of Microsoft C, or version 2.0 or later of Microsoft QuickC (R). To start the Microsoft C Compiler, use the %@AB@%CL%@AE@% command. Table 1.1, "C Compiler Options for Windows Applications," lists and describes the options commonly used for compiling Windows applications.%@CR:C6A00010003 @%%@CR:C6A00010004 @%%@CR:C6A00010005 @%%@CR:C6A00010006 @%%@CR:C6A00010007 @%%@NL@% Table 1.1 C Compiler Options for Windows Applications %@TH: 10 609 02 08 34 34 @%Option What It Does When to Use It%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%-AC%@AE@% Compiles the application for the Used when an application has one compact memory model. code segment but multiple data segments.%@AB@%-AL%@AE@% Compiles the application for the Used when an application has large memory model. multiple segments for both code and data.%@TE: 10 609 02 08 34 34 @% Table 1.1 C Compiler Options for Windows Applications (continued) %@TH: 65 3904 02 08 34 34 @%Option What It Does When to Use It%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%-AM%@AE@% Compiles the application for the Used when an application has medium memory model. multiple code segments but one data segment. Can also be used to create applications using the mixed memory model. See %@AI@%Guide to%@AE@% %@AI@%Programming%@AE@% for a description of the mixed memory model.%@AB@%-AS%@AE@% Compiles the application for the Used when an application has small memory model. only one code and one data segment. Can also be used to create applications using the mixed memory model.%@AB@%-Aw%@AE@% Ensures that pointers receive Used when compiling a their proper segment addresses dynamic-link library (DLL). when cast to 32-bit addresses. %@AB@%-c%@AE@% Compiles only. Required if you have more than one C source module and you want to separate linking from compiling.%@AB@%-Gs%@AE@% Removes stack probes, thereby Recommended for all Windows improving performance. applications after the development process is complete.%@AB@%-Gw%@AE@% Adds the Windows prolog and Required for all Windows source epilog to all functions. code modules. (May be used for source code modules that do not contain exported (callback) functions; but -%@AB@%GW%@AE@% is recommended in this case.)%@AB@%-GW%@AE@% Substitutes a reduced Windows Recommended for Windows source prolog and epilog to functions code modules that do not contain that are far calls within the exported or callback functions. application. (Available only with C version 6.0 and later.) %@AB@%-Os%@AE@% Optimizes for code size instead Recommended for all Windows of speed. source code modules.%@AB@%-Ow%@AE@% Relaxes alias checking within Recommended instead of certain constraints imposed by non-Windows %@AB@%-Oa%@AE@% relax-alias- the Windows environment. checking option. (Available only with C version 6.0 and later.) %@AB@%-Zd%@AE@% Creates an object file for use Required for debugging the with the Symbolic Debugger (%@AB@%%@AE@% source-code module using %@AB@%SYMDEB%@AE@% %@AB@%SYMDEB%@AE@%) or the 80386 Debugger (%@AB@%%@AE@% or %@AB@%WDEB386%@AE@%. %@AB@%WDEB386%@AE@%). %@AB@%-Zi%@AE@% Creates an object file for use Required for debugging the with CodeView for Windows (%@AB@%CVW%@AE@%). source-code module using %@AB@%CVW%@AE@%.%@AB@%-Zp%@AE@% Packs structures on single-byte Required for all Windows source boundaries. code modules that use structures. %@CR:C6A00010008 @%%@CR:C6A00010009 @% %@CR:C6A00010010 @%%@AB@% %@AE@%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 65 3904 02 08 34 34 @% In addition to the options in Table 1.1, "C Compiler Options for Windows Applications," which most Windows applications use, you can supply other compiler options as necessary. Section 1.2, "Compiler Options," describes more fully many of the options you may want to use.%@CR:C6A00010011 @%%@CR:C6A00010012 @%%@CR:C6A00010013 @%%@CR:C6A00010014 @%%@NL@% In the following example, the source file TEST.C is compiled using the recommended %@AB@%CL%@AE@% options for a small-model Windows application source file during application development. %@NL@% %@AS@% CL -c -Os -Gw -AS -Zdp TEST.C%@AE@% With these options, the compiler suppresses linking (%@AB@%-c%@AE@%), optimizes for size (%@AB@%-Os%@AE@%), adds the Windows prolog and epilog to exported functions (%@AB@%-Gw%@AE@%), uses the small memory model (%@AB@%-AS%@AE@%), provides line-number information (%@AB@%-Zd%@AE@%), and packs structures (%@AB@%-Zp%@AE@%).%@CR:C6A00010015 @%%@NL@% %@2@%%@CR:C6A00010016 @%%@AB@%1.2 Compiler Options%@AE@%%@EH@%%@NL@% This section describes some compiler options you may want to use when compiling a Windows application. For a complete description of the C Compiler options, see the %@AI@%Microsoft C Optimizing Compiler User's Guide.%@AE@% %@NL@% This section describes the following types of compiler options:%@CR:C6A00010017 @%%@CR:C6A00010018 @%%@NL@% ■ Memory-model options, which let you compile medium, compact, and large-model applications. (By default, the compiler uses the small memory model.)%@NL@% ■ Options you may want to set during application development.%@NL@% ■ Options for compiling dynamic-link libraries. %@NL@% %@3@%%@CR:C6A00010019 @%%@AB@%1.2.1 Memory-Model Options%@AE@%%@EH@%%@NL@% Windows applications can use the small, medium, compact, or large memory model. (Windows does not support the huge memory model.)%@CR:C6A00010020 @%%@CR:C6A00010021 @%%@NL@% You specify a programming model by supplying the appropriate compiler option on the %@AB@%CL%@AE@% command line when you compile the application source files. You base your choice on the application's need for data and code. The memory-model compiler options are: %@NL@% %@AB@%Memory Model%@AE@% %@AB@%Compiler Option%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Small %@AB@%-AS%@AE@% Medium %@AB@%-AM%@AE@% Compact %@AB@%-AC%@AE@% Large %@AB@%-AL%@AE@% The compact and large memory models are not recommended for Windows applications, unless you're creating a Windows application by porting an existing compact or large-model application from the DOS environment. This is because Windows requires that all data segments of compact and large-model applications be fixed, and Windows can run only one instance of an application with far data segments. The following statement must be in the module-definition (.DEF) file of any compact or large-model application: %@NL@% %@AS@% DATA FIXED%@AE@% When compiling medium, compact, and large-model source files for Windows applications, you can specify the names of the code and data segments to which each source belongs. Use the %@AB@%-NT%@AE@% option to specify code segments; use the %@AB@%-ND%@AE@% option for data segments. If you do not use these options, the C Compiler assumes that the source belongs to the standard code and data segments, _TEXT and _DATA.%@CR:C6A00010022 @%%@CR:C6A00010023 @%%@NL@% For more information on memory models, see %@AI@%Guide to Programming%@AE@% and the appropriate Microsoft C documentation. %@NL@% %@3@%%@CR:C6A00010024 @%%@AB@%1.2.2 Application Development Options%@AE@%%@EH@%%@NL@% To make application development and debugging easier, the C Compiler includes options for the following:%@CR:C6A00010025 @%%@NL@% ■ Provides line-number information so you can display program lines%@NL@% ■ Lets you turn off optimization to make debugging easier%@NL@% ■ Lets you disable stack probes %@NL@% %@4@%%@AB@%Preparing for Debugging%@AE@%%@EH@%%@NL@% Windows applications written in C are easier to debug if the compiler adds debugging information to the object file. You can then use the Symbolic Debugger (%@AB@%SYMDEB%@AE@%) utility or CodeView for Windows (%@AB@%CVW%@AE@%) to help you debug your application.%@CR:C6A00010026 @%%@CR:C6A00010027 @%%@CR:C6A00010028 @%%@CR:C6A00010029 @%%@CR:C6A00010030 @%%@NL@% To add debugging information used by %@AB@%SYMDEB%@AE@%, compile your application with the %@AB@%-Zd%@AE@% option. This option produces an object file containing line-number records corresponding to the line numbers of the source file, as well as global-symbol information which %@AB@%SYMDEB%@AE@% uses. For more information on %@AB@%SYMDEB%@AE@%, see Chapter 8, "Debugging in Real Mode: Symbolic Debugger." %@NL@% To add debugging information used by %@AB@%CVW%@AE@%, use the %@AB@%-Zi%@AE@% option when you compile. The resulting object file contains full symbolic-debugging information, including local function-variable information, full symbol-table information, and line numbers. For more information on %@AB@%CVW%@AE@%, see Chapter 7, "Debugging in Protected Mode: CodeView for Windows." %@NL@% %@4@%%@AB@%Turning Off Optimization%@AE@%%@EH@%%@NL@% While an application is in development, you may want to turn off optimizing to make debugging easier. (By default, the C Compiler optimizes for speed.) To turn off program optimization, use the %@AB@%-Od%@AE@% option.%@CR:C6A00010031 @%%@NL@% %@4@%%@AB@%Using Stack Probes%@AE@%%@EH@%%@NL@% By default, the compiler provides stack probes. Stack probes can be useful during application development, but they can cause a slight performance degradation. When the application-development process is complete, it's a good idea to turn off the stack probes by using the %@AB@%-Gs%@AE@% option.%@CR:C6A00010032 @%%@CR:C6A00010033 @%%@NL@% %@3@%%@CR:C6A00010034 @%%@AB@%1.2.3 Dynamic-Link Library Options%@AE@%%@EH@%%@NL@% When compiling DLLs, you should specify the following compiler options:%@CR:C6A00010035 @%%@NL@% ■ The %@AB@%-Gw%@AE@% option, to ensure that exported functions receive the Windows prolog and epilog. (For modules that do not contain exported functions, you can use the %@AB@%-GW%@AE@% option instead to reduce the size of the prolog and epilog.)%@NL@% ■ The %@AB@%-Aw%@AE@% option, to ensure that pointers receive their proper segment addresses when cast to 32-bit addresses. The %@AB@%-Aw%@AE@% option must follow or be combined with the %@AB@%-AC%@AE@%, %@AB@%-AL%@AE@%, %@AB@%-AM%@AE@%, or %@AB@%-AS%@AE@% option, as appropriate.%@NL@% Dynamic-link libraries written in C have slightly different requirements than do Windows applications written in C. Unlike Windows applications, dynamic-link libraries are not executable programs; although a library is loaded, it does not execute directly. Instead, the code in a library is made available to all applications that need to use it, and an application can execute a portion of the library by calling one of the exported functions in the library.%@CR:C6A00010036 @%%@CR:C6A00010037 @%%@NL@% Like exported (callback) functions in Windows applications, exported functions in libraries must have the Windows prolog and epilog. This means that, for dynamic-link libraries, the %@AB@%-Gw%@AE@% option is required. Exported functions should be listed in the library's module-definition file. See Chapter 2, "Linking Applications: The Linker," for information about module-definition files.%@CR:C6A00010038 @%%@CR:C6A00010039 @%%@CR:C6A00010040 @%%@CR:C6A00010041 @%%@CR:C6A00010042 @%%@CR:C6A00010043 @%%@CR:C6A00010044 @%%@CR:C6A00010045 @%%@CR:C6A00010046 @%%@CR:C6A00010047 @%%@NL@% You should compile dynamic-link libraries with the %@AB@%-Aw%@AE@% option; this ensures that pointers receive their proper segment addresses when cast to 32-bit addresses. Libraries always use the stack of the calling application for parameters and local variables. This means that the values of the DS and SS registers are not equal when the library is executed. Because the C Compiler generates code that assumes that the DS and SS registers are equal, dynamic-link libraries may fail unless compiled with the %@AB@%-Aw%@AE@% option. This option directs the compiler to generate code that does not assume that the registers are equal.%@CR:C6A00010048 @%%@CR:C6A00010049 @%%@NL@% The following example shows the recommended options for compiling libraries: %@NL@% %@AS@% CL -c -AMw -Gsw -Os TESTLIB.C%@AE@% %@2@%%@CR:C6A00010050 @%%@AB@%1.3 Summary%@AE@%%@EH@%%@NL@% The Microsoft C Compiler compiles C-language Windows applications. For more information about using the compiler, see the Microsoft C documentation. %@NL@% %@CR:C6A00020001 @%%@1@%%@AB@%Chapter 2 Linking Applications: The Linker%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% You create executable Microsoft Windows applications and libraries by linking your compiled source files using the linker (%@AB@%LINK%@AE@%). %@AB@%LINK%@AE@% takes your compiled sources, a list of libraries, and a module-definition file, and creates a file that you can load and run with Windows.%@CR:C6A00020002 @%%@CR:C6A00020003 @%%@CR:C6A00020004 @%%@CR:C6A00020005 @%%@CR:C6A00020006 @%%@NL@% %@AB@%LINK%@AE@% comes with Microsoft C; it is not included in the Microsoft Windows Software Development Kit (SDK). Windows requires version 5.1 or later of Microsoft C, or version 2.0 or later of Microsoft QuickC.%@CR:C6A00020007 @%%@CR:C6A00020008 @%%@CR:C6A00020009 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% IMPORTANT %@AI@%Microsoft C version 5.1 and Microsoft QuickC versions 2.0 and later include %@AI@%two linkers. If you are developing your application with one of these %@AI@%versions, use the segmented-executable linker.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% Microsoft C version 6.0 includes %@AB@%ILINK%@AE@%, the incremental linker. This linker does not relink files that have already been linked and that have not changed. %@AB@%ILINK%@AE@% also directly creates .SYM files for use by the Symbolic Debugger (%@AB@%SYMDEB%@AE@%). %@AB@%ILINK%@AE@% also uses the .SYM files it creates to avoid unnecessary relinking. For more information on %@AB@%ILINK%@AE@%, see the Microsoft C 6.0 documentation. %@NL@% This chapter describes the following topics: %@NL@% ■ Module-definition files%@NL@% ■ The difference between applications' and libraries' module-definition files%@NL@% ■ How to use %@AB@%LINK%@AE@% to link Windows applications%@NL@% %@2@%%@CR:C6A00020010 @%%@AB@%2.1 Creating Module-Definition Files%@AE@%%@EH@%%@NL@% Every Windows application and library must have a "module-definition file." A module-definition file is an ordinary text file that defines the application's contents and system requirements. When you link a Windows application, the linker uses the information in the application's module-definition file to determine how to set up the application (for example, how large to make the application's default stack, or whether to mark a particular code segment as moveable in memory). %@NL@% You create a module-definition file using an ordinary ASCII text editor. The file can have any filename you want, but must have the filename extension %@AI@%.%@AE@%DEF. %@NL@% Every module-definition (.DEF) file contains one or more statements. Each statement defines a specific attribute of the application or library, such as its module name, the number and type of program segments, or the number and names of exported and imported functions.%@CR:C6A00020011 @%%@CR:C6A00020012 @%%@CR:C6A00020013 @%%@NL@% Windows module-definition files can contain the following statements:%@CR:C6A00020014 @%%@CR:C6A00020015 @%%@CR:C6A00020016 @%%@NL@% %@AB@%Statement%@AE@% %@AB@%Usage%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%CODE%@AE@% Defines code-segment attributes, such as whether or not a segment is moveable in memory. %@CR:C6A00020017 @%%@CR:C6A00020018 @% %@AB@%DATA%@AE@% Defines data-segment attributes, such as whether there are single or multiple data segments, and whether a segment is moveable in memory. %@CR:C6A00020019 @%%@CR:C6A00020020 @% %@AB@%DESCRIPTION%@AE@% Briefly describes the module. %@CR:C6A00020021 @% %@CR:C6A00020022 @% %@AB@%EXETYPE%@AE@% Tells %@AB@%LINK%@AE@% what type of .EXE header to use (Windows or OS/2).%@CR:C6A00020023 @%%@CR:C6A00020024 @% %@AB@%EXPORTS%@AE@% Lists functions in this module that will be called by Windows or other applications. For example, an application's .DEF file always lists the application's window functions, since Windows must call these functions in order for the application to work properly. %@CR:C6A00020025 @%%@CR:C6A00020026 @% %@AB@%HEAPSIZE%@AE@% Specifies the default size of the local heap in bytes. The recommended size is 5K.%@CR:C6A00020027 @%%@CR:C6A00020028 @% %@AB@%IMPORTS%@AE@% Lists other applications' functions that this module calls. For example, if you wrote a library of utility functions, an application would have to import those functions before it could use them. (You can also import library functions using the %@AB@%IMPLIB%@AE@% utility. See Section 2.2, "Importing Dynamic-Link Libraries," for more information.) %@CR:C6A00020029 @%%@CR:C6A00020030 @% %@AB@%LIBRARY%@AE@% Specifies the module name of a dynamic-link library. %@CR:C6A00020031 @%%@CR:C6A00020032 @% %@AB@%NAME%@AE@% Specifies the module name of an application. %@CR:C6A00020033 @% %@CR:C6A00020034 @% %@AB@%SEGMENTS%@AE@% Specifies the attributes of additional code or data segments. %@CR:C6A00020035 @% %@CR:C6A00020036 @% %@AB@%STACKSIZE%@AE@% Determines the default size of the local stack in bytes. The recommended size is 5K.%@CR:C6A00020037 @%%@CR:C6A00020038 @% %@AB@%Statement%@AE@% %@AB@%Usage%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%STUB%@AE@% Specifies the application's old-style (DOS environment) executable file.%@CR:C6A00020039 @%%@CR:C6A00020040 @% For details on the module-definition statements, see the %@AI@%Reference%@AE@%, %@AI@%Volume %@AI@%2.%@AE@% %@NL@% Because Windows applications and libraries have different needs, the statements you include in a .DEF file will differ slightly, depending on whether you are creating the .DEF file for an application or for a library. The rest of this section describes the specific module-definition needs of applications and libraries. %@NL@% %@3@%%@CR:C6A00020041 @%%@AB@%2.1.1 Creating Module Definitions for Applications%@AE@%%@EH@%%@NL@% A module-definition file for an application must include the following statements:%@CR:C6A00020042 @%%@CR:C6A00020043 @%%@CR:C6A00020044 @%%@CR:C6A00020045 @%%@NL@% ■ A %@AB@%NAME%@AE@% statement that defines the application's module name. Windows uses the module name to identify the application. The module name must match the application's base filename. %@NL@% ■ An %@AB@%EXPORTS%@AE@% statement that lists functions in the module that Windows or other applications will call, such as window and callback functions.%@NL@% ■ An %@AB@%EXETYPE WINDOWS%@AE@% statement, which enables the application to run in the Windows environment. This statement tells %@AB@%LINK%@AE@% to use a Windows executable-file header instead of an OS/2 header (the default).%@CR:C6A00020046 @%%@CR:C6A00020047 @%%@CR:C6A00020048 @%%@CR:C6A00020049 @%%@CR:C6A00020050 @%%@NL@% Although these are the only required statements in the .DEF file, most .DEF files contain additional statements, such as the %@AB@%DATA%@AE@% and %@AB@%CODE%@AE@% statements, to define other aspects of the application.%@CR:C6A00020051 @%%@CR:C6A00020052 @%%@CR:C6A00020053 @%%@CR:C6A00020054 @%%@CR:C6A00020055 @%%@CR:C6A00020056 @%%@CR:C6A00020057 @%%@CR:C6A00020058 @%%@CR:C6A00020059 @%%@NL@% The following example shows a typical .DEF file for a Windows application: %@NL@% %@AS@% ; Sample Module Definition File %@AS@% "NAME Sample %@AS@% DESCRIPTION 'Sample Window Application' %@AS@% %@AS@% EXETYPE WINDOWS %@AS@% %@AS@% DATA MULTIPLE MOVEABLE %@AS@% CODE MOVEABLE DISCARDABLE %@AS@% %@AS@% HEAPSIZE 5120 %@AS@% STACKSIZE 5120 %@AS@% %@AS@% EXPORTS %@AS@% MainWndProc @1 SampleDlgProc @2%@AE@% This is an example of a module-definition file for an application named "Sample". %@NL@% " The %@AB@%NAME%@AE@% statement defines the application's module name as "Sample". %@NL@% The required statement %@AB@%EXETYPE WINDOWS%@AE@% ensures that %@AB@%LINK%@AE@% gives the application a Windows-format header. %@NL@% The %@AB@%DATA MULTIPLE%@AE@% statement tells %@AB@%LINK%@AE@% that this module has multiple data segments (one for each instance of the application). For most Windows applications, the data segment should be defined as %@AB@%MULTIPLE%@AE@%, since most Windows applications can be invoked more than once. %@NL@% The %@AB@%CODE MOVEABLE DISCARDABLE%@AE@% and previous %@AB@%DATA MULTIPLE MOVEABLE%@AE@% statements tell %@AB@%LINK%@AE@% that both the data and code segments are moveable and that the code segment is discardable. It's a good idea to use moveable and discardable code segments and moveable data segments, since they allow Windows to take best advantage of memory. %@NL@% The heap and stack sizes are the recommended 5120 bytes. Heap space is required if the application uses its local heap. It's a good idea for applications to have at least 5120 bytes of stack space. %@NL@% The %@AB@%EXPORTS%@AE@% statement lists the callback functions in the application: the main window function, named "MainWndProc", and a dialog function, "SampleDlgProc".%@CR:C6A00020060 @%%@NL@% %@3@%%@CR:C6A00020061 @%%@AB@%2.1.2 Creating Module Definitions for Libraries%@AE@%%@EH@%%@NL@% A module-definition file for a dynamic-link library must contain the following statements:%@CR:C6A00020062 @%%@CR:C6A00020063 @%%@CR:C6A00020064 @%%@CR:C6A00020065 @%%@CR:C6A00020066 @%%@CR:C6A00020067 @%%@NL@% ■ A %@AB@%LIBRARY%@AE@% statement that defines the library's module name. Windows uses the module name to identify the library.%@CR:C6A00020068 @%%@CR:C6A00020069 @%%@NL@% ■ An %@AB@%EXPORTS%@AE@% statement that lists the functions to be exported by the library; the functions should be exported by ordinals rather than by name, since using ordinals conserves space. Functions in the library are accessible to other applications only if they are listed in the %@AB@%EXPORTS%@AE@% statement.%@CR:C6A00020070 @%%@CR:C6A00020071 @%%@NL@% ■ An %@AB@%EXETYPE WINDOWS%@AE@% statement, which enables the library to run in the Windows environment. This statement tells %@AB@%LINK%@AE@% to use a Windows executable-file header instead of an OS/2 header (the default).%@CR:C6A00020072 @%%@CR:C6A00020073 @%%@NL@% In addition to these required statements, .DEF files for libraries can include other statements. %@NL@% The following example shows a typical .DEF file for a library:%@CR:C6A00020074 @%%@CR:C6A00020075 @%%@NL@% %@AS@% ; Example Module Definition File %@AS@% "LIBRARY MyUtilities %@AS@% DESCRIPTION 'My Utility Functions' %@AS@% %@AS@% EXETYPE WINDOWS %@AS@% %@AS@% DATA SINGLE MOVEABLE %@AS@% CODE MOVEABLE DISCARDABLE %@AS@% %@AS@% HEAPSIZE 4096 %@AS@% %@AS@% EXPORTS %@AS@% UtilityInit @1 %@AS@% UtilityStart @2 %@AS@% UtilityEnd @3 %@AS@% UtilityLoad @4 %@AS@% UtilitySave @5%@AE@% This is a sample module-definition file for a Windows dynamic-link library.%@CR:C6A00020076 @%%@NL@% " The %@AB@%LIBRARY%@AE@% statement defines the library's module name as MyUtilities. %@NL@% The required statement %@AB@%EXETYPE WINDOWS%@AE@% ensures that %@AB@%LINK%@AE@% gives the library a Windows-format header.%@NL@% The statement %@AB@%DATA SINGLE MOVEABLE%@AE@% tells %@AB@%LINK%@AE@% that this library module has a single data segment. Unlike an application, of which several copies can be running at a time, Windows allows only one instance of a library at a time.%@NL@% The heap size is 4096 bytes. Because libraries never have stacks, the library's .DEF file contains no %@AB@%STACK%@AE@% statement; libraries use the stack of the calling application. %@NL@% The required statement %@AB@%EXPORTS%@AE@% lists the library's exported functions by name and ordinal number. An application can then call these functions if the functions' names or ordinals are listed in the %@AB@%IMPORTS%@AE@% statement of the application's .DEF file.%@CR:C6A00020077 @%%@CR:C6A00020078 @%%@CR:C6A00020079 @% %@CR:C6A00020080 @%%@CR:C6A00020081 @%%@CR:C6A00020082 @%%@CR:C6A00020083 @%%@CR:C6A00020084 @%%@NL@% %@2@%%@CR:C6A00020085 @%%@AB@%2.2 Importing Dynamic-Link Libraries%@AE@%%@EH@%%@NL@% When you link an application that makes function calls to a dynamic-link library (DLL), you must identify the imported functions using one of the following methods:%@CR:C6A00020086 @%%@NL@% ■ Use the %@AB@%IMPORTS%@AE@% statement in the application's module-definition file. Section 2.1.2, "Creating Module Definitions for Libraries," describes this method.%@NL@% ■ Use the %@AB@%IMPLIB%@AE@% utility to create a library of imported functions and specify the library in the %@AB@%LINK%@AE@% command line, as described in this section.%@NL@% You can create import libraries by using the %@AB@%IMPLIB%@AE@% utility. %@AB@%IMPLIB%@AE@% reads the exports for a library, as listed in its definition file, and creates an import library. You can link the library into an application.%@CR:C6A00020087 @%%@CR:C6A00020088 @%%@CR:C6A00020089 @%%@CR:C6A00020090 @%%@CR:C6A00020091 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%%@AB@%IMPLIB%@AE@%%@AI@% does not come on the SDK disks. It is shipped with the Microsoft C %@AI@%Compiler. If you did not request %@AE@%%@AI@%%@AB@%IMPLIB%@AE@%%@AE@%%@AI@% to be copied when you installed the %@AI@%C Compiler, you may want to copy it from the C Compiler disks.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% You start %@AB@%IMPLIB%@AE@% by using the %@AB@%IMPLIB%@AE@% command. %@NL@% %@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% IMPLIB imp-lib-name mod-def-file%@AE@% The %@AI@%imp-lib-name%@AE@% parameter specifies the name you want the new import library to have. %@NL@% The %@AI@%mod-def-file%@AE@% parameter specifies the name of the module-definition (.DEF) file for the dynamic-link library. For %@AB@%IMPLIB%@AE@% version 1.1 and later, distributed with Microsoft C version 6.0 and later, you can provide %@AB@%IMPLIB%@AE@% the name of the DLL itself instead of the DLL's module-definition file. %@NL@% The following command creates the import library named MYLIB.LIB from the module-definition file MYLIB.DEF: %@NL@% %@AS@% IMPLIB MYLIB.LIB MYLIB.DEF%@AE@% To link the library, specify it in the %@AB@%LINK%@AE@% command line, as in the following example: %@NL@% %@AS@% LINK SAMPLE, SAMPLE.EXE, , /NOD SLIBCEW LIBW MYLIB, SAMPLE.DEF%@AE@% The example links the import library MYLIB.LIB. %@NL@% For more information on specifying libraries, see Section 2.3.3, "Specifying Libraries on the LINK Command Line."%@CR:C6A00020092 @%%@NL@% %@2@%%@CR:C6A00020093 @%%@AB@%2.3 Linking an Application%@AE@%%@EH@%%@NL@% You can link object (.OBJ) files from compiled application source files, libraries, and module-definition files into an executable file using the linker. The %@AB@%LINK%@AE@% program comes with Microsoft C version 5.1; it is not included in the SDK. %@NL@% %@AB@%LINK%@AE@% combines the code and data of all application files with the appropriate code for any Windows functions that the application calls, and creates a new executable file or DLL.%@CR:C6A00020094 @%%@CR:C6A00020095 @%%@NL@% %@3@%%@CR:C6A00020096 @%%@AB@%2.3.1 Using the LINK Command%@CR:C6A00020097 @%%@AE@%%@EH@%%@NL@% To start the linker, you use the %@AB@%LINK%@AE@% command. You can type this command on the DOS command line, or you can enter it in a batch file or a make file. %@NL@% %@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% LINK «options» object-files,«exe-file»,«map-file», «lib-files»,def-file%@AE@% The %@AI@%options%@AE@% parameter specifies one or more key words (described in Section 2.3.2, "Specifying LINK Command Options") that tell %@AB@%LINK%@AE@% to carry out special operations. %@NL@% The %@AI@%object-files%@AE@% parameter specifies the filenames of one or more compiled application source files. If your application has more than one compiled source file, you must name all of them on the %@AB@%LINK%@AE@% command line. Separate the filenames of object files by spaces or the plus sign (+).%@CR:C6A00020098 @%%@CR:C6A00020099 @%%@NL@% The %@AI@%exe-file%@AE@% parameter specifies the name you want %@AB@%LINK%@AE@% to give to the resulting executable file or dynamic-link library. %@NL@% The %@AI@%map-file%@AE@% parameter specifies the name you want the map file to have. (A map file is used for symbolic debugging with %@AB@%SYMDEB%@AE@% or %@AB@%WDEB386%@AE@%.)%@CR:C6A00020100 @%%@NL@% The %@AI@%lib-files%@AE@% parameter specifies the names of Windows or standard-language libraries. %@NL@% The %@AI@%def-file%@AE@% parameter specifies the filename of the module-definition (.DEF) file. Each application can have only one .DEF file.%@CR:C6A00020101 @%%@NL@% Use commas to separate parameters in the command line.%@CR:C6A00020102 @%%@CR:C6A00020103 @%%@NL@% The following example command line links the application object file SAMPLE.OBJ with the standard Windows library LIBW.LIB: %@NL@% %@AS@% LINK SAMPLE.OBJ/al:16, SAMPLE.EXE, SAMPLE.MAP/map/li, /NOD SLIBCEW.LIB %@AS@%LIBW.LIB, SAMPLE.DEF%@AE@% The command line creates the file SAMPLE.EXE, which has the module name, segments, and exported functions defined by the module-definition file SAMPLE.DEF. It also creates the map file SAMPLE.MAP, used for symbolic debugging. The command searches the library file LIBW.LIB to resolve any external function calls made in the application files. It also searches for the Windows version of the small model emulated math C run-time library. %@NL@% The %@AB@%LINK %@AE@%program uses default filename extensions if you do not provide extensions. For example, the preceding example would have the same results if typed as follows: %@NL@% %@AS@% LINK SAMPLE/al:16, SAMPLE, SAMPLE/map/li, /NOD SLIBCEW LIBW, SAMPLE%@AE@% %@3@%%@CR:C6A00020104 @%%@AB@%2.3.2 Specifying LINK Command Options%@AE@%%@EH@%%@NL@% You can use the %@AB@%LINK%@AE@% %@AI@%options%@AE@% parameter to tell the linker to perform special operations. The %@AB@%LINK%@AE@% options are:%@CR:C6A00020105 @%%@CR:C6A00020106 @%%@NL@% %@AB@%Option%@AE@% %@AB@%Usage%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%/alignment:%@AE@%%@AI@%size%@AE@% Tells the linker to align segment data in the executable file along the boundaries specified by %@AI@%size%@AE@%. The %@AI@%size%@AE@% parameter specifies a boundary size in bytes; for example, the following indicates an alignment boundary of 16 bytes: %@AS@%/alignment:16%@AE@% The %@AI@%size%@AE@% parameter must be a power of 2; therefore, 2, 4, 8, 16, and so on are appropriate values. The default is 512 bytes. It is strongly recommended that you link your application with the alignment set to 16 or less (or 32 if the application is larger than 1 megabyte). The default 512-byte alignment wastes a large amount of disk space, especially for larger applications using many segments and resources. The minimum abbreviation for this option is %@AB@%/al%@AE@%. %@AB@%/codeview%@AE@% Tells the linker to prepare for debugging using CodeView for Windows (%@AB@%%@AE@% %@AB@%CVW%@AE@%). The minimum abbreviation for this option is %@AB@%/co%@AE@%. %@AB@%Option%@AE@% %@AB@%Usage%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%/help%@AE@% Tells the linker to display a list of available options. The minimum abbreviation for this option is /%@AB@%h%@AE@%. %@AB@%/linenumbers%@AE@% Tells the linker to copy line-number information from the object file to the map file. Use this option to prepare for source line debugging with the Symbolic Debugger (%@AB@%SYMDEB%@AE@%). The minimum abbreviation for this option is %@AB@%/li%@AE@%. %@CR:C6A00020107 @% %@CR:C6A00020108 @% %@AB@%/map%@AE@% Tells the linker to create a .MAP file, which the %@AB@%MAPSYM%@AE@% utility uses to create a .SYM file. The .SYM file is then used by the Symbolic Debugger. %@AB@%/nodefaultlibrarysearch%@AE@% Prevents the linker from using the default C run-time libraries. This option is recommended if you use the %@AB@%%@AE@% %@AB@%?LIBC?W.LIB%@AE@% naming of the C runtime libraries instead of %@AB@%?LIBC?.LIB%@AE@%. The minimum abbreviation for this option is %@AB@% /nod.%@AE@% %@AB@%/noextendeddictionarysearch%@AE@% Prevents the linker from searching a library's extended dictionary, which is a list of symbols stored in the library. The linker normally consults this list to speed up library searches. Normally this option is not needed. The linker issues an error message if you need to use this switch. The minimum abbreviation for this option is %@AB@%/noe.%@AE@% %@AB@%Option%@AE@% %@AB@%Usage%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%/nofarcalltrans%@AE@% This option prevents the translation of far calls within the current segment. Without this option, far calls are translated into the assembler statements: %@AS@%.%@AE@% %@AS@%.%@AE@% %@AS@%.%@AE@% %@AS@%NOP%@AE@% %@AS@%PUSH CS%@AE@% %@AS@%NEAR CALL%@AE@% %@AS@%.%@AE@% %@AS@%.%@AE@% %@AS@%.%@AE@% The minimum abbreviation for this option is %@AB@%/nof%@AE@%. %@CR:C6A00020109 @%%@CR:C6A00020110 @% %@AB@%/noignorecase%@AE@% Tells the linker to preserve lowercase letters when matching symbols during linking. The minimum abbreviation for this option is %@AB@%/noi%@AE@%. %@AB@%/pause%@AE@% Tells the linker to pause before copying the executable file to disk. The minimum abbreviation for this option is %@AB@%/pau%@AE@%. %@AB@%/segments:%@AE@%%@AI@%number%@AE@% Sets the maximum number of segments the linker will process to %@AI@%number%@AE@%. For example, the following would tell the linker to process no more than 200 segments: %@AS@%/segments:200%@AE@% The default is 128 segments. Windows limits an application to 254 segments. The minimum abbreviation for this option is %@AB@%/se%@AE@%. %@CR:C6A00020111 @%%@CR:C6A00020112 @% %@AB@%Option%@AE@% %@AB@%Usage%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%/warnfixup%@AE@% Causes the linker to display an error message when an offset fixup occurs (relative to a logical segment) outside the physical segment. The minimum abbreviation for this option is %@AB@%/w%@AE@%. The following %@AB@%LINK%@AE@% options are not allowed when linking Windows applications:%@CR:C6A00020113 @%%@CR:C6A00020114 @%%@CR:C6A00020115 @%%@NL@% %@AB@%/dsallocate%@AE@% %@AB@%/exepack%@AE@% %@AB@%/high%@AE@% %@AB@%/overlayinterrupt%@AE@% %@NL@% The following %@AB@%LINK%@AE@% options are not recommended when linking Windows applications:%@CR:C6A00020116 @%%@NL@% %@AB@%/nogroupassociation%@AE@% %@AB@%/packcode%@AE@% %@AB@%/stack%@AE@% %@NL@% Instead of using the %@AB@%LINK%@AE@% option %@AB@%/stack%@AE@%, set the stack size in the application's .DEF file. %@NL@% For more information on %@AB@%LINK%@AE@% command-line options, see the %@AI@%Microsoft C %@AI@%Optimizing Compiler User's Guide%@AE@%. %@NL@% %@3@%%@CR:C6A00020117 @%%@AB@%2.3.3 Specifying Libraries on the LINK Command Line%@AE@%%@EH@%%@NL@% When you link an application's object files, you must specify the appropriate C-language libraries for Windows and C run-time libraries. The C-language libraries for Windows contain code for the Windows application start-up routines and references for the Windows functions.%@CR:C6A00020118 @%%@CR:C6A00020119 @%%@CR:C6A00020120 @%%@NL@% There are corresponding C-language libraries you will use when linking dynamic-link libraries. Table 2.1 shows which Windows library to use, depending on the memory model and whether you are linking an application or a library.%@CR:C6A00020121 @%%@NL@% Table 2.1 Linking with a Windows C-Language Library %@TH: 16 1093 02 25 20 31 @%Memory Model For an Application For a DLL%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%Emulated Math Package%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Small SLIBCEW.LIB SDLLCEW.LIBMedium MLIBCEW.LIB MDLLCEW.LIBCompact CLIBCEW.LIB CDLLCEW.LIBLarge LLIBCEW.LIB LDLLCEW.LIB%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%Alternate Math Package%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Small SLIBCAW.LIB SDLLCAW.LIBMedium MLIBCAW.LIB MDLLCAW.LIBCompact CLIBCAW.LIB CDLLCAW.LIBLarge LLIBCAW.LIB LDLLCAW.LIB%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 16 1093 02 25 20 31 @% Which C-language libraries you link with depends on your application's programming model and whether or not the model uses floating-point support.%@CR:C6A00020122 @%%@NL@% In addition to these libraries, you must also link with the model-independent Windows import library, LIBW.LIB. %@NL@% Use the %@AB@%/nod%@AE@% option to ensure that the linker will not try to find objects in your non-Windows versions of the C run-time libraries. %@NL@% For example, a small-model application using the emulator math package must be linked with the small-model library SLIBCEW.LIB and LIBW.LIB, as shown in the following example: %@NL@% %@AS@% LINK SAMPLE,,/NOD SLIBCEW LIBW, SAMPLE.DEF%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%You should link your program with the SLIBCEW.LIB or MLIBCEW.LIB library if %@AI@%you chose the coprocessor/emulator option by specifying %@AB@%-FPi%@AE@%%@AI@% on the compiler %@AI@%command line. For your Windows application to use the math %@AI@%coprocessor/emulator, you must include WIN87EM.LIB on your %@AE@%%@AI@%%@AB@%LINK%@AE@%%@AE@%%@AI@% command %@AI@%line. This library contains import information for the WIN87EM.DLL library %@AI@%supplied with the retail version of Windows. %@CR:C6A00020123 @%%@AE@%%@AE@% %@AI@%You should link your program with the SLIBCAW.LIB or MLIBCAW.LIB library if %@AI@%you chose the alternative math option by specifying %@AB@%-FPa%@AE@%%@AI@% on the compiler %@AI@%command line. Ensure that these libraries are available.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00020124 @%%@AB@%2.4 Examining Executable File Headers%@AE@%%@EH@%%@NL@% You can use the %@AB@%EXEHDR%@AE@% utility to determine whether an executable file is a Windows application or a library. The command also lets you find out which functions are exported or imported by a module, determine the amount of space allocated for a module's heap or stack, and determine the size and number of the segments a module contains.%@CR:C6A00020125 @%%@CR:C6A00020126 @%%@CR:C6A00020127 @%%@CR:C6A00020128 @%%@CR:C6A00020129 @%%@NL@% %@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% EXEHDR exe-filename%@AE@% The %@AI@%exe-filename%@AE@% parameter specifies the name of any file with an .EXE extension. %@NL@% The following example displays the header for the executable file HELLO.EXE: %@NL@% %@AS@% EXEHDR HELLO.EXE%@AE@% The format of this header is closely related to the statements contained in the application's module-definition file. %@NL@% For more information about %@AB@%EXEHDR%@AE@%, see the Microsoft C Optimizing Compiler documentation. %@NL@% %@2@%%@CR:C6A00020130 @%%@AB@%2.5 Summary%@AE@%%@EH@%%@NL@% %@AB@%LINK%@AE@% is a tool that takes compiled sources, a list of libraries, and a moduledefinition file, and creates a file that you can load and run with Windows. For additional information see the following: %@NL@% %@AB@%Topic%@AE@% %@AB@%Reference%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Windows versions of C run-time %@AI@%Guide to Programming%@AE@%: Chapter 14, "C libraries and Assembly Language" Module-definition statements %@AI@%Reference, Volume 2%@AE@%: Chapter 10, "ModuleDefinition Statements" %@CR:C6A00030001 @%%@1@%%@AB@%Chapter 3 Compiling Resources: The Resource Compiler%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Microsoft Windows Resource Compiler (%@AB@%RC%@AE@%) is a tool that lets you compile resources, such as icons, cursors, menus, and dialog boxes, that your application uses. You add the resulting binary resource file to your application's binary file to produce an executable Windows application. %@NL@% This chapter describes how to do the following: %@NL@% ■ Include resources in your application%@NL@% ■ Create a resource script file, which describes the resources your application will use%@NL@% ■ Use the Resource Compiler to compile your application's resources and add them to the application's executable file%@CR:C6A00030002 @%%@CR:C6A00030003 @%%@CR:C6A00030004 @%%@CR:C6A00030005 @%%@CR:C6A00030006 @%%@NL@% %@2@%%@CR:C6A00030007 @%%@AB@%3.1 Including Resources in an Application%@AE@%%@EH@%%@NL@% To include resources in your Windows application, follow these steps: %@NL@% 1. Create individual resource files for cursors, icons, bitmaps, dialogs, and fonts, using the appropriate resource editors. %@NL@% %@STUB@% Part 2 of this manual, "Resource Editors," explains how to use these editors. %@NL@% 2. Create a resource script (.RC) file that defines each application resource by specifying its name and description. %@NL@% %@STUB@% If the resource is in a separate file, this description includes the resource's filename.%@NL@% %@STUB@% For example, the .RC file might define a cursor resource by naming it "SampleCursor," describing it as a resource of type "Cursor," and defining it as the cursor contained in the file SAMPLE.CUR. %@NL@% 3. Compile the resource script file using the Resource Compiler. %@NL@% %@STUB@% The result will be a compiled resource file with the filename extension .RES. %@NL@% 4. Add the compiled resources to the application's compiled executable (.EXE) file using the Resource Compiler. %@NL@% %@STUB@% If you want, you can perform this step and the preceding step with a single %@AB@%RC%@AE@% command.%@NL@% %@2@%%@CR:C6A00030008 @%%@AB@%3.2 Creating a Resource Script File%@AE@%%@EH@%%@NL@% After creating individual resource files for your application's icon, cursor, bitmap, font, and dialog resources, you create a resource script file. The resource script file always has the .RC extension, and is often referred to simply as the .RC file.%@CR:C6A00030009 @%%@NL@% The .RC file lists every resource in your application, and describes some types of resources in great detail: %@NL@% ■ For resources that exist in a separate file, such as icons and cursors, the .RC file simply names the resource and the file that contains it.%@NL@% ■ For some types of resources, such as menus, the entire definition of the resource exists within the .RC file.%@NL@% You create a resource script file using an ordinary ASCII text editor. The file can contain resource statements and directives.%@CR:C6A00030010 @%%@NL@% Resource statements name and describe each resource. %@NL@% Directives are a special type of statement that defines an action you want the Resource Compiler to perform on the resource script file before actually compiling it. You can use directives to assign values to names, include the contents of files, and control compilation of the script file. The directives you use in a resource script file are identical to the C-language directives.%@CR:C6A00030011 @%%@CR:C6A00030012 @%%@CR:C6A00030013 @%%@CR:C6A00030014 @%%@CR:C6A00030015 @%%@CR:C6A00030016 @%%@NL@% A line in an .RC file cannot exceed 256 characters. %@NL@% Table 3.1 lists and briefly describes the statements and directives you can use in a resource script file. (See the %@AI@%Reference%@AE@%, %@AI@%Volume 2%@AE@%, for detailed descriptions and syntax.)%@CR:C6A00030017 @%%@CR:C6A00030018 @%%@CR:C6A00030019 @%%@CR:C6A00030020 @%%@CR:C6A00030021 @%%@CR:C6A00030022 @%%@NL@% Table 3.1 Resource Statements %@TH: 7 469 02 24 11 41 @%Type of Statement Statement Description %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Single-line statements %@AB@%BITMAP%@AE@% Defines a bitmap by naming it and specifying the file that contains it. (To use a particular bitmap, the application requests it by name.)%@TE: 7 469 02 24 11 41 @% Table 3.1 Resource Statements (continued) %@TH: 82 4609 02 30 15 31 @%Type of Statement Statement Description %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%CURSOR%@AE@% Defines a cursor by naming it and specifying the file that contains it. (To use a particular cursor, the application requests it by name.) %@AB@%FONT%@AE@% Specifies a file that contains a font. %@AB@%ICON%@AE@% Defines an icon by naming it and specifying the file that contains it. (To use a particular icon, the application requests it by name.)Multiple-line statements %@AB@%ACCELERATORS%@AE@% Defines menu accelerator keys. %@AB@%DIALOG%@AE@% Defines a template that an application can use to create dialog boxes. %@AB@%MENU%@AE@% Defines the appearance and function of an application menu. %@AB@%RCDATA%@AE@% Defines raw data resources. Raw data resources let you include binary data directly into the executable file. %@AB@%STRINGTABLE%@AE@% Defines string resources. String resources are null- terminated ASCII strings that can be loaded from the executable file.Directives %@AB@%#define%@AE@% Defines a specified name by assigning it a given value. %@AB@%#elif%@AE@% Marks an optional clause of a conditional compilation block. %@AB@%#else%@AE@% Marks an optional clause of a conditional compilation block. %@AB@%#endif%@AE@% Marks the end of a conditional compilation block. %@AB@%#if%@AE@% Carries out conditional compilation if a specified expression is true. %@AB@%#ifdef%@AE@% Carries out conditional compilation if a specified name has been defined. %@AB@%#ifndef%@AE@% Carries out conditional compilation if a specified name is not defined. %@AB@%#include%@AE@% Copies the contents of a file into the resource script before the Resource Compiler processes the script. %@AB@%#undef%@AE@% Removes the current definition of the specified name.User-defined resources User-supplied Any data that needs to be added to the executable file.%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 82 4609 02 30 15 31 @% For a detailed description of the statements in a resource script file, see the %@AI@%Reference%@AE@%, %@AI@%Volume 2.%@AE@% %@NL@% For example, the following script file defines the resources for an application called "Shapes": %@NL@% %@AS@% "#include "SHAPES.H" %@AS@% ShapesCursor CURSOR SHAPES.CUR %@AS@% ShapesIcon ICON SHAPES.ICO %@AS@% ShapesMenu MENU %@AS@% BEGIN %@AS@% POPUP "&Shape" %@AS@% BEGIN %@AS@% MENUITEM "&Clear", ID_CLEAR %@AS@% MENUITEM "&Rectangle", ID_RECT %@AS@% MENUITEM "&Triangle", ID_TRIANGLE %@AS@% MENUITEM "&Star", ID_STAR %@AS@% MENUITEM "&Ellipse", ID_ELLIPSE %@AS@% END %@AS@% END%@AE@% " The file uses the %@AB@%#include%@AE@% directive to include the contents of the header file SHAPES.H. %@NL@% The %@AB@%CURSOR%@AE@% statement names the application's cursor resource "ShapesCursor" and specifies the cursor file SHAPES.CUR, which contains the image for that cursor. %@NL@% It does the same for the application's icon resource, "ShapesIcon", using the %@AB@%ICON%@AE@% statement. %@NL@% The script file uses the %@AB@%MENU%@AE@% statement to define an application menu named "ShapesMenu", a pop-up menu with five menu items. %@NL@% The menu definition, enclosed in the %@AB@%BEGIN%@AE@% and %@AB@%END%@AE@% key words, specifies each menu item and the menu ID code that is returned when the user selects that item. For example, the first item on the menu, "Clear", returns the menu ID code "ID_CLEAR" when the user selects it. The ID values are defined in the application header file, SHAPES.H.%@CR:C6A00030023 @%%@NL@% For more information on the resource script file, the syntax of the resource statements, and how to create user-defined resources, see the %@AI@%Reference, %@AI@%Volume 2%@AE@%. %@NL@% %@2@%%@CR:C6A00030024 @%%@AB@%3.3 Using the Resource Compiler%@AE@%%@EH@%%@NL@% The Resource Compiler serves the following functions: %@NL@% ■ It compiles the resource script file and the resource files (such as icon and cursor files) into a binary resource (.RES) file.%@NL@% ■ It combines the compiled .RES file with the executable (.EXE) file created by the linker; the result is an executable Windows application. %@CR:C6A00030025 @%%@CR:C6A00030026 @%%@CR:C6A00030027 @%%@NL@% ■ It marks all Windows applications (even if they have no resources) with a Windows version stamp. ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%All Windows applications and libraries must bear a Windows version stamp. %@AI@%For this reason, use %@AB@%RC%@AE@%%@AI@% on every Windows application and library you build, %@AI@%whether or not it uses any resources.%@CR:C6A00030028 @%%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% To start the Resource Compiler, use the %@AB@%RC%@AE@% command. What you specify on the command line will depend on whether you are compiling resources, adding compiled resources to an executable file, or both.%@CR:C6A00030029 @%%@CR:C6A00030030 @%%@NL@% %@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AB@%RC %@AE@%«%@AI@%options%@AE@%»%@AI@% resource-file %@AE@%«%@AI@%executable-file%@AE@%» %@NL@% There are several ways you can use the %@AB@%RC%@AE@% command: %@NL@% ■ To compile resources separately, use the %@AB@%RC%@AE@% command in the following form:%@NL@% %@STUB@% %@AB@%RC%@AE@% %@AB@%-R%@AE@% «%@AI@%options%@AE@%» %@AI@%script-file%@AE@%%@NL@% %@STUB@% When you use this form, the Resource Compiler ignores the executable file if you specify one.%@NL@% ■ To compile an .RC file and add the resulting .RES file to the executable file, use the %@AB@%RC%@AE@% command in the following form:%@NL@% %@STUB@% %@AB@%RC%@AE@% «%@AI@%options%@AE@%» %@AI@%script-file%@AE@% «%@AI@%executable-file%@AE@%»%@NL@% ■ To compile a 3.0 version of a dynamic-link library (DLL) that does not have a .RES file, use the %@AB@%RC%@AE@% command in the following form:%@NL@% %@STUB@% %@AB@%RC%@AE@% «%@AI@%options%@AE@%» %@AI@%dll-file%@AE@%%@NL@% %@STUB@% When you use this form, the DLL filename must explicitly have an .EXE, .DRV, or .DLL extension.%@NL@% ■ To simply add a compiled resource (.RES) file to an executable file, use the %@AB@%RC%@AE@% command in the following form:%@NL@% %@STUB@% %@AB@%RC%@AE@% «%@AI@%options%@AE@%» %@AI@%res-file.RES%@AE@% «%@AI@%executable-file%@AE@%»%@NL@% The rest of this section explains how to specify each of the %@AB@%RC%@AE@% command's parameters. %@NL@% %@4@%%@AB@%Options Parameter%@AE@%%@EH@%%@NL@% The %@AB@%RC%@AE@% command's %@AI@%options%@AE@% parameter can include one or more of the following:%@CR:C6A00030031 @%%@CR:C6A00030032 @%%@NL@% %@AB@%Option%@AE@% %@AB@%Description%@AE@%%@CR:C6A00030033 @% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%-R%@AE@% Creates an .RES file from an .RC file. Use this option when you do not want to add the compiled .RES file to the .EXE file. %@AB@%-D%@AE@% Defines a symbol for the preprocessor that you can test with the %@AB@%#ifdef%@AE@% directive.%@CR:C6A00030034 @% %@AB@%-FO%@AE@% Renames the .RES file.%@CR:C6A00030035 @% %@AB@%-FE%@AE@% Renames the .EXE file.%@CR:C6A00030036 @% %@AB@%-I%@AE@% Searches the specified directory before searching the directories specified by the INCLUDE environment variable.%@CR:C6A00030037 @% %@AB@%-V%@AE@% Displays messages that report on the progress of the compiler. %@AB@%-X%@AE@% Prevents the Resource Compiler from checking the INCLUDE environment variable when searching for include files or resource files. %@CR:C6A00030038 @% %@AB@%-L%@AE@% or %@AB@%-LIM32%@AE@% Tells Windows that the application uses expanded memory directly, according to the Lotus(R) Intel(R) Microsoft Expanded Memory Specification (EMS), version 3.2.%@CR:C6A00030039 @% %@CR:C6A00030040 @% %@AB@%Option %@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%-M%@AE@% or %@AB@%-MULTINST%@AE@% When Windows is running with the EMS 4.0 memory configuration, this switch assigns each instance of the application task to a distinct EMS bank. (By default, all instances of a task share the same EMS bank.)%@CR:C6A00030041 @% %@AB@%-E%@AE@% For a dynamic-link library, changes the default location of global memory from below the EMS bank line to above the EMS bank line. %@CR:C6A00030042 @% %@AB@%-P%@AE@% Creates a private dynamic-link library (DLL) that is called by only one application. This allows Windows to use memory better, since only one application (or multiple instances of the same application) will be calling into the DLL. For example, in the large-frame EMS memory model, the DLL is loaded above the EMS bank line, freeing memory below the bank line.%@CR:C6A00030043 @% %@AB@%-K%@AE@% Disables the load-optimization feature of the Resource Compiler. If this option is not specified, the compiler arranges segments and resources in the executable file so that all preloaded information is contiguous. This feature allows Windows to load the application much more quickly.%@CR:C6A00030044 @% If you do not specify the %@AB@%-K%@AE@% option, all data segments, nondiscardable code segments, and the entry-point code segment will be preloaded, unless any segment and its relocation information exceed 64K. If the %@AB@%PRELOAD%@AE@% attribute is not assigned to these segments in the module-definition (.DEF) file when you link your application, the compiler will add the preload attribute and display a warning. Resources and segments will have the same segment alignment. This alignment should be as small as possible to prevent the final executable file from growing unnecessarily large. You can set the alignment using the %@AB@%LINK%@AE@% %@AB@%%@AE@% %@AB@%/alignment%@AE@% option. See Chapter 2, "Linking Applications: The Linker," for more information. %@AB@%Option%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%-T%@AE@% Creates an application that runs only with Windows in protected (standard or 386 enhanced) mode. If the user attempts to run the application in real mode, Windows will display a message box telling the user that the application cannot run in real mode. %@AB@%-? %@AE@%or%@AB@% -H%@AE@% Displays a list of the %@AB@%RC%@AE@% command line options. %@CR:C6A00030045 @%%@CR:C6A00030046 @% Options are not case-sensitive; for example,%@AB@% -r%@AE@% and %@AB@%-R%@AE@% are equivalent. You can combine single-letter options if they do not require any additional parameters. For example, the command: %@NL@% %@AS@% RC -R -E -V SAMPLE.RC%@AE@% is equivalent to the command: %@NL@% %@AS@% RC -REV SAMPLE.RC%@AE@% %@4@%%@AB@%Resource-file Parameter%@AE@%%@EH@%%@NL@% The %@AB@%RC%@AE@% command's %@AI@%resource-file%@AE@% parameter specifies the name of the script file that contains the names, types, filenames, and descriptions of the resources you want to add to the .EXE file. It can also specify the name of a compiled .RES file, in which case the Resource Compiler adds the compiled resources to the executable file.%@CR:C6A00030047 @%%@NL@% %@4@%%@AB@%Executable-file Parameter%@AE@%%@EH@%%@NL@% The %@AB@%RC%@AE@% command's %@AI@%executable-file%@AE@% parameter specifies the name of the executable file that the resources should be added to. If you do not specify an executable file, the Resource Compiler uses the executable file with the same name as the script file. %@NL@% %@3@%%@CR:C6A00030048 @%%@AB@%3.3.1 Compiling Resources Separately%@AE@%%@EH@%%@NL@% By default, the Resource Compiler adds the compiled resources to the specified executable file. Sometimes you might want to first compile the resources and then add them to the executable file in separate steps. This can be useful because resource files don't tend to change much after initial development. You can save time by compiling your application's resources separately, then adding the compiled .RES file to your executable file each time you recompile the .EXE file. %@NL@% You can use the %@AB@%-R%@AE@% option to compile the resources separately, without adding them to the executable file. When you use this option, the Resource Compiler compiles the .RC file and creates a compiled resource .RES file.%@CR:C6A00030049 @%%@CR:C6A00030050 @%%@NL@% For example, the following command reads the resource script file SAMPLE.RC and creates the compiled resource file SAMPLE.RES. %@NL@% %@AS@% RC -R SAMPLE.RC%@AE@% The command does not add SAMPLE.RES to the executable file.%@CR:C6A00030051 @%%@NL@% %@3@%%@CR:C6A00030052 @%%@AB@%3.3.2 Defining Names for the Preprocessor%@AE@%%@EH@%%@NL@% You can specify conditional branching in a resource script file, based on whether or not a term is defined on the %@AB@%RC%@AE@% command line using the %@AB@%-D%@AE@% option.%@CR:C6A00030053 @%%@NL@% For example, suppose your application has a pop-up menu, the Debug menu, which you want to appear only during debugging. When you compile the application for normal use, the Debug menu is not included. The resource script file contains the following statements to define the Debug menu: %@NL@% %@AS@% MainMenu MENU %@AS@% BEGIN %@AS@% . %@AS@% . %@AS@% . %@AS@% #ifdef DEBUG %@AS@% POPUP "&Debug" %@AS@% BEGIN %@AS@% MENUITEM "&Memory usage", ID_MEMORY %@AS@% MENUITEM "&Walk data heap", ID_WALK_HEAP %@AS@% END %@AS@% #endif %@AS@% END%@AE@% When compiling resources for a debugging version of the application, you could include the Debug menu by using the following %@AB@%RC%@AE@% command: %@NL@% %@AS@% RC -R -D DEBUG MYAPP.RC%@AE@% To compile resources for a normal version of the application─one that does not include the Debug menu─you could use the following %@AB@%RC %@AE@%command: %@NL@% %@AS@% RC -R MYAPP.RC%@AE@% %@3@%%@CR:C6A00030054 @%%@AB@%3.3.3 Renaming the Compiled Resource File%@AE@%%@EH@%%@NL@% Normally, when compiling resources, the Resource Compiler names the compiled resource file after the .RC file and places it in the same directory as the script file. For example, when compiling MYAPP.RC, you would normally type: %@NL@% %@AS@% RC -R MYAPP.RC%@AE@% The compiler would then create a compiled resource file named MYAPP.RES in the same directory as MYAPP.RC. %@NL@% The %@AB@%-FO%@AE@% option lets you give the resulting .RES file a name that differs from the corresponding .RC script file. For example, to name the resulting .RES file NEWFILE.RES, you could type: %@NL@% %@AS@% RC -R -FO NEWFILE.RES MYAPP.RC%@AE@% The %@AB@%-FO%@AE@% option can also place the .RES file in a different directory. For example, typing the following command places the compiled resource file MYAPP.RES in the directory C:\RESOURCE:%@CR:C6A00030055 @%%@NL@% %@AS@% RC -R -FO C:\SOURCE\RESOURCE\MYAPP.RES MYAPP.RC%@AE@% %@3@%%@CR:C6A00030056 @%%@AB@%3.3.4 Controlling the Directories that RC Searches%@AE@%%@EH@%%@NL@% Normally, the Resource Compiler searches for include files and resource files (such as icon and cursor files) first in the current directory, and then in the directories specified by the INCLUDE environment variable. (The PATH environment variable has no effect on the directories that the Resource Compiler searches.) %@NL@% %@4@%%@AB@%Adding a Directory to Search%@AE@%%@EH@%%@NL@% You can use the %@AB@%-I%@AE@% option to add a directory to the list of directories that the Resource Compiler searches. The compiler then searches the directories in the following order:%@CR:C6A00030057 @%%@NL@% 1. The current directory.%@NL@% 2. The directory or directories you specify by using the %@AB@%-I%@AE@% option, in the order in which they appear on the command line.%@NL@% 3. The list of directories specified by the INCLUDE environment variable, in the order in which the variable lists them, unless you specify the %@AB@%-X%@AE@% option.%@NL@% The following example compiles the resource script file MYAPP.RC and adds the compiled resources to MYAPP.EXE: %@NL@% %@AS@% RC -I C:\SOURCE\STUFF -I D:\RESOURCES MYAPP.RC MYAPP.EXE%@AE@% When compiling the script file, the Resource Compiler searches for include files and resource files first in the current directory, then in C:\SOURCE\STUFF and D:\RESOURCES, and lastly in the directories specified by the INCLUDE environment variable. %@NL@% %@4@%%@AB@%Suppressing the INCLUDE Environment Variable%@AE@%%@EH@%%@NL@% You can prevent the Resource Compiler from using the INCLUDE environment variable when determining the directories to search. To do so, use the %@AB@%-X%@AE@% option. The compiler then searches for files only in the current directory, and in any directories you specify using the %@AB@%-I%@AE@% option.%@CR:C6A00030058 @%%@CR:C6A00030059 @%%@NL@% The following example compiles the resource script file MYAPP.RC and adds the compiled resources to MYAPP.EXE: %@NL@% %@AS@% RC -X -I C:\SOURCE\STUFF MYAPP.RC MYAPP.EXE%@AE@% When compiling the script file, the Resource Compiler searches for include files and resource files first in the current directory and then in C:\SOURCE\STUFF. %@NL@% %@3@%%@CR:C6A00030060 @%%@AB@%3.3.5 Displaying Progress Messages%@AE@%%@EH@%%@NL@% Normally, the Resource Compiler does not display messages that report on its progress as it compiles. You can, however, tell the compiler to display these messages. To do so, use the %@AB@%-V%@AE@% option.%@CR:C6A00030061 @%%@NL@% The following example causes the compiler to report on its progress as it compiles the script file SAMPLE.RC, creates the compiled resource file SAMPLE.RES, and adds the .RES file to the executable file SAMPLE.EXE: %@NL@% %@AS@% RC -V SAMPLE.RC%@AE@% %@2@%%@CR:C6A00030062 @%%@AB@%3.4 Summary%@AE@%%@EH@%%@NL@% The Resource Compiler is a tool that lets you compile resources such as icons, dialog boxes, and fonts into a binary file. You add the binary resource file to the binary source files to produce an executable Windows application. %@NL@% For information related to the Resource Compiler, see the following: %@NL@% %@AB@%Topic%@AE@% %@AB@%Reference%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Creating icons, cursors, and %@AI@%Tools%@AE@%: Chapter 4, "Designing Images: bitmaps SDKPaint" Creating and editing dialog %@AI@%Tools%@AE@%: Chapter 5, "Designing Dialog boxes Boxes: The Dialog Editor" Creating fonts %@AI@%Tools%@AE@%: Chapter 6, "Designing Fonts: The Font Editor" Introduction to application %@AI@%Guide to Programming%@AE@%: Chapter 7, "Menus" menus Introduction to controls, such %@AI@%Guide to Programming%@AE@%: Chapter 8, as "Controls" buttons and check boxes Introduction to dialog boxes; %@AI@%Guide to Programming%@AE@%: Chapter 9, "Dialog also Boxes" explains how to use controls in dialog boxes Syntax and descriptions of each %@AI@%Reference%@AE@%, %@AI@%Volume 2%@AE@%: Chapter 8, resource statement and directive "Resource Script Statements" %@CR:C6A-Part 02 @%%@1@%%@AB@%PART II Resource Editors%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Part 2 describes how to use the Microsoft Windows resource editors: SDKPaint, the Dialog Editor, and the Font Editor. SDKPaint lets you create bitmaps, icons, and cursors for your application. The Dialog Editor lets you create and test dialog boxes on the screen instead of defining dialog statements in a resource script. The Font Editor lets you create fonts and update information in the font file header. %@NL@% %@CR:C6A00040001 @%%@1@%%@AB@%Chapter 4 Designing Images: SDKPaint%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Microsoft Windows SDKPaint (%@AB@%SDKPAINT%@AE@%) lets you create bitmaps, icons, and cursors for your applications. Using SDKPaint, you can draw bitmaps, icons, and cursors and examine their appearance on screens of various colors. The editor also simulates how images appear on different display devices.%@CR:C6A00040002 @%%@NL@% This chapter describes the following: %@NL@% ■ How SDKPaint works with bitmap, icon, and cursor files%@NL@% ■ The SDKPaint window, including its menu items and commands%@NL@% ■ Opening files and images within the files%@NL@% ■ Drawing with SDKPaint tools%@NL@% ■ Using the SDKPaint palette, including working with different color types%@NL@% ■ Customizing the palette, including editing colors, saving changes to the palette, and loading customized palettes%@NL@% ■ Defining a cursor hotspot%@NL@% ■ Using the clipboard to transfer images between editors, to move images from one resource to another, and to create multiple images %@NL@% %@2@%%@CR:C6A00040003 @%%@AB@%4.1 How SDKPaint Works with Files%@AE@%%@EH@%%@NL@% SDKPaint creates or modifies bitmap (.BMP), icon (.ICO), and cursor (.CUR) files.%@CR:C6A00040004 @%%@CR:C6A00040005 @%%@CR:C6A00040006 @%%@CR:C6A00040007 @%%@CR:C6A00040008 @%%@NL@% You can include these files in the resource script that you use to compile the resource (.RES) file. The .RES file is a component of the build that produces an executable file for your application. %@NL@% Figure 4.1 illustrates the process of incorporating bitmap, icon, and cursor files into an executable application. For detailed information on this process, see Chapter 3, "Compiling Resources: The Resource Compiler." %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@3@%%@CR:C6A00040009 @%%@AB@%4.1.1 File Types%@AE@%%@EH@%%@NL@% The bitmap (.BMP) files that SDKPaint produces define device-independent monochrome or color bitmaps. Each .BMP file defines one bitmap. Bitmaps that you create and save using SDKPaint can range in size from 1-by-1 to 72-by-72 pixels.%@CR:C6A00040010 @%%@CR:C6A00040011 @%%@NL@% Unlike bitmap files, icon (.ICO) and cursor (.CUR) files define a family of images. Each image in an icon or cursor file is designed for display on a different kind of device. SDKPaint distinguishes the different kinds of images by pixel dimensions and color capabilities. For example, when the application wants to use an icon, it requests the icon by name. Windows then selects the appropriate icon image in the specified file according to the pixel dimensions and color capabilities required by the device driver.%@CR:C6A00040012 @%%@CR:C6A00040013 @%%@CR:C6A00040014 @%%@NL@% %@3@%%@CR:C6A00040015 @%%@AB@%4.1.2 Icon and Cursor Data: The SDKPAINT.DAT File%@AE@%%@EH@%%@NL@% SDKPaint uses the SDKPAINT.DAT file to store display-device information for individual icon or cursor images within a file. The SDKPAINT.DAT file you install initially contains information about common display devices, such as EGA and VGA.%@CR:C6A00040016 @%%@CR:C6A00040017 @%%@NL@% SDKPAINT.DAT is an ASCII, comma-delimited file that you can edit to add information about display devices. Each string in the file defines a display device. A string is terminated by a carriage return (no null character) and contains the following six fields: %@NL@% %@AS@% name,num-colors,curs-horz-size,curs-vert-size,icon-horz-size, %@AS@%icon-vert-size%@AE@% Field definitions are as follows: %@NL@% %@AB@%Field%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AI@%name%@AE@% Name of the display device. The name can contain up to 10 uppercase and lowercase letters. %@AI@%num-colors%@AE@% Number of colors of the icon or cursor image. %@AI@%curs-horz-size%@AE@% Horizontal size of a cursor image in pixels. %@AI@%curs-vert-size%@AE@% Vertical size of a cursor image in pixels. %@AI@%icon-horz-size%@AE@% Horizontal size of an icon image in pixels. %@AI@%icon-vert-size%@AE@% Vertical size of an icon image in pixels. In addition to information about icon and cursor images, SDKPAINT.DAT can include comments. Indicate comments by placing a semicolon (;) at the beginning of the comment line. %@NL@% For example, the following SDKPAINT.DAT file specifies information for icons and cursors displayed on two devices: %@NL@% %@AS@% ";This is a sample SDKPAINT.DAT file %@AS@% 4-Plane,16,32,32,32,32 %@AS@% 3-Plane,16,32,32,32,32%@AE@% " This line is a comment.%@NL@% This line defines a device with four color planes. The device displays 16-color cursors and icons. Cursors and icons on this device are 32-by-32 pixels.%@NL@% This line defines a device with three color planes, which also displays 16-color cursors and icons. Cursors and icons on this device are also 32-by-32 pixels.%@NL@% SDKPaint displays information from the SDKPAINT.DAT file when you load an icon or cursor image into SDKPaint. For information about loading images, see "Loading an Image into the Workspace" in Section 4.3.3.%@CR:C6A00040018 @%%@NL@% %@2@%%@CR:C6A00040019 @%%@AB@%4.2 The SDKPaint Window%@AE@%%@EH@%%@NL@% The SDKPaint window varies with the kind of resource you are editing. Figure 4.2 illustrates the SDKPaint window after a user has opened an icon file.%@CR:C6A00040020 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% Regardless of the type of image you edit, the menu bar contains the following menus:%@CR:C6A00040021 @%%@NL@% %@TH: 72 3485 02 34 42 @%Menu Commands%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%File This menu contains the following commands: New─Initializes the workspace with a bitmap, icon, or cursor image. Open─Opens existing .BMP, .ICO, and .CUR files for editing. Save and Save As─Save changes to bitmaps, icons, and cursors. Exit─Exits the editor. %@CR:C6A00040022 @%%@CR:C6A00040023 @%%@CR:C6A00040024 @%%@CR:C6A00040025 @% Edit This menu contains the following commands: Undo─Restores the image to its state before the last edit. Copy─Moves an image to the clipboard. Paste─Moves an image from the clipboard.Image This menu contains the following commands: New─Initializes the workspace with an icon or cursor image. Open─Opens images in a bitmap, icon, or cursor file. %@CR:C6A00040026 @%%@CR:C6A00040027 @%%@CR:C6A00040028 @%%@CR:C6A00040029 @%%@CR:C6A00040030 @% Save─Retains an icon or cursor currently in the workspace. Restore─Restores an image to its state when initially loaded into the editor or when last retained. Clear─Sets to white all the pixels in the work area. Delete─Deletes an image from the work area and clears the image from the SDKPaint window.Brushsize This menu lets you choose among three sizes of brushes to draw an image.Palette This menu contains the following commands: Edit Colors─Changes the currently selected color to the hue you specify or restores the color to its default value. Get Colors─Loads a color palette (.PAL) file into the editor. Save Colors─Saves newly-created colors in a .PAL file.Hotspot This menu contains commands that let you define or display the hotspot of a cursor. For information about the hotspot, see Section 4.7, "Defining the Cursor Hotspot."%@CR:C6A00040031 @% %@CR:C6A00040032 @%%@CR:C6A00040033 @%%@TE: 72 3485 02 34 42 @% %@2@%%@CR:C6A00040034 @%%@AB@%4.3 Opening Files and Images%@AE@%%@EH@%%@NL@% Before editing an existing bitmap, icon, or cursor, you must first open a file to prepare the workspace for the kind of image you are going to edit.%@CR:C6A00040035 @%%@NL@% %@3@%%@CR:C6A00040036 @%%@AB@%4.3.1 Converting Files to 3.0 Format%@AE@%%@EH@%%@NL@% When you open a version 2.0 or later bitmap, icon, or cursor file, SDKPaint automatically converts it to 3.0 format as it is loaded into the editor.%@CR:C6A00040037 @%%@NL@% %@3@%%@CR:C6A00040038 @%%@AB@%4.3.2 Opening Bitmaps%@AE@%%@EH@%%@NL@% To open an existing bitmap file, choose the Open command from the File menu. SDKPaint opens the file and loads its image into the workspace of the SDKPaint window.%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%SDKPaint opens and loads only 2-color and 16-color bitmaps.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% If you are creating a new bitmap instead of editing one that exists, do the following:%@CR:C6A00040039 @%%@NL@% 1. Choose the New command from the File menu. %@NL@% %@STUB@% The editor displays the Resource Type dialog box.%@NL@% 2. Choose the Bitmap option.%@NL@% %@STUB@% SDKPaint displays a dialog box that lets you enter the height and width of the bitmap image you are creating and placing in the file. The dialog box also prompts you for the number of bitmap colors.%@CR:C6A00040040 @%%@CR:C6A00040041 @%%@NL@% 3. Specify either 2 or 16 colors. %@NL@% %@STUB@% By default, the first time you open a bitmap file, SDKPaint uses values appropriate to the display on which it is running. If you subsequently open additional bitmap files, SDKPaint specifies by default the values of the most recently created bitmap.%@NL@% SDKPaint prepares the workspace of the SDKPaint window for the bitmap image that you will create. %@NL@% %@3@%%@CR:C6A00040042 @%%@AB@%4.3.3 Opening Icons and Cursors%@AE@%%@EH@%%@NL@% Because icon and cursor files contain multiple images, you must first open a file and then load a specified image into the workspace. %@NL@% %@4@%%@AB@%Specifying an Icon or Cursor File%@AE@%%@EH@%%@NL@% To open an existing icon or cursor file, choose the Open command from the File menu. SDKPaint offers you a choice of files to open. %@NL@% If you want to create icons or cursors that you will save in a new file, choose the New command from the File menu. %@NL@% When SDKPaint displays the Resource Type dialog box, do the following:%@CR:C6A00040043 @%%@NL@% %@TH: 37 2010 02 34 42 @%Image Type Procedure%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Icon To specify a new icon file: 1. Choose the Icon option. SDKPaint displays an Icon Sizes dialog box. By default, SDKPaint displays icon image information appropriate for the display on which SDKPaint is running. %@CR:C6A00040044 @%%@CR:C6A00040045 @% %@CR:C6A00040046 @% 2. Choose the device type from the combo box. If you want to create an icon image for a different type of device, open the drop-down combo box and choose the kind of device you want to target.Cursor To specify a new cursor file, do the following: 1. Choose the Cursor option. SDKPaint displays a Cursor Sizes dialog box. By default, SDKPaint displays cursor image information appropriate for the display on which SDKPaint is running. 2. Choose the device type from the combo box. If you want to create a cursor for a different type of device, open the drop-down combo box and choose the kind of device you want to target.%@CR:C6A00040047 @%%@CR:C6A00040048 @%%@CR:C6A00040049 @% %@CR:C6A00040050 @%%@TE: 37 2010 02 34 42 @% %@4@%%@AB@%Loading an Image into the Workspace%@AE@%%@EH@%%@NL@% After opening a file, you can either load an existing image into the workspace of the SDKPaint window or specify that you will create a new image. %@NL@% To load an icon or cursor image with a specified pixel dimension into the workspace, choose the Open command from the Image menu. SDKPaint first prompts you for the image you want and then displays the image you select.%@CR:C6A00040051 @%%@NL@% To load a new icon or cursor image with a specified pixel dimension into the workspace, choose the New command from the Image menu. The editor displays a dialog box that prompts you first for the characteristics of the image you want to create and then asks for information about the pixel dimensions of the image. %@NL@% %@2@%%@CR:C6A00040052 @%%@AB@%4.4 Drawing with SDKPaint Tools%@AE@%%@EH@%%@NL@% Whether editing an existing image or creating a new image from scratch, use the tools displayed at the bottom of the SDKPaint window to draw your bitmap, icon, or cursor.%@CR:C6A00040053 @%%@CR:C6A00040054 @%%@CR:C6A00040055 @%%@NL@% Table 4.1 illustrates and describes SDKPaint tools. %@NL@% Table 4.1 SDKPaint Tools %@TH: 47 2928 02 16 30 30 @%Tool Illustration Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Oil Can %@AU@%(Please refer to the printed%@AE@% Fills a bordered area with %@AU@%book)%@AE@% the current drawing color.Paintbrush %@AU@%(Please refer to the printed%@AE@% Paints the image using the %@AU@%book)%@AE@% current drawing width and color. Rectangle %@AU@%(Please refer to the printed%@AE@% Draws a hollow rectangle %@AU@%book)%@AE@% using the current drawing color.Full Rectangle %@AU@%(Please refer to the printed%@AE@% Draws a rectangle and fills %@AU@%book)%@AE@% it with the current drawing color.Circle %@AU@%(Please refer to the printed%@AE@% Draws a hollow circle or %@AU@%book)%@AE@% ellipse using the current drawing color.Full Circle %@AU@%(Please refer to the printed%@AE@% Draws a circle or ellipse %@AU@%book)%@AE@% and fills it with the current drawing color.Line %@AU@%(Please refer to the printed%@AE@% Draws a straight line %@AU@%book)%@AE@% between selected star and end points using the current drawing color.Pick Rectangle %@AU@%(Please refer to the printed%@AE@% Selects a rectangular region %@AU@%book)%@AE@% in the image. Choose the Copy command from the Edit menu to transfer the selected portion of the image to the clipboard. Choose the Paste command from the Edit menu to transfer the contents of the clipboard to the selected region. The selected region reverts to the entire workspace following a copy or paste operation.%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 47 2928 02 16 30 30 @% %@2@%%@CR:C6A00040056 @%%@AB@%4.5 Using the SDKPaint Palette%@AE@%%@EH@%%@NL@% The SDKPaint palette defines available and currently selected colors for drawing and display. SDKPaint displays two types of colors in the palette: true colors and dithered colors. When you are creating a bitmap or icon, the 16 colors that SDKPaint displays in the leftmost eight columns of the palette are true colors. The remaining colors are dithered. When you are creating a cursor, all colors of the palette are true colors.%@CR:C6A00040057 @%%@CR:C6A00040058 @%%@CR:C6A00040059 @%%@CR:C6A00040060 @%%@NL@% The 16 true colors are red, green, and blue (RGB) values guaranteed to be distinct on a device that displays 16 or more colors. %@NL@% If you are working with icons or cursors, you can get information about the RGB values of a color on the palette by first selecting the color and then choosing the Edit Colors command from the Palette menu. If you are editing a bitmap image, you can also get the information by double-clicking the color. The editor lists RGB values of the selected color in the Edit Colors dialog box.%@CR:C6A00040061 @%%@CR:C6A00040062 @%%@NL@% The palette differs with the type of resource you are editing. Figure 4.3 illustrates the palette that SDKPaint displays when you are editing a bitmap.%@CR:C6A00040063 @%%@CR:C6A00040064 @%%@CR:C6A00040065 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% The palette displays 16 true and 12 dithered colors that you can use to define screen background. %@NL@% Figure 4.4 illustrates the palette that SDKPaint displays when you are editing an icon.%@CR:C6A00040066 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% The palette displays 16 true and 12 dithered colors. %@NL@% Figure 4.5 illustrates the palette that SDKPaint displays when you are editing a cursor.%@CR:C6A00040067 @%%@CR:C6A00040068 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% The palette indicates that you can use only black and white opaque colors to define a cursor. The palette also displays 16 true colors that you can use for screen and inverse color.%@CR:C6A00040069 @%%@NL@% The following section describes how to use the colors that the palette displays. %@NL@% %@3@%%@CR:C6A00040070 @%%@AB@%4.5.1 Working with Opaque, Screen, and Inverse Colors%@AE@%%@EH@%%@NL@% Images comprise one or more of the following types of colors: %@NL@% %@AB@%Color%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Color (opaque) Colors that retain their hue regardless of the color of the screen.%@CR:C6A00040071 @% %@CR:C6A00040072 @% %@CR:C6A00040073 @% Screen The color that defines the screen background. %@CR:C6A00040074 @% Inverse The color that is the inverse of the screen color. SDKPaint always displays the inverse color of the currently specified screen color.%@CR:C6A00040075 @% To select an opaque, screen, or inverse color from the palette, do the following: %@NL@% 1. Select the type of color you want to draw within the color type window.%@NL@% 2. Click the color displayed in the palette.%@NL@% %@STUB@% SDKPaint displays the selected color in the color type window.%@NL@% When using the opaque color type, you can associate a color with the left mouse button by clicking that color with the left mouse button. The color you select appears in the box labeled "Left." %@NL@% To associate an opaque color with the right mouse button, click the color with the right mouse button. The selected color appears in the box labeled "Right." %@NL@% The following sections describe how to use opaque, screen, and inverse colors. %@NL@% %@4@%%@AB@%Using Opaque Colors%@AE@%%@EH@%%@NL@% The following describes the opaque color options for each image:%@CR:C6A00040076 @%%@NL@% %@AB@%Image%@AE@% %@AB@%Color Options%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Bitmap%@CR:C6A00040077 @% Bitmaps are either monochrome or color.%@CR:C6A00040078 @% Icon Icons can use the full spectrum of the palette. %@CR:C6A00040079 @%%@CR:C6A00040080 @% %@CR:C6A00040081 @% Cursor Cursors are monochrome. %@CR:C6A00040082 @% %@CR:C6A00040083 @% %@4@%%@AB@%Using Screen Colors%@AE@%%@EH@%%@NL@% Screen colors let you see how your icon or cursor looks against various screens. SDKPaint displays screen colors in the viewing area of the SDKPaint window. In addition to the selection method described above, you can change screen colors as follows:%@CR:C6A00040084 @%%@CR:C6A00040085 @%%@CR:C6A00040086 @%%@NL@% ■ Select a color from the palette and then click in the viewing area.%@NL@% %@STUB@% This method changes the screen color, regardless of the color type you have selected. If you are currently drawing with the opaque color type, using this procedure changes the color of the screen to the color you select from the palette. %@NL@% ■ Select the inverse color type and then click a color in the palette. %@NL@% %@STUB@% SDKPaint displays the inverse color you have selected and automatically displays the corresponding screen color. %@NL@% %@4@%%@AB@%Using Inverse Colors%@AE@%%@EH@%%@NL@% When the opaque colors of an icon or cursor are identical to the color of the screen on which they are displayed, the icon or cursor is not visible. Inverse colors are useful for defining the image when this condition occurs. For example, if you outline an icon in an inverse color, the border of the icon is visible when the screen and opaque colors are identical.%@CR:C6A00040087 @%%@CR:C6A00040088 @%%@CR:C6A00040089 @%%@NL@% In addition to the selection method described in the preceding section, you can change the inverse color by choosing a new screen color. When you change the screen color, SDKPaint automatically displays the compatible inverse color. %@NL@% %@2@%%@CR:C6A00040090 @%%@AB@%4.6 Customizing the Palette%@AE@%%@EH@%%@NL@% SDKPaint lets you customize the palette by editing colors. After editing one or more colors, you can save them in a special palette that you load into the editor.%@CR:C6A00040091 @%%@NL@% This section describes how to do the following: %@NL@% ■ Edit colors for bitmaps and color icons%@NL@% ■ Save a palette that you have customized%@NL@% ■ Load a customized palette into the editor %@NL@% %@3@%%@CR:C6A00040092 @%%@AB@%4.6.1 Editing Colors%@AE@%%@EH@%%@NL@% SDKPaint lets you edit the palette used to draw bitmaps and color icons. To edit a color from the palette that is currently loaded in SDKPaint, do the following:%@CR:C6A00040093 @%%@CR:C6A00040094 @%%@CR:C6A00040095 @%%@NL@% 1. Select the color you want to edit.%@NL@% 2. Choose the Edit Colors command from the Palette menu. %@NL@% %@STUB@% If you are editing a bitmap, you can also double-click the color on the palette. In either case, SDKPaint displays the Edit Colors dialog box.%@NL@% 3. Change the RGB values of the color.%@NL@% %@STUB@% The editor displays the changes to the color in the dialog box.%@NL@% 4. Choose OK if you are satisfied with the new color.%@NL@% %@STUB@% If you want to cancel your edits on the color, choose Cancel.%@NL@% %@3@%%@CR:C6A00040096 @%%@AB@%4.6.2 Saving a Palette%@AE@%%@EH@%%@NL@% After you customize a palette by editing selected colors on it, you can save the palette for future use by choosing the Save Colors command from the Palette menu. SDKPaint prompts you for the filename of the palette you are saving.%@CR:C6A00040097 @%%@NL@% SDKPaint assigns the extension .PAL to custom palettes by default. %@NL@% %@3@%%@CR:C6A00040098 @%%@AB@%4.6.3 Loading a Customized Palette%@AE@%%@EH@%%@NL@% Choose the Get Colors command from the Palette menu to load a customized palette into SDKPaint. SDKPaint prompts you for the name and location of the palette you want to use. %@NL@% After you load the palette into SDKPaint, you can return to the default palette by doing the following:%@CR:C6A00040099 @%%@NL@% 1. Choose the Edit Colors command from the Palette menu.%@NL@% 2. Select Default in the Edit Colors dialog box.%@NL@% %@2@%%@CR:C6A00040100 @%%@AB@%4.7 Defining the Cursor Hotspot%@AE@%%@EH@%%@NL@% To define the hotspot of a cursor do the following: %@NL@% 1. Choose the Set Hotspot command from the Hotspot menu.%@NL@% %@STUB@% SDKPaint changes the cursor to a bullseye and displays a window that gives the coordinates of the cursor as you move it around the work area. %@NL@% 2. Click the left mouse button to define the hotspot. %@NL@% %@STUB@% Clicking the mouse button when the cursor is outside the work area disables the Set Hotspot command.%@CR:C6A00040101 @% %@CR:C6A00040102 @%%@CR:C6A00040103 @%%@CR:C6A00040104 @%%@NL@% To show the current hotspot, choose the Show Hotspot command from the Hotspot menu. The editor displays the coordinates of the current hotspot in a window. To delete the window, choose Show Hotspot again. %@NL@% %@2@%%@CR:C6A00040105 @%%@AB@%4.8 Using the Clipboard%@AE@%%@EH@%%@NL@% SDKPaint lets you transfer images to and from the clipboard using the Copy and Paste commands from the Edit menu. Transferring images is useful to do the following:%@CR:C6A00040106 @%%@NL@% ■ Load an image created using Paintbrush or another paint program.%@NL@% ■ Move an image from one resource type to another, such as when using a cursor image to create an icon.%@CR:C6A00040107 @%%@CR:C6A00040108 @%%@NL@% ■ Create multiple device-specific versions of one image.%@NL@% The editor uses two data formats when transferring images to and from the clipboard. To transfer opaque colors, SDKPaint uses the CF_BITMAP format. To transfer inverse colors, the editor uses a private format. Many drawing applications, such as Paintbrush, recognize the CF_BITMAP format. %@NL@% The image you transfer from the clipboard may be smaller or larger than the selected rectangular region of the image. By default, the selected region is the entire workspace; you can select a smaller region using the Pick Rectangle tool. %@NL@% When the clipboard image is not the same size as the selected region, SDKPaint displays a dialog box that gives you the following options:%@CR:C6A00040109 @%%@NL@% ■ Stretch/shrink Clipboard bitmap?%@NL@% ■ Clip Clipboard bitmap?%@NL@% If you select the Stretch/shrink option, SDKPaint stretches or compresses the image as necessary. For details about this process, see the description of the %@AB@%StretchBlt%@AE@% function in the %@AI@%Reference, Volume 1%@AE@%. %@NL@% If you select the Clip option, SDKPaint pastes the clipboard bitmap to the screen, justified on the top left corners of the workspace and viewing area. SDKPaint modifies rows and columns of the image as follows: %@NL@% %@AB@%Size of Clipboard Bitmap%@AE@% %@AB@%Rows and Columns Modified%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Smaller than selected region Rows at the bottom and columns at the far right of the selected region remain unchanged. Larger than selected region SDKPaint clips rows at the bottom and columns at the far right of the clipboard bitmap. %@2@%%@CR:C6A00040110 @%%@AB@%4.9 Using ZoomIn to Examine Images%@AE@%%@EH@%%@NL@% The Microsoft Windows ZoomIn utility (%@AB@%ZOOMIN%@AE@%) allows you to examine screen images in detail. ZoomIn captures images from the screen and expands or contracts the size of the pixels of that image. For example, you could use ZoomIn to capture the image of a character displayed with the system font, expand that image to show the pixel pattern of the character, and then duplicate the character in the image you are creating with SDKPaint. %@NL@% When you run ZoomIn, the utility displays a small overlapped window with a vertical scroll bar. To capture an image, press the left mouse button while the cursor is inside the client area of the ZoomIn window. A rectangle appears that shows the size of the area on the screen which ZoomIn will display. Drag the rectangle to the image on the screen you want to capture, and then release the mouse button. %@NL@% To vary the detail of the image, use the vertical scroll bar of the ZoomIn window. Scrolling up decreases the detail, and scrolling down increases the detail. To change the size of the image captured by ZoomIn, resize the ZoomIn window. %@NL@% %@2@%%@CR:C6A00040111 @%%@AB@%4.10 Summary%@AE@%%@EH@%%@NL@% SDKPaint is a tool that lets you design bitmaps, icons, and cursors. %@NL@% For more information on subjects related to creating images, see the following:%@NL@% %@AB@%Subject%@AE@% %@AB@%Reference%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Resource files %@AI@%Tools%@AE@%: Chapter 3, "Compiling Resources: The Resource Compiler" Icons %@AI@%Guide to Programming%@AE@%: Chapter 5, "Icons" Cursors %@AI@%Guide to Programming%@AE@%: Chapter 6, "The Cursor, the Mouse, and the Keyboard" Bitmaps %@AI@%Guide to Programming%@AE@%: Chapter 11, "Bitmaps" Clipboard files %@AI@%Reference%@AE@%,%@AI@% Volume 2%@AE@%: Chapter 9, "File Formats" %@CR:C6A00050001 @%%@1@%%@AB@%Chapter 5 Designing Dialog Boxes: The Dialog Editor%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Microsoft Windows Dialog Editor (%@AB@%DIALOG%@AE@%) is a tool that lets you design and test a dialog box on the display screen instead of defining dialog statements in a resource script. Using the Dialog Editor, you can add, modify, and delete controls in a dialog box. The Dialog Editor saves the changes you make as resource script statements. You then compile these statements into a binary resource file that is linked to your application's executable file.%@CR:C6A00050002 @%%@CR:C6A00050003 @%%@CR:C6A00050004 @%%@CR:C6A00050005 @%%@CR:C6A00050006 @%%@CR:C6A00050007 @%%@NL@% This chapter describes the following topics:%@CR:C6A00050008 @%%@NL@% ■ How the Dialog Editor works with files%@NL@% ■ Installing custom controls%@NL@% ■ Viewing the Dialog Editor window%@NL@% ■ Opening resource files, include files, and dialog boxes%@NL@% ■ Editing individual controls%@NL@% ■ Working with groups of controls%@NL@% ■ Working with dialog boxes%@NL@% ■ Moving a dialog box between resources%@NL@% ■ Working with include files ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%You must use a mouse or similar pointing device with the Dialog Editor.%@CR:C6A00050009 @%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@NL@% %@2@%%@CR:C6A00050010 @%%@AB@%5.1 How the Dialog Editor Works with Files%@AE@%%@EH@%%@NL@% The Dialog Editor creates or modifies the following types of files:%@CR:C6A00050011 @%%@CR:C6A00050012 @%%@CR:C6A00050013 @%%@NL@% %@AB@%File Type%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Dialog script (.DLG) Text file containing %@AB@%DIALOG%@AE@% and %@AB@%CONTROL%@AE@% statements that the Resource Compiler interprets Resource file (.RES) Binary file containing multiple dialog resources, and other resources such as bitmaps, icons, menus, and string tables %@CR:C6A00050014 @% %@CR:C6A00050015 @% %@AB@%File Type%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Include file (.H) Text file containing %@AB@%#define%@AE@% constants that are associated with symbol names for the various controls located in a dialog box %@CR:C6A00050016 @%%@CR:C6A00050017 @% Figure 5.1 illustrates how the Dialog Editor manages these files. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@3@%%@CR:C6A00050018 @%%@AB@%5.1.1 The Dialog Script%@AE@%%@EH@%%@NL@% The most important output of the Dialog Editor is the dialog script (.DLG) file. You can define more than one dialog box in a .DLG file. The following exemplifies a .DLG script that Dialog Editor produces:%@CR:C6A00050019 @%%@CR:C6A00050020 @%%@NL@% %@AS@% FirstBox DIALOG LOADONCALL MOVEABLE DISCARDABLE 12, 20, 130, 113 %@AS@% STYLE WS_DLGFRAME | WS_POPUP %@AS@% BEGIN %@AS@% CONTROL "Option 1", 102, "button", BS_RADIOBUTTON | %@AS@% WS_TABSTOP | WS_CHILD, 33, 19, 28, 12 %@AS@% CONTROL "Option 2", 103, "button", BS_RADIOBUTTON | %@AS@% WS_TABSTOP | WS_CHILD, 33, 36, 28, 12 %@AS@% CONTROL "Option 3", 104, "button", BS_RADIOBUTTON | %@AS@% WS_TABSTOP | WS_CHILD, 33, 53, 28, 12 %@AS@% CONTROL "Ok", 1, "button", BS_PUSHBUTTON | %@AS@% WS_TABSTOP | WS_CHILD, 29, 86, 24, 14 %@AS@% CONTROL "Cancel", 2, "button", BS_PUSHBUTTON | %@AS@% WS_TABSTOP | WS_CHILD, 70, 86, 24, 14 %@AS@% END %@AS@% %@AS@% SecondBox DIALOG LOADONCALL MOVEABLE DISCARDABLE 30, 40, 135, 125 %@AS@% STYLE WS_DLGFRAME | WS_POPUP %@AS@% BEGIN %@AS@% . %@AS@% . %@AS@% .%@AE@% You include the dialog script within your application's resource script (.RC) file by using an %@AB@%#include%@AE@% statement that refers to the .DLG file. If you name the dialog script MYDLGS.DLG, your .RC file might look similar to the following example:%@CR:C6A00050021 @%%@CR:C6A00050022 @%%@NL@% %@AS@% #include "mydlgs.h" %@AS@% . %@AS@% . %@AS@% . %@AS@% MainMenu MENU %@AS@% BEGIN %@AS@% POPUP "&File" %@AS@% BEGIN %@AS@% MENUITEM "&New", MI_FILE_NEW %@AS@% . %@AS@% . %@AS@% . %@AS@% END %@AS@% END %@AS@% %@AS@% #include "mydlgs.dlg" %@AS@% . %@AS@% . %@AS@% .%@AE@% Using the %@AB@%#include%@AE@% directive, include the .DLG script into the application's overall .RC script. Then compile the .RC text file to produce an .RES binary file using the %@AB@%-r%@AE@% switch. Finally, link the .RES file into your application's .EXE file. %@NL@% See Section 5.1.3, "The Include File," for more information on how to include the .H header and the .DLG files. %@NL@% %@3@%%@CR:C6A00050023 @%%@AB@%5.1.2 The Resource File%@AE@%%@EH@%%@NL@% The Dialog Editor produces an .RES file that is a companion to the .DLG file. This .RES file is a compiled, binary representation of the dialog script.%@CR:C6A00050024 @%%@NL@% The purpose of the .RES file produced by the Dialog Editor is solely to reedit the dialog script. The Dialog Editor does not read in .DLG files; it reads only in .RES files. Note that this .RES file should not be linked to your application's .EXE file because it does not include the other resources─such as bitmaps, icons, menus, and string tables─required by your application. %@NL@% There are two methods for reediting a dialog resource. The first method is to read back into the Dialog Editor the .RES file that the editor produced as a companion to the .DLG file.%@CR:C6A00050025 @%%@CR:C6A00050026 @%%@CR:C6A00050027 @%%@NL@% The second method is to read into the Dialog Editor the .RES file that the Resource Compiler produced from the combined .RC and .DLG scripts. %@NL@% Which method you choose is a matter of personal preference. The advantage of the first method is that you can group together categories of dialog boxes into separate .DLG files and their corresponding .RES files, and manage them separately. Also, it is not necessary for you to use the Resource Compiler to convert the .DLG text file into the binary .RES format required as input to the Dialog Editor. The advantage of the second method is that you can discard .RES files produced by the Dialog Editor and free up disk space. %@NL@% %@3@%%@CR:C6A00050028 @%%@AB@%5.1.3 The Include File%@AE@%%@EH@%%@NL@% The include (.H) file produced by the Dialog Editor contains %@AB@%#define%@AE@% statements that identify controls in dialog boxes.%@CR:C6A00050029 @%%@NL@% When creating a dialog box, you can assign symbolic names to controls. You use the symbolic names in your application's C source code to refer to the controls. As a result of these assignments, the Dialog Editor produces a header file containing %@AB@%#define%@AE@% statements such as the following:%@CR:C6A00050030 @%%@CR:C6A00050031 @%%@CR:C6A00050032 @%%@NL@% %@AS@% #define DI_OPTION1 102 %@AS@% #define DI_OPTION2 103 %@AS@% #define DI_OPTION3 104%@AE@% By including the header file in your C source code with an %@AB@%#include%@AE@% statement, you can refer to the controls by symbolic names, rather than numeric values, as the following illustrates: %@NL@% %@AS@% BOOL FAR PASCAL FirstDlgProc(hDlg, wMessage, wParam, lParam) %@AS@% . %@AS@% . %@AS@% . %@AS@% switch (wMessage) %@AS@% { %@AS@% case DI_OPTION1: %@AS@% /* Respond to Ok button here */ %@AS@% break; case DI_OPTION2: %@AS@% /* Respond to Cancel button here */ %@AS@% break; %@AS@% . %@AS@% . %@AS@% .%@AE@% You must include the header file in your application's resource script file before including the dialog script. This is necessary because the dialog script refers to the controls using the symbolic names instead of the numeric values. For an example of including files, see Section 5.1.1, "The Dialog Script." %@NL@% When assigning ID values to controls, you can assign any number you want; however, there are some special guidelines for ID values 1 and 2. %@NL@% %@4@%%@AB@%ID Value of 1%@AE@%%@EH@%%@NL@% When the user presses ENTER, Windows automatically sends a WM_COMMAND message to the dialog-input function. If the dialog box has a default button (for example, the OK button), pressing ENTER sends a WM_COMMAND message with the ID value. If you have a default OK button, you should assign it an ID value of 1 so that it is activated when the user presses ENTER. This is consistent with the recommended guidelines for creating a Windows application set forth in %@AI@%Guide to Programming%@AE@%. %@NL@% Windows defines the ID value of 1 as IDOK. %@NL@% %@4@%%@AB@%ID Value of 2%@AE@%%@EH@%%@NL@% When the user presses CANCEL or ESCAPE, Windows automatically sends a WM_COMMAND message with the ID value of 2. If you have a Cancel button in a dialog box, it should have an ID value of 2.%@CR:C6A00050033 @%%@NL@% Windows defines the ID value of 2 as IDCANCEL. %@NL@% %@2@%%@CR:C6A00050034 @%%@AB@%5.2 Installing and Removing Custom Controls%@AE@%%@EH@%%@NL@% The Dialog Editor provides a menu and toolbox of standard controls─such as edit fields and list boxes─that you can select when designing a dialog box. In addition, you can incorporate nonstandard custom controls into a dialog box.%@CR:C6A00050035 @%%@CR:C6A00050036 @%%@NL@% You can develop or acquire any number of custom controls and maintain them in a catalog recognized by the Dialog Editor. A custom control consists of a dynamic-link library (DLL) that contains the window procedure for the control. The DLL also contains functions that interact with the Dialog Editor. For more information on developing custom controls, see %@AI@%Guide to %@AI@%Programming%@AE@%.%@CR:C6A00050037 @%%@CR:C6A00050038 @%%@NL@% The Dialog Editor maintains the catalog of custom controls in your WIN.INI file under the heading [User Controls]. Each entry equates the name of a custom control with the full pathname of the control's DLL file, as shown in the following example:%@CR:C6A00050039 @%%@NL@% %@AS@% [user controls] %@AS@% rainbow = c:\myctrls\rainbow.dll%@AE@% The Dialog Editor lets you add and remove custom controls from this catalog. %@NL@% %@3@%%@CR:C6A00050040 @%%@AB@%5.2.1 Installing a Custom Control%@AE@%%@EH@%%@NL@% To install a custom control in the catalog, do the following: %@NL@% 1. Choose the Add Custom Control command from the File menu.%@NL@% 2. Specify the full pathname of the DLL file that defines your custom control.%@CR:C6A00050041 @%%@NL@% If you want to call up a custom control only during a Dialog Editor session, without permanently adding it to your custom control catalog, then select the Create Temporary Control radio button in the Add Control dialog box.%@CR:C6A00050042 @%%@NL@% For information on working with custom controls, see Section 5.5, "Editing Dialog Box Controls." %@NL@% %@3@%%@CR:C6A00050043 @%%@AB@%5.2.2 Removing a Custom Control%@AE@%%@EH@%%@NL@% To remove a custom control from the catalog, choose the Remove Control command from the File menu. The editor displays a Remove Control Library dialog box that lists custom controls you can remove.%@CR:C6A00050044 @%%@NL@% %@2@%%@CR:C6A00050045 @%%@AB@%5.3 Viewing a Dialog Box: The Dialog Editor Window%@AE@%%@EH@%%@NL@% Figure 5.2 illustrates the Dialog Editor window after a user has loaded a dialog box and has chosen the Toolbox and Status commands from the Options menu.%@CR:C6A00050046 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% The menu bar contains the following menus:%@CR:C6A00050047 @%%@NL@% %@TH: 95 3875 02 34 42 @%Menu Commands%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%File This menu contains the following commands: New─Creates .DLG and companion .RES files Open─Opens existing .RES files for editing Save and Save As─Save changes to a dialog boxes Add Custom Control and Remove Custom Control─Adds and removes members of your custom control catalog Exit─Exits the editorInclude This menu contains the following commands: New─Creates a new include file Open─Opens an existing include file Save and Save As─Save changes to include files View/Edit─Displays and edits include files Hex Values─Toggles the display of hexadecimal and decimal values in include filesDialog This menu contains the following commands: New─Creates a new dialog box View─Lists current dialog boxes in the resource file Flags─Sets memory flags Groups─Sets tab stops and group markers Rename─Renames the current dialog box Test─Toggles work and test modes to allow you to test your dialog boxEdit This menu contains the following commands: Restore─Reverts to last saved version of a dialog box Cut─Moves a dialog box to the clipboard Copy─Copies a dialog box to the clipboard Paste─Copies a dialog box from the clipboard Erase Dialog─Removes a dialog box Styles─Changes the style of a control or dialog box Group Mode─Allows you to move a group of controls as a unit Duplicate Mode─Allows you to duplicate controls by dragging themControl This menu contains different types of controls that you can select for the dialog box. Options This menu contains the following commands: Status─Displays and hides the Selected Item Status window Toolbox─Displays and hides the Toolbox window Grid─Allows you to specify grid increments for aligning controls%@TE: 95 3875 02 34 42 @% %@3@%%@CR:C6A00050048 @%%@AB@%5.3.1 The Mode Display%@AE@%%@EH@%%@NL@% Beneath the menu bar, the Dialog Editor displays the mode you are currently using. The modes are as follows: %@NL@% %@TH: 14 693 02 34 42 @%Mode Meaning%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Work Indicates you are creating or modifying a dialog boxTest Indicates you are testing a box Work/Group Indicates that you are in the process of selecting and moving a group of controlsWork/Copy Indicates that you are in the process of duplicating controls %@CR:C6A00050049 @%%@TE: 14 693 02 34 42 @% %@3@%%@CR:C6A00050050 @%%@AB@%5.3.2 The Toolbox%@AE@%%@EH@%%@NL@% The Toolbox is a convenient alternative to choosing controls from the Control menu. Initially, the Dialog Editor does not display the Toolbox. If you choose the Toolbox command in the Options menu, the editor displays the toolbox in the upper-right corner of the window.%@CR:C6A00050051 @%%@CR:C6A00050052 @%%@NL@% You can move the Toolbox by dragging its title bar. %@NL@% %@3@%%@CR:C6A00050053 @%%@AB@%5.3.3 The Selected Item Status Window%@AE@%%@EH@%%@NL@% When you choose the Status command from the Options menu, the Dialog Editor displays the Selected Item Status window in the lower-right corner of the Dialog Editor window. You can move the Selected Item Status window or close it by choosing the Status command from the Options menu a second time. The window supplies the following information about the currently displayed dialog box and its controls:%@CR:C6A00050054 @%%@CR:C6A00050055 @%%@CR:C6A00050056 @%%@NL@% %@TH: 22 1176 02 34 42 @%Field Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Dialog The name of the dialog box being edited.(x, y) Position of the upper-left corner of the selected dialog box or control.(cx, cy) Offset of the selected dialog box or control.Control Type of control selected (for example, Radio Button or Check Box). If the dialog box itself is selected, the editor displays "Dialog Box" in this field.ID Value Identifier of the selected control. The identifier is displayed as either a number or a symbol. If the dialog box is selected instead of a control, no ID value is shown.%@TE: 22 1176 02 34 42 @% Size and position values are given in horizontal and vertical dialog units. The horizontal units are 1/4 of the dialog base width unit; the vertical units are 1/8 of the dialog base height unit. The current dialog base units are computed from the height and width of the current system font. The %@AB@%GetDialogBaseUnits%@AE@% function returns the dialog base units in pixels.%@CR:C6A00050057 @%%@CR:C6A00050058 @%%@NL@% When you change the dialog box or controls, the window reflects the change. %@NL@% %@2@%%@CR:C6A00050059 @%%@AB@%5.4 Opening Files and Dialog Boxes%@AE@%%@EH@%%@NL@% After invoking %@AB@%DIALOG%@AE@%, you can open the following: %@NL@% ■ An existing or new resource file%@NL@% ■ An existing or new include file%@NL@% ■ An existing or new dialog box%@NL@% Whenever you open a new resource or include file, the editor offers you the opportunity of saving your previous work.%@CR:C6A00050060 @%%@NL@% %@3@%%@CR:C6A00050061 @%%@AB@%5.4.1 Opening a Resource File%@AE@%%@EH@%%@NL@% Using the File menu, you can either create a new resource file or open an existing resource file.%@CR:C6A00050062 @%%@NL@% If opening an existing resource file, you can specify an .RES file that either the Dialog Editor or the Resource Compiler created. %@NL@% %@3@%%@CR:C6A00050063 @%%@AB@%5.4.2 Opening an Include File%@AE@%%@EH@%%@NL@% After you load a resource file, Dialog Editor prompts you for an include file. The include file associates symbolic names with control identifiers.%@CR:C6A00050064 @%%@CR:C6A00050065 @%%@NL@% If you are already working with an include file, you can choose to continue working with it or open a new one. %@NL@% If you loaded an existing resource file, the Dialog Editor displays the Open File window. To edit an include file, choose one of the files listed. %@NL@% %@3@%%@CR:C6A00050066 @%%@AB@%5.4.3 Opening a Dialog Box%@AE@%%@EH@%%@NL@% If you are loading an existing resource file, the Dialog Editor offers you the choice of opening an existing dialog box. The editor displays a list of dialog boxes available for editing in the View Dialog window. If you want to create a new dialog box in the existing resource file, choose the Cancel button from the View Dialog window.%@CR:C6A00050067 @%%@NL@% %@4@%%@AB@%Opening an Existing Dialog Box%@AE@%%@EH@%%@NL@% To open an existing dialog box, choose it from the list that the View Dialog window displays. The dialog box appears in the working area of the Dialog Editor window.%@CR:C6A00050068 @%%@NL@% %@4@%%@AB@%Creating a New Dialog Box%@AE@%%@EH@%%@NL@% To create a new dialog box, choose the New command from the Dialog menu. The Dialog Editor prompts you for a dialog box name.%@CR:C6A00050069 @%%@CR:C6A00050070 @%%@CR:C6A00050071 @%%@NL@% %@2@%%@CR:C6A00050072 @%%@AB@%5.5 Editing Dialog Box Controls%@AE@%%@EH@%%@NL@% The Dialog Editor lets you add, modify, and delete dialog box controls, which are described in Table 5.1. %@NL@% Table 5.1 Dialog Box Controls %@TH: 66 4516 02 23 26 27 @%Control Illustration Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Push button %@AU@%(Please refer to the %@AE@% Push buttons let the user %@AU@%printed book)%@AE@% choose an immediate action, such as canceling the dialog box. %@CR:C6A00050073 @% %@CR:C6A00050074 @%Radio button %@AU@%(Please refer to the %@AE@% Radio buttons are %@AU@%printed book)%@AE@% typically used in groups to give the user a choice of selections. The user can select only one radio button in a group at a time.%@CR:C6A00050075 @% %@CR:C6A00050076 @%Check box %@AU@%(Please refer to the %@AE@% Check boxes are %@AU@%printed book)%@AE@% independent of one another, although two or more often appear next to each other to give the user a choice of selections. The user can turn any number of check boxes on or off at a given moment. %@CR:C6A00050077 @% %@CR:C6A00050078 @%Horizontal scroll bar %@AU@%(Please refer to the %@AE@% Scroll bars let the user %@AU@%printed book)%@AE@% scroll data. They are usually associated with another control or window that contains text or graphics. %@CR:C6A00050079 @% %@CR:C6A00050080 @% %@CR:C6A00050081 @% Vertical scroll bar %@AU@%(Please refer to the %@AE@% %@AU@%printed book)%@AE@%Edit %@AU@%(Please refer to the %@AE@% Edit controls display %@AU@%printed book)%@AE@% both numbers and text, and let the user type in numbers and text. %@CR:C6A00050082 @%%@CR:C6A00050083 @% Static text %@AU@%(Please refer to the %@AE@% Static text controls %@AU@%printed book)%@AE@% label other controls, such as edit controls. %@CR:C6A00050084 @% %@CR:C6A00050085 @% Group box %@AU@%(Please refer to the %@AE@% Group boxes enclose a %@AU@%printed book)%@AE@% collection or group of other controls, such as a group of radio buttons. %@CR:C6A00050086 @% %@CR:C6A00050087 @%List box %@AU@%(Please refer to the %@AE@% List boxes display a list %@AU@%printed book)%@AE@% of strings, such as file or directory names. %@CR:C6A00050088 @% %@CR:C6A00050089 @% Combo box %@AU@%(Please refer to the %@AE@% Combo boxes combine list %@AU@%printed book)%@AE@% boxes with edit controls. %@CR:C6A00050090 @% %@CR:C6A00050091 @%Frame %@AU@%(Please refer to the %@AE@% A hollow rectangle you %@AU@%printed book)%@AE@% can use to frame a control or group of controls. %@CR:C6A00050092 @% %@CR:C6A00050093 @% %@TE: 66 4516 02 23 26 27 @% Table 5.1 Dialog Box Controls (continued) %@TH: 18 1225 02 11 32 33 @%Control Illustration Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Icon %@AU@%(Please refer to the printed %@AE@% A rectangular space in which %@AU@%book)%@AE@% you can place an icon. Do not size the icon space; icons automatically size themselves. %@CR:C6A00050094 @% %@CR:C6A00050095 @% Rectangle %@AU@%(Please refer to the printed %@AE@% A filled rectangle you can use %@AU@%book)%@AE@% for graphical emphasis. %@CR:C6A00050096 @% %@CR:C6A00050097 @% Custom A control you design and define in a DLL file. See Section 5.2, "Installing and Removing Custom Controls." %@CR:C6A00050098 @%%@CR:C6A00050099 @% %@CR:C6A00050100 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 18 1225 02 11 32 33 @% %@3@%%@CR:C6A00050101 @%%@AB@%5.5.1 Adding Controls%@AE@%%@EH@%%@NL@% The Dialog Editor lets you choose the controls you want to add to a dialog box from either the Control menu or the Toolbox. The Toolbox displays an icon for each control.%@CR:C6A00050102 @%%@NL@% %@4@%%@AB@%Enabling the Toolbox%@AE@%%@EH@%%@NL@% To enable the Toolbox, choose the Toolbox command from the Options menu. The Dialog Editor displays the Toolbox in the upper-right section of the Dialog Editor window. You can move the Toolbox by dragging its title bar.%@CR:C6A00050103 @%%@CR:C6A00050104 @%%@CR:C6A00050105 @%%@NL@% %@4@%%@AB@%Adding Standard Controls%@AE@%%@EH@%%@NL@% To add standard controls to a dialog box, do the following: %@NL@% 1. Choose the control you want to add from either the Control menu or the Toolbox. %@NL@% %@STUB@% Choosing either a control command in the Control menu or a control icon in the Toolbox changes the cursor to a plus sign (+). %@NL@% 2. Position the cursor where you want to add the control.%@NL@% 3. Click the mouse button. %@NL@% If the control includes text, add the text using the method described in Section 5.5.2, "Working with Individual Controls." %@NL@% %@4@%%@AB@%Adding Custom Controls%@AE@%%@EH@%%@NL@% After you have installed a custom control using the procedure described in Section 5.2.1, "Installing a Custom Control," the control is accessible in the Control menu and the Toolbox. To add the custom control to a dialog box, choose either the Custom Control command from the Control menu or the Custom Control icon from the Toolbox. The Dialog Editor displays the Select Custom Control dialog box illustrated in Figure 5.3.%@CR:C6A00050106 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% The window lets you select and view a specified custom control. To complete the selection, choose the OK button. %@NL@% You can specify the styles for custom controls as you would standard controls. For information about editing controls, see the next section. %@NL@% %@3@%%@CR:C6A00050107 @%%@AB@%5.5.2 Working with Individual Controls%@AE@%%@EH@%%@NL@% The Dialog Editor lets you make changes to individual controls, as follows: %@NL@% ■ Moving a control%@NL@% ■ Resizing a control%@NL@% ■ Changing control identifiers and styles%@NL@% ■ Adding or changing text associated with a control%@NL@% ■ Duplicating a control%@NL@% ■ Deleting a control %@NL@% %@4@%%@AB@%Moving a Control%@AE@%%@EH@%%@NL@% The Dialog Editor lets you move individual controls. Use the mouse to drag a control to its new position and the DIRECTION keys to make fine adjustments to the control position.%@CR:C6A00050108 @%%@NL@% The DIRECTION keys let you move a control horizontally and vertically by dialog units. (For a description of dialog units, see Section 5.3.3, "The Selected Item Status Window.") By default, controls move one dialog unit each time you press a DIRECTION key. To change the distance moved, choose the Grid command from the Options menu. The Grid command lets you specify the number of dialog units moved along the %@AI@%x%@AE@% and %@AI@%y%@AE@% axes. If you choose new grid coordinates after you have placed a control, the control will align with the new grid coordinates when you move it.%@CR:C6A00050109 @%%@NL@% For information about moving groups of controls, see Section 5.6, "Working with Groups of Controls." %@NL@% %@4@%%@AB@%Resizing a Control%@AE@%%@EH@%%@NL@% To change the size of a control, do the following: %@NL@% 1. Select the control.%@NL@% 2. Drag one of the eight small rectangles that appear on the boundaries. %@CR:C6A00050110 @%%@CR:C6A00050111 @%%@NL@% Dragging one of the corner rectangles changes the width and height of the control simultaneously. %@NL@% The Grid command in the Options menu also affects how a control is resized. When you resize the control, it will automatically size to the nearest grid coordinate. However, if you select new grid coordinates and then resize the control, the size of the control will change in increments of the grid coordinates, but relative to the control's current position. The control itself will not move when you resize it, even though it may no longer be aligned with the grid. To ensure that a control aligns with new grid coordinates, you must move the control. %@NL@% %@4@%%@AB@%Changing Control Identifiers and Styles%@AE@%%@EH@%%@NL@% To change the identifier or style of a control, do the following:%@CR:C6A00050112 @%%@CR:C6A00050113 @%%@CR:C6A00050114 @%%@NL@% 1. Double-click the control, or select the control and choose the Styles command from the Edit menu. %@NL@% %@STUB@% The Dialog Editor displays a window that lists the identifier, text, and style of the control selected. Figure 5.4 illustrates the Button Control Style dialog box.%@CR:C6A00050115 @%%@CR:C6A00050116 @%%@CR:C6A00050117 @%%@NL@% %@STUB@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% 2. To change the identifier, type the new identifier in the ID Value box. %@NL@% %@STUB@% If you supply a symbolic name instead of a numeric value, the Dialog Editor checks to determine whether or not you have already defined the name in the current include file. If you have not, the editor offers you the option of adding the name.%@NL@% 3. To change the style of a control, select the styles you want in the Styles box.%@NL@% %@4@%%@AB@%Adding or Changing Text%@AE@%%@EH@%%@NL@% In addition to changing identifiers and styles, the Style window lets you add or modify text associated with a control.%@CR:C6A00050118 @%%@CR:C6A00050119 @%%@CR:C6A00050120 @%%@NL@% To add or modify text, type the text in the Text box. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%When you add an icon control to a dialog box, the names of the control and %@AI@%the identifier in the .RC file should be the same. For example, if the .RC %@AI@%file defines an icon as "myicon", name the control "myicon" also.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@4@%%@AB@%Duplicating A Control%@AE@%%@EH@%%@NL@% You can copy a control from an existing control in your dialog box by using either of the following methods: %@NL@% ■ Drag the original control while holding down the CONTROL key. The Mode Display beneath the menu bar indicates "Work/Copy" during this operation. A copy of the original control follows the cursor until you release the drag.%@CR:C6A00050121 @%%@CR:C6A00050122 @%%@NL@% ■ Choose the Duplicate Controls command from the Edit menu. While Duplicate Controls is selected, the Mode Display beneath the menu bar indicates "Work/Copy." In this mode, the effect of dragging a control is to duplicate it, rather than move it. To cancel this mode, toggle it by choosing the Duplicate Controls command again.%@NL@% %@4@%%@AB@%Deleting A Control%@AE@%%@EH@%%@NL@% To delete a control, select it and press the DELETE key or choose the Clear Control command from the Edit menu. The Dialog Editor deletes the selected control from the dialog box.%@CR:C6A00050123 @%%@CR:C6A00050124 @%%@NL@% %@2@%%@CR:C6A00050125 @%%@AB@%5.6 Working with Groups of Controls%@AE@%%@EH@%%@NL@% The Dialog Editor lets you do the following with groups of controls: %@NL@% ■ Move controls as a group%@NL@% ■ Define the input focus sequence of a group %@NL@% %@3@%%@CR:C6A00050126 @%%@AB@%5.6.1 Moving Groups of Controls%@AE@%%@EH@%%@NL@% To move a group of controls, do the following: %@NL@% 1. Choose the Group Move command from the Edit menu. %@NL@% %@STUB@% The work mode will indicate "Work/Group."%@NL@% 2. Click each control in the group you want to move. %@NL@% %@STUB@% The editor outlines each control you select, and the group itself, with a gray line.%@CR:C6A00050127 @% %@CR:C6A00050128 @%%@NL@% 3. Click the mouse button while pointing to a location in the group rectangle not occupied by one of the controls.%@NL@% 4. While holding down the mouse button, drag the group of controls to a new position.%@NL@% 5. Cancel the "Work/Group" mode by toggling the Group Move command in the Edit menu.%@NL@% You must select %@AI@%all%@AE@% the controls you want to move, even if one control encloses another. For instance, to move several radio buttons and the group box that encloses them, you must select each radio button %@AI@%and%@AE@% the group box, and then move them as a unit. %@NL@% %@3@%%@CR:C6A00050129 @%%@AB@%5.6.2 Defining Input Focus Sequence%@AE@%%@EH@%%@NL@% The Groups command in the Dialog menu lets you specify the input focus sequence in a group of controls, as follows:%@CR:C6A00050130 @%%@CR:C6A00050131 @%%@NL@% ■ Specify the controls forming a group. A group defines a sequence of controls within which the user can shift input focus by using the DIRECTION keys.%@NL@% ■ Specify tab stops that define how input shifts from group to group as the user presses the TAB key.%@NL@% ■ Specify the sequential order in which individual and groups of controls receive input focus as the user presses DIRECTION and TAB keys.%@NL@% When you choose the Groups command, the Dialog Editor displays the Order Groups window illustrated in Figure 5.5. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@4@%%@AB@%Defining a Group%@AE@%%@EH@%%@NL@% To specify a group of controls, place a group marker before the first control in the group and another after the last control, as follows:%@CR:C6A00050132 @%%@CR:C6A00050133 @%%@CR:C6A00050134 @%%@CR:C6A00050135 @%%@NL@% 1. Select the first control in the group.%@NL@% 2. Click the Group Marker button.%@NL@% %@STUB@% The Dialog Editor inserts a group marker above the control. %@NL@% 3. Select the control below the last control in the group.%@NL@% 4. Click the Group Marker button. %@NL@% %@STUB@% The Dialog Editor inserts a group marker below the last control in the group. This marker defines the beginning of the next group.%@NL@% Placing a group marker before a control instructs the Dialog Editor to assign the WS_GROUP style to the control. %@NL@% To delete a group marker, select the group marker and click the Delete Group button.%@CR:C6A00050136 @%%@CR:C6A00050137 @%%@NL@% %@4@%%@AB@%Setting and Deleting Tab Stops%@AE@%%@EH@%%@NL@% Tab stops determine where input focus shifts when the user presses the TAB key. Set or delete tab stops on individual controls, or on the first control in a group, as follows:%@CR:C6A00050138 @%%@CR:C6A00050139 @%%@CR:C6A00050140 @%%@NL@% 1. Select the control on which you want to set or remove a tab stop.%@NL@% 2. Click the Tab Stop or Delete Tab button to set or delete a tab, respectively. %@NL@% An asterisk appears next to each control on which a tab stop is set. %@NL@% Placing a tab stop on a control instructs the Dialog Editor to assign the WS_TABSTOP style to the control. %@NL@% %@4@%%@AB@%Changing the Input Focus Sequence of Controls%@AE@%%@EH@%%@NL@% By default, controls receive input focus in the order in which you place them in the dialog box, not their position in the dialog box. Repositioning controls does not affect the order in which they receive input focus. %@NL@% To change the order in which controls receive user input, reorder the controls listed in the Order Groups window as follows:%@CR:C6A00050141 @%%@CR:C6A00050142 @%%@NL@% 1. Select the control you want to move.%@NL@% 2. Move the cursor to the position where you want the control to appear in the list box. %@NL@% %@STUB@% The cursor changes from an arrow to a short, horizontal bar. The bar appears only in places where you can insert the control.%@NL@% 3. Click the mouse button to insert the control.%@NL@% %@2@%%@CR:C6A00050143 @%%@AB@%5.7 Working with a Dialog Box%@AE@%%@EH@%%@NL@% In addition to adding, changing, and deleting controls in a dialog box, you can do the following to the box as a whole: %@NL@% ■ Change its size and name%@NL@% ■ Define its styles%@NL@% ■ Set flags that indicate how Windows stores the box in memory%@NL@% ■ Erase the box %@NL@% %@3@%%@CR:C6A00050144 @%%@AB@%5.7.1 Resizing a Dialog Box%@AE@%%@EH@%%@NL@% To change the size of a dialog box, select it and drag one of its resize handles.%@CR:C6A00050145 @%%@NL@% For information about resizing a control, see Section 5.5.2, "Working with Individual Controls." %@NL@% The Grid command in the Options menu affects how a dialog box is resized. When you resize the dialog box, it will automatically size to the nearest grid coordinate. However, the presence of the grid does not affect how a dialog box is moved. %@NL@% %@3@%%@CR:C6A00050146 @%%@AB@%5.7.2 Renaming a Dialog Box%@AE@%%@EH@%%@NL@% To rename a dialog box, do the following:%@CR:C6A00050147 @%%@NL@% 1. Choose the Rename command from the Dialog menu.%@NL@% 2. Enter the new name in the Name Dialog window.%@NL@% %@3@%%@CR:C6A00050148 @%%@AB@%5.7.3 Defining Styles%@AE@%%@EH@%%@NL@% To define the styles of a dialog box, do the following:%@CR:C6A00050149 @%%@CR:C6A00050150 @%%@NL@% 1. Select the dialog box.%@NL@% 2. Choose the Styles command from the Edit menu.%@NL@% 3. Select the relevant styles from the Dialog Box Styles window.%@NL@% %@3@%%@CR:C6A00050151 @%%@AB@%5.7.4 Setting Memory Flags%@AE@%%@EH@%%@NL@% To set memory flags for the currently displayed dialog box, do the following:%@CR:C6A00050152 @%%@CR:C6A00050153 @%%@NL@% 1. Choose the Flags command from the Dialog menu.%@NL@% 2. Select the relevant memory flags from the Memory Flags window.%@NL@% Memory flags are as follows: %@NL@% ■ Moveable─Dialog resource data segment can be moved in memory if necessary to compact memory.%@NL@% ■ Preload─Dialog resource data segment is loaded immediately.%@NL@% ■ Discard─Dialog resource data segment can be discarded if no longer needed.%@NL@% By default, dialog boxes are moveable, loaded on call rather than preloaded, and discardable. %@NL@% For more information about memory flags, see %@AI@%Guide to Programming%@AE@% and the %@AI@%Reference, Volume 2%@AE@%. %@NL@% %@3@%%@CR:C6A00050154 @%%@AB@%5.7.5 Canceling Edits%@AE@%%@EH@%%@NL@% To cancel edits on a dialog box, use either the Restore or the Clear command from the Edit menu. The Restore command cancels edits and reloads the currently displayed dialog box. The Clear command removes the currently displayed dialog box from the work area and the resource.%@CR:C6A00050155 @%%@CR:C6A00050156 @%%@NL@% %@2@%%@CR:C6A00050157 @%%@AB@%5.8 Moving a Dialog Box Between Resources%@AE@%%@EH@%%@NL@% To move a dialog box from one resource file to another, use the Cut, Copy, and Paste commands from the Edit menu, as follows:%@CR:C6A00050158 @%%@NL@% 1. Cut or copy the currently displayed dialog box to the clipboard. %@NL@% %@STUB@% The Cut command removes the dialog box from the work area and copies the resource to the clipboard; the Copy command copies the box to the clipboard.%@NL@% 2. Load a new resource file into the Dialog Editor.%@NL@% 3. Paste the dialog box from the clipboard to the work area.%@NL@% The Dialog Editor supports the clipboard bitmap format (CF_BITMAP) so that other clipboard viewers can paste dialog box images. The editor also uses a private clipboard format, "Dialog," for its own use. The Dialog Editor can paste from the clipboard only if an instance of the Dialog Editor has previously copied data to the clipboard in the private "Dialog" format.%@CR:C6A00050159 @%%@NL@% %@2@%%@CR:C6A00050160 @%%@AB@%5.9 Working with Include Files%@AE@%%@EH@%%@NL@% Dialog Editor lets you create and modify include files that define symbolic names for controls.%@CR:C6A00050161 @%%@NL@% This section describes the following: %@NL@% ■ How to create new include files when editing a dialog box%@NL@% ■ How to load existing include files into the Dialog Editor%@NL@% ■ How to edit include files%@NL@% ■ How to save include files%@NL@% Table 5.2 describes the commands used for editing include files. %@NL@% Table 5.2 Commands for Editing Include Files %@TH: 19 899 02 34 42 @%Command Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%New Creates a new include file.Open Opens an existing include file.Save Saves a specified include file.Save As Renames an include file and saves it.View/Edit Displays the View/Edit Include File window. This window enables the user to edit symbolic definitions for controls.Hex Values Toggles the display of identifier values between decimal and hexidecimal.%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 19 899 02 34 42 @% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The Dialog Editor works with include files that have only %@AB@%#define%@AE@%%@AI@% %@AI@%directives. The Dialog Editor will not work with header files that contain %@AI@%other directives, such as %@AE@%%@AI@%%@AB@%typedef%@AE@%%@AE@%%@AI@%, or comments preceded by a semicolon ( ; %@AI@%). When the Dialog Editor saves the include file, it strips out any blank %@AI@%lines that may have existed previously in the include file.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00050162 @%%@AB@%5.9.1 Creating New Include Files%@AE@%%@EH@%%@NL@% The Dialog Editor lets you create new include files to define symbol names for controls in your dialog boxes. You can create new include files either when you create a new resource file or when you are editing a dialog box.%@CR:C6A00050163 @%%@CR:C6A00050164 @%%@NL@% Typically, you create a new include file when creating a new resource file. After creating a new resource file using the method described in Section 5.4.1, "Opening a Resource File," the Dialog Editor asks whether or not you want to create a new include file. %@NL@% When creating a new include file, you can give it a name identical to the resource filename. Giving the resource and include files identical names causes the Dialog Editor to open the include file automatically each time you load the corresponding resource file into the editor. If you give the resource file and include file different filenames, the Dialog Editor prompts you for the include file you want to open. %@NL@% If you want to create a new include file while you are editing a dialog box, choose the New command from the Include menu. %@NL@% %@3@%%@CR:C6A00050165 @%%@AB@%5.9.2 Loading Existing Include Files%@AE@%%@EH@%%@NL@% Just as you can create a new include file either when loading a resource file at the beginning of an editing session or later when editing a dialog box, you can load existing include files either at the beginning or during your editing session.%@CR:C6A00050166 @%%@CR:C6A00050167 @%%@NL@% Typically, you load an existing include file into the editor at the beginning of an editing session. When you open a resource file at the beginning of a session, the Dialog Editor automatically loads the corresponding include file, if the file has the same name as the resource file you open. If the include filename is different than the resource filename, the editor asks you to select the include file you want to open. %@NL@% If you want to open an existing include file while you are editing a dialog box, choose the Open command from the Include menu. The Dialog Editor displays an Open File window that lists include files you can load. %@NL@% %@3@%%@CR:C6A00050168 @%%@AB@%5.9.3 Editing Include Files%@AE@%%@EH@%%@NL@% You can edit an include file in the following ways:%@CR:C6A00050169 @%%@CR:C6A00050170 @%%@NL@% ■ Select individual controls and define their symbolic names.%@NL@% ■ Open the file and edit its symbolic names and identifiers.%@NL@% The second method lets you define symbolic names for controls as you work with them.%@CR:C6A00050171 @%%@NL@% %@4@%%@AB@%Defining Names by Individual Control%@AE@%%@EH@%%@NL@% Instead of opening an include file and editing it as a whole, you can define symbolic names for individual controls as you work with them. The Dialog Editor saves the names in the include file that you loaded into the editor. %@NL@% To define the symbolic name of an individual control as you are working with it, do the following: %@NL@% 1. Double-click the control. %@NL@% %@STUB@% The Dialog Editor displays a Style window.%@NL@% 2. Enter the symbolic name of the control in the ID Value field. %@NL@% %@STUB@% If you have not defined the symbolic name before, the Dialog Editor displays the following warning message: "That symbol does not exist."%@NL@% 3. Click the OK button in the Warning Message window. %@NL@% %@STUB@% The Dialog Editor displays the View/Edit Include File window with the symbolic name you have defined for the control.%@NL@% 4. Click the Add button to complete adding the symbolic name to the include file.%@NL@% %@4@%%@AB@%Editing the File%@AE@%%@EH@%%@NL@% To edit an include file, do the following:%@CR:C6A00050172 @%%@CR:C6A00050173 @%%@CR:C6A00050174 @%%@CR:C6A00050175 @%%@NL@% 1. Choose the View/Edit command from the Include menu. The editor displays the View/Edit Include File window.%@NL@% 2. Select the symbol you want to edit.%@NL@% 3. Make the change in the Symbol Name or ID Value text box.%@NL@% 4. Choose the Change button. %@NL@% 5. Select the symbol and choose the Delete command.%@NL@% %@3@%%@CR:C6A00050176 @%%@AB@%5.9.4 Saving Include Files%@AE@%%@EH@%%@NL@% When saving an include file, give the file a name identical to the name of its corresponding resource file, if possible. If the resource file and include file have the same name, the Dialog Editor loads the include file automatically when you open its corresponding resource file.%@CR:C6A00050177 @%%@CR:C6A00050178 @%%@NL@% %@2@%%@CR:C6A00050179 @%%@AB@%5.10 Summary%@AE@%%@EH@%%@NL@% This chapter described the Dialog Editor, a tool that lets you design a dialog box on the display screen instead of defining dialog statements in a resource script file. For further information, see the following: %@NL@% %@AB@%Topic%@AE@% %@AB@%Reference%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Resource file %@AI@%Tools%@AE@%: Chapter 3, "Compiling Resources: management The Resource Compiler" Introduction to dialog boxes %@AI@%Guide to Programming%@AE@%: Chapter 8, "Controls," and Chapter 9, "Dialog Boxes" Memory flags %@AI@%Guide to Programming%@AE@%: Chapter 15, "Memory Management" and %@AI@%Reference, Volume 2%@AE@%: Chapter 8, "Resource Script Statements" Control and dialog box styles %@AI@%Reference, Volume 2%@AE@%: Chapter 8, "Resource Script Statements" %@AI@%System Application Architecture, Common %@AE@% %@AI@%User Access: Advanced Interface Design %@AE@% %@AI@%Guide%@AE@% %@CR:C6A00060001 @%%@1@%%@AB@%Chapter 6 Designing Fonts: The Font Editor%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Microsoft Windows Font Editor (%@AB@%FONTEDIT%@AE@%) lets you modify existing fonts to create new fonts for your applications. Using the Font Editor, you can modify each character in a font, or the height, width, and character mapping of a font itself. In addition, you can use the editor to update information in the font file header.%@CR:C6A00060002 @%%@NL@% This chapter describes the following:%@CR:C6A00060003 @%%@NL@% ■ Editing letters, numbers, and other characters in the font%@NL@% ■ Modifying the height, width, and character mapping of the font%@NL@% ■ Changing information in the font file header%@NL@% You can use the Font Editor only to create and edit raster fonts. %@NL@% After creating a new font with the Font Editor, you must add the new font to a font resource file. %@NL@% For information on creating vector fonts and adding fonts to the font resource file, see the %@AI@%Reference, Volume 2%@AE@%.%@CR:C6A00060004 @%%@CR:C6A00060005 @%%@CR:C6A00060006 @%%@CR:C6A00060007 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%You must use a mouse or similar pointing device with the Font Editor.%@CR:C6A00060008 @%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00060009 @%%@AB@%6.1 Opening a Font%@AE@%%@EH@%%@NL@% To create a new font, you must open and edit an existing font. You cannot create a new font from scratch. The font file you open must be in Windows 2.0 or 3.0 format.%@CR:C6A00060010 @%%@CR:C6A00060011 @%%@NL@% If you do not have an existing 2.0 or 3.0 font to edit, the SDK disks provide two "seed" fonts that are installed in your Windows development tools directory (named \WINDEV by default). The ATRM1111.FNT is a fixed-pitch font, while the VGASYS.FNT is a variable-pitch font. %@NL@% After opening a font, the Font Editor displays the font, a specified character, and information about the character. Figure 6.1 illustrates the Font Editor window. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% The Font Editor window has the following features:%@CR:C6A00060012 @%%@CR:C6A00060013 @%%@CR:C6A00060014 @%%@CR:C6A00060015 @%%@NL@% %@AB@%Feature%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Character window Contains a copy of the character you want to edit. A grid divides the window into rectangles. Each rectangle represents a pixel. %@CR:C6A00060016 @%%@CR:C6A00060017 @% Character-viewing window Displays two instances of the character in its normal size. The character-viewing window lets you examine the effect of the changes you make to the character. It also lets you see external character leading, the amount of vertical separation between lines. %@CR:C6A00060018 @%%@CR:C6A00060019 @% Character information Displays the character ANSI value and the character width and height in pixels. %@CR:C6A00060020 @% %@CR:C6A00060021 @% Font window Displays normal-size copies of the characters in the font. This window is moveable.%@CR:C6A00060022 @% The following sections describe how to edit characters displayed in the Font Editor window. %@NL@% %@2@%%@CR:C6A00060023 @%%@AB@%6.2 Editing Characters%@AE@%%@EH@%%@NL@% The Font Editor lets you change characters. This section describes how to change characters in the following ways: %@NL@% ■ By turning on and off individual pixels%@NL@% ■ By adding and deleting columns or rows of pixels%@NL@% ■ By modifying specified blocks of pixels%@CR:C6A00060024 @%%@CR:C6A00060025 @%%@CR:C6A00060026 @%%@NL@% ■ By changing the width of a specified character, if the character belongs to a variable-pitch font%@CR:C6A00060027 @%%@NL@% %@STUB@% %@AI@%NOTE %@AE@%When you select a new character for editing, the Font Editor updates the current workspace with the character you have edited. If you do not want to save your edits, make sure you cancel changes, using the Refresh command in the Edit menu, before you make the new selection. See Section 6.2.6, "Canceling Changes to a Character," for more information on the Refresh command. %@NL@% %@3@%%@CR:C6A00060028 @%%@AB@%6.2.1 Turning Pixels On or Off%@AE@%%@EH@%%@NL@% The Font Editor lets you change characters pixel by pixel. To turn a character pixel on or off, point to the pixel and click the left mouse button. To turn several pixels on or off, drag the cursor over the pixels you want to change.%@CR:C6A00060029 @%%@CR:C6A00060030 @%%@CR:C6A00060031 @%%@CR:C6A00060032 @%%@NL@% %@3@%%@CR:C6A00060033 @%%@AB@%6.2.2 Changing Rows and Columns of Pixels%@AE@%%@EH@%%@NL@% The Font Editor lets you copy or delete rows and columns of pixels. The Row and Column menus each contain Add and Delete commands. %@NL@% %@4@%%@AB@%Adding a Row or Column%@AE@%%@EH@%%@NL@% The Font Editor adds rows and columns to a character by copying the row or column you select. To add a row or column, do the following: %@NL@% 1. Choose the Add command from the appropriate menu.%@NL@% 2. Select the row or column you want to delete by clicking on it.%@NL@% The Font Editor duplicates the row or column selected.%@CR:C6A00060034 @%%@CR:C6A00060035 @%%@CR:C6A00060036 @%%@CR:C6A00060037 @%%@CR:C6A00060038 @%%@NL@% When adding a new row, the Font Editor inserts it between the selected row and the row immediately below it. The Font Editor pushes all rows below the new row down one, and deletes the row at the bottom of the Character window. Figure 6.2 illustrates selecting a row for addition to the character. Figure 6.3 illustrates the character after the Font Editor has duplicated the row.%@CR:C6A00060039 @%%@CR:C6A00060040 @%%@CR:C6A00060041 @%%@CR:C6A00060042 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% When adding a new column, the Font Editor inserts it between the selected column and the one to its right. The Font Editor inserts the new column and pushes all columns to its right one column to the right, and deletes the column at the far right of the Character window. Figure 6.4 illustrates selecting a column for addition to the character. Figure 6.5 illustrates the character after the Font Editor has duplicated the column. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@4@%%@AB@%Deleting a Row or Column%@AE@%%@EH@%%@NL@% To delete a row or column of pixels, do the following: %@NL@% 1. Choose the Delete command from the appropriate menu.%@NL@% 2. Select the row or column you want to delete by clicking on it.%@NL@% Deleting a row causes all rows below it to move up one, and causes the last row in the Character window to be duplicated.%@CR:C6A00060043 @%%@CR:C6A00060044 @%%@CR:C6A00060045 @%%@CR:C6A00060046 @%%@CR:C6A00060047 @%%@CR:C6A00060048 @%%@NL@% When you delete a whole column, all columns to the right of the deleted column move left one, and the column at the far right of the Character window is duplicated. %@NL@% %@3@%%@CR:C6A00060049 @%%@AB@%6.2.3 Modifying Blocks of Pixels%@AE@%%@EH@%%@NL@% The Fill menu provides commands that let you select and change specified blocks of pixels. The commands on the Fill menu are useful if you want to modify a large number of pixels in the same way. For example, you can select a block of pixels and fill all of them in one operation.%@CR:C6A00060050 @%%@CR:C6A00060051 @%%@CR:C6A00060052 @%%@NL@% The Fill menu contains the following commands: %@NL@% %@AB@%Command%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Clear Changes a specified block of pixels to background pixels. Solid Fills a specified block with foreground pixels. Hatched Creates alternate foreground and background pixels in a specified block. Inverted Changes foreground pixels to background pixels, and vice versa, in a specified block. Left=Right Rotates a specified block horizontally 180 degrees. Top=Bottom Rotates a specified block vertically 180 degrees. Copy Copies pixels in a specified block to the clipboard. Paste Fills a specified block with pixels from the clipboard. If you are pasting pixels from the clipboard, be sure the area of the Character window in which you want to paste is the same size as the block on the clipboard. If you try to paste your data from the clipboard into an area that is larger or smaller than the block, the Font Editor tries to stretch or squeeze the block to fit.%@CR:C6A00060053 @%%@CR:C6A00060054 @%%@CR:C6A00060055 @%%@CR:C6A00060056 @%%@CR:C6A00060057 @%%@NL@% The procedure for carrying out commands in the Fill menu is as follows:%@CR:C6A00060058 @%%@CR:C6A00060059 @%%@NL@% 1. Choose the relevant command from the menu.%@NL@% 2. Select the block of pixels you want to change.%@NL@% The editor executes the relevant operation on all pixels within the specified block. %@NL@% %@3@%%@CR:C6A00060060 @%%@AB@%6.2.4 Changing Character Width%@AE@%%@EH@%%@NL@% Use the Width menu to change the width of a character belonging to a variable-pitch font. Commands in the Width menu change the number of columns in the character bitmap in the following ways:%@CR:C6A00060061 @%%@CR:C6A00060062 @%%@NL@% %@AB@%Command%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Wider (left) Adds a blank column to the left side of the character. %@CR:C6A00060063 @% %@CR:C6A00060064 @% Wider (right) Adds a blank column to the right side of the character. Wider (both) Adds a blank column to each side of the character. Narrower (left) Deletes a column from the left side of the character. Narrower (right) Deletes a column from the right side of the character. Narrower (both) Deletes a column from each side of the character. ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The width of a character can be changed only on variable-pitch fonts.%@CR:C6A00060065 @%%@AE@% %@AI@%Characters in a variable-pitch font cannot be wider than the maximum %@AI@%character width. If you try to make a character cell wider than the maximum %@AI@%character width, a dialog box appears, warning you that the maximum %@AI@%character width will increase. %@CR:C6A00060066 @%%@CR:C6A00060067 @%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00060068 @%%@AB@%6.2.5 Storing Changes to a Character%@AE@%%@EH@%%@NL@% You can store changes to a character by selecting it in the Font-viewing window.%@CR:C6A00060069 @%%@CR:C6A00060070 @%%@NL@% The Font Editor stores your selection by copying it back to the font buffer. The Font-viewing window is updated to show the new character. %@NL@% You can also store changes to a character by making a new selection. The Font Editor copies the old selection into the font buffer before copying the new selection to the Character window. This is useful if you want to continue editing characters in the same font. %@NL@% %@3@%%@CR:C6A00060071 @%%@AB@%6.2.6 Canceling Changes to a Character%@AE@%%@EH@%%@NL@% To recover from an editing mistake, use either the Undo command or the Refresh command from the Edit menu.%@CR:C6A00060072 @%%@NL@% The Undo command restores the character window to its state before the last change in the window.%@CR:C6A00060073 @%%@CR:C6A00060074 @%%@NL@% The Undo command cannot cancel changes made to a character that you have stored in the buffer. %@NL@% To cancel all changes you have made to a character, use the Refresh command from the Edit menu. The Refresh command replaces the current character in the character window with a copy from the Font window. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%You cannot cancel changes to a character by selecting a new character. %@AI@%Selecting a new character, or reselecting the current character, causes the %@AI@%Font Editor to store all changes to the character in the font buffer. Only %@AI@%the Refresh command cancels changes. %@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00060075 @%%@AB@%6.3 Editing a Font%@AE@%%@EH@%%@NL@% To change the height, width, and character-mapping ANSI value of a font, use the Size command in the Font menu. The command displays a dialog box that contains the following options:%@CR:C6A00060076 @%%@CR:C6A00060077 @%%@CR:C6A00060078 @%%@CR:C6A00060079 @%%@CR:C6A00060080 @%%@CR:C6A00060081 @%%@CR:C6A00060082 @%%@NL@% %@AB@%Option%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Character Pixel Height Defines the height (in pixels) of the characters in the font. %@CR:C6A00060083 @% Maximum Width (variable-width Defines the width (in pixels) of the fonts only) widest possible character in a variable-pitch font. %@CR:C6A00060084 @% Character Pixel Width Defines the width (in pixels) of all (fixed-pitch fonts only) characters in a fixed-pitch font. In fixed-pitch fonts all characters have equal width. %@CR:C6A00060085 @% First Character Defines the character value (for example, the ANSI value) of the first character in the font. The first character is the character to the far left when you scroll the contents of the font-viewing window to the far right. %@CR:C6A00060086 @%%@CR:C6A00060087 @% %@CR:C6A00060088 @% %@AB@%Option%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Last Character Defines the character value (for example, the ANSI value) of the last character in the font. The last character is the character to the far right when you scroll the contents of the font-viewing window to the far left.%@CR:C6A00060089 @%%@CR:C6A00060090 @% Pitch %@NL@% Defines the font as either Fixed or Variable. Fixed and Variable are mutually exclusive. %@CR:C6A00060091 @% %@CR:C6A00060092 @% %@CR:C6A00060093 @% %@CR:C6A00060094 @% %@CR:C6A00060095 @%%@CR:C6A00060096 @% You can change a font from fixed-pitch to variable-pitch by selecting Variable in the Size dialog box. You cannot change a variable-pitch font to fixed-pitch. Weight Lists options that define the font weight, ranging from thin to heavy. Each option represents the specific degree of heaviness (i.e., thickness of stroke) of the font. The options are mutually exclusive. %@CR:C6A00060097 @%%@CR:C6A00060098 @% %@2@%%@CR:C6A00060099 @%%@AB@%6.4 Changing Font File Header Information%@AE@%%@EH@%%@NL@% To change the information in the font file header, use the Header command in the Font menu. The Header command displays a dialog box that contains the following information about the font:%@CR:C6A00060100 @%%@CR:C6A00060101 @%%@CR:C6A00060102 @%%@CR:C6A00060103 @%%@NL@% %@AB@%Item%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Face Name The name used to distinguish the font from other fonts. It is not necessarily the same as the font filename. The face name can be as many as 32 characters. %@CR:C6A00060104 @% File Name The name of the font file being edited. %@CR:C6A00060105 @% Copyright Either a copyright notice or additional information about the font. It can be as many as 60 characters in length. %@CR:C6A00060106 @% Nominal Point Size The point size of the characters in the font. One point is equal to approximately 1/72 of an inch. %@CR:C6A00060107 @% %@AB@%Item%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Height of Ascent The distance (in pixels) from the top of an ascender to the baseline. %@CR:C6A00060108 @% Nominal Vert. The vertical resolution at which the Resolution characters were digitized. %@CR:C6A00060109 @% Nominal Horiz. The horizontal resolution at which the Resolution characters were digitized. %@CR:C6A00060110 @% External Leading The pixel height of the external leading. External leading is the vertical distance (in rows) from the bottom of one character cell to the top of the character cell below it. The Character-viewing window shows two copies of the character, one above the other, so that you can see the effect of the leading. %@CR:C6A00060111 @% %@CR:C6A00060112 @% Internal Leading The pixel height of the internal leading. Internal leading is the vertical distance (in rows) within a character cell above the top of the tallest letter; only marks such as accents, umlauts, and tildes for capital letters should appear within the space designated as internal leading. %@CR:C6A00060113 @%%@CR:C6A00060114 @% Default Character The character value (for example, the ANSI value) of the default character. The default character is used whenever your application tries to use a character that does not exist in the font. %@CR:C6A00060115 @%%@CR:C6A00060116 @%%@CR:C6A00060117 @% Break Character The character value of the break character. The break character is used to pad lines that have been justified. The break character is typically the space character. (For example, in the ANSI character set, the value is 32.) %@CR:C6A00060118 @% ANSI, OEM, or These options define the character set. SYMBOL The ANSI character set (value zero) is the default Windows character set. The OEM character set (value 255) is machine-specific. The Symbol character set (value 2) contains special characters typically used to represent mathematical and scientific formulas. The number to the right of these options defines the character set. It can be any value from 0 to 255, but only 0, 2, and 255 have a predefined meaning. %@CR:C6A00060119 @% %@CR:C6A00060120 @%%@CR:C6A00060121 @% %@AB@%Item %@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Font Family The family to which the font belongs. Font families define the general characteristics of the font as follows: %@CR:C6A00060122 @% %@CR:C6A00060123 @% %@AB@%Family%@AE@% %@AB@%%@AE@% %@AB@%Description%@AE@% %@AB@%Name%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Roman Proportionally-spaced fonts with serifs. Modern Fixed-pitch fonts. Swiss Proportionally-spaced fonts without serifs. Decorative Novelty fonts. Script Cursive or script fonts. Dontcare Custom font. Italic This option defines an italic font. Underline This option defines an underlined font. %@CR:C6A00060124 @% Strikeout This option defines a font whose characters have been struck out. %@CR:C6A00060125 @% %@2@%%@CR:C6A00060126 @%%@AB@%6.5 Summary%@AE@%%@EH@%%@NL@% The Font Editor lets you modify existing fonts on the screen to create new fonts for your application. For an introduction to Windows fonts, see Chapter 18, "Fonts," in %@AI@%Guide to Programming%@AE@%. %@NL@% %@CR:C6A-Part 03 @%%@1@%%@AB@%PART III Debugging and Optimization Tools%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Part 3 describes Microsoft Windows debugging and optimization tools. The SDK includes three debuggers: Code View for Windows, Symbolic Debugger, and Windows 80386 Debugger. Use Code View for Windows to debug your application with protected-mode (standard or 386 enhanced) Windows, and the Symbolic Debugger to debug your application with real-mode Windows. Use the 80386 Debugger for more advanced debugging in protected mode. %@NL@% The SDK also includes tools that let you monitor messages and analyze memory management. Spy lets you monitor messages sent to a specified window or to all windows. It is useful for verifying that the messages you think a window is receiving are, in fact, being received. Heap Walker, Profiler, Swap, and Shaker help you analyze memory management. Heap Walker is useful for analyzing your application when it allocates objects in the global heap. Profiler lets you determine the amount of time Windows spends executing sections of code. Swap ets you analyze the calls, swaps, discards, and returns that occur when your application runs. It is useful for minimizing the number of procedure calls that occur across segment boundaries. Shaker lets you see the effect of memory movement on your applications. %@NL@% %@CR:C6A00070001 @%%@1@%%@AB@%Chapter 7 Debugging in Protected Mode: CodeView for Windows%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Version 3.0 of the Microsoft CodeView(R) for Windows (%@AB@%CVW%@AE@%) debugger is a powerful, easy-to-use tool for analyzing the behavior of programs. With %@AB@%CVW%@AE@%, you have the power to test completely the execution of your program and examine your data simultaneously. You can isolate problems quickly because you can display any combination of variables─global or local─%@AI@%while%@AE@% you halt or trace a program's execution.%@CR:C6A00070002 @%%@NL@% The %@AB@%CVW%@AE@% debugger provides a variety of ways to analyze a program. You can use the debugger to examine source code, disassemble machine code, or examine a mixed display that shows you precisely what machine instructions correspond to each of your C-language statements. You can also monitor the occurrence of specific Windows messages. %@NL@% %@AB@%CVW%@AE@% is similar to CodeView (CV) for DOS version 3.0. If you are familiar with CV for DOS, see Section 7.2.2, "Differences between CVW and CodeView for DOS," for a concise description of %@AB@%CVW%@AE@%'s unique features.%@CR:C6A00070003 @%%@CR:C6A00070004 @%%@CR:C6A00070005 @%%@NL@% This chapter serves as a complement to the %@AB@%CVW%@AE@% on-line Help system. A significant portion of the %@AB@%CVW%@AE@% documentation is on-line. For information on using the %@AB@%CVW%@AE@% on-line Help system, see Section 7.7, "Getting On-line Help in %@AB@%CVW%@AE@%." %@NL@% This chapter describes the following: %@NL@% ■ Requirements for using %@AB@%CVW%@AE@%%@NL@% ■ Differences between %@AB@%CVW%@AE@% other Microsoft debuggers%@NL@% ■ Preparing to run %@AB@%CVW%@AE@% %@NL@% ■ Starting %@AB@%CVW%@AE@%%@NL@% ■ Working with the %@AB@%CVW%@AE@% screen%@NL@% ■ Displaying program data%@NL@% ■ Controlling program execution%@NL@% ■ Advanced %@AB@%CVW%@AE@% debugging techniques%@NL@% ■ Customizing %@AB@%CVW%@AE@% behavior with the TOOLS.INI file%@NL@% ■ Using %@AB@%CVW%@AE@% to debug a sample application%@NL@% %@STUB@% %@AI@%NOTE %@AE@%%@AB@%CVW%@AE@% supports the Microsoft Mouse, or any fully compatible pointing device. All operations are first described using the mouse. The keyboard command follows.%@NL@% %@2@%%@CR:C6A00070006 @%%@AB@%7.1 Requirements for Use%@AE@%%@EH@%%@NL@% To use version 3.0 of %@AB@%CVW%@AE@%, your system must meet the standard requirements for running the Microsoft Windows Software Development Kit (SDK). For a list of the SDK requirements, see the %@AI@%Installation and Update Guide%@AE@%. %@AB@%CVW%@AE@% specifically requires the following: %@NL@% ■ A secondary monochrome display adapter and monitor. (%@AB@%CVW%@AE@% version 3.0 does not support a serial terminal.) For IBM PS/2 systems, %@AB@%CVW%@AE@% supports (through the %@AB@%/8%@AE@% option) a dual-monitor configuration, where an 8514/a monitor serves as the Windows screen and a VGA monitor serves as the debugging screen.%@NL@% ■ At least 384K of extended memory. For applications compiled with many symbols, 1 megabyte or more of extended memory is required.%@CR:C6A00070007 @%%@NL@% ■ For 80386-based systems, the following entry in the [386enh] section of your SYSTEM.INI file: %@AS@% device=windebug.386%@AE@% %@NL@% %@STUB@% The SDK %@AB@%INSTALL%@AE@% program automatically adds this entry to your SYSTEM.INI file.%@NL@% ■ A PATH environment variable that lists the directory containing CVW.EXE, WINDEBUG.DLL, WINDEBUG.386, and CVW.HLP. The SDK %@AB@%INSTALL%@AE@% program will place WINDEBUG.DLL and WINDEBUG.386 in the same directory as CVW.EXE.%@NL@% %@2@%%@CR:C6A00070008 @%%@AB@%7.2 Comparing %@AB@%CVW%@AE@% with Other Microsoft Debuggers%@AE@%%@EH@%%@NL@% If you have programmed in the Windows environment, you may have used the Symbolic Debugger %@AB@%(SYMDEB)%@AE@% or %@AB@%CVW%@AE@% version 2.0 to debug Windows applications. Or you may have used CodeView (CV) for DOS, which accompanies the Microsoft C Optimizing Compiler. This section describes the features and functions of %@AB@%CVW%@AE@% that are different from these other Microsoft debugging tools. %@NL@% %@3@%%@CR:C6A00070009 @%%@AB@%7.2.1 Differences between CVW and SYMDEB%@AE@%%@EH@%%@NL@% %@AB@%CVW%@AE@% has all the capabilities of %@AB@%SYMDEB%@AE@% and a number of features that %@AB@%SYMDEB%@AE@% does not provide. The following list summarizes differences between %@AB@%SYMDEB%@AE@% and %@AB@%CVW%@AE@%.%@CR:C6A00070010 @%%@NL@% %@AB@%SYMDEB Feature%@AE@% %@AB@%CVW Feature%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Debugs applications in real Debugs applications in protected mode. mode. Examines only global (static) Examines both global and local variables. variables. When examining variables, you Examines memory directly, but also uses must specify simple memory the C expression evaluators to combine addresses or symbol names. any program variables with higher level-language syntax. Provides only breakpoints to Provides breakpoints, tracepoints, and halt execution. watchpoints to set Boolean conditions and then break execution whenever these conditions become true. Does not set breakpoints or Sets breakpoints and tracepoints on tracepoints on Windows messages. Windows messages. Uses only line-oriented Uses line-oriented or menu-driven commands. commands. ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%%@AB@%CVW%@AE@%%@AI@% version 3.0 supports Windows in protected mode (that is, standard and %@AI@%386 enhanced modes) only; it does not support Windows in real mode. Use %@AI@%%@AE@%%@AI@%%@AB@%SYMDEB%@AE@%%@AE@%%@AI@% for real-mode debugging.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00070011 @%%@AB@%7.2.2 Differences between CVW and CodeView for DOS%@AE@%%@EH@%%@NL@% Like CV for DOS, %@AB@%CVW%@AE@% allows you to display and modify %@AI@%any%@AE@% program variable, section of addressable memory, or processor register. Also like CV for DOS, %@AB@%CVW%@AE@% lets you monitor the path of execution and precisely control where execution pauses. However, CV for DOS and %@AB@%CVW%@AE@% differ in the following ways:%@CR:C6A00070012 @%%@NL@% %@AB@%CV for DOS Feature%@AE@% %@AB@%CVW Feature%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Starts from the DOS prompt. Starts from within Windows. ALT+/ repeats a search. CTRL+R repeats a search. Exits back to DOS. Under normal termination conditions, exits back to Windows. Abnormal terminations of %@AB@%CVW%@AE@% may cause the Windows session to be terminated also. In addition to these differences %@AB@%CVW%@AE@% includes the following unique features: %@NL@% ■ The ability to track your application's segments and data as Windows moves their locations in memory. As items are moved, the debugger readjusts its symbol table accordingly.%@NL@% ■ The %@AB@%(lh)%@AE@% and %@AB@%(gh)%@AE@% type casts, which you can use to dereference local and global handles of a memory object into near and far pointer addresses. For a more detailed description, see "Dereferencing Memory Handles" in Section 7.8.6.%@NL@% ■ Windows-specific commands. %@AB@%CVW%@AE@% has six new commands:%@NL@% %@AB@%Command%@AE@% %@AB@%What it does%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%wdl%@AE@% (Windows Display Local Heap) Displays a list of the memory objects in the local heap. %@AB@%wdg%@AE@% (Windows Display Global Displays a list of the memory objects in Heap) the global heap. %@AB@%wdm%@AE@% (Windows Display Module Displays a list of the application and List) library modules known by Windows. %@AB@%wwm%@AE@% (Windows Watch Message) Displays a Windows message or class of messages in the %@AB@%CVW%@AE@% Command window. %@AB@%wbm%@AE@% (Windows Break Message) Sets a breakpoint on a Windows message or class of messages. %@CR:C6A00070013 @% %@AB@%wka%@AE@% (Windows Kill Application) Terminates the currently executing task. You should use this command with caution. See Section 7.10.4, "Interrupting Your Program," for more information.%@CR:C6A00070014 @% %@2@%%@CR:C6A00070015 @%%@AB@%7.3 Preparing to Run CVW%@AE@%%@EH@%%@NL@% Before beginning a %@AB@%CVW%@AE@% debugging session, you must do the following: %@NL@% ■ Set up a secondary monitor on which to display %@AB@%CVW%@AE@% information.%@NL@% ■ Ensure that the Windows application you are going to debug has been compiled and linked properly.%@NL@% In addition to these mandatory steps, it is also recommended that you set up a debugging version of Windows. %@NL@% The following sections describe how to prepare your system for running %@AB@%CVW%@AE@%. %@NL@% %@3@%%@CR:C6A00070016 @%%@AB@%7.3.1 Setting Up a Secondary Monitor%@AE@%%@EH@%%@NL@% In addition to the graphics adapter card and graphics display monitor required for your Windows display, you need a monochrome adapter card and monochrome display monitor to use %@AB@%CVW%@AE@%.%@CR:C6A00070017 @%%@NL@% To set up a secondary monitor for debugging, do the following: %@NL@% 1. Install a secondary monochrome adapter card in a free slot on your computer and connect the monochrome monitor to the port in the back.%@NL@% 2. Set the secondary-display-adapter switches to the appropriate settings, according to the display adapter and computer manufacturer recommendations.%@NL@% If your system is an IBM PS/2, it must be configured with an 8514/a monitor as the primary monitor, and a VGA as the secondary monitor. To use this configuration, specify the %@AB@%/8%@AE@% (8514/a) option when you choose the Run command from the %@AB@%CVW%@AE@% File menu. If your VGA monitor is monochrome, you must also use the %@AB@%/B%@AE@% (black and white) option. The 8514/a serves as the Windows screen and the VGA as the debugging screen. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% IMPORTANT %@AI@%Do not attempt to run non-Windows applications or the DOS shell while %@AI@%running %@AB@%CVW%@AE@%%@AI@% with the %@AE@%%@AI@%%@AB@%/8%@AE@%%@AE@%%@AI@% option.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% By default, the debugging screen operates in 50-line mode in this configuration. If you specify the %@AB@%/8%@AE@% option, you can optionally specify the %@AB@%/25%@AE@% or %@AB@%/43%@AE@% option for 25- or 43-line mode, respectively, on the VGA debugging screen. %@NL@% With the secondary monitor connected to your system, you can view %@AB@%CVW%@AE@% output and Windows output simultaneously. %@NL@% %@3@%%@CR:C6A00070018 @%%@AB@%7.3.2 Setting Up the Debugging Version of Windows%@AE@%%@EH@%%@NL@% You can run %@AB@%CVW%@AE@% with either the debugging or retail version of Windows. %@NL@% The debugging version performs error checking which is not available in the retail version. For example, the debugging version of Windows checks whether a window handle passed to a Windows function is valid. When the debugging version of Windows detects such an error, it reports a fatal exit. If this happens while you are running %@AB@%CVW%@AE@%, the fatal exit is reported in the %@AB@%CVW%@AE@% Command window. Section 7.11, "Handling Abnormal Termination of the Application," discusses this error handling in greater detail. %@NL@% Another advantage to using the debugging version of Windows with %@AB@%CVW%@AE@% is the additional support which the Windows core dynamic-link libraries (DLLs) (KRNL286.EXE, KRNL386.EXE, GDI.EXE, and USER.EXE) provide for debugging. These DLLs contain symbol information which makes it easier to determine the cause of an error. For example, if your application causes a general protection (GP) fault while running with the debugging version, Windows can display symbol information for the Windows code that was executing when the GP fault was detected. If, instead, you were running with the retail version of Windows, Windows would only be able to display CS:IP address values of the code that was executing when the fault occurred. %@NL@% %@AB@%CVW%@AE@% does not automatically use these Windows core DLL symbols. To provide %@AB@%CVW%@AE@% access to these symbols, you must specify one or more of the core DLLs either using the %@AB@%/L%@AE@% command-line option or in response to the DLL prompt within %@AB@%CVW%@AE@%. If you are running %@AB@%CVW%@AE@% with Windows in standard mode, specify KRNL286.EXE. In 386 enhanced mode, specify KRNL386.EXE. Section 7.4.4, "Starting a Debugging Session for DLLs," explains how to load symbols from a DLL. %@NL@% Installing the debugging version of Windows requires only three simple steps: %@NL@% 1. Rename or copy the KRNL286.EXE, KRNL386.EXE, GDI.EXE, and USER.EXE files located in the Windows system directory. If you accepted the default Windows directory name offered by Windows Setup, the Windows system directory is named \WINDOWS\SYSTEM. %@NL@% 2. Copy the debugging version of these files from the Windows development debugging directory (named \WINDEV\DEBUG by default) to the Windows system directory.%@NL@% 3. Copy the corresponding symbol files from the debugging directory to the system directory.%@NL@% %@3@%%@CR:C6A00070019 @%%@AB@%7.3.3 Preparing Windows Applications for Debugging%@AE@%%@EH@%%@NL@% To prepare a Windows application for use with %@AB@%CVW%@AE@%, take the following steps: %@NL@% 1. Compile your C source code with the %@AB@%/Zi%@AE@% option and, optionally, the %@AB@%/Od%@AE@% options.%@CR:C6A00070020 @%%@NL@% %@STUB@% The %@AB@%/Zi%@AE@% option directs the compiler to produce object files that contain CodeView symbolic information. The %@AB@%/Od%@AE@% option disables the compiler's optimization. If optimization is enabled, the code generated by the compiler does not match as closely the statements in the C source code. Using the %@AB@%/Od%@AE@% option makes debugging easier.%@NL@% %@STUB@% For example:%@NL@% %@AS@% CL -d -c -AS -Gsw -Zpei -Od OUTPUT.C%@AE@% 2. Link your application with the %@AB@%/CO%@AE@% option.%@NL@% %@STUB@% The %@AB@%/CO%@AE@% option directs the linker to produce an executable file that contains CodeView information. This information is used directly by %@AB@%CVW%@AE@%. %@NL@% %@STUB@% Note that no other switches, intermediate files, or programs (such as %@AB@%MAPSYM%@AE@%, used with %@AB@%SYMDEB%@AE@%) are required for %@AB@%CVW%@AE@%. For example:%@NL@% %@AS@% LINK OUTPUT,,,/NOD /CO SLIBW SLIBCEW, OUTPUT.DEF%@AE@% After compiling and linking your application with these options, you can start a %@AB@%CVW%@AE@% debugging session.%@CR:C6A00070021 @%%@NL@% %@2@%%@CR:C6A00070022 @%%@AB@%7.4 Starting a Debugging Session%@AE@%%@EH@%%@NL@% Like most Windows applications, you can start CodeView for Windows several ways. For a complete description of how to start Windows applications, see the %@AI@%Windows User's Guide%@AE@%. To specify %@AB@%CVW%@AE@% options, you must choose the Run command from the File menu in Program Manager. See Section 7.4.5, "Using %@AB@%CVW%@AE@% File Run Options," for more information on %@AB@%CVW%@AE@% options.%@CR:C6A00070023 @%%@NL@% You can run %@AB@%CVW%@AE@% to perform the following tasks: %@NL@% ■ Debug a single application%@NL@% ■ Debug multiple instances of an application%@NL@% ■ Debug multiple applications%@NL@% ■ Debug dynamic-link libraries (DLLs)%@NL@% This section describes the methods you use to perform these tasks, and summarizes the syntax of the Run command in the File menu of %@AB@%CVW%@AE@%. %@NL@% %@3@%%@CR:C6A00070024 @%%@AB@%7.4.1 Starting a Debugging Session for a Single Application%@AE@%%@EH@%%@NL@% After you start %@AB@%CVW%@AE@% from Windows, %@AB@%CVW%@AE@% will display the Command Line dialog box on your secondary monitor. To start debugging a single application: %@NL@% 1. At the Command Line prompt, type the name of the application. If you do not include an extension, %@AB@%CVW%@AE@% assumes the .EXE extension by default. You can also include any arguments that the application recognizes. The following shows the syntax of the command to start debugging a single application:%@NL@% %@STUB@% %@AB@%appname«.EXE» «%@AE@%%@AI@%application_arguments%@AE@%%@AB@%»%@AE@%%@NL@% 2. Press ENTER or click OK.%@NL@% %@STUB@% %@AB@%CVW%@AE@% displays the following prompt:%@NL@% %@AS@% Name any other DLL or executable with debug info:%@AE@% %@STUB@% Since you are debugging only one application and no DLLs, press ENTER or click OK. %@AB@%CVW%@AE@% loads the application and displays the source code for the application's WinMain routine on the debugging screen.%@NL@% 3. Set breakpoints in the code, if you desire.%@NL@% 4. Use the %@AB@%go%@AE@% command to resume execution of the application. %@NL@% If you want to avoid the start-up dialog boxes, you can start %@AB@%CVW%@AE@% more quickly by specifying the application name as an argument in the Run command line, as follows: %@NL@% 1. Choose the Run command from the Windows File menu.%@NL@% 2. Type the application name and any application arguments in the %@AB@%CVW%@AE@% command line. The following shows the syntax of the command line to start debugging a single application:%@NL@% %@STUB@% %@AB@%CVW «%@AE@%%@AI@%cvw_options%@AE@%%@AB@%» appname«.EXE» «%@AE@%%@AI@%application_arguments%@AE@%%@AB@%»%@AE@% %@NL@% 3. Press ENTER or click OK.%@NL@% %@3@%%@CR:C6A00070025 @%%@AB@%7.4.2 Starting a Debugging Session for Multiple Instances of an Application%@AE@%%@EH@%%@NL@% Windows can run multiple instances of an application simultaneously, which can be a potential problem for your application. For example, two instances of an application might interfere with each other, or perhaps one could corrupt the data of the other. %@NL@% To help you solve problems associated with running multiple instances of a program, %@AB@%CVW%@AE@% allows you to debug multiple instances of an application simultaneously. You can determine which instance of an application you are looking at by examining the DS register at any breakpoint.%@CR:C6A00070026 @%%@NL@% To debug multiple instances of an application, perform the following steps: %@NL@% 1. Start %@AB@%CVW%@AE@% as usual for your application.%@NL@% 2. Run one or more additional instances of your application by choosing the Run command from the File menu in Windows. %@NL@% Specifying your application name more than once when starting %@AB@%CVW%@AE@% does not have the effect of loading multiple instances of the application. %@NL@% The breakpoints you set in your application will apply to all instances of the application. To determine which instance of the application has the current focus in %@AB@%CVW%@AE@%, examine the DS register. %@NL@% %@3@%%@CR:C6A00070027 @%%@AB@%7.4.3 Starting a Debugging Session for Multiple Applications%@AE@%%@EH@%%@NL@% You can debug two or more applications at the same time, such as a DDE Client and Server. However, global symbols shared by both applications (such as the symbol name "WINMAIN") are not distinguished. %@AB@%CVW%@AE@% always resolves symbol references to the first application named when you started %@AB@%CVW%@AE@%. %@NL@% Perform the following steps to debug more than one application at the same time: %@NL@% 1. Start %@AB@%CVW%@AE@% as usual for a single application.%@NL@% 2. Provide the name of the second application when %@AB@%CVW%@AE@% displays this prompt: %@AS@% Name any other DLL or executable with debug info:%@AE@% %@NL@% %@STUB@% You %@AI@%must%@AE@% include the .EXE extension of the filename of the second application.%@NL@% 3. Set breakpoints in either or both applications, using the File Open Module command to display the source code for the different modules.%@NL@% 4. Use the %@AB@%go%@AE@% command to continue execution of the first application. %@NL@% 5. Choose the Run command from the File menu in Windows to start execution of the second application.%@NL@% Alternatively, you can use the %@AB@%/L%@AE@% option on the Run command line in %@AB@%CVW%@AE@% to load the symbols for a second application, as shown: %@NL@% %@AS@% cvw /l second.exe first.exe%@AE@% The %@AB@%/L%@AE@% option and the name of the second application must precede the name of the first application on the Run command line. You can repeat the %@AB@%/L%@AE@% option for each application to be included in the debugging session. %@NL@% Once %@AB@%CVW%@AE@% starts, choose the Run command from the File menu in Windows to start execution of the second application. %@NL@% %@3@%%@CR:C6A00070028 @%%@AB@%7.4.4 Starting a Debugging Session for DLLs%@AE@%%@EH@%%@NL@% You can debug one or more DLLs while you are debugging an application. As with multiple applications, global symbols shared by both applications are not distinguished. %@NL@% Perform the following steps to debug a DLL at the same time as an application: %@NL@% 1. Start %@AB@%CVW%@AE@% as usual for the application.%@NL@% 2. Provide the name of the DLL when %@AB@%CVW%@AE@% displays this prompt: %@AS@% Name any other DLL or executable with debug info:%@AE@% %@NL@% %@STUB@% %@AB@%CVW%@AE@% assumes the .DLL extension if you do not supply an extension with the filename. If your DLL has another extension (such as .DRV), you must specify it explicitly.%@NL@% 3. Set breakpoints in either the application or the DLL, using the File Open Module command to display the source code for the different modules.%@NL@% 4. Use the %@AB@%go%@AE@% command to continue execution of the application. %@NL@% Alternatively, you can use the %@AB@%/L%@AE@% option on the %@AB@%CVW%@AE@% File Run command line to specify the DLL, as shown: %@NL@% %@AS@% cvw /l appdll appname.exe%@AE@% The %@AB@%/L%@AE@% option and the name of the DLL must precede the name of the first application on the %@AB@%CVW%@AE@% File Run command line. You can repeat the %@AB@%/L%@AE@% option for each DLL to be included in the debugging session. The .DLL extension is the default extension for the %@AB@%/L%@AE@% option. %@NL@% %@AB@%CVW%@AE@% allows you to debug the LibEntry initialization routine of a DLL. If your application implicitly loads the library, then a special technique is required to debug the LibEntry routine. An application implicitly loads a DLL if the library routines are imported in the application's module-definition (.DEF) file, or if your application imports library routines through an import library when you link the application. An application explicitly loads a DLL by calling the %@AB@%LoadLibrary%@AE@% function. %@NL@% If your application implicitly loads the DLL and you specify the application at the Command Line prompt, %@AB@%CVW%@AE@% automatically loads the DLL and executes the DLL's LibEntry routine when %@AB@%CVW%@AE@% loads the application. This gives you no opportunity to debug the LibEntry routine. To avoid this problem, perform the following steps: %@NL@% 1. Do not provide the name of your application at the Command Line prompt. Instead, provide the name of any "dummy" application which does not implicitly load the library.%@NL@% 2. Enter the name of your DLL, being sure to include the extension if it is not .DLL, at the following prompt: %@AS@% Name any other DLL or executable with debug info:%@AE@% %@NL@% 3. Use the File Open Module command to display the source code for the library module containing the LibEntry routine. Set breakpoints in the LibEntry routine.%@NL@% 4. Use the File Open Module command to display the source code for other library or application modules and set desired breakpoints.%@NL@% 5. Use the %@AB@%go%@AE@% command to start execution of the "dummy" application.%@NL@% 6. Execute your application (that is, the application that implicitly loads the DLL) by choosing the Run command from the File menu in Windows. %@AB@%CVW%@AE@% will resume control when the breakpoint in the LibEntry routine is encountered.%@NL@% Alternatively, you can use the %@AB@%CVW%@AE@% File Run command line to identify the "dummy" application, your application, and the DLL, as shown: %@NL@% %@AS@% cvw /l appdll dummyapp%@AE@% %@3@%%@CR:C6A00070029 @%%@AB@%7.4.5 Using CVW File Run Options%@AE@%%@EH@%%@NL@% Sections 7.4.1 through 7.4.4 illustrated different ways to use the %@AB@%CVW%@AE@% File Run command line. The following shows the general syntax of this command line: %@NL@% %@AS@% CVW «cvw_options» app_name«.EXE» «app_arguments»%@AE@% None of the parameters are case-sensitive. %@NL@% The following list describes these parameters. %@NL@% %@TH: 90 5342 02 15 30 31 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%cvw_options%@AE@% Specifies one or more options that modify how %@AB@%CVW%@AE@% runs. Acceptable options are: Option Purpose %@AB@%/L%@AE@% %@AI@%dll_or_exe%@AE@% Specifies the name of an application or DLL that has been compiled and linked with %@AB@%CVW%@AE@% symbols. %@AB@%CVW%@AE@% assumes the default file extension .DLL if no extension is supplied. You can use the %@AB@%/L%@AE@% option more than once to specify multiple DLLs or executable files. %@AB@%/C%@AE@% %@AI@%command%@AE@% Specifies one or more %@AB@%CVW%@AE@% commands which %@AB@%CVW%@AE@% executes when it loads the application specified by the %@AI@%app_name%@AE@% parameter. The commands must be enclosed in double quotation marks ( " ) and separated with semicolons ( ; ). %@AB@%/M%@AE@% Disables the use of the mouse at the debugging screen. You should use this option when you set breakpoints in code that is responsive to mouse movements on the Windows (application) screen. %@AB@%/TSF%@AE@% Toggles the save state-file status. See Section <NO>7</NO>.5, "Saving Session Information," for details. %@AB@%/8%@AE@% Allows %@AB@%CVW%@AE@% to recognize a dual-monitor configuration. See <NO>7</NO>.3.1, "Setting Up a Secondary Monitor," for more information. %@AB@%/B%@AE@% Specifies a monochrome VGA monitor used as the secondary display with an 8514/a display. This option is valid only in conjunction with the %@AB@%%@AE@% %@AB@%/8%@AE@% option. Option Purpose %@AB@%/25%@AE@% Specifies 25-line mode for the secondary VGA monitor. This option is valid only in conjunction with the %@AB@%/8%@AE@% option. %@AB@%/43%@AE@% Specifies 43-line mode for the secondary VGA monitor. This option is valid only in conjunction with the %@AB@%/8%@AE@% option. %@AB@%/50%@AE@% Specifies 50-line mode for the secondary VGA monitor. This option is valid only in conjunction with the %@AB@%/8%@AE@% option. The %@AB@%/50%@AE@% option is not required, since 50-line mode is the default for the dual-monitor configuration.%@AI@%app_name%@AE@% Specifies the pathname of the application for which %@AB@%%@AE@% %@AB@%CVW%@AE@% will load symbols and issue an initial breakpoint. The .EXE extension is optional.%@AI@%app_arguments%@AE@% Specifies one or more arguments recognized by the application that %@AB@%CVW%@AE@% loads.%@TE: 90 5342 02 15 30 31 @% %@2@%%@CR:C6A00070030 @%%@AB@%7.5 Saving Session Information%@AE@%%@EH@%%@NL@% After your session, %@AB@%CVW%@AE@% stores session information in a file called CURRENT.STS, which is located in the directory pointed to by the INIT environment variable or in the current directory. If this file does not already exist, %@AB@%CVW%@AE@% automatically creates it. Session information includes: %@NL@% ■ CodeView display windows that were opened.%@NL@% ■ Breakpoint locations.%@NL@% CodeView for Windows saves this information, which becomes the default the next time you run a %@AB@%CVW%@AE@% session for that application.%@CR:C6A00070031 @%%@NL@% You can disable this feature by placing the following entry in your TOOLS.INI file: (The default is "y" ─yes.) %@NL@% %@AS@% [cvw] %@AS@% StateFileRead: n%@AE@% The %@AB@%/TSF%@AE@% option temporarily toggles this setting when you run %@AB@%CVW%@AE@%. That is, if TOOLS.INI disables this feature, running %@AB@%CVW%@AE@% with the %@AB@%/TSF%@AE@% option saves session information for that session only. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%If your Windows session abnormally terminates while %@AB@%CVW%@AE@%%@AI@% is running, the %@AI@%CURRENT.STS file may be corrupted. This may cause %@AE@%%@AI@%%@AB@%CVW%@AE@%%@AE@%%@AI@% to fail when it first %@AI@%tries to execute the application you are debugging. If this happens, delete %@AI@%the CURRENT.STS file before attempting to run %@AE@%%@AI@%%@AB@%CVW%@AE@%%@AE@%%@AI@% again.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00070032 @%%@AB@%7.6 Working with the CVW Screen%@AE@%%@EH@%%@NL@% When you start %@AB@%CVW%@AE@%, the %@AB@%CVW%@AE@% menu bar and three display windows─the Local window, the Source window, and the Command window─will appear on your secondary monitor. Figure 7.1 illustrates how the screen appears during a debugging session. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@3@%%@CR:C6A00070033 @%%@AB@%7.6.1 Using CVW Display Windows%@AE@%%@EH@%%@NL@% %@AB@%CVW%@AE@% divides the screen into logically separate sections called display windows, so that a large amount of information can be displayed in an organized and easy-to-read fashion. Each %@AB@%CVW%@AE@% display window is a distinct area on your monitor that operates independently of the other display windows. The name of each display window appears in the top of the window's frame. The following list describes the seven types of %@AB@%CVW%@AE@% display windows:%@CR:C6A00070034 @%%@NL@% %@AB@%CVW Display Window%@AE@% %@AB@%Purpose%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Source window Displays the source code. You can open a second source window to view an include file, another source file, or the same source file at a different location. Command window Accepts debugging commands. Watch window Displays the current values of selected variables. Local window Lists the values of all variables local to the current function or block. Memory window Shows the contents of memory. You can open a second Memory window to view a different section of memory. Register window Displays the contents of the microprocessor's registers, as well as the processor flags. 8087 window Displays the registers of the coprocessor or its software emulator. Help window Displays the Help options or any Help information that you request. %@4@%%@AB@%Opening Display Windows%@AE@%%@EH@%%@NL@% There are two ways to open %@AB@%CVW%@AE@% display windows:%@CR:C6A00070035 @%%@NL@% ■ Choose a window from the View menu. (Note that you can open more than one Source or Memory window.)%@NL@% ■ Perform an operation that automatically opens a window if it is not already open. For example, selecting a Watch variable automatically opens the Watch window.%@NL@% CodeView continually and automatically updates the contents of all its display windows. %@NL@% %@4@%%@AB@%Selecting Display Windows%@AE@%%@EH@%%@NL@% To select a window, click anywhere inside of it. You can also press F6 or SHIFT+F6 to move the focus from one window to the next.%@CR:C6A00070036 @%%@NL@% The selected window is called the "current" window and is marked in three ways: %@NL@% ■ The window's name is displayed in white.%@NL@% ■ The text cursor appears in the window.%@NL@% ■ The vertical and horizontal scroll bars are moved into the window.%@NL@% Typing commands into the Source window causes %@AB@%CVW%@AE@% to temporarily shift its focus to the Command window. Whatever you type is appended to the last line in the Command window. If the Command window is closed, %@AB@%CVW%@AE@% beeps in response to your entry and ignores the input. %@NL@% %@4@%%@AB@%Adjusting Display Windows%@AE@%%@EH@%%@NL@% %@AB@%CVW%@AE@% display windows often contain more information than they can display on the screen. Although you cannot change the relative positions of the display windows, you can manipulate a selected window using the mouse, as follows:%@CR:C6A00070037 @%%@NL@% ■ To scroll the window vertically or horizontally, use the vertical or horizontal scroll bar.%@NL@% ■ To maximize a window so that it fills the screen, click the Up arrow at the right end of the window's top border. To restore the window to its previous size and position, click the Double arrow at the right end of the top border.%@NL@% ■ To change the size of a window: 1. Position the cursor anywhere on the border between two windows.%@NL@% 2. Press and hold down the left mouse button. %@NL@% %@STUB@% Two double arrows will appear on the line.%@NL@% 3. Drag the mouse to enlarge or reduce the window. %@NL@% %@NL@% ■ To remove a window, click the small, dotted box at the left end of the top border. %@NL@% %@STUB@% The adjacent windows automatically expand to recover the empty space.%@NL@% You can also use the following keyboard commands:%@CR:C6A00070038 @%%@NL@% %@AB@%Keyboard Command%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% PAGE UP or PAGE DOWN Scrolls through the text vertically. CTRL+F10 Maximizes a selected display window. CTRL+F8 Changes the size of a selected display window. CTRL+F4 Removes a selected display window. You can also choose the Maximize, Size, and Close commands from the View menu to manipulate a selected display window. %@NL@% The different %@AB@%CVW%@AE@% display windows can help you to conduct a variety of debugging activities simultaneously. These activities are initiated and controlled with %@AB@%CVW%@AE@% debugging commands, which can be typed in the %@AB@%CVW%@AE@% Command window or selected using the %@AB@%CVW%@AE@% menus. %@NL@% %@3@%%@CR:C6A00070039 @%%@AB@%7.6.2 Using the CVW Menu Bar%@AE@%%@EH@%%@NL@% In addition to display windows, the %@AB@%CVW%@AE@% screen includes a menu bar, which contains the following menus:%@CR:C6A00070040 @%%@NL@% %@TH: 154 7674 02 34 42 @%Menu Command%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%File This menu contains the following commands: Open Source opens any text file and reads it into the currently active source window. Open Module opens the source file of any module for which %@AB@%CVW%@AE@% information has been loaded and reads it into the currently active source window. Exit ends your %@AB@%CVW%@AE@% session and returns you to Windows.Edit This menu contains the following commands: Copy copies selected text to the paste buffer Paste inserts text from the paste buffer into the active window at the present cursor location, if that location is valid (for example, text cannot be pasted into the source window).View This menu contains the following commands: Source opens a new Source window. Memory opens a new Memory window. Register acts as a switch to open and close the Register window. 8087 acts as a switch to open and close the 8087 window. Local acts as a switch to open and close the Local window. Watch acts as a switch to open and close the Watch window. Command acts as a switch to open and close the Command window. Help acts as a switch to open and close the Help window. Maximize enlarges the current window so that it fills the screen. Size changes the size of the current window. Close closes the current window.Search%@CR:C6A00070041 @% This menu contains the following commands: Find searches for the next occurrence of a string or a regular expression that you supply in the Find dialog box. Selected Text searches for the next occurrence of a string of selected text. Repeat the Last Find searches for the next occurrence of whatever you specified in the previous Find command. Label/Function searches for a function or label definition in the active Source window and, if one is found, changes the input focus to the active Source window.Run This menu contains the following command: Animate continues the execution of a program while displaying the execution path in the Source window. This type of display is called an "animated trace" display.Watch This menu contains the following commands: Add Watch adds an expression to the Watch window. Delete Watch deletes an expression from the Watch window. Set Breakpoint tells the program where to halt execution; you can set breakpoints on lines of source code, variables and expressions, and Windows messages. Edit Breakpoint performs editing functions on breakpoints; they can be added, removed, modified, enabled or disabled. Quick Watch selects one expression for the Quick Watch window.Options This menu contains the following commands: Source Window sets the display characteristics of the active Source window. Memory Window sets the display characteristics of the active Memory window. Trace Speed sets the speed of program tracing and execution. Case Sensitivity, when turned on, treats uppercase and lowercase letters as different characters. When turned off, it does not differentiate between uppercase and lowercase letters. 386 Instructions, when turned on, recognizes all 80386 instructions in 32-bit values. When turned off, it reads all instructions as 16-bit values Calls The contents and size of this menu change as your program executes. It shows the currently executing routine and the trail of routines from which it was called. Your application must execute, at least, the beginning of the WinMain procedure before %@AB@%CVW%@AE@% will display the current routine. When you select one of the lines in the Calls menu, %@AB@%CVW%@AE@% displays the source code corresponding to the calling location in the active source window.Help This menu contains Help information on various CodeView topics.%@TE: 154 7674 02 34 42 @% For a more detailed description of the %@AB@%CVW%@AE@% menu and commands, refer to %@AB@%CVW%@AE@% Help. %@NL@% %@2@%%@CR:C6A00070042 @%%@AB@%7.7 Getting On-line Help in %@AB@%CVW%@AE@%%@AE@%%@EH@%%@NL@% %@AB@%CVW%@AE@% on-line Help contains detailed information and examples not found in this chapter. You can get on-line help by choosing a command from the Help menu described in the previous section, or selecting an item on your screen and pressing F1. Help is available on items such as commands, menus%@CR:C6A00070043 @%, dialog boxes, and error messages.%@CR:C6A00070044 @%%@NL@% %@2@%%@CR:C6A00070045 @%%@AB@%7.8 Displaying Program Data%@AE@%%@EH@%%@NL@% %@AB@%CVW%@AE@% offers a variety of ways to display program variables, processor registers, and memory. You can also modify the values of all these items as the program executes. This section describes how to display:%@CR:C6A00070046 @%%@NL@% ■ Variables in the Watch window.%@NL@% ■ Expressions in the Watch window.%@NL@% ■ Arrays and structures in the Watch window.%@NL@% ■ A single expression in the Quick Watch window.%@NL@% ■ Windows messages in the Command window.%@NL@% ■ Memory in the Memory window.%@NL@% ■ The contents of registers in the Register window. %@NL@% %@3@%%@CR:C6A00070047 @%%@AB@%7.8.1 Displaying Variables%@AE@%%@EH@%%@NL@% You can use the Watch window to monitor the value of a given variable throughout the execution of your program. For example, %@AB@%do%@AE@%, %@AB@%for%@AE@%, and %@AB@%while%@AE@% loops can cause problems when they don't terminate correctly. By displaying loop variables in the Watch window, you can determine if a loop variable achieves its proper value.%@CR:C6A00070048 @%%@NL@% To add a variable to the Watch window: %@NL@% 1. In the Source window, use the mouse or the DIRECTION keys to position the cursor on the name of the variable you want to watch.%@NL@% 2. Select the Add Watch command from the Watch menu, or press CONTROL+W.%@NL@% %@STUB@% A dialog box will appear with the selected variable's name displayed in the Expression field.%@NL@% 3. Press ENTER or click the OK button to add the variable to the Watch window.%@NL@% %@STUB@% If you want to add a different variable than the one shown in the dialog box, type its name over the one displayed, and then press ENTER.%@NL@% The Watch window appears at the top of the screen. Adding a Watch variable opens the Watch window automatically if it is not already open. %@NL@% When you add a local variable, you may get the following message: %@NL@% %@AS@% Watch Expression Not in Context%@AE@% This message appears when program execution has not yet reached the C function that defines the local variable. Global variables (those declared outside C functions) never cause %@AB@%CVW%@AE@% to display this message; you can watch them from anywhere in the program. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%If you are debugging more than one application or DLL, and if two or more of %@AI@%these contain global variables with the same name, %@AB@%CVW%@AE@%%@AI@% will display the %@AI@%variable of only the first application or DLL containing that variable name. %@AI@%%@AE@%%@AE@% %@AI@%For example, if you are debugging App1 and App2, and both contain a global %@AI@%variable named hInst, %@AB@%CVW%@AE@%%@AI@% will always display the value of hInst in App1, %@AI@%even if %@AE@%%@AI@%%@AB@%CVW%@AE@%%@AE@%%@AI@% stopped at a breakpoint in App2.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% The Watch window will hold as many variables as you like; the quantity is limited only by available memory. You can scroll through the Watch window to position it at those variables you want to view. %@AB@%CVW%@AE@% automatically updates all watched variables as the program runs, including those not currently visible. %@NL@% To remove a variable from the Watch window: %@NL@% 1. Choose the Delete Watch command from the Watch menu.%@NL@% 2. Scroll through the dialog box and select the variable you want to remove.%@NL@% You can also position the cursor on any line in the Watch window and press CONTROL+Y to delete the line.%@CR:C6A00070049 @%%@NL@% %@3@%%@CR:C6A00070050 @%%@AB@%7.8.2 Displaying Expressions%@AE@%%@EH@%%@NL@% You might have noticed that the Add Watch dialog box prompts for an expression, not simply a variable name. You can add any valid combination of variables, constants, or operators as an expression for %@AB@%CVW%@AE@% to evaluate and display in the Watch window.%@CR:C6A00070051 @%%@NL@% The advantage of evaluating expressions is that you can reduce several variables to a single value, which can be easier to interpret than the components that make it up. For example, imagine a %@AB@%for%@AE@% loop with two variables whose ratio is supposed to remain constant. You suspect that one of these variables sometimes takes the wrong value. With (var1 / var2) displayed as an expression in the Watch window, you can easily see when the quotient changes, without having to mentally divide two numbers. %@NL@% You can also display Boolean expressions. For example, if a variable is never supposed to be greater than 100 or less than 25, the expression (var > 100) evaluates to 1 (true) when var goes out-of-bounds. %@NL@% %@3@%%@CR:C6A00070052 @%%@AB@%7.8.3 Displaying Arrays and Structures%@AE@%%@EH@%%@NL@% A program variable is usually a scalar quantity (a single character, integer or floating-point value). The variable appears in the Watch window with the variable name to the left, followed by an equal sign (%@AB@%=%@AE@%), and the current value. The Watch window must provide a different way to display "aggregate" data items, such as arrays and structures.%@CR:C6A00070053 @%%@NL@% Arrays and structures contain multiple values that can be arranged in one or more layers. You can control how these variables appear in the Watch window─whether all, part, or none of their internal structure is displayed. %@NL@% An array initially appears in the Watch window in this form: %@NL@% %@AS@% +Wordholder[] = [...]%@AE@% The brackets indicate that this variable contains more than one element. The plus sign (%@AB@%+%@AE@%) indicates that the variable has more elements than are displayed on the screen. You can expand the variable to display any or all of its components; this technique is called "dereferencing." %@NL@% To dereference (expand) the array, double-click anywhere on the line. You can also position the cursor on the line and press ENTER. For example, if Wordholder is a six-character array containing the word "Basic," the Watch window display changes to: %@NL@% %@AS@% -Wordholder[] %@AS@% [0] = 66 'B' %@AS@% [1] = 97 'a' %@AS@% [2] = 115 's' %@AS@% [3] = 105 'i' %@AS@% [4] = 99 'c' %@AS@% [5] = 0 ''%@AE@% Note that both the individual character values and their ASCII decimal equivalents are listed. The minus sign (-) indicates no further expansion is possible. To contract the array, double-click its line again or position the cursor on the line and press ENTER. %@NL@% %@4@%%@AB@%Displaying Character Arrays%@AE@%%@EH@%%@NL@% If viewing a character array in this form is inconvenient, cast the variable's name to a character pointer by placing the following in front of the name: %@NL@% %@AS@% (char *)%@AE@% The character array is then displayed as a string delimited by apostrophes.%@CR:C6A00070054 @%%@NL@% %@4@%%@AB@%Displaying Multidimensional Arrays%@AE@%%@EH@%%@NL@% You can display arrays with more than one dimension. For example, imagine a 5-by-5 integer array named Matrix, whose diagonal elements are the numbers 1 through 5 and whose other elements are zero. Unexpanded, the array is displayed like this:%@CR:C6A00070055 @%%@NL@% %@AS@% +Matrix[] = [...]%@AE@% Double-clicking Matrix (or pressing ENTER) changes the display to: %@NL@% %@AS@% -Matrix[] %@AS@% +[0][] = [...] %@AS@% +[1][] = [...] %@AS@% +[2][] = [...] %@AS@% +[3][] = [...] %@AS@% +[4][] = [...]%@AE@% The actual values of the elements are not shown yet. You have to descend one more level to see them. For example, to view the elements of the third row of the array, position the cursor anywhere on the +[2] line and press ENTER. The following code shows the third row of the array dereferenced: %@NL@% %@AS@% -Matrix[] %@AS@% +[0][] = [...] %@AS@% +[1][] = [...] %@AS@% -[2][] %@AS@% [0] = 0 %@AS@% [1] = 0 %@AS@% [2] = 3 %@AS@% [3] = 0 %@AS@% [4] = 0 %@AS@% +[3][] = [...] %@AS@% +[4][] = [...]%@AE@% Dereferencing the fifth row (+[4]) of the array produces this display: %@NL@% %@AS@% -Matrix[] %@AS@% +[0][] = [...] %@AS@% +[1][] = [...] %@AS@% -[2][] %@AS@% [0] = 0 %@AS@% [1] = 0 %@AS@% [2] = 3 %@AS@% [3] = 0 %@AS@% [4] = 0 %@AS@% +[3][] = [...] %@AS@% -[4][] %@AS@% [0] = 0 %@AS@% [1] = 0 %@AS@% [2] = 0 %@AS@% [3] = 0 %@AS@% [4] = 5%@AE@% Any element of an array or structure can be independently expanded or contracted; you need not display every element of the variable. If you only want to view one or two elements of a large array, specify the particular array or structure elements in the expression field of the Add Watch dialog box. %@NL@% You can dereference a pointer in the same way as an array or structure. The Watch window will display the pointer address, followed by all the elements of the variable to which the pointer currently refers. You can display multiple levels of indirection (that is, pointers referencing other pointers) simultaneously. %@NL@% %@4@%%@AB@%Displaying Dynamic Array Elements%@AE@%%@EH@%%@NL@% An array may have dynamic elements that change as some other variable changes. Just as you can display a particular element of an array by specifying its subscript, you can also display a dynamic array element, by specifying its variable subscript. For example, suppose that the loop variable p is a subscript for the array variable Catalogprice. The Watch window expression Catalogprice[p] displays only the array element currently specified by the variable p, not the entire array.%@CR:C6A00070056 @%%@NL@% You can mix constant and variable subscripts. For example, the expression BigArray[3][i] displays only the element in the third row of the array to which the index variable i points. %@NL@% %@3@%%@CR:C6A00070057 @%%@AB@%7.8.4 Using the Quick Watch Command%@AE@%%@EH@%%@NL@% Using the Quick Watch command is a convenient way to take a quick look at a variable or expression. Since the Quick Watch window can only display one variable at a time, you would not use it for most of the variables you want to view.%@CR:C6A00070058 @%%@NL@% Selecting the Quick Watch command from the Watch menu (or pressing SHIFT+F9) displays the Quick Watch dialog box. If the text cursor is in the Source, Local, or Watch window, the variable at the current cursor position appears in the dialog box. %@NL@% The Quick Watch display automatically expands arrays and structures to their first level. For example, an array with three dimensions will expand to the first dimension. You can expand or contract an element just as you would in the Watch window; position the cursor on the appropriate line and press ENTER. If the array needs more lines than the Quick Watch window can display, drag the mouse along the scroll bar, or press DOWN ARROW or PAGE DOWN to view the rest of the array. %@NL@% You can add Quick Watch variables to the Watch window. If you decide to add a Quick Watch item to the Watch window, select the Add Watch button. Arrays and structures appear in the Watch window expanded as they were displayed in the Quick Watch box. %@NL@% %@3@%%@CR:C6A00070059 @%%@AB@%7.8.5 Tracing Windows Messages%@AE@%%@EH@%%@NL@% You can trace the occurrence of a Windows message or an entire class of Windows messages by using the %@AB@%wwm%@AE@% (Watch Windows Message) command. %@AB@%CVW%@AE@% will display the messages in the %@AB@%CVW%@AE@% Command window.%@CR:C6A00070060 @%%@NL@% To trace a Windows message or message class, type the %@AB@%wwm%@AE@% command in the Command window. The syntax for the command is: %@NL@% %@AS@% wwm winproc msgname | msgclasses%@AE@% The %@AI@%winproc%@AE@% parameter is the symbol name or address of an application's window function. The %@AI@%msgname%@AE@% parameter is the name of a Windows message, such as WM_PAINT. The %@AI@%msgclasses%@AE@% parameter is a string of characters that identify one or more classes of messages to be traced. The classes are consistent with those defined in the Windows Spy application; they are: %@NL@% %@AB@%Message Class%@AE@% %@AB@%Type of Windows Message%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% m mouse w window management n input s system i initialization c clipboard d DDE z nonclient For example, the following command traces all mouse and input messages sent to MainWndProc: %@NL@% %@AS@% wwm MainWndProc mn%@AE@% The %@AB@%CVW%@AE@% Command window displays Windows messages in the following format: %@NL@% %@AS@% HWND:lc00 wParm:0000 lParm:000000 msg:000F WM_PAINT%@AE@% %@3@%%@CR:C6A00070061 @%%@AB@%7.8.6 Displaying Memory%@AE@%%@EH@%%@NL@% Selecting the Memory command from the View menu opens a Memory window. %@AB@%CVW%@AE@% allows you to have two Memory windows open at one time.%@CR:C6A00070062 @%%@NL@% By default, memory is displayed as hexadecimal byte values, with 16 bytes per line. At the end of each line is a second display of the same memory in ASCII form. Values that correspond to printable ASCII characters (decimal 32 through 127) are displayed in that form. Values outside this range are shown as periods ( . ). %@NL@% Byte values are not always the most convenient way to view memory. If the area of memory you are examining contains character strings or floating-point values, you might prefer to view them in a directly readable form. The Memory Window command of the Options menu displays a dialog box with a variety of display options: %@NL@% ■ ASCII characters%@NL@% ■ Byte, word, or double-word binary values%@NL@% ■ Signed or unsigned integer decimal values%@NL@% ■ Short (32-bit), long (64-bit), or 10-byte (80-bit) floating-point values%@NL@% You can also directly cycle through these display formats by pressing SHIFT+F3. %@NL@% If a section of memory cannot be displayed as a valid floating-point number, the number shown includes the characters NAN (not a number). %@NL@% %@4@%%@AB@%Displaying Local and Global Memory Objects%@AE@%%@EH@%%@NL@% %@AB@%CVW%@AE@% also allows you to display global and local memory objects in their respective Windows heaps. You can display the heap of global memory objects with the %@AB@%wdg%@AE@% (Display Global Heap) command, and the heap of local memory objects with the %@AB@%wdl%@AE@% (Display Local Heap) command. Both of these commands will display the entire heap of global or local memory objects in the Command window.%@CR:C6A00070063 @%%@NL@% For the %@AB@%wdg%@AE@% command, you can specify the single object parameter to display a partial list of the global heap. When you use the single object parameter with the %@AB@%wdg%@AE@% command, the Command window will display the first five memory objects in the global heap, starting at the handle rather than at the beginning of the heap. The following illustrates the output format of the %@AB@%wdg%@AE@% (Display Global Heap) command: %@NL@% %@AS@% " %@AS@% 047E (0A7D) 00000020b MYAPP PRIV MOVEABLE DISCARDABLE %@AS@% %@AS@% 0A6D 00000134b MYAPP DATA FIXED PGLOCKED=0001 %@AS@% %@AS@% 0806 (0805) 00000600b PDB (0465) %@AS@% %@AS@% FREE 000000A0b%@AE@% The following describes the indicated fields: %@NL@% %@TH: 36 1121 01 03 36 37 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%" A global memory handle value. Global memory objects are displayed in the order in which Windows manages them, which is typically not in ascending handle order. A memory selector. This value is not displayed if the selector value is the same as the global handle, as is the case for DATA objects. The length in bytes of the global memory object. The name of the application or library module that allocated the object. The name "PDB" is for Process Descriptor Block. The type of global memory object: Type Meaning PRIV Application or DLL global data, or system object CODE Code segment DATA Data segment of application or DLL FREE Free memory block in the global heap%@TE: 36 1121 01 03 36 37 @% %@TH: 30 976 01 02 37 37 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% One or more of the following combinations of memory allocation attributes: %@AB@%MOVEABLE %@AE@% %@AB@%MOVEABLE DISCARDABLE%@AE@% %@AB@%FIXED%@AE@% The disposition of the object if it is moveable: Disposition Meaning LOCKED=%@AI@%number%@AE@% Number of times the object has been locked with the %@AB@%GlobalLock%@AE@% or %@AB@%%@AE@% %@AB@%LockData%@AE@% functions PGLOCKED=%@AI@%number%@AE@% Number of times Windows has locked the object in its linear address space. The owner handle of the Process Descriptor Block. A free memory block, followed by the size of the free block.%@TE: 30 976 01 02 37 37 @% The following shows the output of the %@AB@%wdl%@AE@% (Display Local Heap) command: %@NL@% %@AS@% " %@AS@% 190A: 000A BUSY (16DA)%@AE@% The following describes the indicated fields: %@NL@% %@TH: 16 482 01 03 36 37 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%" The offset of the local memory object in the local data segment. The length in bytes of the object. One of the following dispositions: Disposition Meaning BUSY Currently allocated FREE A free block in the local heap A local memory handle%@TE: 16 482 01 03 36 37 @% %@4@%%@AB@%Displaying Variables with a Live Expression%@AE@%%@EH@%%@NL@% Section 7.8.4, "Using the Quick Watch Command," explained how to display a specific array element by adding the appropriate expression to the Watch window. It is also possible to watch a particular array element or structure element in the Memory window. This %@AB@%CVW%@AE@% display feature is called a "live expression."%@CR:C6A00070064 @%%@NL@% "Live" means that the area of memory displayed changes to reflect the value of a pointer or subscript. For example, if Buffer is an array and pBuf is a pointer to that array, then *pBuf points to the array element currently referenced. A live expression displays the section of memory beginning with this element. %@NL@% %@AB@%CVW%@AE@% displays live expressions in a Memory window. To create a live expression: %@NL@% 1. Select the Memory Window command from the Options menu.%@NL@% 2. Select the live expression check box and type the name of the element you want to view. %@NL@% %@STUB@% For example, if StrgPtr is a pointer to an array of characters, and you want to see what it currently points to, type:%@NL@% %@AS@% *StrgPtr%@AE@% 3. Click the OK button or press ENTER.%@NL@% A new Memory window opens. The first memory location in the window is the first memory location of the live expression. The section of memory displayed changes to the section the pointer currently references. %@NL@% You can use the Memory Window command of the Options menu to display the value of the live expression in a readable form. This is especially convenient when the live expression represents strings or floating-point values, which are difficult to interpret in hexadecimal form. %@NL@% It is usually more convenient to view an item in the Watch window than as a live expression. However, you might find some items easier to view as live expressions. For example, you can examine what is currently at the top of the stack by specifying SS:SP as the live expression. %@NL@% %@4@%%@AB@%Dereferencing Memory Handles%@AE@%%@EH@%%@NL@% In a Windows application, the %@AB@%LocalLock%@AE@% and %@AB@%GlobalLock%@AE@% functions are used to dereference memory handles into near or far pointers. In a debugging session, you may know the handle of the memory object, but might not know what near or far address it dereferences to, unless you are debugging in an area where the program has just completed a %@AB@%LocalLock%@AE@% and %@AB@%GlobalLock%@AE@% function call. To get the near and far pointer addresses for your local and global handles, use the %@AB@%(lh)%@AE@% and %@AB@%(gh)%@AE@% type casts. For example, you could use %@AB@%(lh)%@AE@% to dereference the array in the following code:%@CR:C6A00070065 @%%@NL@% %@AS@% HANDLE hLocalMem; %@AS@% int near *pnArray; %@AS@% hLocalMem = LocalAlloc(LMEM_MOVEABLE,100); %@AS@% pnArray = LocalLock(hLocalMem); %@AS@% /* load values into the array */ %@AS@% LocalUnlock(hLocalMem);%@AE@% To properly display this array in %@AB@%CVW%@AE@%, you would use the following command: %@NL@% %@AS@% dw (lh)hLocalMem%@AE@% If you set a breakpoint immediately after the %@AB@%LocalLock%@AE@% function, you could find out where the local object was allocated in the application's data segment by looking at the value of the pnArray variable. To display the value of pnArray, use the following %@AB@%CVW%@AE@% command: %@NL@% %@AS@% dw pnArray%@AE@% Note that you cannot rely on the value of pnArray anywhere else in the program because it may change or the memory object may move. %@NL@% If the memory object is a string, you can display it using double type casting, as shown: %@NL@% %@AS@% HANDLE hGlobalMem; %@AS@% LPSTR lpstr; %@AS@% %@AS@% hGlobalMem = GlobalAlloc(GMEM_MOVEABLE, 10L) %@AS@% lpstr = GlobalLock(hGlobalMem); %@AS@% lstrcpy(lpstr,"ABCDEF"); %@AS@% GlobalUnlock(hGlobalMem);%@AE@% You could then display the contents of the string with the following statement: %@NL@% %@AS@% ? *(char far*) (gh)lpstr,s%@AE@% The %@AB@%(gh)%@AE@% type cast will return a pointer to the far address of the global memory object. %@NL@% %@3@%%@CR:C6A00070066 @%%@AB@%7.8.7 Displaying the Contents of Registers%@AE@%%@EH@%%@NL@% Selecting the Register command from the View menu (or pressing F2) opens a window on the right side of the screen. The current values of the microprocessor's registers appear in this window.%@CR:C6A00070067 @%%@NL@% At the bottom of the window are a group of mnemonics representing the processor flags. When you first open the Register window, all values are shown in normal-intensity video. Any subsequent changes are marked in high-intensity video. For example, suppose the overflow flag is not set when the Register window is first opened. The corresponding mnemonic is NV and it appears in normal-intensity video. If the overflow flag is subsequently set, the mnemonic changes to OV and appears in high-intensity video. %@NL@% Selecting the 386 Instructions command from the Options menu displays the registers as 32-bit values. This command is valid only if your computer uses an 80386 processor. Selecting this command a second time changes the registers back to 16-bit values. %@NL@% You can also display the registers of an 8087/287/387 coprocessor in a separate window by selecting the 8087 command from the View menu. If your program uses the coprocessor emulator, the emulated registers are displayed instead. %@NL@% %@3@%%@CR:C6A00070068 @%%@AB@%7.8.8 Displaying Windows Modules%@AE@%%@EH@%%@NL@% The %@AB@%wdm%@AE@% (Dump Modules) command displays a list of all the DLL and task modules that Windows has loaded. For each module, the list shows the module handle, the type of module (DLL or task), the name of the module, and the pathname of the module. %@NL@% %@2@%%@CR:C6A00070069 @%%@AB@%7.9 Modifying Program Data%@AE@%%@EH@%%@NL@% You can easily change the values of variables, memory locations, or registers displayed in the Watch, Local, Memory, Register, or 8087 window. Simply position the cursor at the value you want to change and type in the appropriate value. If you change your mind, press ALT+BACKSPACE to undo the last change you made. %@NL@% The Memory window displays the starting address of each line in segment:offset form. Altering the address automatically shifts the display to the corresponding section of memory. If that section is not used by your program, memory locations are displayed as double question marks (??).%@CR:C6A00070070 @%%@NL@% You can also change the values of memory locations by modifying the right side of the memory display, which shows memory values in ASCII form. For example, to change a byte from decimal 75 to decimal 85, place the cursor over the letter K, which corresponds to the position where the memory value is 75 (K is ASCII 75), and type in U (U is ASCII 85). %@NL@% To change a processor flag, click its mnemonic; or position the cursor on a mnemonic, and then press any key (except TAB or SPACEBAR). Repeat these operations to restore the flag to its previous setting. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% IMPORTANT %@AI@%You should be especially cautious when altering "machine-level" values. The %@AI@%effect of changing a register, flag, or memory location may vary from no %@AI@%effect at all to crashing the operating system. You can alter most items %@AI@%from the Watch window; although sometimes it is useful to modify a register %@AI@%or memory directly.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% One example of altering memory directly would be to replace values in the AX register. C functions return their values through this register. By altering the AX register directly, you can change a returned value without having to execute the function that returns it.%@CR:C6A00070071 @%%@NL@% %@2@%%@CR:C6A00070072 @%%@AB@%7.10 Controlling Program Execution%@AE@%%@EH@%%@NL@% This section describes how you can use %@AB@%CVW%@AE@% to control the execution of your application.%@CR:C6A00070073 @%%@NL@% There are two possible forms of program execution in CodeView for Windows: %@NL@% %@AB@%Program Execution%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Continuous The program executes until either a previously specified "breakpoint" has been reached or the program terminates normally. Single-step The program pauses after each line of code has been executed. %@CR:C6A00070074 @% Sections 7.10.1, "Continuous Execution," and 7.10.2, "Single-Step Execution," explain the most effective way to use each form of execution. Section 7.10.3, "Jumping to a Particular Location," explains how to force the system to jump to a particular location in your program. Section 7.10.4, "Interrupting Your Program," tells you how to interrupt your program. %@NL@% %@3@%%@CR:C6A00070075 @%%@AB@%7.10.1 Continuous Execution%@AE@%%@EH@%%@NL@% Continuous execution lets you quickly execute bug-free sections of code. The simplest way to initiate continuous execution is to click the right mouse button on the line of code you want to debug or examine in more detail. The program executes at full speed up to the start of this line, then pauses. You can do the same thing by positioning the text cursor on this line, then pressing F7.%@CR:C6A00070076 @%%@NL@% You can also pause execution at a specific line of code with a breakpoint. %@AB@%CVW%@AE@% provides you with several types of breakpoints to control your program's execution. The sections that follow describe how to use breakpoints. %@NL@% %@4@%%@AB@%Selecting Breakpoint Lines%@AE@%%@EH@%%@NL@% You can skip over the parts of the program that you don't want to examine by specifying one or more lines as breakpoints. The program executes at full speed up to the first breakpoint, then pauses. Pressing F5 continues program execution up to the next breakpoint, and so on. You can set as many breakpoints as you want, provided that you have available memory.%@CR:C6A00070077 @%%@NL@% There are several ways to set breakpoints: %@NL@% ■ Double-click anywhere on the desired breakpoint line. The selected line is highlighted to show that it is a breakpoint. To remove the breakpoint, double-click on the line a second time.%@NL@% ■ Position the cursor anywhere on the line at which you want execution to pause. Press F9 to select the line as a breakpoint and highlight it. Press F9 a second time to remove the breakpoint and highlighting.%@NL@% ■ Display the Set Breakpoint dialog box by choosing Set Breakpoint from the Watch menu. Choose one of the breakpoint options that permits you to specify a line (location). The line on which the text cursor currently rests is the default breakpoint line in the Location field. If this line is not the location you want, replace it with the line number where you want the breakpoint. When you type in a new line number, make sure that you precede it with a period.%@NL@% A breakpoint line must be a program line that represents executable code. You cannot select a blank line, a comment line, or a declaration line (such as a variable declaration or a preprocessor statement) as a breakpoint.%@CR:C6A00070078 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%By default, Microsoft compilers optimize your code. In the process of %@AI@%optimization, some lines of code may be repositioned or reorganized for more %@AI@%efficient execution. These changes can prevent CodeView from recognizing the %@AI@%corresponding lines of source code as breakpoints. Therefore, it is a good %@AI@%idea to disable optimization during development (use the %@AB@%/Od%@AE@%%@AI@% switch). You %@AI@%can restore optimization once debugging is completed.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% A breakpoint can also be set at a function or an explicit address. To set a breakpoint at a function, simply enter its name in the Set Breakpoint dialog box. To set a breakpoint at an address, enter the address in CS:IP form. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%If you are debugging more than one application or DLL that share names for %@AI@%certain window procedures (such as MainWndProc), you can only refer by name %@AI@%to the procedure that is defined in the first application or DLL.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% You can remove a breakpoint by selecting it in the Source window and pressing F9 or the using the Edit Breakpoints screen of the Watch menu. When your program pauses at a breakpoint, you can continue execution by pressing F5 or clicking the F5 button in the display. %@CR:C6A00070079 @% %@NL@% %@4@%%@AB@%Setting Breakpoint Values%@AE@%%@EH@%%@NL@% Breakpoints are not limited to specific lines of code. %@AB@%CVW%@AE@% can also break execution when an expression reaches a particular value, or just changes value. Use one of the following methods to set a breakpoint value:%@CR:C6A00070080 @%%@NL@% ■ To pause execution when an expression %@AI@%changes%@AE@% value, type the name of the expression in the expression field.%@NL@% ■ To pause execution when a expression %@AI@%reaches%@AE@% a particular value, type an expression that is usually false in the Expression field of the Set Breakpoint dialog box. %@NL@% %@STUB@% For example, if you want to pause when a variable called looptest equals 17, type:%@NL@% %@AS@% looptest == 17. %@AE@% %@STUB@% Execution will halt when this statement becomes true.%@NL@% You can also use the Set Breakpoint dialog box to combine value breakpoints with line breakpoints so that execution stops at a specific line only if an expression has simultaneously reached a particular value, or changed value. %@NL@% For large variables (such as arrays or character strings), you can specify the number of bytes you want checked (up to 32K) in the length field. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%When a breakpoint is tied to a variable, %@AB@%CVW%@AE@%%@AI@% must check the variable's value %@AI@%after each machine instruction is executed. This computational overhead %@AI@%slows execution greatly. For maximum speed when debugging, either tie value %@AI@%breakpoints to specific lines, or only set value breakpoints after you have %@AI@%reached the section of code that needs to be debugged.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@4@%%@AB@%Setting Breakpoints on Windows Messages%@AE@%%@EH@%%@NL@% In the Windows environment, you can also set a breakpoint on a Windows message or an entire class of Windows messages. This feature lets you track your application's response to user input and window-management messages.%@CR:C6A00070081 @%%@NL@% To set a breakpoint on a Windows message or message class, type the %@AB@%wbm%@AE@% (Windows Breakpoint Message) command in the Watch window. The syntax for the command is: %@NL@% %@AS@% wbm winproc msgname | msgclasses%@AE@% The %@AI@%winproc%@AE@% parameter is the symbol name or address of an application's window function. The %@AI@%msgname%@AE@% parameter is the name of a Windows message, such as WM_PAINT. The %@AI@%msgclasses%@AE@% parameter is a string of characters that identify one or more classes of messages. The classes are consistent with those defined in the Windows Spy application; they are: %@NL@% %@AB@%Message Class%@AE@% %@AB@%Type of Windows Message%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% m mouse w window management n input s system %@AB@%Message Class%@AE@% %@AB@%Types of Windows Message%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% i initialization c clipboard d DDE z nonclient For example, if your application is failing to refresh the client area of a window, you might set a breakpoint on the WM_PAINT message so that you can watch your program's behavior. The following command will halt execution whenever the application's MainWndProc function receives a WM_PAINT message: %@NL@% %@AS@% wbm MainWndProc WM_PAINT%@AE@% %@4@%%@AB@%Using Breakpoints%@AE@%%@EH@%%@NL@% Here are several examples that show how breakpoints can help you find the cause of a problem.%@CR:C6A00070082 @%%@NL@% One of the most common bugs is a %@AB@%for%@AE@% loop that executes too many or too few times. If you set a breakpoint that encloses the loop statements, the program pauses after each iteration. With the loop variable or critical program variables in the Watch or Local windows, you can easily see what the loop is doing wrong. %@NL@% You do not have to pause a program the first time you reach a breakpoint. %@AB@%CVW%@AE@% lets you specify the number of times you want to ignore the breakpoint condition before pausing. To specify how many times a breakpoint line is executed: %@NL@% 1. Choose the Set Breakpoint command from the Watch menu.%@NL@% 2. Type the decimal number in the Pass Count field of the dialog box.%@NL@% For example, suppose your program repeatedly calls a function to create a binary tree. You suspect that something goes wrong with the process about halfway through. You could mark the line that calls the function as the breakpoint, then specify how many times this line is to execute before execution pauses. Running the program creates a representative (but unfinished) tree structure that can be examined from the Watch window. You can then continue your analysis using "single-step" execution, which is described in the next section. %@NL@% Another programming error is erroneously assigning a value to a variable. If you enter a variable in the expression field of the Set Breakpoint dialog box, execution will break every time the variable changes value. By evaluating a variable expression, you can halt execution when its value changes unintentionally. %@NL@% Breakpoints are a convenient way to pause the program so that you can assign new values to variables. For example, if a limit value is set by a variable, you can change the value to see if it affects the program's execution. Similarly, you can pass a variety of values to a %@AB@%switch%@AE@% statement to see if they are correctly processed. This ability to alter variables is an especially convenient way to test new functions without having to write a stand-alone test program. %@NL@% When your program reaches a breakpoint and you change a variable, you might want to watch each step execute while you check the value of that variable. You can do this with a %@AB@%CVW%@AE@% technique called "single-stepping." %@NL@% %@3@%%@CR:C6A00070083 @%%@AB@%7.10.2 Single-Step Execution%@AE@%%@EH@%%@NL@% When single-stepping, %@AB@%CVW%@AE@% pauses after each line of code is executed. If a line contains more than one executable statement, %@AB@%CVW%@AE@% executes all the statements on the line before pausing. The next line to be executed is highlighted in reverse video. %@NL@% You can use either the Step function or the Trace function to single-step through a program. Step does not display each function call as the program executes. All the code in the function is executed; but the function appears to execute as a single step. To use Step, press F10. Trace displays each step of every function for which %@AB@%CVW%@AE@% has symbolic information. Each line of the function is executed as a separate step. To use Trace, press F8. (%@AB@%CVW%@AE@% has no symbolic information about run-time functions; therefore, they are executed as a single step.) You can alternate between Trace and Step as you like. The method you use depends on whether you want to see what happens within a particular function.%@CR:C6A00070084 @%%@NL@% You can trace through the program continuously, without having to press F8, by choosing the Animate command from the Run menu. The speed of execution is controlled by the Trace Speed command from the Options menu. You can halt animated execution at any time by pressing any key.%@CR:C6A00070085 @%%@CR:C6A00070086 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%Attempting to step or trace through Windows start-up code while viewing %@AI@%assembly-language listing will cause unpredictable results. To step through %@AI@%your program while viewing assembly-language instructions, first set a %@AI@%breakpoint at the WinMain function and begin stepping through the program %@AI@%only after the breakpoint has been reached.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00070087 @%%@AB@%7.10.3 Jumping to a Particular Location%@AE@%%@EH@%%@NL@% At times you may wish to force the system to jump to a particular location in your program during execution. For example, you might want to avoid executing code that you know has bugs, or you might want to repeatedly execute a particularly troublesome portion of your program. %@NL@% To jump to a specific location in your application: %@NL@% 1. Choose the Source command from the Options menu and select the Mix Source and Assembly and the Show Machine Code options.%@NL@% 2. In the Source window, view the line of source code to which you want to jump.%@NL@% 3. Examine the code offset of the first machine instruction for the assembled statement.%@NL@% 4. Use the %@AB@%rip%@AE@% (Register IP) command to change the IP register to this code offset, supplying the value as a hexadecimal number.%@NL@% %@AB@%CVW%@AE@% highlights the line to which you have jumped. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% IMPORTANT %@AI@%Do not jump from one procedure to another. Jumping from one procedure to %@AI@%another disrupts the stack. %@AE@% %@AI@%When jumping to a specific point in your application, remember that %@AI@%assembled source code for a given statement may rely on memory values and %@AI@%registers set in previous instructions that you have skipped. This is %@AI@%particularly true if you have not disabled optimization by compiling the %@AI@%source module using the %@AB@%-Od%@AE@%%@AI@% option.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00070088 @%%@AB@%7.10.4 Interrupting Your Program%@AE@%%@EH@%%@NL@% There may be times when you want to halt your program immediately. You can force an immediate interrupt of a %@AB@%CVW%@AE@% session by pressing CONTROL+ALT+SYSREQ. You then have the opportunity to change debugging options, such as adding breakpoints and modifying variables. To resume continuous execution, just press F5; to single-step, press F10.%@CR:C6A00070089 @% %@NL@% You should take care when you interrupt the %@AB@%CVW%@AE@% session. For example, if you interrupted the session while Windows code or other system code was executing, attempting to use the Step or Trace functions will produce unpredictable results. When you interrupt the %@AB@%CVW%@AE@% session, it is usually safest to set breakpoints in your code and then resume continuous execution, rather than using Step or Trace. %@NL@% An infinite loop in your code presents a special problem. Again, since you should avoid using Step or Trace after interrupting your program, you should try to locate the loop by setting breakpoints in places you suspect are in the loop. %@NL@% Whether or not you locate the infinite loop, you will have to terminate your application. The %@AB@%wka%@AE@% (Windows Kill Application) command terminates the currently executing task. Since this task is not necessarily your program, you should use the %@AB@%wka%@AE@% command only when your application is the currently executing task. %@NL@% If your application is the currently executing task and is executing a module containing symbol information, the %@AB@%CVW%@AE@% Source window will highlight the current instruction. However, if your application contains modules that were not compiled with the %@AB@%/Zi%@AE@% option, it will be more difficult to determine whether the assembly-language code displayed in the Source window belongs to your application or to another task. In this case, use the %@AB@%wdg%@AE@% (Windows Dump Global Heap) command, supplying the value in the CS register as the parameter. %@AB@%CVW%@AE@% will display a listing that will indicate whether the code segment belongs to your application. If it does, you can use the %@AB@%wka%@AE@% command without affecting other tasks. However, the %@AB@%wka%@AE@% command does not perform all the cleanup tasks associated with the normal termination of a Windows application. For example, GDI objects created during the execution of the program but not destroyed before you terminated the program will remain allocated in the system-wide global heap. This will reduce the amount of memory available during your Windows session. Because of this, you should use the %@AB@%wka%@AE@% command to terminate the application only if you cannot terminate it normally. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The %@AB@%wka%@AE@%%@AI@% command simulates a fatal error in your application. Because of %@AI@%this, when you use the %@AE@%%@AI@%%@AB@%wka%@AE@%%@AE@%%@AI@% command, Windows displays an "Unexpected %@AI@%Application Error" message box. %@AE@%%@AE@% %@AI@%After you close this message box, Windows may not release subsequent mouse %@AI@%input messages from the system queue until you press a key. If this happens, %@AI@%the cursor will move on the Windows screen, but Windows will not appear to %@AI@%respond to the mouse. After you press any key, Windows will then respond to %@AI@%all mouse events that occurred before you pressed the key. %@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00070090 @%%@AB@%7.11 Handling Abnormal Termination of the Application%@AE@%%@EH@%%@NL@% Your application can terminate abnormally in one of two ways while you are debugging it with %@AB@%CVW%@AE@%. It can cause a fatal exit, or it can cause a GP fault. In both cases, %@AB@%CVW%@AE@% regains control, giving you the opportunity to examine the state of the system when your application terminated. In particular, you can often determine the location in your application's code where the error occurred, or which call caused the error. %@AB@%CVW%@AE@% allows you to view registers, dump the global heap, display memory, and examine the source code. %@NL@% Once you have determined where the error occurred, use the %@AB@%q%@AE@% command to terminate %@AB@%CVW%@AE@%. In most cases, control will return to Windows. %@NL@% %@3@%%@CR:C6A00070091 @%%@AB@%7.11.1 Handling a Fatal Exit%@AE@%%@EH@%%@NL@% If the abnormal termination was a fatal exit, and the application was running with the retail version of Windows, the %@AB@%CVW%@AE@% Command window displays the following: %@NL@% %@AS@% Trap 13 (0DH) -- General Protection Fault.%@AE@% The CS:IP register contains an address in the Windows code itself. This small amount of information provides little to help you locate the last call that your application made before the error was detected. %@NL@% If, however, your application was running with the debugging version of Windows, the %@AB@%CVW%@AE@% Command window displays a stack trace that is much more useful for finding the error in your source code. %@NL@% After the stack trace appears in the %@AB@%CVW%@AE@% Command window, Windows displays this prompt: %@NL@% %@AS@% Abort, Break, or Ignore?%@AE@% To locate the cause of the error, press B. This allows %@AB@%CVW%@AE@% to regain control from Windows. %@NL@% In most cases, the stack trace will have scrolled off the top of the %@AB@%CVW%@AE@% Command window, but once %@AB@%CVW%@AE@% regains control, you can scroll it back to examine the entire stack trace. The following information appears at the top of the stack trace: %@NL@% ■ A fatal exit number. See the %@AI@%Reference, Volume 2%@AE@%, for a listing of the possible fatal exit numbers.%@NL@% ■ The CS:IP address or the name of the Windows function where the error was detected, or the name of the last Windows function called before the error was detected. %@NL@% Following this information, additional Windows functions might be listed in the stack trace. Somewhere near the top of the stack trace a CS:IP address will be listed without a Windows function name. In most cases, this is the location in the source code of your application where the call to a Windows function occurred that triggered the fatal exit. %@NL@% To examine this location in your source code, open a Source window if necessary and use the %@AB@%v%@AE@% command followed by the CS:IP address, being sure to precede both the segment and the offset with the "0x" hexadecimal prefix. For example, if %@AB@%CVW%@AE@% indicates that the error occurred at 07DA:0543 in your application, enter the following command: %@NL@% %@AS@% v 0x07DA:0x0543%@AE@% If you had compiled the module where the error occurred using the C Compiler %@AB@% -Zi%@AE@% option, the %@AB@%CVW%@AE@% Source window displays the location in your code where the errant call to a Windows function occurred. %@NL@% The first CS:IP address without a name in the stack trace may point to a location in your code without symbols. For example, the code might be in a DLL you didn't specify with the %@AB@%/L%@AE@% command-line option or at the %@AB@%CVW%@AE@% prompt. Or the address might be in a module that you did not compile with the %@AB@%-Zi%@AE@% option. In such cases, %@AB@%CVW%@AE@% reports that no source code is available. If this happens, continue down the stack trace, using the %@AB@%v%@AE@% command with each unnamed CS:IP address. You likely will find a location in a module that was compiled with the %@AB@%-Zi%@AE@% option, and this location might have made a call into one of your modules which you did not compile using the %@AB@%-Zi%@AE@% option. %@NL@% Section 7.16, "A Sample Session in CVW," shows a sample fatal-exit stack trace and how to use that information to locate an error. %@NL@% %@3@%%@CR:C6A00070092 @%%@AB@%7.11.2 Handling a GP Fault%@AE@%%@EH@%%@NL@% When a GP fault occurs, %@AB@%CVW%@AE@% displays a message in the Command window to notify you of the event. If the GP fault occurred at an instruction in one of your modules, %@AB@%CVW%@AE@% displays the corresponding source code if it had been compiled using the %@AB@%-Zi%@AE@% option. You can obtain information about the chain of calls leading up to the GP fault using the %@AB@%CVW%@AE@% Call menu. This displays a backtrace of calls in the form of a series of segments and offsets, starting at the most recent call. %@NL@% If your application was running with the debugging version of Windows, the backtrace will show window function names next to some of the segment/offset pairs. By examining the window function names, you might be able to determine where in your code the error occurred. %@NL@% %@2@%%@CR:C6A00070093 @%%@AB@%7.12 Ending a CVW Session%@AE@%%@EH@%%@NL@% To terminate a %@AB@%CVW%@AE@% session, use the Exit command in the File menu, or type the %@AB@%q%@AE@% (Quit) command in the Command window.%@CR:C6A00070094 @%%@NL@% %@2@%%@CR:C6A00070095 @%%@AB@%7.13 Restarting a %@AB@%CVW%@AE@% Debugging Session%@AE@%%@EH@%%@NL@% You can terminate your application without terminating %@AB@%CVW.%@AE@% While Windows is terminating the application, it will notify %@AB@%CVW%@AE@%, and %@AB@%CVW%@AE@% will display the following message: %@NL@% %@AS@% Program terminated normally (0)%@AE@% The value in parentheses is the return value of the WinMain function. This value is usually the %@AI@%wParam%@AE@% parameter of the WM_QUIT message, which in turn is the value of the %@AI@%nExitCode%@AE@% parameter passed to the %@AB@%PostQuitMessage%@AE@% function. %@NL@% If you were debugging more than one application or DLL, you can then use the %@AB@%go%@AE@% command to continue the debugging session. You can also restart the application you just terminated by using the %@AB@%go%@AE@% command and then restarting your application through Windows File Manager or Program Manager.%@CR:C6A00070096 @%%@NL@% %@2@%%@CR:C6A00070097 @%%@AB@%7.14 Advanced %@AB@%CVW%@AE@% Techniques%@AE@%%@EH@%%@NL@% Once you are comfortable displaying and changing variables, and controlling the program's execution, you might want to experiment with the following advanced techniques: %@NL@% ■ Using multiple Source windows%@NL@% ■ Calling functions%@NL@% ■ Checking for undefined pointers%@NL@% ■ Handling register variables%@NL@% ■ Redirecting CodeView input and output %@NL@% %@3@%%@CR:C6A00070098 @%%@AB@%7.14.1 Using Multiple Source Windows%@AE@%%@EH@%%@NL@% You can have two Source windows open at the same time. The windows can display two different sections of source code for the same program. They can both track CS:IP addresses; or, one can display a high-level listing and one can display an assembly-language listing. You can move freely between the Source windows, executing a single line of source code or a single assembly instruction at a time.%@CR:C6A00070099 @%%@NL@% %@3@%%@CR:C6A00070100 @%%@AB@%7.14.2 Calling Functions%@AE@%%@EH@%%@NL@% You can call any C function in your program from the Command window or the Watch window. The format for calling C functions is: %@NL@% %@AI@%?funcname (varlist)%@AE@% %@NL@% %@AB@%CVW%@AE@% evaluates the function and displays its returned value in the Command window. %@NL@% The function does not have to be one that is called by your program. You can evaluate any function that is included in the .OBJ parameters specified on the %@AB@%LINK%@AE@% command line.%@CR:C6A00070101 @%%@NL@% This feature allows you to run functions from within %@AB@%CVW%@AE@% that you would not normally include in the final version of your program. For example, you could call a function that checks the integrity of the data structure. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%Directly calling a Windows application procedure or dialog function might %@AI@%have unpredictable results.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00070102 @%%@AB@%7.14.3 Checking for Undefined Pointers%@AE@%%@EH@%%@NL@% Until a pointer has been explicitly assigned a value, its value is undefined. Its value can be completely random, or it can be some consistent value that does not point to a useful data address (such as -1). %@NL@% Accessing a value through an uninitialized pointer address can cause inexplicable or erratic program behavior, because the data is not being read from or written to the intended location. For example, suppose that var1 is mistakenly written to the address specified by an uninitialized pointer, then var2 is also written there. When var1 is read back it does not have its original value, having been overwritten by var2. %@NL@% At present, all Microsoft C static or global near pointers have an uninitialized value of 0. That is, they point to the base address of the data segment. (There is no guarantee, however, that future versions of the Microsoft C Compiler will be the same; C language specifications do not define the value of an uninitialized pointer.) %@NL@% You can take advantage of this consistency. If you specify DS:0 as a breakpoint expression, %@AB@%CVW%@AE@% automatically halts execution if your program attempts to write a nonzero value to a null pointer address. This is an easy way to see whether or not you have initialized all of your pointers.%@CR:C6A00070103 @%%@NL@% %@3@%%@CR:C6A00070104 @%%@AB@%7.14.4 Handling Register Variables%@AE@%%@EH@%%@NL@% A register variable is stored in one of the microprocessor's registers, rather than in RAM. This speeds up access to the variable. %@NL@% There are two ways for a conventional variable to become a register variable. One way is declaring the variable as a register variable. If a register is free, the compiler will store the variable there. The other way occurs during optimization, when the compiler stores an often-used variable (such as a loop variable) in a register to speed up execution.%@CR:C6A00070105 @%%@NL@% Register variables can cause problems when debugging. As with local variables, they are only visible within the function where they are defined. In addition, a register variable might not always be displayed with its current value. %@NL@% In general, it is a good idea to turn off all optimization (using the %@AB@%/Od%@AE@% option when compiling) and to avoid declaring register variables until the program has been fully debugged. Any side effects produced by optimization or register variables can then be easily isolated. %@NL@% %@3@%%@CR:C6A00070106 @%%@AB@%7.14.5 Redirecting %@AB@%CVW%@AE@% Input and Output%@AE@%%@EH@%%@NL@% You can cause %@AB@%CVW%@AE@% to receive input from an input file and generate output to an output file. To redirect %@AB@%CVW%@AE@% input and output, use the %@AB@%CVW%@AE@% start-up command with the %@AB@%/C%@AE@% option as follows:%@CR:C6A00070107 @%%@NL@% %@AS@% CVW /c "<infile; t >outfile" myprog%@AE@% When you redirect input, %@AB@%CVW%@AE@% will execute any commands in %@AI@%infile%@AE@% during start-up. When %@AB@%CVW%@AE@% exhausts all commands in the input file, focus automatically shifts to the Command window. %@NL@% When you redirect output, it is both sent to %@AI@%outfile%@AE@% and echoed to the Command window. The %@AB@%t%@AE@% parameter must precede the %@AB@%>%@AE@% in the command to send output to the Command window. %@NL@% Redirection is a useful way to automate %@AB@%CVW%@AE@% start-up. It also lets you keep a viewable record of command-line input and output, but no record of mouse operations. Some applications (particularly interactive ones) may need modification to allow for redirection of input to the application itself. %@NL@% %@2@%%@CR:C6A00070108 @%%@AB@%7.15 Customizing CVW with the TOOLS.INI File%@AE@%%@EH@%%@NL@% The TOOLS.INI file customizes the behavior and user interface of several Microsoft products. The TOOLS.INI file is a plain ASCII text file. You should place it in a directory pointed to the INIT environment variable. (If you do not use the INIT environment variable, CodeView for Windows only looks for TOOLS.INI in its source directory.)%@CR:C6A00070109 @%%@NL@% The CodeView for Windows section of TOOLS.INI is preceded by the following line: %@NL@% %@AS@% [cvw]%@AE@% Most of the TOOLS.INI customizations control screen colors, but you can also specify start-up commands or the name of the file that receives CodeView for Windows output. The Help system contains full information about all of the TOOLS.INI switches for %@AB@%CVW%@AE@%. %@NL@% %@2@%%@CR:C6A00070110 @%%@AB@%7.16 A Sample Session in %@AB@%CVW%@AE@%%@AE@%%@EH@%%@NL@% The following sample session demonstrates how to use the %@AB@%CVW%@AE@% debugger to examine a Windows application. The session will use the SDK sample application called Output, which writes text and draws three shapes─a rectangle, an ellipse, and a dashed semicircle─on the screen. %@NL@% Before you begin the %@AB@%CVW%@AE@% session, you must prepare the Output application for debugging. Compile and link the Output make file after you make the following changes to the %@AB@%CL%@AE@% and %@AB@%LINK%@AE@% commands: %@NL@% 1. Add the %@AB@%-Zi%@AE@% option to %@AB@%CL%@AE@% command by changing %@AB@%-Zpe%@AE@% to %@AB@%-Zpei%@AE@%, and add the %@AB@%-Od%@AE@% option: %@AS@% CL -c -Gsw -Oas -Zpei -Od OUTPUT.C%@AE@% %@NL@% 2. Add the %@AB@%-Co%@AE@% option to the %@AB@%LINK%@AE@% command: %@AS@% LINK OUTPUT,,,/NOD /CO SLIBCEW LIBW, OUTPUT.DEF%@AE@% %@NL@% After you compile with these options, start Windows and then start a %@AB@%CVW%@AE@% session for Output. See Section 7.4, "Starting a Debugging Session," for more information about starting %@AB@%CVW%@AE@%. To start the %@AB@%CVW%@AE@% session: %@NL@% 1. Choose Run from the File menu in Windows and type the following command in the Run dialog box: %@AS@% CVW%@AE@% %@NL@% %@STUB@% The debugging monitor displays the %@AB@%CVW%@AE@% Start-up dialog box.%@NL@% 2. Type the application name in the %@AB@%CVW%@AE@% Start-up dialog box: %@AS@% OUTPUT%@AE@% %@NL@% %@STUB@% Your debugging monitor displays the DLL dialog box.%@NL@% 3. In this session, you will not be debugging additional DLLs, so leave the command line blank and press ENTER.%@NL@% The %@AB@%CVW%@AE@% menu, the Source window, the Command window, and the Local window appear on the debugging monitor. The Source window displays the source code for Output. Notice its title: %@NL@% %@AS@% source1 CS:IP output.c (ACTIVE)%@AE@% The title indicates that the Source window is the active, or selected, window. %@NL@% Before you start executing the application, set a breakpoint in your source code. For example, you could halt Output after it displays text on the user's screen, but before it draws the rectangle. You know that Output will draw the rectangle in response to a Windows WM_PAINT message, so use the Find command to scan the source code for WM_PAINT. To search for this message: %@NL@% 1. Choose the Find option from the %@AB@%CVW%@AE@% Search menu.%@NL@% %@STUB@% %@AB@%CVW%@AE@% displays the Find dialog box. %@NL@% 2. Type the following on the command line: %@AS@% WM_PAINT%@AE@% %@NL@% %@STUB@% Select the Match Upper/Lower Case checkbox; press ENTER. %@NL@% %@STUB@% %@AB@%CVW%@AE@% finds the first occurrence of "WM_PAINT" in a comment. This is not the location you want. To continue the search:%@NL@% 3. Choose the Repeat Last Find option from the Search menu. %@NL@% %@STUB@% This time the Source window displays the %@AB@%case%@AE@% WM_PAINT: statement. This is the location you were looking for.%@NL@% Within this %@AB@%case%@AE@% statement, find the %@AB@%Rectangle%@AE@% function. Scroll downward through the Source window until you see the following code: %@NL@% %@AS@% Rectangle ( %@AS@% hDC %@AS@% ,nDrawX %@AS@% ,nDrawY %@AS@% ,nDraw + 50 %@AS@% ,nDraw + 30 %@AS@% );%@AE@% Notice that the statement is spread over several lines. To set a breakpoint on a multiline statement, you must position the cursor on the last line of the statement. If you try to set a breakpoint on any other line, %@AB@%CVW%@AE@% will not accept it. To set a breakpoint on this statement: %@NL@% 1. Click the ");" characters─the last line of the statement. %@NL@% %@STUB@% The blinking cursor is now on this line. %@NL@% 2. Choose the Set Breakpoint command on the Options menu, or press F9.%@NL@% %@AB@%CVW%@AE@% displays the line in bold characters to indicate that it is a breakpoint. Also, the Command window displays the following message: %@NL@% %@AS@% Break at: output.c!.297%@AE@% You have two ways to display a list of the breakpoints: %@NL@% ■ You can use the %@AB@%bl%@AE@% command. In the Command window, type: %@AS@% bl%@AE@% %@NL@% %@STUB@% The Command window will display a list of the breakpoint messages. %@NL@% ■ You can use the Edit Breakpoints command on the Watch menu. The Breakpoint dialog box will display a list of breakpoint messages.%@NL@% The message for the breakpoint you just set is: %@NL@% %@AS@% 0) E output.c!.297%@AE@% The following table uses this message to illustrate the format for %@AB@%CVW%@AE@% breakpoint messages: %@NL@% %@AB@%Message Content%@AE@% %@AB@%What it Means%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% 0) Indicates the sequence number of the breakpoint in the Source Code. This is the first breakpoint. E Indicates that the breakpoint is Enabled. output.c!.297 Indicates that the breakpoint is set on line number 297 of the OUTPUT.C source code file. When you are ready to execute the Output application, click in the Command window and type the %@AB@%go%@AE@% command at the prompt: %@NL@% %@AS@% g%@AE@% The Output application will start running and displaying the text on the user's screen (the Windows monitor). While the application is running, Windows has control of the session. When the application reaches the breakpoint line, %@AB@%CVW%@AE@% takes control and halts the application before the line is executed. Notice that the %@AB@%CVW%@AE@% Source window displays the breakpoint line in reverse video to indicate where the application has stopped. %@NL@% At this point, %@AB@%CVW%@AE@% has control of the session. You can use the %@AB@%CVW%@AE@% menus and commands to display values, edit breakpoints, or otherwise modify your debugging session. %@NL@% Instead of resuming continuous execution, single-step through the application as it draws the rectangle on the Windows screen. To execute a single statement, press F10. The Output application draws a rectangle on the screen and then stops. The %@AB@%CVW%@AE@% Source window displays the next statement of code in reverse video: %@NL@% %@AS@% SelectObject(hDC, hGreenBrush);%@AE@% Single-step through the next several statements by pressing F10. As you single-step, the Output application draws each shape on the Windows screen and then Windows passes control of the session back to %@AB@%CVW%@AE@%. You can resume continuous execution at any time by pressing F5. %@NL@% When the application is finished executing, it passes control back to %@AB@%CVW%@AE@%. To terminate %@AB@%CVW%@AE@%, select the Quit option from the File menu. %@NL@% If the application is running and you want to interrupt it and terminate execution: %@NL@% 1. Press CONTROL+ALT+SYSREQ. %@NL@% 2. Select the Quit command from the File menu in %@AB@%CVW%@AE@%.%@NL@% You will be returned to Windows. Your application will continue to run. %@NL@% To see how %@AB@%CVW%@AE@% handles a fatal exit, you will need to introduce a severe error into the code of Output. Replace the %@AI@%hDC%@AE@% parameter of the %@AB@%DrawText%@AE@% function in the WM_PAINT case statement of MainWndProc with (HDC)0. Recompile the application and run %@AB@%CVW%@AE@% to debug the application. %@NL@% When the debugging version of Windows reaches the call to %@AB@%DrawText%@AE@%, it detects an invalid display-context handle and displays in the %@AB@%CVW%@AE@% Command window a stack trace similar to the following: %@NL@% %@AS@% FatalExit code = 0x0000 %@AS@% Stack trace: %@AS@% GDI!_TEXT:VALIDATEHANDLE+0046 %@AS@% GDI!_TEXT:GSV+0018 %@AS@% USER!_WMG:DRAWTEXT+000D %@AS@% 0A35:03E9 %@AS@% USER!_FFFE:INTRNALUPDATEWINDOW+0033 %@AS@% USER!_FFFE:UPDATEWINDOW+0019 %@AS@% 0A35:011E %@AS@% 0A35:0031 %@AS@% 0A35:0629 %@AS@% %@AS@% Abort, Break, or Ignore?%@AE@% The fatal exit code value 0x0000 indicates that an invalid handle was passed to a GDI function. See the %@AI@%Reference, Volume 2%@AE@% for a complete list of fatal exit codes. %@NL@% To locate the cause of the error in your source code, respond to the prompt by pressing B. %@AB@%CVW%@AE@% will then display: %@NL@% %@AS@% Break caused by INT3 in code%@AE@% Find the first CS:IP address without a label. In this case, it is 0A35:03E9. Use the %@AB@%v%@AE@% command with this address, remembering to add the 0x hexadecimal prefix, as shown: %@NL@% %@AS@% v 0x0A35:0x03E9%@AE@% %@AB@%CVW%@AE@% will display source code similar to the following: %@NL@% %@AS@% DrawText ( %@AS@% (HDC)0 %@AS@% , szText %@AS@% , strlen(szText) %@AS@% , &rcTextBox %@AS@% , DT_CENTER |DT_EXTERNALLEADING | DT_NOCLIP %@AS@% | DT_NOPREFIX | DT_WORDBREAK %@AS@% );%@AE@% This is the function call that you changed to cause the fatal exit. %@NL@% %@2@%%@CR:C6A00070111 @%%@AB@%7.17 Summary%@AE@%%@EH@%%@NL@% CodeView for Windows is a tool that lets you debug Windows applications in protected mode. With %@AB@%CVW%@AE@% running on your secondary monitor, you can view and modify program data, and control execution, as you run your Windows application. %@NL@% For information related to CodeView for Windows, see the following: %@NL@% %@AB@%Topic%@AE@% %@AB@%Reference%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Programming Windows applications %@AI@%Guide to Programming%@AE@% System requirements %@AI@%Installation and Update Guide%@AE@% Fatal exit codes %@AI@%Reference, Volume 2%@AE@%: Appendix C, "Windows Debugging Messages" %@AB@%CVW%@AE@% commands CVW on-line Help %@CR:C6A00080001 @%%@1@%%@AB@%Chapter 8 Debugging in Real Mode: Symbolic Debugger%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Microsoft Windows Symbolic Debugger (%@AB@%SYMDEB%@AE@%) is a debugging program that helps you test executable files for applications that run in real mode. To debug applications that run in protected mode, use the Microsoft CodeView for Windows (%@AB@%CVW%@AE@%) debugger. %@AB@% %@AE@%For information on%@AB@% CVW%@AE@%, see Chapter 7,%@AB@% %@AE@% "Debugging in Protected Mode: CodeView for Windows."%@AB@% %@AE@%%@CR:C6A00080002 @%%@AB@% %@AE@%%@CR:C6A00080003 @%%@NL@% %@AB@%SYMDEB%@AE@% lets you refer to data and instructions by name rather than by address. The Symbolic Debugger can access program locations through addresses, global symbols, or line-number references, making it easy to locate and debug specific sections of code. You can debug C programs at the source-file level as well as at the machine level. You can display the source statements of a program, the disassembled machine code of the program, or a combination of source statements and disassembled machine code. %@NL@% Using %@AB@%SYMDEB%@AE@%, you can display and execute program code, set breakpoints that stop the execution of your program, examine and change values in memory, and debug programs that use the floating-point emulation conventions used by Microsoft languages.%@CR:C6A00080004 @%%@NL@% This chapter describes the following topics: %@NL@% ■ Preparing symbol files for an application%@NL@% ■ Setting up the debugging terminal%@NL@% ■ Starting %@AB@%SYMDEB%@AE@% with Windows%@NL@% ■ Working with symbol maps%@NL@% ■ Interpreting %@AB@%SYMDEB%@AE@%'s allocation messages%@NL@% ■ Setting breakpoints and interpreting backtraces%@NL@% ■ Displaying the application's code and viewing its source file%@NL@% The chapter also provides the syntax and description of each %@AB@%SYMDEB%@AE@% command. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%To use the Symbolic Debugger, you must have an extra monochrome card or a %@AI@%serial terminal, or both.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00080005 @%%@AB@%8.1 Preparing Symbol Files%@AE@%%@EH@%%@NL@% Windows applications are difficult to debug without symbolic information about Windows and the application. To take advantage of the Symbolic Debugger's symbolic features, first prepare a symbol file that %@AB@%SYMDEB%@AE@% can use.%@CR:C6A00080006 @%%@CR:C6A00080007 @%%@CR:C6A00080008 @%%@NL@% The steps for setting up a symbol file depend on the method used to create the program. The following sections describe those steps for applications written in C or assembly language. %@NL@% %@3@%%@CR:C6A00080009 @%%@AB@%8.1.1 MAPSYM Program%@AE@%%@EH@%%@NL@% The %@AB@%MAPSYM%@AE@% program creates symbol files for symbolic debugging. The program converts the contents of an application's symbol map (.MAP) file into a form suitable for loading with %@AB@%SYMDEB%@AE@%, copying the result to a symbol (.SYM) file.%@CR:C6A00080010 @%%@CR:C6A00080011 @%%@CR:C6A00080012 @%%@CR:C6A00080013 @%%@NL@% %@4@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% mapsym «{/ | -}l» «{/ | -}n» mapfilename%@AE@% %@AB@%Parameter%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AI@%mapfilename%@AE@% Specifies the filename for a symbol map file that was created during linking. If you do not give a filename extension, .MAP is assumed. If you do not give a full pathname, the current directory and drive are assumed. The %@AB@%MAPSYM%@AE@% program creates a new symbol file having the same name as the map file but with the .SYM extension.%@CR:C6A00080014 @% %@AB@%/l%@AE@% Directs %@AB@%MAPSYM%@AE@% to display information about the conversion on the screen. The information includes the names of groups defined in the program, the program start address, the number of segments, and the number of symbols per segment. %@AB@%/n%@AE@% Directs %@AB@%MAPSYM%@AE@% to ignore line-number information in the map file. The resulting symbol file contains no line-number information. In the following example, %@AB@%MAPSYM%@AE@% uses the symbol information in FILE.MAP to create FILE.SYM on the current drive and directory: %@NL@% %@AS@% mapsym /l file.map%@AE@% Information about the conversion is sent to the screen. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The %@AB@%MAPSYM%@AE@%%@AI@% program always places the new symbol file in the current drive %@AI@%and directory.%@AE@%%@AE@% %@AI@%To create a map file for %@AB@%MAPSYM%@AE@%%@AI@% input, you must specify the %@AE@%%@AI@%%@AB@%/map%@AE@%%@AE@%%@AI@% option when %@AI@%linking. To add line-number information to the map file, specify the %@AI@%appropriate option when compiling, and specify the %@AE@%%@AI@%%@AB@%/linenumbers%@AE@%%@AE@%%@AI@% option when %@AI@%linking.%@AE@%%@AE@% %@AI@%The %@AB@%MAPSYM%@AE@%%@AI@% program can process up to 10,000 symbols for each segment in the %@AI@%application, and up to 1024 segments.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00080015 @%%@AB@%8.1.2 The Incremental Linker%@AE@%%@EH@%%@NL@% Microsoft C version 6.0 includes , the incremental linker (%@AB@%ILINK%@AE@%). %@AB@%ILINK%@AE@% directly creates .SYM files for use by the Symbolic Debugger (%@AB@%SYMDEB%@AE@%). If you use %@AB@%ILINK%@AE@% to link your files and create .SYM files, you do not have to use %@AB@%MAPSYM%@AE@%. %@NL@% For more information on %@AB@%ILINK%@AE@%, see the Microsoft C Optimizing Compiler version 6.0 documentation. %@NL@% %@3@%%@CR:C6A00080016 @%%@AB@%8.1.3 Symbols with C-Language Applications%@AE@%%@EH@%%@NL@% To prepare a symbol file for an application written in the C language, follow these steps:%@CR:C6A00080017 @%%@CR:C6A00080018 @%%@NL@% 1. Compile your source file using the %@AB@%-Zd%@AE@% option to produce line numbers in the object file.%@NL@% %@STUB@% Debugging is easier if you disable the compiler's optimization using the %@AB@%-Od%@AE@% option.%@NL@% 2. Link the object file to produce an executable version of the program by specifying a map filename in the linker's command line and giving the %@AB@%/map%@AE@% and %@AB@%/linenumbers%@AE@% options.%@NL@% %@STUB@% Make sure the map filename is the same as the application's module name given in the module-definition file. %@NL@% 3. Use the %@AB@%MAPSYM%@AE@% program to produce a symbol file. For information about using %@AB@%MAPSYM%@AE@%, see Section 8.1.1, "MAPSYM Program."%@CR:C6A00080019 @%%@NL@% The following example shows how to use symbols with C-language applications: %@NL@% %@AS@% cl -d -c -AS -Gsw -Od -Zdp test.c %@AS@% link test,test,test/map/li,/NOD slibcew slibw, test %@AS@% mapsym test%@AE@% %@3@%%@CR:C6A00080020 @%%@AB@%8.1.4 Symbols with Assembly-Language Applications%@AE@%%@EH@%%@NL@% To prepare symbol files for Windows applications written in assembly language, follow these steps:%@CR:C6A00080021 @%%@CR:C6A00080022 @%%@CR:C6A00080023 @%%@NL@% 1. Make sure that all symbols you might want to use with %@AB@%SYMDEB%@AE@% are declared public.%@NL@% %@STUB@% Segment and group names should not be declared public. They are automatically available for debugging.%@CR:C6A00080024 @%%@CR:C6A00080025 @%%@NL@% 2. Assemble your source file.%@NL@% 3. Link the object file to produce an executable version of the application by specifying a map filename in the linker's command line and giving the %@AB@%/map%@AE@% option.%@NL@% %@STUB@% Make sure the map filename is the same as the application's module name given in the module-definition file. %@NL@% 4. Use the %@AB@%MAPSYM%@AE@% program to create a symbol file. For information about using %@AB@%MAPSYM%@AE@%, see Section 8.1.1, "MAPSYM Program." %@CR:C6A00080026 @%%@NL@% The following is an example of the syntax used when preparing symbol files, written in assembly language, for debugging: %@NL@% %@AS@% masm test; %@AS@% link test,test,test/map,slibw slibc libh,test %@AS@% mapsym test%@AE@% %@2@%%@CR:C6A00080027 @%%@AB@%8.2 Setting Up the Debugging Terminal%@AE@%%@EH@%%@NL@% While it is running, Windows takes complete control of the system console, making debugging through the console impossible. To debug Windows applications, you can either set up a remote terminal connected through the computer's serial port, or set up a secondary monochrome display adapter and monitor.%@CR:C6A00080028 @%%@CR:C6A00080029 @%%@NL@% %@3@%%@CR:C6A00080030 @%%@AB@%8.2.1 Setting Up a Remote Terminal%@AE@%%@EH@%%@NL@% To set up a remote terminal for debugging, follow these steps:%@CR:C6A00080031 @%%@NL@% 1. Select a serial port on your computer and connect a terminal to it. %@NL@% 2. Use the DOS MODE command to set the baud rate and line protocol of the serial port to correct values for use with the terminal.%@NL@% %@STUB@% Line protocol includes the number of stop bits, type of parity checking, and number of transmission bits used by the terminal.%@CR:C6A00080032 @%%@NL@% 3. When you start the Symbolic Debugger, redirect its input and output to the remote terminal using the %@AB@%= =%@AE@% command to specify a communication port.%@NL@% %@STUB@% For example, the following command redirects all subsequent %@AB@%SYMDEB%@AE@% command input and output to COM2:%@NL@% %@AS@% == com2 %@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE Debugging through a remote terminal disables the normal function of the CONTROL+S%@AI@% key combination. Do not use this key combination while debugging %@AI@%Windows %@AI@% %@AI@% %@AI@% %@AI@% %@AI@%%@3@%%@CR:C6A00080035 @%%@AB@%8.2.2 Setting Up a Secondary Monitor%@AE@%%@EH@%%@NL@% To set up a secondary monitor for debugging, follow these steps:%@CR:C6A00080036 @%%@CR:C6A00080037 @%%@CR:C6A00080038 @%%@CR:C6A00080039 @%%@NL@% 1. Install a secondary monochrome display adapter in a free slot of your computer and connect the monochrome monitor to it.%@NL@% 2. Set the secondary display adapter switches to the appropriate settings.%@NL@% %@STUB@% Follow the display adapter and computer manufacturer's recommendations.%@NL@% 3. When you start the Symbolic Debugger, use the %@AB@%/m%@AE@% option to redirect %@AB@%SYMDEB%@AE@% output to the secondary monitor. %@NL@% %@STUB@% %@AI@%NOTE %@AE@%When the %@AB@%/m%@AE@% option is given, the Symbolic Debugger redirects output to the secondary monitor, but continues to use the system keyboard for input until the application being debugged is started. While the application is running, %@AB@%SYMDEB%@AE@% yields complete control of the keyboard to the application. As soon as the application reaches a breakpoint or terminates, %@AB@%SYMDEB%@AE@% reclaims the keyboard and permits user input again.%@CR:C6A00080040 @%%@NL@% %@2@%%@CR:C6A00080041 @%%@AB@%8.3 Starting SYMDEB with Windows%@AE@%%@EH@%%@NL@% To start the Symbolic Debugger with Windows, enter the following %@AB@%SYMDEB%@AE@% command line at the DOS command prompt:%@CR:C6A00080042 @%%@NL@% %@AS@% SYMDEB «options» «symbolfiles» WIN.COM /R «arguments»%@AE@% The %@AI@%options%@AE@% parameter specifies one or more %@AB@%SYMDEB%@AE@% options. The %@AI@%symbolfiles%@AE@% parameter specifies the names of symbol files. The %@AI@%arguments%@AE@% parameter specifies arguments that you want to pass to WIN.COM.%@CR:C6A00080043 @%%@CR:C6A00080044 @%%@NL@% If you want additional symbolic information about Windows, add the full pathname of the debug, the nondebug, or the kernel version of the symbol file, as in the following example: %@NL@% %@AS@% ... ,APP.SYM\WM\DEBUG\GDI.SYM%@AE@% Once started, the Symbolic Debugger displays a start-up message followed by the %@AB@%SYMDEB%@AE@% command prompt (-). When you see the prompt you can enter %@AB@%SYMDEB%@AE@% commands. These commands are described in Section 8.9, "SYMDEB Commands." %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%To set breakpoints in discardable library code in a large frame EMS %@AI@%environment, add the following entry to the [kernel] section of WIN.INI:%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@AS@% [Kernel] %@AS@% EnableEMSDebug=1%@AE@% %@AI@%Adding the entry will slow down debugging.%@AE@% The following section describes the elements of the %@AB@%SYMDEB%@AE@% command line. %@NL@% %@3@%%@CR:C6A00080045 @%%@AB@%8.3.1 Specifying SYMDEB Options%@AE@%%@EH@%%@NL@% You can specify one or more %@AB@%SYMDEB%@AE@% options in the command line. These options control the operation of the Symbolic Debugger. Options must appear before WIN.COM on the command line so that %@AB@%SYMDEB%@AE@% will not interpret them as program arguments.%@CR:C6A00080046 @%%@NL@% The %@AB@%SYMDEB%@AE@% tool has the following command-line options: %@NL@% %@AB@%Option%@AE@% %@AB@%Meaning%@AE@% %@CR:C6A00080047 @% %@CR:C6A00080048 @% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%/m%@AE@% Redirects %@AB@%SYMDEB%@AE@% output to a secondary monochrome monitor and permits debugging of Windows applications without redirecting input and output to a remote terminal. The %@AB@%SYMDEB%@AE@% utility assumes that the necessary display adapter and monitor are installed. %@CR:C6A00080049 @% %@AB@%/x%@AE@% Disables the "more" feature. Unless this option is specified, the Symbolic Debugger automatically stops lengthy output and does not continue the display until the user presses a key. The %@AB@%SYMDEB%@AE@% utility stops the output after displaying enough lines to fill the screen, then prompts the user to continue by displaying the message "[more]". If this option is specified, the Symbolic Debugger continues to display output until the command is completely executed. %@CR:C6A00080050 @% %@CR:C6A00080051 @% %@AB@%Option%@AE@% %@AB@%Meaning%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%/w%@AE@%%@AI@%number%@AE@% Sets the memory-allocation reporting level. The reporting level defines what kind of memory allocation and movement messages the Symbolic Debugger will display when Windows loads and moves program segments. The %@AI@%number%@AE@% parameter specifies the reporting level and can be 0, 1, 2, or 3. Level 0 specifies no reporting. Level 1, the default level if the %@AB@%/w%@AE@% option is not given, generates allocation messages only. Level 2 generates movement messages only. Level 3 generates both allocation and movement messages. See Section 8.6, "Displaying Allocation Messages," for more information about allocation messages. %@CR:C6A00080052 @% %@AB@%/@%@AE@%%@AI@%filename%@AE@% Directs the Symbolic Debugger to load macro definitions from the file specified by %@AI@%filename%@AE@%. Macro definitions define the meaning of the debugger's 10 macro commands. The given file must contain one or more macro definitions in the following form: %@CR:C6A00080053 @% %@CR:C6A00080054 @% %@AB@%m%@AE@%%@AI@%number%@AE@%%@AB@%=%@AE@%%@AI@%command-string%@AE@% Specifies the macro and one or more %@AB@%%@AE@% %@AB@%SYMDEB%@AE@% commands. The %@AI@%number%@AE@% parameter specifies the macro; the %@AI@%command-string%@AE@% parameter specifies commands. %@AB@%/n%@AE@% Permits use of nonmaskable interrupts on non-IBM computers. To use nonmaskable interrupts, you must have a system that is equipped with the proper hardware, such as the following products: %@CR:C6A00080055 @% ■ IBM Professional Debugging Facility ■ Software Probe (Atron Corporation) The %@AB@%SYMDEB%@AE@% utility requires only the hardware provided with these products; no additional software is needed. If you are using one of these products with a non-IBM system, you must use the %@AB@%/n%@AE@% option to take advantage of the break capability. Using a nonmaskable-interrupt break system is more reliable than using the interactive break key because you can always stop program execution regardless of the state of interrupts and other conditions. %@CR:C6A00080056 @%%@CR:C6A00080057 @%%@CR:C6A00080058 @% %@AB@%Option%@AE@% %@AB@%Meaning%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%/i%@AE@%«bm» Directs the Symbolic Debugger to use features available on IBM-compatible computers. The option is not necessary if you have an IBM PC, because %@AB@%SYMDEB%@AE@% automatically checks the hardware on start-up. If %@AB@%SYMDEB%@AE@% does not find that the hardware is an IBM PC, it assumes that the hardware is a generic DOS machine. Without this option, the Symbolic Debugger cannot take advantage of special hardware features such as the IBM 8259 Interrupt Controller, the IBM-style video display, and other capabilities of the IBM basic input and output system (BIOS). %@CR:C6A00080059 @% %@AB@%/f%@AE@%%@AI@%filename%@AE@% Prevents association of the named symbol file with the executable file that has the same name. This option is rarely used and is not recommended for debugging Windows applications. %@AB@%/%@AE@%%@AI@%commands%@AE@% Directs the Symbolic Debugger to execute commands in the %@AI@%commands%@AE@% list immediately after starting. Commands in the list must be separated with semicolons and the entire list must be enclosed in double quotation marks. The slash (/) is required. %@CR:C6A00080060 @% %@CR:C6A00080061 @%%@CR:C6A00080062 @% %@CR:C6A00080063 @% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%You can specify a hyphen instead of a slash for the option designator. You %@AI@%can also use both uppercase and lowercase letters to specify the option.%@CR:C6A00080064 @%%@CR:C6A00080065 @%%@CR:C6A00080066 @%%@CR:C6A00080067 @%%@CR:C6A00080068 @%%@CR:C6A00080069 @%%@AE@% %@AI@%Files containing a hyphen in the filename must be renamed before use with %@AB@%SYMDEB%@AE@%%@AI@%. Otherwise, %@AE@%%@AI@%%@AB@%SYMDEB%@AE@%%@AE@%%@AI@% will interpret the hyphen as an option designator.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00080070 @%%@AB@%8.3.2 Specifying Symbol Files%@AE@%%@EH@%%@NL@% To debug a Windows application symbolically, you should load symbol files for the following items:%@CR:C6A00080071 @%%@CR:C6A00080072 @%%@NL@% ■ The application%@NL@% ■ Windows kernel, user, and GDI (graphics device interface) libraries%@NL@% ■ Other Windows libraries used by the application%@NL@% The symbol file for the application is not required. The symbol files for the Windows libraries are optional, but recommended. They are helpful when trying to trace calls made to routines that are not in the application or to trace window messages.%@CR:C6A00080073 @%%@CR:C6A00080074 @%%@CR:C6A00080075 @%%@CR:C6A00080076 @%%@CR:C6A00080077 @%%@CR:C6A00080078 @%%@CR:C6A00080079 @%%@CR:C6A00080080 @%%@CR:C6A00080081 @%%@CR:C6A00080082 @%%@NL@% You must give the complete filename and extension when naming a symbol file. If the symbol file is not in the current directory, you must supply a full pathname. All symbol files must be specified before the WIN.COM file.%@CR:C6A00080083 @%%@CR:C6A00080084 @%%@NL@% You should always name the application's symbol file before any other symbol files. %@NL@% The following example shows how to specify a symbol file: %@NL@% %@AS@% SYMDEB \APP\TEST.SYM USER.SYM GDI.SYM \APP\TESTLIB.SYM WIN.COM /R%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The Windows symbol files for the kernel, user, and GDI libraries, WIN.COM, %@AI@%USER.SYM, and GDI.SYM, are provided as part of the Microsoft Windows %@AI@%Software Development Kit (SDK).%@AE@% %@AI@%You can create symbol files for other Windows libraries by using the same %@AI@%methods you used to create application symbol files.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00080085 @%%@AB@%8.3.3 Passing the Application to Windows%@AE@%%@EH@%%@NL@% You can pass the name of your application to Windows by placing the full pathname on the %@AB@%SYMDEB%@AE@% command line immediately after the WIN.COM filename. Windows receives the name as an argument when you start WIN.COM from within %@AB@%SYMDEB%@AE@%. Windows uses the name to load and run the application.%@CR:C6A00080086 @%%@CR:C6A00080087 @%%@NL@% The following example shows how to pass an application to Windows: %@NL@% %@AS@% SYMDEB \APP\TEST.SYM WIN.COM /R \APP\TEST.EXE%@AE@% If you do not supply your application's name as an argument, you can load and start your application by starting WIN.COM and using the Windows shell to load the application. %@NL@% %@3@%%@CR:C6A00080088 @%%@AB@%8.3.4 Using SYMDEB Keys%@AE@%%@EH@%%@NL@% The Symbolic Debugger provides a number of special keys for controlling input and output and program execution. The following is a list of these keys:%@CR:C6A00080089 @%%@NL@% %@AB@%Key%@AE@% %@AB@%Action%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% SCROLL LOCK Suspends and restores %@AB@%SYMDEB%@AE@% output. The key is typically used to temporarily stop the output of lengthy displays. To suspend output, press SCROLL LOCK. To restore output, press the key again. %@CR:C6A00080090 @% %@CR:C6A00080091 @% %@CR:C6A00080092 @% %@CR:C6A00080093 @% CONTROL + SYSREQ Generates an immediate breakpoint that halts program execution and returns control to the Symbolic Debugger. (Available on the IBM PC/AT(R) only.) %@CR:C6A00080094 @% %@CR:C6A00080095 @% %@CR:C6A00080096 @% %@CR:C6A00080097 @% %@AB@%Key%@AE@% %@AB@%Action%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% CONTROL + C Cancels the current %@AB@%SYMDEB%@AE@% command. This key combination does not apply to commands that pass execution control to the application being debugged.%@CR:C6A00080098 @%%@CR:C6A00080099 @%%@CR:C6A00080100 @%%@CR:C6A00080101 @% %@2@%%@CR:C6A00080102 @%%@AB@%8.4 Working with Symbol Maps%@AE@%%@EH@%%@NL@% Symbol files that the Symbolic Debugger has loaded for debugging are called symbol maps. The Symbolic Debugger utility lets you examine symbol maps and use the symbols in the maps to set breakpoints and display variables and functions.%@CR:C6A00080103 @%%@CR:C6A00080104 @%%@NL@% Although symbol maps are in memory, %@AB@%SYMDEB%@AE@% allows access to only one symbol map at a time. You can display a list of symbol maps at any time, but to display or use the symbols in a map, you must first open that map. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The Symbolic Debugger requires that the filename of the application's .SYM %@AI@%file be the same as the application's module name (specified in the %@AI@%application's module-definition file). If these names are not identical, the %@AI@%Symbolic Debugger will not be able to determine the correct segment %@AI@%addresses for symbols in the application.%@CR:C6A00080105 @%%@CR:C6A00080106 @%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00080107 @%%@AB@%8.4.1 Listing the Symbol Maps%@AE@%%@EH@%%@NL@% You can display a list of the symbol maps by using the %@AB@%x%@AE@% command with the asterisk (*) argument. The command displays the names of all maps in memory, the name of each segment belonging to a map, and the 16-bit paragraph address of each segment. (The %@AB@%x%@AE@% command without an argument displays only the open map.)%@CR:C6A00080108 @%%@CR:C6A00080109 @%%@CR:C6A00080110 @%%@NL@% For example, type the following to display a list of the symbol maps: %@NL@% %@AS@% -x *%@AE@% The resulting list could look like the following: %@NL@% %@AS@% [ 0000 TEST ] %@AS@% [ 0001 IGROUP ] %@AS@% 0002 DGROUP %@AS@% 0000 TESTLIB %@AS@% 0001 _TEXT %@AS@% 0002 DGROUP%@AE@% The open map name is enclosed in brackets ([ ]). The active segment in the map is also enclosed in brackets. Segment addresses appear immediately before the segment names.%@CR:C6A00080111 @%%@CR:C6A00080112 @%%@CR:C6A00080113 @%%@CR:C6A00080114 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The Symbolic Debugger does not display a segment's actual address until the %@AI@%code or data corresponding to that segment has been loaded. If you list the %@AI@%symbol maps before loading an application, %@AB@%SYMDEB%@AE@%%@AI@% displays low-memory %@AI@%addresses as a warning that the segments are not yet in memory.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% Once an application is loaded, %@AB@%SYMDEB%@AE@% appends a number to the end of the data-segment name in the symbol map. This number shows which instance of the application the data segment belongs to. If you load multiple instances of an application, %@AB@%SYMDEB%@AE@% adds a new data-segment name to the symbol map for that application. %@NL@% In the following example, %@AB@%SYMDEB%@AE@% places parentheses around the active data segment to show which instance of the application is currently running: %@NL@% %@AS@% [ 0000 TEST ] %@AS@% [ 88F0 IGROUP ] %@AS@% ( 87E0 DGROUP ) %@AS@% 8944 DGROUP1%@AE@% %@3@%%@CR:C6A00080115 @%%@AB@%8.4.2 Opening a Symbol Map%@AE@%%@EH@%%@NL@% To access the symbols in a symbol map, you must open the symbol map using the %@AB@%xo%@AE@% command. For example, to open the symbol map named TEST, you would type the following:%@CR:C6A00080116 @%%@CR:C6A00080117 @%%@NL@% %@AS@% -xo test!%@AE@% The Symbolic Debugger opens the symbol map and lets you examine and use symbols from the map.%@CR:C6A00080118 @%%@CR:C6A00080119 @%%@NL@% You can use the %@AB@%xo%@AE@% command to open a different symbol map at any time. %@NL@% %@3@%%@CR:C6A00080120 @%%@AB@%8.4.3 Displaying Symbols%@AE@%%@EH@%%@NL@% You can use the %@AB@%x?%@AE@% command to display the symbols in the open symbol map. The command lists each symbol by name and also gives the symbol's address offset. For example, to display the symbol TestWndProc%@AB@%,%@AE@% type the following:%@CR:C6A00080121 @%%@CR:C6A00080122 @%%@CR:C6A00080123 @%%@NL@% %@AS@% -x? testwndproc%@AE@% The command displays the name and address of the segment to which the symbol belongs, as in the following example: %@NL@% %@AS@% [ 88E0 IGROUP ] %@AS@% 005A TESTWNDPROC%@AE@% The symbol's absolute address can be computed using the segment's address and the symbol's offset. In the preceding example, the function TestWndProc is in the segment IGROUP at address 88E0:005A. %@NL@% If the symbol is an external symbol (for example, a function or variable defined outside of the application), no group name is given and the offset is always zero, as shown in the following example: %@NL@% %@AS@% 0000 SHOWWINDOW%@AE@% You can use the asterisk (*) as a wildcard character with the %@AB@%x%@AE@% command to display more than one symbol at a time. For example, the following command displays all symbols in the IGROUP segment:%@CR:C6A00080124 @%%@CR:C6A00080125 @%%@NL@% %@AS@% -x? igroup:*%@AE@% The following command displays all symbols in the DGROUP segment that begin with an underscore (_): %@NL@% %@AS@% -x? dgroup:_*%@AE@% %@2@%%@CR:C6A00080126 @%%@AB@%8.5 Starting the Application%@AE@%%@EH@%%@NL@% You can start the application by using the %@AB@%g%@AE@% command. The command directs the Symbolic Debugger to pass execution control to the program at the current code address. (Immediately after starting %@AB@%SYMDEB%@AE@% with Windows, the current code address is the start address of the WIN.COM. file.)%@CR:C6A00080127 @%%@CR:C6A00080128 @%%@CR:C6A00080129 @%%@NL@% If you have supplied your application's filename as a WIN.COM argument on the %@AB@%SYMDEB%@AE@% command line, WIN.COM starts your application automatically. Otherwise, it starts the Windows shell, which will load and run your application. %@NL@% %@2@%%@CR:C6A00080130 @%%@AB@%8.6 Displaying Allocation Messages%@AE@%%@EH@%%@NL@% The Symbolic Debugger displays memory-allocation messages to show that Windows has created, freed, or moved memory blocks. The messages are intended to help you locate your application's program code and data in memory. The messages can also be used to see the effect of the application on Windows memory management. The Symbolic Debugger actually displays messages only if the memory-allocation reporting level is set to an appropriate value (see the %@AB@%/w%@AE@% option in Section 8.3.1, "Specifying SYMDEB Options").%@CR:C6A00080131 @%%@CR:C6A00080132 @%%@NL@% When Windows allocates a new block of memory and the reporting level is 1 or 3, the Symbolic Debugger displays a message of the following form: %@NL@% %@AI@%module-name%@AS@%!%@AE@%segment-name=segment-address%@AS@% %@AE@%%@AE@%%@NL@% The %@AI@%module-name%@AE@% field specifies the name of the application or library to receive the allocated memory. The %@AI@%segment-name%@AE@% field specifies the name of the code or data segment within the application or library that will occupy the memory block. The %@AI@%segment-address%@AE@% field specifies the 16-bit paragraph address of the memory block. %@NL@% When Windows moves a block of memory and the reporting level is 2 or 3, the Symbolic Debugger displays a message of the following form: %@NL@% %@AI@%old-address%@AE@% %@AS@%moved to%@AE@% %@AI@%new-address%@AE@% %@NL@% The %@AI@%old-address%@AE@% and %@AI@%new-address%@AE@% fields specify the old and new 16-bit paragraph addresses of the memory block. %@NL@% When Windows frees a block of memory and the reporting level is 1 or 3, the Symbolic Debugger displays a message of the following form: %@NL@% %@AI@%segment-address%@AE@% %@AS@%freed%@AE@% %@NL@% The %@AI@%segment-address%@AE@% field specifies the 16-bit paragraph address of the block to be freed. %@NL@% The following is an example of allocation messages that %@AB@%SYMDEB%@AE@% might display: %@NL@% %@AS@% TEST!IGROUP=886F %@AS@% TEST!DGROUP=8799 %@AS@% GDI!Code=1C32 %@AS@% 8344 moved to 8230 %@AS@% 7C12 freed%@AE@% %@3@%%@CR:C6A00080133 @%%@AB@%8.6.1 Setting Breakpoints with Symbols%@AE@%%@EH@%%@NL@% You can use the %@AB@%bp%@AE@% command and symbols to set breakpoints in your application code even before loading the application. The %@AB@%bp%@AE@% command uses the symbol to compute the instruction address at which to break execution. If the application has not been loaded, %@AB@%SYMDEB%@AE@% sets a virtual breakpoint. A virtual breakpoint has no effect on execution until the application is actually loaded. Once an application is loaded, %@AB@%SYMDEB%@AE@% computes the actual code addresses of all virtual breakpoints and enables the breakpoints.%@CR:C6A00080134 @%%@CR:C6A00080135 @%%@CR:C6A00080136 @%%@CR:C6A00080137 @%%@NL@% For example, to set a breakpoint at the application's WinMain function, you would type the following:%@CR:C6A00080138 @%%@CR:C6A00080139 @%%@NL@% %@AS@% -bp winmain%@AE@% After you set the breakpoint, the application breaks and returns control to %@AB@%SYMDEB%@AE@% when this address is encountered. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%If you do not set breakpoints before starting the application, use an %@AI@%interrupt key to break execution (see Section 8.3.4, "Using SYMDEB Keys," %@AI@%for more information on %@AB@%SYMDEB%@AE@%%@AI@% keys).%@CR:C6A00080140 @%%@CR:C6A00080141 @%%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00080142 @%%@AB@%8.6.2 Displaying Variables%@AE@%%@EH@%%@NL@% You can use the %@AB@%d%@AE@% command to display the content of the application's global variables. The command frequently takes the variable's symbol as an argument and computes the variable's address using the address of the variable's segment and its offset. The symbol map containing the symbol must be open. See Section 8.9, "SYMDEB Commands," for details of arguments to the %@AB@%d%@AE@% command.%@CR:C6A00080143 @%%@CR:C6A00080144 @%%@CR:C6A00080145 @%%@CR:C6A00080146 @%%@CR:C6A00080147 @%%@NL@% When there are multiple instances of the application being debugged, %@AB@%SYMDEB%@AE@% uses the address of the active data segment to compute a variable's address. To display a variable in another instance, supply an absolute segment address. For example, to display the value of %@AI@%hInstance%@AE@% in the first instance, you must first determine the 16-bit paragraph address of the first DGROUP segment by typing the following: %@NL@% %@AS@% -x %@AE@% %@AB@%SYMDEB%@AE@% displays the name and address of each segment in the open map, as in the following example: %@NL@% %@AS@% [ 0000 TEST ] %@AS@% [ 8A12 IGROUP ] %@AS@% 89A0 DGROUP %@AS@% ( 8882 DGROUP1 )%@AE@% Specify the address when typing the %@AB@%d%@AE@% command, as follows: %@NL@% %@AS@% -dw 89A0:hinstance%@AE@% %@AB@%SYMDEB%@AE@% displays the contents of the specified variable, as follows: %@NL@% %@AS@% 88AO:0010 0235 0000 0000 0000 0000 0000 0000 0000%@AE@% %@3@%%@CR:C6A00080148 @%%@AB@%8.6.3 Displaying Application Source Statements%@AE@%%@EH@%%@NL@% You can display the source statements of an application by using the %@AB@%v%@AE@%, %@AB@%s+%@AE@%, and %@AB@%s&%@AE@% commands. The %@AB@%v%@AE@% command displays the source lines of the application beginning with the source line corresponding to the current code address (CS:IP). The %@AB@%s+%@AE@% command directs the Symbolic Debugger to display source lines whenever you use the %@AB@%u%@AE@% command. The %@AB@%s&%@AE@% command directs the Symbolic Debugger to display both source lines and unassembled code whenever you use the %@AB@%u%@AE@% command. For more information on these commands, see Section 8.9, "SYMDEB Commands."%@CR:C6A00080149 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%If a symbol file does not contain line-number information, the %@AB@%v%@AE@%%@AI@%, %@AE@%%@AI@%%@AB@%s+%@AE@%%@AE@%%@AI@%, and %@AE@%%@AI@%%@AB@%s&%@AE@%%@AE@%%@AI@% %@AI@%commands have no effect.%@AE@%%@AE@% %@AI@%If the application source file is not in the current directory, or the file %@AI@%does not have the same name as the symbol file, %@AB@%SYMDEB%@AE@%%@AI@% prompts for the %@AI@%file's correct name and/or pathname.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00080150 @%%@AB@%8.7 Quitting SYMDEB%@AE@%%@EH@%%@NL@% You can terminate %@AB@%SYMDEB%@AE@% at any time by using the %@AB@%q%@AE@% command to return to the DOS prompt. Before quitting %@AB@%SYMDEB%@AE@%, however, you must end the current Windows session and restore the console display to its normal display modes.%@CR:C6A00080151 @%%@CR:C6A00080152 @%%@NL@% Follow these general rules: %@NL@% ■ Use the %@AB@%q%@AE@% command to quit, if you have not started Windows.%@NL@% ■ Open the Windows shell and choose the Close command from its System menu, then use the %@AB@%q%@AE@% command, if you have started Windows and it is still operational. Make sure that all instances of the shell are closed.%@NL@% %@STUB@% %@AI@%IMPORTANT %@AE@%When Windows terminates as a result of a fatal exit, the Symbolic Debugger displays a fatal-exit message and returns the %@AB@%SYMDEB%@AE@% prompt. Do not attempt to restart Windows or quit %@AB@%SYMDEB%@AE@%. You must reboot the system to continue.%@CR:C6A00080153 @%%@CR:C6A00080154 @%%@CR:C6A00080155 @%%@CR:C6A00080156 @%%@NL@% %@2@%%@CR:C6A00080157 @%%@AB@%8.8 SYMDEB Command Overview and Tables%@AE@%%@EH@%%@NL@% This section contains a complete listing of commands that can be used with the Symbolic Debugger. It also describes the arguments and expressions used with %@AB@%SYMDEB%@AE@% commands, as well as predefined names used as register and register-flag names. Table 8.1 is a summary of the syntax and meaning of %@AB@% %@AB@%SYMDEB%@AE@% commands:%@CR:C6A00080158 @%%@NL@% Table 8.1 SYMDEB Commands %@TH: 26 1247 02 38 38 @%Syntax Meaning%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%a %@AE@%«%@AI@%address%@AE@%» Assemble instruction mnemonics%@AB@%ba %@AE@%%@AI@%option size%@AE@% address«%@AI@%value%@AE@%» Set address breakpoint(s) on 80386 «%@AI@%command-string%@AE@%» machines%@AB@%bc %@AE@%%@AI@%id-list%@AE@% Clear breakpoint(s) %@AB@%bd %@AE@%%@AI@%id-list%@AE@% Disable breakpoint(s)%@AB@%be %@AE@%%@AI@%id-list%@AE@% Enable breakpoint(s) %@AB@%bl%@AE@% List breakpoint(s) %@AB@%bp%@AE@%«%@AI@%id%@AE@%» %@AI@%address %@AE@%«%@AI@%value%@AE@%» Set breakpoint(s) «%@AI@%command-string%@AE@%» %@AB@%c %@AE@%%@AI@%range address%@AE@% Compare %@AB@%d %@AE@%«%@AI@%range%@AE@%» Dump memory using previous type %@AB@%da %@AE@%«%@AI@%range%@AE@%» Dump memory ASCII %@AB@%db %@AE@%«%@AI@%range%@AE@%» Dump memory bytes %@TE: 26 1247 02 38 38 @% Table 8.1 SYMDEB Commands (continued) %@TH: 121 5466 02 38 38 @%Syntax Meaning%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%dd %@AE@%«%@AI@%range%@AE@%» Dump memory doublewords %@AB@%df%@AE@% Display list of global free blocks%@AB@%dg%@AE@% Display global heap %@AB@%dh%@AE@% Display local heap for current data segment register%@AB@%%@AE@%%@AB@%dl %@AE@%«%@AI@%range%@AE@%» Dump memory, long floating point %@AB@%dm%@AE@% Display list of loaded modules%@AB@%dq%@AE@% Dump list of current tasks, their SS:BP, CS:IP, nEvents, priority, module name, and queue handle%@AB@%ds %@AE@%«%@AI@%range%@AE@%» Dump memory, short floating point %@AB@%dt %@AE@%«%@AI@%range%@AE@%» Dump memory 10-byte reals %@AB@%du%@AE@% Display LRU list%@AB@%dw %@AE@%«%@AI@%range%@AE@%» Dump memory words %@AB@%e %@AE@%%@AI@%address %@AE@%«%@AI@%value%@AE@%» Enter using previous type %@AB@%ea %@AE@%%@AI@%address %@AE@%«%@AI@%value%@AE@%» Enter ASCII %@AB@%eb %@AE@%%@AI@%address %@AE@%«%@AI@%value%@AE@%» Enter bytes %@AB@%ed %@AE@%%@AI@%address %@AE@%«%@AI@%value%@AE@%» Enter doublewords %@AB@%el %@AE@%%@AI@%address %@AE@%«%@AI@%value%@AE@%» Enter long floating point %@AB@%es %@AE@%%@AI@%address %@AE@%«%@AI@%value%@AE@%» Enter short floating point %@AB@%et %@AE@%%@AI@%address %@AE@%«%@AI@%value%@AE@%» Enter 10-byte reals %@AB@%ew %@AE@%%@AI@%address %@AE@%«%@AI@%value%@AE@%» Enter words %@AB@%f %@AE@%%@AI@%range list%@AE@% Fill %@AB@%g %@AE@%«= %@AI@%startaddress %@AE@%» «%@AI@%breakaddress%@AE@%»... Go %@AB@%h %@AE@%%@AI@%value1 value2%@AE@% Add hexadecimal command%@AB@%i %@AE@%%@AI@%value%@AE@% Input from port %@AB@%k %@AE@%«%@AI@%value%@AE@%» Backtrace stack %@AB@%kt %@AE@%%@AI@%pdb %@AE@%«%@AI@%value%@AE@%» Backtrace task %@AB@%kv %@AE@%«%@AI@%value%@AE@%» Annotate each stack frame with the associated frame pointer value%@AB@%l %@AE@%«%@AI@%address %@AE@%«%@AI@%drive record count%@AE@%» » Load %@AB@%m %@AE@%%@AI@%range address%@AE@% Move %@AB@%m%@AE@%%@AI@%id%@AE@%«= %@AI@%command-string%@AE@%» Define or execute macro %@AB@%n %@AE@%«%@AI@%filename%@AE@%»«%@AI@%arguments%@AE@%» Set name %@AB@%o %@AE@%%@AI@%value byte%@AE@% Output to port %@AB@%p %@AE@%«= %@AI@%startaddress%@AE@%» «%@AI@%value%@AE@%» Trace program instruction or call%@AB@%q%@AE@% Quit %@AB@%r %@AE@%«%@AI@%register%@AE@%» « «= » %@AI@%value%@AE@%» Register %@AB@%s %@AE@%%@AI@%range list%@AE@% Search %@AB@%s-%@AE@% Set machine debugging only %@AB@%s&%@AE@% Set machine and source debugging %@AB@%s+%@AE@% Set source debugging only %@AB@%t %@AE@%«= %@AI@%startaddress%@AE@%» «%@AI@%value%@AE@%» Trace program instruction %@AB@%u %@AE@%«%@AI@%range%@AE@%» Display unassembled instructions %@AB@%v %@AE@%%@AI@%range%@AE@% View source lines %@AB@%w %@AE@%«%@AI@%address %@AE@%«%@AI@%drive record count%@AE@%» » Write to disk or file %@AB@%x %@AE@%«*| ?» %@AI@%symbol%@AE@% Examine symbol(s) %@AB@%xo %@AE@%«%@AI@%symbol%@AE@%!» Open symbol map/segment %@AB@%z %@AE@%%@AI@%symbol value%@AE@% Set symbol value %@AB@%?%@AE@% Display list of %@AB@%SYMDEB%@AE@% commands and operators%@AB@%? %@AE@%%@AI@%expression%@AE@% Compute and display expression %@AB@%.%@AE@% Display current source line %@AB@%< %@AE@%%@AI@%filename%@AE@% Redirect %@AB@%SYMDEB%@AE@% input %@AB@%> %@AE@%%@AI@%filename%@AE@% Redirect %@AB@%SYMDEB%@AE@% output %@AB@%= = f%@AE@%%@AI@%ilename%@AE@% Redirect %@AB@%SYMDEB%@AE@% input and output { %@AI@%filename%@AE@% Redirect program input } %@AI@%filename%@AE@% Redirect program output %@AB@%~ %@AE@%%@AI@%filename%@AE@% Redirect program input and output %@AB@%! %@AE@%«%@AI@%dos-command%@AE@%» Shell escape %@AB@%* %@AE@%%@AI@%comment%@AE@% Comment %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 121 5466 02 38 38 @% Any combination of uppercase and lowercase letters may be used in commands and arguments. If a command uses two or more parameters, separate them with a single comma (,) or one or more spaces.%@CR:C6A00080159 @%%@NL@% The following provides examples of %@AB@%SYMDEB%@AE@% commands: %@NL@% %@AS@% ds _avg L 10 %@AS@% U .22 %@AS@% f DS:100,110 ff,fe,01,00%@AE@% For complete information about command syntax, see Section 8.9, "SYMDEB Commands." %@NL@% %@3@%%@CR:C6A00080160 @%%@AB@%8.8.1 Command Arguments%@AE@%%@EH@%%@NL@% Command arguments are numbers, symbols, line numbers, or expressions used to specify addresses or values to be used by %@AB@%SYMDEB%@AE@% commands. The following is a list of argument syntax and meaning:%@CR:C6A00080161 @%%@CR:C6A00080162 @%%@CR:C6A00080163 @%%@NL@% %@AB@%Argument%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AI@%address%@AE@% Specifies absolute, relative, or symbolic address of a variable or function. The Symbolic Debugger permits a wide variety of address types. See Section 8.8.2, "Address Arguments," for a complete description of address arguments. %@AI@%byte%@AE@% Specifies a %@AI@%value%@AE@% argument representing a byte value. It must be within the range 0 to 255. %@AI@%command-string%@AE@% Specifies one or more %@AB@%SYMDEB%@AE@% commands. If more than one command is given, they must be separated by semicolons (;). %@AI@%count%@AE@% Specifies a %@AI@%value%@AE@% argument representing the number of disk records to read or write. %@AI@%dos-command%@AE@% Specifies a DOS command. %@AI@%drive%@AE@% Specifies a %@AI@%value%@AE@% argument representing a disk drive. Drives are numbered 0 for A, 1 for B, 2 for C, and so on. %@AI@%expression%@AE@% Specifies a combination of arguments and operators that represents a single value or address. See Section 8.8.3, "Expressions," for a list and explanation of expression operators. %@AI@%filename%@AE@% Specifies the name of a file or a device. The filename must follow the DOS filenaming conventions. %@AI@%id%@AE@% Specifies a decimal number representing a breakpoint or macro identifier. The number must be within the range 0 to 9. %@AB@%Argument%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AI@%id-list%@AE@% Specifies one or more unique decimal numbers representing a list of breakpoint identifiers. The numbers must be within the range 0 to 9. If more than one number is given, they must be separated using spaces or commas. The wildcard character (*) can be used to specify all breakpoints. %@CR:C6A00080164 @% %@AI@%list%@AE@% Specifies one or more %@AI@%value%@AE@% arguments. The values must be within the range 0 to 65,535. If more than one value is given, they must be separated using spaces or commas. A %@AI@%list%@AE@% can also be specified as a list of ASCII values. The list can contain any combination of characters and must be enclosed in either single or double quotation marks. If the enclosing mark appears within the list, it must be given twice. %@AI@%range%@AE@% Specifies an address range. Address ranges have two forms: a start and end address pair, and a start address and object count. The first form consists of two %@AI@%address%@AE@% arguments, the first specifying the start address and the second specifying the end address. The second form consists of an %@AI@%address%@AE@% argument, the letter %@AB@%l%@AE@%, and a %@AI@%value%@AE@% argument. The %@AI@%address%@AE@% specifies the starting address; the %@AI@%value%@AE@% specifies the number of objects after the address to examine or display. The size of an object depends on the command. If a command requires a %@AI@%range%@AE@% but only a start address is given in the command, the command assumes the range has an object count of 128. This default count does not apply to commands that require a range followed immediately by a %@AI@%value%@AE@% or an address argument. %@AI@%record%@AE@% Specifies a %@AI@%value%@AE@% argument representing the first disk record to be read or written to. %@CR:C6A00080165 @% %@CR:C6A00080166 @%%@CR:C6A00080167 @% %@AI@%register%@AE@% Specifies the name of a CPU register. It can be any one of the following: %@TH: 5 185 01 04 04 04 64 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%AX CX ES SIBP DI F SPBX DS IP SSCS DX PC%@TE: 5 185 01 04 04 04 64 @% The names IP and PC refer to the same register: the instruction pointer. The name F is a special name for the flags register. Each flag within the flags register has a unique name based on its value. These names can be used to set or clear the flag. Table 8.2 lists the flag names: %@NL@% Table 8.2 Flag Values %@TH: 12 730 02 17 16 43 @%Flag Set Clear%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Overflow ov nvDirection dn (decrement)%@AB@%%@AE@% up (increment)%@AB@%%@AE@% %@AB@%%@AE@% Interrupt ei (enabled)%@AB@%%@AE@% di (disabled)%@AB@%%@AE@%Sign ng (negative)%@AB@%%@AE@% pl (positive)%@AB@%%@AE@%Zero zr nzAuxiliary Carry ac naParity pe (even)%@AB@%%@AE@% po (odd)%@AB@%%@AE@%Carry cy nc%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 12 730 02 17 16 43 @% %@AB@%Argument%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AI@%symbol%@AE@% Identifies the address of a variable, function, or segment. A symbol consists of one or more characters, but always begins with a letter, underscore (_), question mark (?), at symbol (@), or dollar sign ($). Symbols are available only when the .SYM file that defines their names and values has been loaded. Any combination of uppercase and lowercase letters can be used; %@AB@%SYMDEB%@AE@% is not case-sensitive. For some commands, the wildcard character (*) may be used as part of a symbol to represent any combination of characters. %@CR:C6A00080168 @%%@CR:C6A00080169 @%%@CR:C6A00080170 @%%@CR:C6A00080171 @%%@CR:C6A00080172 @%%@CR:C6A00080173 @%%@CR:C6A00080174 @%%@CR:C6A00080175 @%%@CR:C6A00080176 @% %@CR:C6A00080177 @%%@CR:C6A00080178 @%%@CR:C6A00080179 @%%@CR:C6A00080180 @% %@AI@%pdb%@AE@% Specifies a %@AI@%value%@AE@% argument representing the segment address of a program descriptor block. %@AI@%value%@AE@% Specifies an integer number in binary, octal, decimal, or hexadecimal format. A value consists of one or more digits optionally followed by a radix: Y for binary, O or Q for octal, T for decimal, or H for hexadecimal. If no radix is given, hexadecimal is assumed. %@AB@%SYMDEB%@AE@% truncates leading digits if the number is greater than 65,535. Leading zeros are ignored. Hexadecimal numbers have precedence over symbols, thus FAA is a number. %@3@%%@CR:C6A00080181 @%%@AB@%8.8.2 Address Arguments%@AE@%%@EH@%%@NL@% Address arguments specify the location of variables and functions. The following list explains the syntax and meaning of the various addresses used in %@AB@%SYMDEB%@AE@%: %@CR:C6A00080182 @% %@CR:C6A00080183 @% %@CR:C6A00080184 @%%@NL@% %@AB@%Syntax%@AE@% %@AB@%Meaning%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AI@%segment%@AE@%%@AB@%:%@AE@%%@AI@%offset%@AE@% Specifies an absolute address. A full address has both a %@AI@%segment%@AE@% address and an %@AI@%offset%@AE@%, separated by a colon (:). A partial address is just an %@AI@%offset%@AE@%. In both cases, the %@AI@%segment%@AE@% or %@AI@%offset%@AE@% can be any number, register name, or symbol. If no %@AI@%segment%@AE@% is given, the %@AB@%a%@AE@%, %@AB@%g%@AE@%, %@AB@%l%@AE@%, %@AB@%p%@AE@%, %@AB@%t%@AE@%, %@AB@%%@AE@% %@AB@%u%@AE@%, and %@AB@%w%@AE@% commands use the CS register for the default segment address. All other commands use DS. %@AI@%name%@AE@%{%@AB@%+ %@AE@%|%@AB@% -%@AE@%}%@AI@%offset%@AE@% Specifies a symbol-relative address. The %@AI@%name%@AE@% can be any symbol. The %@AI@%offset%@AE@% specifies the offset in bytes. The address can be specified as a positive (+) or negative (-) offset. %@AB@%.%@AE@%{%@AB@%+ %@AE@%|%@AB@% -%@AE@%}%@AI@%number%@AE@% Specifies a relative line number. The %@AI@%%@AE@% %@AI@%number%@AE@% is an offset (in lines) from the current source line to the new line. If + is given, the new line is closer to the end of the source file. If - is given, the new line is closer to the beginning. %@AB@%.%@AE@%«%@AI@%filename%@AE@%%@AB@%:%@AE@%»%@AI@%number%@AE@% Specifies an absolute line number. If %@AI@%%@AE@% %@AI@%filename%@AE@% is given, the specified line is assumed to be in the source file corresponding to the symbol file identified by %@AI@%filename%@AE@%. If no filename is given, the current instruction address (the current values of the CS and IP registers) determines which source file contains the line. %@AI@%symbol%@AE@%«{%@AB@%+ %@AE@%|%@AB@% -%@AE@%}%@AI@%number%@AE@%» Specifies a symbolic line number. The %@AI@%%@AE@% %@AI@%symbol%@AE@% can be any instruction or procedure label. If %@AI@%number%@AE@% is given, the %@AI@%number%@AE@% is an offset (in lines) from the given label or procedure name to the new line. If + is given, the new line is closer to the end of the source file. If - is given, the new line is closer to the beginning.%@CR:C6A00080185 @% %@CR:C6A00080186 @% %@CR:C6A00080187 @% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%Line numbers can be used only with programs developed with compilers that %@AI@%copy line-number data to the object file.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00080188 @%%@AB@%8.8.3 Expressions%@AE@%%@EH@%%@NL@% An expression is a combination of arguments and operators that evaluates to an 8-bit, 16-bit, or 32-bit value. Expressions can be used as values in any command.%@CR:C6A00080189 @%%@CR:C6A00080190 @%%@NL@% An expression can combine any symbol, number, or address with any of the unary and binary operators in Tables 8.3 and 8.4. %@NL@% Table 8.3 Unary Operators %@TH: 14 745 02 10 41 25 @%Operator Meaning Precedence%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%++ Unary plus Highest- Unary minusnot 1's complementseg Segment address of operandoff Address offset of operandby Low-order byte from given addresswo Low-order word from given addressdw Doubleword from given addresspoi Pointer from given address (same as %@AB@%dw%@AE@%)port One byte from given portwport Word from given port Lowest%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 14 745 02 10 41 25 @% Table 8.4 Binary Operators %@TH: 12 549 02 10 30 36 @%Operator Meaning Precedence%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%* Multiplication Highest/ Integer divisionmod Modulus: Segment override++ Addition- Subtractionand Bitwise Boolean ANDxor Bitwise Boolean exclusive ORor Bitwise Boolean OR Lowest%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 12 549 02 10 30 36 @% Unary address operators assume DS as the default segment for addresses. Expressions are evaluated in order of operator precedence. If adjacent operators have equal precedence, the expression is evaluated from left to right. Use parentheses to override this order. %@NL@% The following exemplifies the use of Unary expressions: %@NL@% %@AS@% SEG 0001:0002 ; Equals 1 %@AS@% OFF 0001:0002 ; Equals 2 %@AS@% 4+2*3 ; Equals 10 (0Ah) %@AS@% 4+(2*3) ; Equals 10 (0Ah) %@AS@% (4+2)*3 ; Equals 18 (12h)%@AE@% %@2@%%@CR:C6A00080191 @%%@AB@%8.9 SYMDEB Commands%@AE@%%@EH@%%@NL@% The first part of this chapter described how to use the Symbolic Debugger, a debugger that helps you test executable files for Windows applications that run in real mode. %@NL@% For more information about debugging Windows applications, see Chapter 7, "Debugging in Protected Mode: CodeView for Windows," and Chapter 9, "Advanced Debugging in Protected Mode: 80386 Debugger." %@NL@% This section provides information on %@AB@%SYMDEB%@AE@% commands. Most notably, it provides the syntax for each command. %@NL@% %@2@%%@CR:C6A00080192 @%%@AB@%a ─ Assemble%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080193 @%%@AE@%%@EH@%%@NL@% %@AS@% a«address»%@AE@% This command assembles instruction mnemonics and places the resulting instruction codes into memory at %@AI@%address%@AE@%. If no %@AI@%address%@AE@% is given, the asssembly starts at the address given by the current values of the CS and IP registers. To assemble a new instruction, type the desired mnemonic and press ENTER. To terminate assembly, press ENTER. There are the following assembly rules:%@CR:C6A00080194 @%%@NL@% ■ Use %@AB@%retf%@AE@% for the far return mnemonic.%@NL@% ■ Use %@AB@%movsb%@AE@% or %@AB@%movsw%@AE@% for string-manipulation mnemonics.%@NL@% ■ Use the %@AB@%near%@AE@% or %@AB@%far%@AE@% prefix with labels to override default distance. The %@AB@%ne%@AE@% abbreviation stands for %@AB@%near%@AE@%.%@NL@% ■ Use the %@AB@%word ptr%@AE@% or %@AB@%byte ptr%@AE@% prefix with destination operands to specify size. The %@AB@%wo%@AE@% abbreviation stands for %@AB@%word ptr%@AE@%; %@AB@%by%@AE@% for %@AB@%byte %@AB@% ptr%@AE@%.%@NL@% ■ Use square brackets around constant operands to specify absolute memory addresses. Constants without brackets are treated as constants.%@NL@% ■ Use the %@AB@%db%@AE@% mnemonics to assemble byte values or ASCII strings directly into memory.%@NL@% ■ Use 8087, 80287, or 80387 instructions only if your system has these math coprocessors.%@NL@% The 80286 protected-mode mnemonics cannot be assembled. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%Assembling over code can destroy checksum and cause a fatal exit.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00080195 @%%@AB@%ba ─ Breakpoint Address%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080196 @%%@AE@%%@EH@%%@NL@% %@AS@% ba option size address «value» «command-string»%@AE@% This command, available only on 80386 machines, sets an address breakpoint at a given address. If your program accesses memory at this address, %@AB@%SYMDEB%@AE@% will stop execution and display the current values of all registers and flags. %@NL@% There are three types of breakpoints you can set with the %@AI@%option%@AE@% parameter. If %@AB@%I%@AE@% is specified, %@AB@%SYMDEB%@AE@% takes a breakpoint when the CPU fetches an instruction from the given %@AI@%address%@AE@%. If %@AB@%R%@AE@% is specified, %@AB@%SYMDEB%@AE@% takes a breakpoint when the CPU reads or writes a byte, word, or doubleword to the given %@AI@%address%@AE@%. If %@AB@%U%@AE@% is specified, %@AB@%SYMDEB%@AE@% takes a breakpoint when the CPU writes a byte, word, or doubleword to the given address. %@NL@% The %@AI@%size%@AE@% parameter specifies the size of the data that %@AB@%SYMDEB%@AE@% expects to find read or written at the given %@AI@%address%@AE@%. If %@AB@%B%@AE@% is specified (8-bit byte), the command will break only at one address (for example, 0:10). If %@AB@%W%@AE@% is specified (16-bit word), the command will break at one of two addresses within that range (for example, 0:10 or 0:11 will cause a break within that word). If %@AB@%D%@AE@% is specified (32-bit doubleword), the command will break at one of four addresses within that range (for example, 0:08, 0:09, 0:10, or 0:11 will cause a break within that doubleword). %@NL@% The %@AI@%address%@AE@% parameter can specify any valid address. The address value is rounded down if necessary to the nearest byte, word, or doubleword boundary (for example, if a doubleword address of 0:14 was requested, the command would access the address of the nearest doubleword boundary below the address, in this case 0:12). %@NL@% The optional %@AI@%value%@AE@% parameter specifies the number of times the breakpoint is to be ignored before being taken. It can be any 16-bit value. %@NL@% The %@AI@%command-string%@AE@% parameter specifies an optional list of commands to be executed each time the breakpoint is taken. Each %@AB@%SYMDEB%@AE@% command in the list can include parameters and is separated from the next command by a semicolon. %@NL@% The %@AB@%bc%@AE@%, %@AB@%bd%@AE@%, %@AB@%be%@AE@%, and %@AB@%bl%@AE@% commands can all be used on these breakpoints. %@NL@% %@2@%%@CR:C6A00080197 @%%@AB@%bc ─ Breakpoint Clear%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080198 @%%@CR:C6A00080199 @%%@AE@%%@EH@%%@NL@% %@AS@% bc id-list%@AE@% This command permanently removes one or more previously set breakpoints. If %@AI@%id-list%@AE@% is given, the command removes the breakpoints named in the list. The %@AI@%id-list%@AE@% can be any combination of integer values from 0 to 9. If the wildcard character (*) is given, the command removes all breakpoints. %@NL@% %@2@%%@CR:C6A00080200 @%%@AB@%bd ─ Breakpoint Disable%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080201 @%%@AE@%%@EH@%%@NL@% %@AS@% bd id-list%@AE@% This command disables, but does not delete, one or more breakpoints. If %@AI@%id-list%@AE@% is given, the command disables the breakpoints named in the list. The %@AI@%id-list%@AE@% can be any combination of integer values from 0 to 9. If the wildcard character (*) is given, the command disables all breakpoints.%@CR:C6A00080202 @%%@NL@% %@2@%%@CR:C6A00080203 @%%@AB@%be ─ Breakpoint Enable%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080204 @%%@CR:C6A00080205 @%%@AE@%%@EH@%%@NL@% %@AS@% be id-list%@AE@% This command restores one or more breakpoints that were temporarily disabled by a %@AB@%bd%@AE@% command. If %@AI@%id-list%@AE@% is given, the command enables the breakpoints named in the list. The %@AI@%id-list%@AE@% can be any combination of integer values from 0 to 9. If the wildcard character (*) is given, the command enables all breakpoints. %@NL@% %@2@%%@CR:C6A00080206 @%%@AB@%bl ─ Breakpoint List%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080207 @%%@AE@%%@EH@%%@NL@% %@AS@% bl%@AE@% This command lists current information about all breakpoints. The command displays the breakpoint number, the enabled status, the address of the breakpoint, the number of passes remaining, and the initial number of passes (in parentheses). The enabled status can be enabled (e), disabled (d), or virtual (v). A virtual breakpoint is a breakpoint set at a symbol whose .EXE file has not yet been loaded.%@CR:C6A00080208 @%%@NL@% %@2@%%@CR:C6A00080209 @%%@AB@%bp ─ Breakpoint Set%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080210 @%%@CR:C6A00080211 @%%@CR:C6A00080212 @%%@AE@%%@EH@%%@NL@% %@AS@% bp«id» address «value» «command-string»%@AE@% This command creates a "sticky" breakpoint at the given %@AI@%address%@AE@%. Sticky breakpoints stop execution and display the current values of all registers and flags. Sticky breakpoints remain in the program until removed using the %@AB@%bc%@AE@% command, or temporarily disabled using the %@AB@%bd%@AE@% command. The Symbolic Debugger allows up to 10 sticky breakpoints (0 through 9). The optional %@AI@%id%@AE@% parameter specifies which breakpoint is to be created. If no %@AI@%id%@AE@% is given, the first available breakpoint number is used. The %@AI@%address%@AE@% parameter can be any valid instruction address (it must be the first byte of an instruction). The optional %@AI@%value%@AE@% parameter specifies the number of times the breakpoint is to be ignored before being taken. It can be any 16-bit value. The optional %@AI@%command-string%@AE@% parameter specifies a list of commands to be executed each time the breakpoint is taken. Each %@AB@%SYMDEB%@AE@% command in the list can include parameters and is separated from the next command by a semicolon (;).%@CR:C6A00080213 @%%@NL@% %@2@%%@CR:C6A00080214 @%%@AB@%c ─ Compare%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080215 @%%@CR:C6A00080216 @%%@AE@%%@EH@%%@NL@% %@AS@% c range address%@AE@% This command compares the bytes in the memory locations specified by %@AI@%range%@AE@% with the corresponding bytes in the memory locations beginning at %@AI@%address%@AE@%. If all corresponding bytes match, the command displays its prompt and waits for the next command. If one or more pairs of corresponding bytes do not match, the command displays each pair of mismatched bytes. %@NL@% %@2@%%@CR:C6A00080217 @%%@AB@%d ─ Dump%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@CR:C6A00080218 @%%@CR:C6A00080219 @%Syntax %@NL@% %@AS@% d «range»%@AE@% This command displays the contents of memory in the given %@AI@%range%@AE@%. The command displays data in the same format as the most recent dump command. (Dump commands include %@AB@%d%@AE@%, %@AB@%da%@AE@%, %@AB@%db%@AE@%, %@AB@%dd%@AE@%, %@AB@%dg%@AE@%, %@AB@%dh%@AE@%, %@AB@%dl%@AE@%, %@AB@%dq%@AE@%, %@AB@%ds%@AE@%, %@AB@%dt%@AE@%, and %@AB@%dw%@AE@%.) If no range is given and no previous dump command has been used, the command displays bytes starting from DS:IP. %@NL@% %@2@%%@CR:C6A00080220 @%%@AB@%da ─ Dump ASCII%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080221 @% %@CR:C6A00080222 @%%@CR:C6A00080223 @%%@AE@%%@EH@%%@NL@% %@AS@% da «range»%@AE@% This command displays the ASCII characters in the given %@AI@%range%@AE@%. Each line displays up to 48 characters. The display continues until the first null byte or until all characters in the range have been shown. Nonprintable characters, such as carriage returns and line feeds, are displayed as periods (.). %@NL@% %@2@%%@CR:C6A00080224 @%%@AB@%db ─ Dump Bytes%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080225 @% %@CR:C6A00080226 @%%@CR:C6A00080227 @%%@AE@%%@EH@%%@NL@% %@AS@% db «range»%@AE@% This command displays the hexadecimal and ASCII values of the bytes in the given %@AI@%range%@AE@%. Each display line shows the address of the first byte in the line, followed by up to 16 hexadecimal byte values. The byte values are immediately followed by the corresponding ASCII values. The eighth and ninth hexadecimal values are separated by a hyphen (-). Nonprintable ASCII values are displayed as periods (.).%@CR:C6A00080228 @%%@CR:C6A00080229 @%%@NL@% %@2@%%@CR:C6A00080230 @%%@AB@%dd ─ Dump Doublewords%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080231 @%%@CR:C6A00080232 @%%@CR:C6A00080233 @%%@AE@%%@EH@%%@NL@% %@AS@% dd «range»%@AE@% This command displays the hexadecimal values of the doublewords (4-byte values) in the given %@AI@%range%@AE@%. Each display line shows the address of the first doubleword in the line and up to four hexadecimal doubleword values. %@NL@% %@2@%%@CR:C6A00080234 @%%@AB@%df ─ Display Global Free List%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% df%@AE@% This command displays a list of the free global memory objects in the global heap. The list has the following form:%@CR:C6A00080235 @%%@CR:C6A00080236 @%%@NL@% %@AS@% segment-address: size owner%@AE@% The %@AI@%segment-address%@AE@% field specifies the segment address of the first byte of the memory object. The %@AI@%size%@AE@% field specifies the size in paragraphs (multiples of 16 bytes) of the object. %@NL@% The %@AI@%owner%@AE@% field always specifies that the module is free. %@NL@% %@2@%%@CR:C6A00080237 @%%@AB@%dg ─ Display Global Heap%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080238 @%%@AE@%%@EH@%%@NL@% %@AS@% dg%@AE@% This command displays a list of the global memory objects in the global heap. The list has the following form:%@CR:C6A00080239 @%%@NL@% %@AS@% segment-address: size segment-type owner «handle flags chain»%@AE@% The %@AI@%segment-address%@AE@% field specifies the segment address of the first byte of the memory object. The %@AI@%size%@AE@% field specifies the size in paragraphs (multiples of 16 bytes) of the object. The %@AI@%segment-type%@AE@% field specifies the type of object. The type can be any one of the following: %@NL@% %@AB@%Segment Type%@AE@% %@AB@%Meaning%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%CODE%@AE@% Segment contains program code. %@AB@%DATA%@AE@% Segment contains program data and possible stack and local heap data. %@AB@%FREE%@AE@% Segment belongs to pool of free memory objects ready for allocation by an application. %@AB@%PRIV%@AE@% Segment contains private data. %@AB@%SENTINAL%@AE@% Segment marks the beginning or end of the global heap. The %@AI@%owner%@AE@% field specifies the module name of the application or library that allocated the memory object. The name "pdb" is used for memory objects that represent program descriptor blocks. These blocks contain execution information about applications.%@CR:C6A00080240 @%%@NL@% The %@AI@%handle%@AE@% field specifies the handle of the global memory object. If %@AB@%SYMDEB%@AE@% displays no handle, the segment is fixed. %@NL@% The %@AI@%flags%@AE@% field specifies the following: %@NL@% %@AB@%Flag%@AE@% %@AB@%Meaning%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% D The segment is moveable and discardable. L The segment is locked. If the segment is locked, the lock count appears to the right of the flag. If %@AB@%SYMDEB%@AE@% displays a handle, but no flag, the segment is moveable but nondiscardable. %@NL@% The chain field specifies the previous and next segment addresses in the LRU list. %@AB@%SYMDEB%@AE@% displays the addresses only if the segment is moveable and discardable (the D flag). %@NL@% %@2@%%@CR:C6A00080241 @%%@AB@%dh ─ Display Local Heap%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080242 @%%@AE@%%@EH@%%@NL@% %@AS@% dh%@AE@% This command displays a list of the local memory objects in the local heap (if any) belonging to the current data segment. The command uses the current value of the DS register to locate the data segment and check for a local heap. The list of memory objects has the following form:%@CR:C6A00080243 @%%@NL@% %@AS@% offset: size { BUSY | FREE }%@AE@% The %@AI@%offset%@AE@% field specifies the address offset from the beginning of the data segment to the local memory object. The %@AI@%size%@AE@% field specifies the size of the memory object in bytes. If %@AB@%BUSY%@AE@% is given, the object has been allocated and is currently in use. If %@AB@%FREE%@AE@% is given, the object is in the pool of free objects ready to be allocated by the application. A special memory object, %@AB@%SENTINAL%@AE@%, may also be displayed. %@NL@% %@2@%%@CR:C6A00080244 @%%@AB@%dl ─ Dump Long Reals%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080245 @%%@AE@%%@EH@%%@NL@% %@AS@% dl «range»%@AE@% This command displays the hexadecimal and decimal values of the long (8-byte) floating-point numbers within the given %@AI@%range%@AE@%. Each display line shows the address of the floating-point number, the hexadecimal values of the bytes in the number, and the decimal value of the number.%@CR:C6A00080246 @%%@CR:C6A00080247 @%%@NL@% %@2@%%@CR:C6A00080248 @%%@AB@%dm ─ Display Global Module List%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080249 @%%@AE@%%@EH@%%@NL@% %@AS@% dm%@AE@% This command displays a list of the global modules in the global heap. The list has the following form:%@CR:C6A00080250 @%%@NL@% %@AS@% module-handle module-type module-name file-name%@AE@% The %@AI@%module-handle%@AE@% field specifies the handle of the module. The %@AI@%module-type%@AE@% field specifies either a dynamic-link library (DLL) or the name of the application you are debugging. The %@AI@%module-name%@AE@% field specifies the name of the module. The %@AI@%file-name%@AE@% field specifies the name of the file from which you loaded the application. %@NL@% %@2@%%@CR:C6A00080251 @%%@AB@%dq ─ Dump Task Queue%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080252 @%%@CR:C6A00080253 @%%@AE@%%@EH@%%@NL@% %@AS@% dq%@AE@% This command displays a list containing information about the various task queues supported by the system. The list has the following form: %@NL@% %@AS@% task-descriptor-block stack-segment:stack-pointer number-of-events %@AS@%priority internal-messaging-information module%@AE@% The %@AI@%task-descriptor-block%@AE@% field specifies the selector or segment address. The task descriptor block is identical to the "pdb."%@CR:C6A00080254 @%%@CR:C6A00080255 @%The %@AI@%stack-segment:stack-pointer%@AE@% field specifies the stack segment and pointer. The %@AI@%number-of-events%@AE@% field specifies the number of events waiting for the segment. The %@AI@%priority%@AE@% field specifies the priority of the segment. The %@AI@%internal-messaging-information%@AE@% field specifies information about internal messages. The %@AI@%module%@AE@% field specifies the module name. %@NL@% %@2@%%@CR:C6A00080256 @%%@AB@%ds ─ Dump Short Reals%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080257 @%%@AE@%%@EH@%%@NL@% %@AS@% ds «range»%@AE@% This command displays the hexadecimal and decimal values of the short (4-byte) floating-point numbers in the given %@AI@%range%@AE@%. Each display line shows the address of the floating-point number, the hexadecimal values of the bytes in the number, and the decimal value of the number.%@CR:C6A00080258 @%%@CR:C6A00080259 @%%@NL@% %@2@%%@CR:C6A00080260 @%%@AB@%dt ─ Dump Ten-Byte Reals%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080261 @%%@CR:C6A00080262 @%%@AE@%%@EH@%%@NL@% %@AS@% dt «range»%@AE@% This command displays the hexadecimal and decimal values of the 10-byte floating-point numbers in the given %@AI@%range%@AE@%. Each display line shows the address of the floating-point number, the hexadecimal values of the bytes in the number, and the decimal value of the number. %@NL@% %@2@%%@CR:C6A00080263 @%%@AB@%du ─ Display Global LRU List%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080264 @%%@CR:C6A00080265 @%%@AE@%%@EH@%%@NL@% %@AS@% du%@AE@% This command displays a list of the least-recently-used (LRU) global memory objects in the global heap. The list has the following form: %@NL@% %@AS@% segment-address: size segment-type owner «handle flags chain»%@AE@% The %@AI@%segment-address%@AE@% field specifies the segment address of the first byte of the memory object. The %@AI@%size%@AE@% field specifies the size in paragraphs (multiples of 16 bytes) of the object. The %@AI@%segment-type%@AE@% field specifies the type of object. The type can be any one of the following: %@NL@% %@AB@%Segment Type%@AE@% %@AB@%Meaning%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%CODE%@AE@% Segment contains program code. %@AB@%DATA%@AE@% Segment contains program data and possible stack and local heap data. %@AB@%FREE%@AE@% Segment belongs to pool of free memory objects ready for allocation by an application. %@AB@%PRIV%@AE@% Segment contains private data. %@AB@%SENTINAL%@AE@% Segment marks the beginning or end of the global heap. The %@AI@%owner%@AE@% field specifies the module name of the application or library that allocated the memory object. The name "pdb" is used for memory objects that represent program descriptor blocks. These blocks contain execution information about applications.%@CR:C6A00080266 @%%@NL@% The %@AI@%handle%@AE@% field specifies the handle of the global memory object. %@NL@% The %@AI@%flags%@AE@% field specifies D, which means the segment is moveable and discardable. %@NL@% The %@AI@%chain%@AE@% field specifies the previous and next segment addresses in the LRU list. %@NL@% %@2@%%@CR:C6A00080267 @%%@AB@%dw ─ Dump Words%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080268 @%%@AE@%%@EH@%%@NL@% %@AS@% dw «range»%@AE@% This command displays the hexadecimal values of the words (2-byte values) in the given %@AI@%range%@AE@%. Each display line shows the address of the first word in the line and up to eight hexadecimal word values.%@CR:C6A00080269 @%%@NL@% %@2@%%@CR:C6A00080270 @%%@AB@%e ─ Enter%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080271 @%%@AE@%%@EH@%%@NL@% %@AS@% e address «list»%@AE@% This command enters one or more values into memory. The size of the value entered depends on the most recently used Enter command. (Enter commands are %@AB@%e%@AE@%, %@AB@%ea%@AE@%, %@AB@%eb%@AE@%, %@AB@%ed%@AE@%, %@AB@%el%@AE@%, %@AB@%es%@AE@%, %@AB@%et%@AE@%, and %@AB@%ew%@AE@%.) The default is %@AB@%eb%@AE@% (bytes). If no %@AI@%list%@AE@% is given, the command displays the value at %@AI@%address%@AE@% and prompts for a new value. If %@AI@%list%@AE@% is given, the command replaces the value at %@AI@%address%@AE@% and at each subsequent address until all values in the list have been used. %@NL@% %@2@%%@CR:C6A00080272 @%%@AB@%ea ─ Enter Address%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080273 @%%@CR:C6A00080274 @%%@CR:C6A00080275 @%%@AE@%%@EH@%%@NL@% %@AS@% ea address «list»%@AE@% This command enters an ASCII string into memory. If no %@AI@%list%@AE@% is given, the command displays the byte at %@AI@%address%@AE@% and prompts for a replacement. If %@AI@%list%@AE@% is given, the command replaces the bytes at %@AI@%address%@AE@%, then displays the next byte and prompts for a replacement. %@NL@% %@2@%%@CR:C6A00080276 @%%@AB@%eb ─ Enter Bytes%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080277 @%%@AE@%%@EH@%%@NL@% %@AS@% eb address «list»%@AE@% This command enters one or more byte values into memory. If %@AI@%list%@AE@% is given, the command replaces the byte at %@AI@%address%@AE@% and bytes at each subsequent address until all values in the list have been used. If no %@AI@%list%@AE@% is given, the command displays the byte at %@AI@%address%@AE@% and prompts for a new value. To skip to the next byte, enter a new value or press the SPACEBAR. To move back to the previous byte, type a hyphen (-). To exit from the command, press ENTER. %@NL@% %@2@%%@CR:C6A00080278 @%%@AB@%ed ─ Enter Doublewords%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080279 @%%@AE@%%@EH@%%@NL@% %@AS@% ed address «value»%@AE@% This command enters a doubleword value into memory. If no %@AI@%value%@AE@% is given, the command displays the doubleword at %@AI@%address%@AE@% and prompts for a replacement. If %@AI@%value%@AE@% is given, the command replaces the doubleword at %@AI@%address%@AE@%, then displays the next doubleword and prompts for a replacement. Doublewords must be typed as two words separated by a colon.%@CR:C6A00080280 @%%@CR:C6A00080281 @%%@CR:C6A00080282 @%%@NL@% %@2@%%@CR:C6A00080283 @%%@AB@%el ─ Enter Long Reals%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080284 @%%@AE@%%@EH@%%@NL@% %@AS@% el address «value»%@AE@% This command enters a long-real value into memory. If no %@AI@%value%@AE@% is given, the command displays the long-real value at %@AI@%address%@AE@% and prompts for a replacement. If %@AI@%value%@AE@% is given, the command replaces the long-real value at %@AI@%address%@AE@%, then displays the next long-real value and prompts for a replacement.%@CR:C6A00080285 @%%@NL@% %@2@%%@CR:C6A00080286 @%%@AB@%es ─ Enter Short Reals%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080287 @%%@AE@%%@EH@%%@NL@% %@AS@% es address «value»%@AE@% This command enters a short-real value into memory. If no %@AI@%value%@AE@% is given, the command displays the short-real value at %@AI@%address%@AE@% and prompts for a replacement. If %@AI@%value%@AE@% is given, the command replaces the short-real value at %@AI@%address%@AE@%, then displays the next short-real value and prompts for a replacement.%@CR:C6A00080288 @%%@NL@% %@2@%%@CR:C6A00080289 @%%@AB@%et ─ Enter Ten-Byte Reals%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080290 @%%@AE@%%@EH@%%@NL@% %@AS@% et address «value»%@AE@% This command enters a 10-byte real value into memory. If no %@AI@%value%@AE@% is given, the command displays the 10-byte real value at %@AI@%address%@AE@% and prompts for a replacement. If %@AI@%value%@AE@% is given, the command replaces the 10-byte real value at %@AI@%address%@AE@%, then displays the next 10-byte real value and prompts for a replacement. %@NL@% %@2@%%@CR:C6A00080291 @%%@AB@%ew ─ Enter Words%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080292 @%%@AE@%%@EH@%%@NL@% %@AS@% ew address «value»%@AE@% This command enters a word value into memory. If no %@AI@%value%@AE@% is given, the command displays the word at %@AI@%address%@AE@% and prompts for a replacement. If %@AI@%value%@AE@% is given, the command replaces the word at %@AI@%address%@AE@%, then displays the next word and prompts for a replacement. %@NL@% %@2@%%@CR:C6A00080293 @%%@AB@%f ─ Fill%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080294 @%%@AE@%%@EH@%%@NL@% %@AS@% f range list%@AE@% This command fills the addresses in the given %@AI@%range%@AE@% with the values in %@AI@%list%@AE@%. If %@AI@%range%@AE@% specifies more bytes than the number of values in the list, the list is repeated until all bytes in the range are filled. If %@AI@%list%@AE@% has more values than the number of bytes in the range, the command ignores any extra values. %@NL@% %@2@%%@CR:C6A00080295 @%%@AB@%g ─ Go%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% g «= startaddress» «breakaddress»...%@AE@% This command passes execution control to the program at the given %@AI@%startaddress%@AE@%. Execution continues to the end of the program or until %@AI@%break %@AI@%address%@AE@% is encountered. The program also stops at any breakpoints set using the %@AB@%bp%@AE@% command. If no %@AI@%startaddress%@AE@% is given, the command passes execution to the address specified by the current values of the CS and IP registers. If %@AI@%breakaddress%@AE@% is given, it must specify an instruction address (that is, the address must contain the first byte of an instruction). Up to 10 break addresses, in any order, can be given at one time.%@CR:C6A00080296 @%%@NL@% %@2@%%@CR:C6A00080297 @%%@AB@%h ─ Hex%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080298 @%%@AE@%%@EH@%%@NL@% %@AS@% h value1 value2%@AE@% This command displays the sum and difference of two hexadecimal numbers, %@AI@%value1%@AE@% and %@AI@%value2%@AE@%. %@NL@% %@2@%%@CR:C6A00080299 @%%@AB@%i ─ Input%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080300 @%%@CR:C6A00080301 @%%@AE@%%@EH@%%@NL@% %@AS@% i value%@AE@% This command reads and displays one byte from the input port specified by %@AI@%value%@AE@%. The %@AI@%value%@AE@% parameter can specify any 16-bit port address. %@NL@% %@2@%%@CR:C6A00080302 @%%@AB@%k ─ Backtrace Stack%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080303 @%%@AE@%%@EH@%%@NL@% %@AS@% k «value»%@AE@% This command displays the current stack frame. Each line shows the name of a procedure, its arguments, and the address of the statement that called it. The command displays two 2-byte arguments by default. If %@AI@%value%@AE@% is given, the command displays that many 2-byte arguments. Using the %@AB@%k%@AE@% command at the beginning of a function (before the function prolog has been executed) will give incorrect results. The command uses the BP register to compute the current backtrace, and this register is not correctly set for a function until its prolog has been executed.%@CR:C6A00080304 @%%@NL@% %@2@%%@CR:C6A00080305 @%%@AB@%kt ─ Backtrace Task Stack%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080306 @%%@CR:C6A00080307 @%%@AE@%%@EH@%%@NL@% %@AS@% kt pdb «value»%@AE@% This command displays the stack frame of the program specified by %@AI@%pdb%@AE@%. Each line shows the name of a procedure, its arguments, and the address of the statement that called it. The command displays two 2-byte arguments by default. If %@AI@%value%@AE@% is given, the command displays that many 2-byte arguments. The %@AI@%pdb%@AE@% parameter must specify the segment address of the program descriptor block for the task to be traced. %@NL@% To obtain the %@AI@%pdb%@AE@% value, use the %@AB@%dq %@AE@%(Dump Task Queue) command.%@CR:C6A00080308 @%%@NL@% %@2@%%@CR:C6A00080309 @%%@AB@%kv ─ Verbose Backtrace Stack%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080310 @%%@AE@%%@EH@%%@NL@% %@AS@% kv «value»%@AE@% This command displays information that the %@AB@%k%@AE@% (Backtrace Stack) command provides, plus information about stack location and frame pointer values for each frame. %@NL@% %@2@%%@CR:C6A00080311 @%%@AB@%l ─ Load%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080312 @%%@CR:C6A00080313 @%%@AE@%%@EH@%%@NL@% %@AS@% l «address «drive record count» »%@AE@% This command copies the contents of a named file or the contents of a given number of logical disk records into memory. The contents are copied to %@AI@%address%@AE@% or to a default address, and the BX:CX register pair is set to the number of bytes loaded. %@NL@% To load a file, set the filename using the %@AB@%n%@AE@% command (otherwise, %@AB@%SYMDEB%@AE@% uses whatever name is currently at location DS:5C). If %@AI@%address%@AE@% is not given, %@AB@%SYMDEB%@AE@% copies bytes to CS:100. If the named file has an .EXE extension, the %@AB@%l%@AE@% command adjusts the load address to the address given in the .EXE file header. The command strips any header information from an .EXE file before loading. If the named file has an .HEX extension, the %@AB@%l%@AE@% command adds that file's start address to %@AI@%address%@AE@% before loading the file. %@NL@% To load logical records from a disk, set %@AI@%drive%@AE@% to 0 (drive A), 1 (drive B), or 2 (drive C). Set %@AI@%record%@AE@% to the first logical record to be read (any one- to four-digit hexadecimal number). Set %@AI@%count%@AE@% to the number of records to read (any one- to four-digit hexadecimal number).%@CR:C6A00080314 @%%@CR:C6A00080315 @%%@CR:C6A00080316 @%%@CR:C6A00080317 @%%@NL@% %@2@%%@CR:C6A00080318 @%%@AB@%m ─ Move%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080319 @%%@CR:C6A00080320 @%%@AE@%%@EH@%%@NL@% %@AS@% m range address%@AE@% This command moves the block of memory specified by %@AI@%range%@AE@% to the location starting at %@AI@%address%@AE@%. All moves are guaranteed to be performed without data loss. %@NL@% %@2@%%@CR:C6A00080321 @%%@AB@%m%@AI@%id%@AE@%%@AB@%%@AE@%─ Macro%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080322 @%%@CR:C6A00080323 @%%@CR:C6A00080324 @% %@CR:C6A00080325 @%%@AE@%%@EH@%%@NL@% %@AS@% mid«= command-string»%@AE@% This command defines or executes a %@AB@%SYMDEB%@AE@% command macro. The %@AI@%id%@AE@% parameter identifies the macro to be defined or executed. There are 10 macros, numbered 0 through 9. If %@AI@%command-string%@AE@% is specified, the command assigns the %@AB@%SYMDEB%@AE@% commands given in the string to the macro. If no string is given, the command executes the commands currently assigned to the macro. Macros are initially empty unless the %@AB@%/@%@AE@% option is used when the Symbolic Debugger is started. This option reads a set of macro definitions from a specified file. %@NL@% %@2@%%@CR:C6A00080326 @%%@AB@%n ─ Name%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080327 @%%@CR:C6A00080328 @%%@CR:C6A00080329 @%%@CR:C6A00080330 @%%@AE@%%@EH@%%@NL@% %@AS@% n «filename» «arguments»%@AE@% This command sets the filename for subsequent %@AB@%l%@AE@% and %@AB@%w%@AE@% commands, or sets program arguments for subsequent execution of a loaded program. If %@AI@%filename%@AE@% is given, all subsequent %@AB@%l%@AE@% and %@AB@%w%@AE@% commands will use this name when accessing disk files. If %@AI@%arguments%@AE@% is given, the command copies all arguments, including spaces, to the memory location starting at DS:81 and sets the byte at DS:80 to a count of the total number of characters copied. If the first two arguments are also filenames, the command creates file control blocks at addresses DS:5C and DS:6C and copies the names (in proper format) to these blocks. %@NL@% %@2@%%@CR:C6A00080331 @%%@AB@%o ─ Output%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080332 @%%@AE@%%@EH@%%@NL@% %@AS@% o value byte%@AE@% This command sends the given %@AI@%byte%@AE@% to the output port specified by %@AI@%value%@AE@%. The %@AI@%value%@AE@% parameter can specify any 16-bit port address. %@NL@% %@2@%%@CR:C6A00080333 @%%@AB@%p ─ Program Step%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080334 @%%@AE@%%@EH@%%@NL@% %@AS@% p «=startaddress» «value»%@AE@% This command executes an instruction, then displays the current values of all registers and flags. If %@AI@%startaddress%@AE@% is given, the command starts execution at the given address. Otherwise, it starts execution at the instruction pointed to by the current CS and IP registers. If %@AI@%value%@AE@% is given, the command executes %@AI@%value%@AE@% number of instructions before stopping. The command automatically executes and returns from any call instructions or software interrupts it encounters, leaving execution control at the next instruction after the call or interrupt.%@CR:C6A00080335 @%%@CR:C6A00080336 @%%@NL@% %@2@%%@CR:C6A00080337 @%%@AB@%q ─ Quit%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080338 @%%@CR:C6A00080339 @% %@CR:C6A00080340 @%%@AE@%%@EH@%%@NL@% %@AS@% q%@AE@% This command terminates %@AB@%SYMDEB%@AE@% execution and returns control to DOS. %@NL@% %@2@%%@CR:C6A00080341 @%%@AB@%r ─ Register%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080342 @%%@AE@%%@EH@%%@NL@% %@AS@% r «register« «= »value» »%@AE@% This command displays the contents of CPU registers and allows the contents to be changed to new values.%@CR:C6A00080343 @%%@CR:C6A00080344 @%%@NL@% If no %@AI@%register%@AE@% is specified, the command displays all registers, all flags, and the instruction at the address pointed to by the current CS and IP register values. If %@AI@%register%@AE@% is specified, the command displays the current value of the register and prompts for a new value. If both %@AI@%register%@AE@% and %@AI@%value%@AE@% are specified, the command changes the register to the specified value. %@NL@% %@2@%%@CR:C6A00080345 @%%@AB@%s ─ Search%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080346 @%%@AE@%%@EH@%%@NL@% %@AS@% s range list%@AE@% This command searches the given %@AI@%range%@AE@% of memory locations for the byte values given in %@AI@%list%@AE@%. The command displays the address of each byte found. %@NL@% %@2@%%@CR:C6A00080347 @%%@AB@%Set Source Mode%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% s- %@AS@% s& %@AS@% s+%@AE@% These commands set the display mode for commands that display instruction code.%@CR:C6A00080348 @%%@CR:C6A00080349 @%%@NL@% ■ If %@AB@%s-%@AE@% is given, %@AB@%SYMDEB%@AE@% disassembles and displays the instruction code in memory.%@NL@% ■ If %@AB@%s&%@AE@% is given, %@AB@%SYMDEB%@AE@% displays both the actual program source line and the disassembled code.%@NL@% ■ If %@AB@%s+%@AE@% is given, %@AB@%SYMDEB%@AE@% displays the actual program source line corresponding to the instruction to be displayed.%@CR:C6A00080350 @%%@CR:C6A00080351 @%%@CR:C6A00080352 @%%@NL@% To access a source file for the first time, %@AB@%SYMDEB%@AE@% might display the following prompt: %@NL@% %@AS@% Source file name for mapname(cr for none)?%@AE@% In such cases, type the name, including extension, of the source file corresponding to the symbol file %@AI@%mapname%@AE@%. %@NL@% %@2@%%@CR:C6A00080353 @%%@AB@%t ─ Trace%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% t «= startaddress» «value»%@AE@% This command executes an instruction, then displays the current values of all registers and flags. If %@AI@%startaddress%@AE@% is given, the command starts execution at the given address. Otherwise, it starts execution at the instruction pointed to by the current CS and IP registers. If %@AI@%value%@AE@% is given, the command continues to execute %@AI@%value%@AE@% number of instructions before stopping. In source-only %@AB@%(s+)%@AE@% mode, %@AB@%t%@AE@% operates directly on source lines. The %@AB@%t%@AE@% command can be used to trace instructions in ROM.%@CR:C6A00080354 @%%@CR:C6A00080355 @%%@CR:C6A00080356 @%%@CR:C6A00080357 @%%@CR:C6A00080358 @%%@NL@% %@2@%%@CR:C6A00080359 @%%@AB@%u ─ Unassemble%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080360 @%%@AE@%%@EH@%%@NL@% %@AS@% u «range»%@AE@% This command displays the instructions and/or statements of the program being debugged. The %@AB@%s%@AE@% command sets the display format. If %@AI@%range%@AE@% is given, the command displays instructions generated from code within the given range. Otherwise, the command displays the instructions generated from the first eight lines of code at the current address. The 80286 protected-mode mnemonics cannot be displayed.%@CR:C6A00080361 @%%@NL@% %@2@%%@CR:C6A00080362 @%%@AB@%v ─ View%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080363 @%%@AE@%%@EH@%%@NL@% %@AS@% v range%@AE@% This command displays source lines beginning at the specified range. The symbol file must contain line-number information. %@NL@% %@2@%%@CR:C6A00080364 @%%@AB@%w ─ Write%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080365 @%%@CR:C6A00080366 @%%@AE@%%@EH@%%@NL@% %@AS@% w «address «drive record count» »%@AE@% This command writes the contents of a given memory location to a named file, or to a given logical record on disk. To write to a file, set the filename with an %@AB@%n%@AE@% command, and set the BX:CX register pair to the number of bytes to be written. If no %@AI@%address%@AE@% is given, the command copies bytes starting from the address CS:100, where CS is the current value of the CS register. %@NL@% To write to a logical record on disk, set %@AI@%drive%@AE@% to any number in the range zero (drive A) to 2 (drive C), set %@AI@%record%@AE@% to the first logical record to receive the data (a one- to four-digit hexadecimal number), and set %@AI@%count%@AE@% to the number of records to write to the disk (a one- to four-digit hexadecimal number). Do not write data to an absolute disk sector unless you are sure the sector is free; otherwise, you may destroy data. %@NL@% %@2@%%@CR:C6A00080367 @%%@AB@%x ─ Examine Symbol Map%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080368 @%%@AE@%%@EH@%%@NL@% %@AS@% x «* | ? symbol»%@AE@% This command displays the name and load-segment addresses of the current symbol map, segments in that map, and symbols within those segments. %@NL@% If no parameter is given, the command displays the current symbol map name and the segments within that map. If the asterisk (*) is specified, the command displays the names and load-segment addresses for all currently loaded symbol maps. If %@AB@%?%@AE@% is specified, the command displays all symbols within the given symbol map that match the %@AI@%symbol%@AE@% specification. A %@AI@%symbol%@AE@% specification has the following form:%@CR:C6A00080369 @%%@CR:C6A00080370 @%%@CR:C6A00080371 @%%@CR:C6A00080372 @%%@NL@% %@AS@% «mapname!» «segmentname:]] «symbolname»%@AE@% If %@AI@%mapname%@AE@%%@AB@%!%@AE@% is given, the command displays information for that symbol map. The %@AI@%mapname %@AE@%parameter must specify the filename (without extension) of the corresponding symbol file. %@NL@% If %@AI@%segmentname%@AE@%%@AB@%:%@AE@% is given, the command displays the name and load-segment address for that segment. The %@AI@%segmentname%@AE@% parameter must specify the name of a segment named within the specified or currently open symbol map. %@NL@% If %@AI@%symbolname%@AE@% is given, the command displays the segment address and segment offset for that symbol. The %@AI@%symbolname%@AE@% parameter must specify the name of a symbol in the given segment. %@NL@% To display information about more than one segment or symbol, enter a partial segmentname or %@AI@%symbolname%@AE@% ending with an asterisk (*). The asterisk acts as a wildcard character.%@CR:C6A00080373 @%%@CR:C6A00080374 @%%@CR:C6A00080375 @%%@NL@% %@2@%%@CR:C6A00080376 @%%@AB@%xo ─ Open Symbol Map%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080377 @%%@AE@%%@EH@%%@NL@% %@AS@% xo «symbol!»%@AE@% This command sets the active symbol map and/or segment. If %@AI@%symbol%@AE@%%@AB@%!%@AE@% is given, the command sets the active symbol map to the given map. The %@AI@%symbol%@AE@% parameter must specify the filename (without extension) of one of the symbol files specified in the %@AB@%SYMDEB%@AE@% command line. A map file can be opened only if it was loaded by providing its name in the %@AB@%SYMDEB%@AE@% command line. %@NL@% %@2@%%@CR:C6A00080378 @%%@AB@%z ─ Set Symbol Value%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% z symbol value %@AE@% This command sets the address of %@AI@%symbol%@AE@% to %@AI@%value%@AE@%. %@NL@% %@2@%%@CR:C6A00080379 @%%@AB@%? ─ Display Help%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% ?%@AE@% This command displays a list of all %@AB@%SYMDEB%@AE@% commands and operators.%@CR:C6A00080380 @%%@NL@% %@2@%%@CR:C6A00080381 @%%@AB@%? ─ Display Expression%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% ? expression%@AE@% This command displays the value of %@AI@%expression%@AE@%. The display includes a full address, a 16-bit hexadecimal value, a full 32-bit hexadecimal value, a decimal value (enclosed in parentheses), and a string value (enclosed in double quotation marks). The %@AI@%expression%@AE@% parameter can specify any combination of numbers, symbols, addresses, and operators.%@CR:C6A00080382 @%%@CR:C6A00080383 @%%@NL@% %@2@%%@CR:C6A00080384 @%%@AB@%. ─ Source-Line Display%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080385 @%%@AE@%%@EH@%%@NL@% %@AS@% .%@AE@% This command displays the current source line. %@NL@% %@2@%%@CR:C6A00080386 @%%@AB@%Redirect Input%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080387 @%%@CR:C6A00080388 @%%@CR:C6A00080389 @%%@AE@%%@EH@%%@NL@% %@AS@% <filename %@AS@% { filename%@AE@% The %@AB@%%@AE@% command causes %@AB@%SYMDEB%@AE@% to read all subsequent command input from the specified file. The %@AB@%{%@AE@% command reads all input for the debugged program from the specified file. %@NL@% %@2@%%@CR:C6A00080390 @%%@AB@%Redirect Output%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080391 @%%@AE@%%@EH@%%@NL@% %@AS@% >filename %@AS@% }filename%@AE@% The %@AB@%>%@AE@% command causes %@AB@%SYMDEB%@AE@% to write all subsequent command output to the specified file. The %@AB@%}%@AE@% command writes all output from the debugged program to the specified file. %@NL@% %@2@%%@CR:C6A00080392 @%%@AB@%Redirect Input and Output%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080393 @%%@CR:C6A00080394 @%%@AE@%%@EH@%%@NL@% %@AS@% = =filename %@AS@% ~ filename%@AE@% The %@AB@%= = %@AE@%command causes %@AB@%SYMDEB%@AE@% to both read from and write to the device specified in the filename. The %@AB@%~%@AE@% command causes the debugged program to both read from and write to the given device. %@NL@% %@2@%%@CR:C6A00080395 @%%@AB@%! ─ Shell Escape%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% ! «dos-command»%@AE@% This command passes control to COMMAND.COM, the DOS command processor, letting the user carry out DOS commands. The DOS EXIT command returns control to %@AB@%SYMDEB%@AE@%. If %@AI@%dos-command%@AE@% is given, %@AB@%SYMDEB%@AE@% passes the command to COMMAND.COM for execution, then receives control back as soon as the command is completed.%@CR:C6A00080396 @%%@CR:C6A00080397 @%%@CR:C6A00080398 @%%@CR:C6A00080399 @%%@CR:C6A00080400 @%%@NL@% %@2@%%@CR:C6A00080401 @%%@AB@%* ─ Comment%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00080402 @%%@AE@%%@EH@%%@NL@% %@AS@% *comment%@AE@% This command echoes %@AI@%comment%@AE@% on the screen (or other output device). %@NL@% %@CR:C6A00090001 @%%@1@%%@AB@%Chapter 9 Advanced Debugging in Protected Mode: 80386 Debugger%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Microsoft Windows 80386 Debugger (%@AB@%WDEB386%@AE@%) is used to test and debug Windows applications and dynamic-link libraries (DLLs) running in standard or 386 enhanced mode, but not in real mode. It runs only on systems with an Intel 80386 CPU. The debugger provides commands that allow the operator to inspect and manipulate test code and environment status, install breakpoints, and perform other debugging operations. %@NL@% %@AB@%WDEB386%@AE@% offers debugging features not available in CodeView for Windows (%@AB@%CVW%@AE@%), but lacks the the convenient character-oriented window interface of %@AB@%CVW%@AE@%. %@NL@% To use the debugger, a serial terminal must be connected to the system running the debugger and test program. The terminal connection requirements are described in Section 9.2, "Starting the Debugger." %@NL@% This chapter describes the following: %@NL@% ■ Preparing symbol files%@NL@% ■ Starting the 80386 Debugger%@NL@% ■ How the 80386 Debugger traps a failed application%@NL@% ■ Debugger command format%@NL@% ■ Common %@AB@%WDEB386%@AE@% commands%@NL@% ■ %@AB@%WDEB386%@AE@% commands used with Windows in 386 enhanced mode%@NL@% %@2@%%@CR:C6A00090002 @%%@AB@%9.1 Preparing Symbol Files for the 80386 Debugger%@AE@%%@EH@%%@NL@% Application symbol files should be prepared for the debugger in the same way as the files are prepared for the Symbolic Debugger (%@AB@%SYMDEB%@AE@%). %@NL@% 1. Compile your C source files with the %@AB@%-Zd%@AE@% option.%@NL@% %@STUB@% This will prepare the object files for use by the 80386 Debugger.%@NL@% 2. Run %@AB@%LINK%@AE@% to link these object files.%@NL@% %@STUB@% %@AB@%WDEB386%@AE@% does not use line number information, so you need not use the %@AB@%/linenumbers%@AE@% option.%@NL@% 3. Run the %@AB@%MAPSYM%@AE@% program to create an application symbol file for the debugger.%@NL@% %@2@%%@CR:C6A00090003 @%%@AB@%9.2 Starting the Debugger%@AE@%%@EH@%%@NL@% The command line options are: %@NL@% %@AS@% WDEB386 «/C: {1 | 2 | 3 | 4}» «/V«P»» «/S: symfilespec»... winfilespec %@AS@%«parameters»%@AE@% For example, the following typical commands are valid: %@NL@% %@AS@% WDEB386 /V /S:\windows\system\krnl286.sym /S:myapp.sym \windows\win.com /s %@AS@%myapp %@AS@% %@AS@% WDEB386 /C:1 /S:krnl386.sym /s:user.sym /S:\myapp\myapp.sym %@AS@%\windows\win.com /3 myapp%@AE@% Use the %@AB@%/C:%@AE@% option to specify a COM port for debugger output. If no COM port option is specified, then the debugger checks first for COM2, and if not found, then checks for COM1. If neither COM1 nor COM2 exists, the debugger will look for any other COM port in the ROM data area (40:0). A three-wire null modem cable is all that is needed for terminal connection (no DTR/CTS handshaking is used). %@NL@% The %@AB@%/V%@AE@% and %@AB@%/VP%@AE@% options enable Verbose mode, which displays messages indicating which segments are loading. %@AB@%/V%@AE@% displays the messages for both Windows in 386 enhanced mode and for Windows applications; %@AB@%/VP%@AE@% displays the messages for applications only. %@NL@% Use the %@AB@%/S:%@AE@% option to specify a symbol file to be loaded. These switches are optional and can be repeated. If the symbol files are not in your current directory, you must supply a full pathname for the symbol files. %@AB@%WDEB386%@AE@% does not use the PATH environment variable to locate any of the files supplied on the command line. %@NL@% When memory is low, you can use more symbol files by running the 80386 Debugger in the Windows directory and specifying the full pathname of WIN386.EXE (such as \WINDOWS\SYSTEM\WIN386.EXE) instead of WIN.COM. %@NL@% A program specification is required, and any characters after the program specification are passed to the program as parameters. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The 80386 Debugger does not display your source lines. %@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00090004 @%%@AB@%9.3 When an Application Fails%@AE@%%@EH@%%@NL@% If a Windows application running in standard or 386 enhanced mode attempts to read or write memory using a bad selector, beyond a selector limit, or with a selector set to 0, then a general protection (GP) fault occurs. %@NL@% Windows in 386 enhanced mode traps this fault and causes the debugger to display something like the following: %@NL@% %@AS@% GENERAL PROTECTION VIOLATION %@AS@% AX=xxxxxxxx BX=xxxxxxxx CX=xxxxxxxx DX=xxxxxxxx SI=xxxxxxxx DI=xxxxxxxx %@AS@% IP=00000FA0 SP=xxxxxxxx BP=xxxxxxxx CR2=xxxxxxxx CR3=xxxx IOPL=3 F=─ %@AS@%─ %@AS@% CS=00AD SS=xxxx DS=xxxx ES=xxxx FS=xxxx GS=xxxx ─ NV UP EI PL ZR NA PE NC %@AS@% 00AD:00000FA0 MOV BX, WORD PTR ES:[BX] %@AS@% %@AS@%You can determine the cause of the fault by looking at the value and the %@AS@%limit of the selector by dumping the LDT entry with the command: %@NL@% %@AS@% %@AS@%%@AS@% DL selector%@AE@% The ability to continue execution depends on the cause of the fault. If the fault was caused by reading or writing beyond the selector limit, then sometimes it is possible to skip the instruction by incrementing the IP, using: %@NL@% %@AS@% R IP %@AS@% IP=xxxx %@AS@% :%@AE@% You might have to disassemble the instruction with code bytes shown to determine how many bytes it contains. To do this, use the following commands: %@NL@% %@AS@% Y CODEBYTES %@AS@% R%@AE@% If the fault is caused by a critical logic error, such as trying to use a selector for a temporary variable, then there probably is no way to continue execution of the application. Rebooting the machine may be the only option. %@NL@% %@2@%%@CR:C6A00090005 @%%@AB@%9.4 Debugger Command Format%@AE@%%@EH@%%@NL@% Each debugger command consists of one or two letters, usually followed by one or more parameters. These commands and parameters are not case-sensitive. %@NL@% If a syntax error occurs in a debugger command, the debugger redisplays the command line and indicates the error with a caret (^) and the word "Error," as in the following example: %@NL@% %@AS@% A100 %@AS@% ^ Error%@AE@% %@3@%%@CR:C6A00090006 @%%@AB@%9.4.1 Command Keys%@AE@%%@EH@%%@NL@% The following is a list of command keys: %@NL@% %@TH: 5 292 02 12 64 @%Key Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%CONTROL+C Halts debugger output and returns to the debugger prompt.CONTROL+S Freezes a 80386 Debugger display.CONTROL+Q Restarts the display.%@TE: 5 292 02 12 64 @% CONTROL+S and CONTROL+Q are ignored if the target system is executing code. %@NL@% %@3@%%@CR:C6A00090007 @%%@AB@%9.4.2 Command Parameters%@AE@%%@EH@%%@NL@% You can separate 80386 Debugger command parameters with delimiters (spaces or commas), but the only required delimiter is between two consecutive hexadecimal values. The following commands are equivalent: %@NL@% %@AS@% dCS:100 110 %@AS@% d CS:100 110 %@AS@% d,CS:100,110%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%Selector is the term used to indicate the value in a segment register while %@AI@%in protected mode. Segment is the equivalent in real mode. Although the %@AI@%following discussion uses selector, the discussion applies to segments as %@AI@%well.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% The following describes the parameters you can use with the 80386 Debugger commands: %@NL@% %@TH: 105 6149 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%addr%@AE@% Represents an address parameter in one of two forms. The first form contains either an alphabetic selector register or a four-digit selector address, and an offset value. The second form is a physical address using the % operator. You can omit the selector name or selector address, in which case the default selector is DS. This default selector is used for all commands except %@AB@%g%@AE@%, %@AB@%p%@AE@%,%@AB@% t%@AE@%, and %@AB@%u%@AE@%. The default selector for these commands is CS. All numeric values are hexadecimal. Example addresses include: %@AS@%CS:0100%@AE@% %@AS@%04BA:0100%@AE@% A colon is required between the selector name (whether numeric or alphabetic) and the offset value. The selector portion is treated as a selector or segment as appropriate for the current processor mode (protected or real) unless specifically overridden by the # or & operator.%@AI@%byte%@AE@% Specifies a 2-digit hexadecimal value.%@AI@%cmds%@AE@% Specifies an optional set of debugger commands to be executed with the %@AB@%bp%@AE@% (Set Breakpoints) or %@AB@%j%@AE@% (Conditional Execute) commands. %@AI@%dword%@AE@% Represents an 8-digit (4-byte) hexadecimal value. A %@AB@%DWORD%@AE@% is most commonly used as a physical address.%@AI@%expr%@AE@% Represents a combination of parameters and operators that evaluates to an 8, 16, or 32-bit value. An %@AI@%expr%@AE@% parameter can be used as a value in any command. An %@AI@%%@AE@% %@AI@%expr%@AE@% parameter can combine any symbol, number, or address with any of the binary and unary operators. %@AI@%group-name%@AE@% Specifies the name of a group that contains the map symbols you want to display. %@AI@%list%@AE@% Specifies a series of byte values or a string. The %@AI@%list%@AE@% parameter must be the last parameter on the command line. Following is an example of the %@AB@%f%@AE@% (Fill) command using a %@AI@%list%@AE@% parameter: %@AS@%fCS:100 42 45 52 54 41%@AE@%%@AI@%map-name%@AE@% Specifies the name of a symbol map file.%@AI@%range%@AE@% Contains two addresses (%@AI@%addr addr%@AE@%) or one address, an %@AB@%L%@AE@%, and a value (%@AI@%addr %@AE@%%@AB@%L%@AE@%%@AI@% %@AE@% %@AI@%word%@AE@%, where %@AI@%word%@AE@% is the number of items on which the command should operate; %@AB@%L %@AE@% 80 is the default). Sample %@AI@%ranges%@AE@% include: %@AS@%CS:100 110%@AE@% %@AS@%CS:100 L 10%@AE@% %@AS@%CS:100%@AE@% The limit for %@AI@%range%@AE@% is 10000 (hexadecimal). To specify a word of 10000 using only four digits, use 0000 or 0. %@AI@%reg%@AE@% Specifies the name of a microprocessor register.%@AI@%string%@AE@% Represents any number of characters enclosed in single (") or double ("") quotation marks. If the quotation marks must appear within a %@AI@%string%@AE@%, you must use two sets of quotation marks. For example, the following strings are legal: %@AS@%'This ''string'' is OK.' %@AE@% %@AS@%"This ""string"" is OK."%@AE@% However, the following strings are illegal: %@AS@%"This "string" is not OK."%@AE@% %@AS@%"This 'string' is not OK."%@AE@% The ASCII values of the characters in the string are used as a list of byte values. %@AI@%word%@AE@% Specifies a 4-digit (2-byte) hexadecimal value.%@TE: 105 6149 02 34 42 @% %@3@%%@CR:C6A00090008 @%%@AB@%9.4.3 Binary and Unary Operators%@AE@%%@EH@%%@NL@% The following list contains, in descending order of precedence, the binary operators that can be used in 80386 Debugger commands. %@NL@% %@TH: 20 847 02 16 60 @%Operator Meaning%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%( ) Parentheses: Address binder * Multiplication / Integer division MOD Modulus (remainder) ++ Addition - Subtraction > Greater-than relational operator< Less-than relational operator >= Greater-than/equal-to relational operator <= Less-than/equal-to relational operator == Equal-to relational operator != Not-equal-to relational operator AND Bitwise Boolean AND XOR Bitwise Boolean exclusive OR OR Bitwise Boolean OR && Logical AND |- |-|| Logical OR%@TE: 20 847 02 16 60 @% The following list contains, in descending order of precedence, the unary operators that can be used in 80386 Debugger commands. %@NL@% %@TH: 34 1256 02 34 42 @%Operator Meaning%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%&(seg) Interpret address using segment value#(sel) Interpret address using selector value %%(phy) Interpret address as a physical value %(lin) Interpret address as a linear value - Two's complement ! Logical NOT operator NOT One's complement SEG Segment address of operand OFF Address offset of operand BY Low-order byte from given address WO Low-order word from given address DW Doubleword from given address POI Pointer (4 bytes) from given address─this operator only works with 16:16 addressesPORT 1 byte from given port WPORT Word from given port%@TE: 34 1256 02 34 42 @% %@2@%%@CR:C6A00090009 @%%@AB@%9.5 Common Command Directory%@AE@%%@EH@%%@NL@% This section documents the commands available in all environments using the 80386 Debugger. These commands are usually one or two alphabetical characters, though some are characters preceded by a period (called "dot" commands). %@NL@% This section consists of a listing of commands and brief descriptions followed by detailed descriptions of the commands, including syntax, purpose, input parameters and examples. %@NL@% %@TH: 57 2725 02 16 60 @%Command Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%?%@AE@% Display expression%@AB@%?%@AE@% Display help%@AB@%.?%@AE@% Display external commands%@AB@%.b%@AE@% Set COM port baud rate%@AB@%.df%@AE@% Display global free list%@AB@%.dg%@AE@% Display global heap%@AB@%.dh%@AE@% Display local heap%@AB@%.dm%@AE@% Display global module list%@AB@%.dq%@AE@% Dump task queue%@AB@%.du%@AE@% Display global LRU list%@AB@%.reboot%@AE@% Reboot target system%@AB@%bc%@AE@% Clear breakpoints%@AB@%bd%@AE@% Disable breakpoints%@AB@%be%@AE@% Enable breakpoints%@AB@%bl%@AE@% List breakpoints%@AB@%bp%@AE@% Set breakpoints%@AB@%c%@AE@% Compare memory %@AB@%d%@AE@% Display memory%@AB@%db%@AE@% Display bytes%@AB@%dd%@AE@% Display doublewords%@AB@%dg%@AE@% Display GDT%@AB@%di%@AE@% Display IDT%@AB@%dl%@AE@% Display LDT%@AB@%dt%@AE@% Display TSS%@AB@%dw%@AE@% Display words%@AB@%e%@AE@% Enter byte%@AB@%f%@AE@% Fill memory%@AB@%g%@AE@% Go%@AB@%h%@AE@% Hexadecimal arithmetic%@AB@%i%@AE@% Input byte%@AB@%j%@AE@% Conditional execute%@AB@%k%@AE@% Backtrace stack%@AB@%ka%@AE@% Set backtrace arguments%@AB@%kt%@AE@% Backtrace task stack%@AB@%kv%@AE@% Verbose backtrace stack%@AB@%la%@AE@% List absolute symbols%@AB@%lg%@AE@% List groups%@AB@%lm%@AE@% List map%@AB@%ln%@AE@% List near%@AB@%ls%@AE@% List symbols%@AB@%m%@AE@% Move memory%@AB@%o%@AE@% Output to port%@AB@%p%@AE@% Program trace%@AB@%r%@AE@% Display registers%@AB@%s%@AE@% Search bytes%@AB@%t%@AE@% Trace instructions%@AB@%u%@AE@% Unassemble bytes%@AB@%v%@AE@% Set interrupt vector trapping%@AB@%vl%@AE@% Display interrupt trapping information%@AB@%w%@AE@% Change map%@AB@%y%@AE@% Debugger configuration options%@AB@%z%@AE@% Zap embedded INT 1 and INT 3 instructions%@AB@%zd%@AE@% Execute default command string%@AB@%zl%@AE@% Display default command string%@AB@%zs%@AE@% Change default command string%@TE: 57 2725 02 16 60 @% %@2@%%@CR:C6A00090010 @%%@AB@%? ─ Display Expression%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% ? expr | "string"%@AE@% The %@AB@%?%@AE@% command displays the value of a specified expression or string. An expression is first evaluated and then displayed in hexadecimal, decimal, octal, and binary format. The debugger also displays an ASCII character representation of the evaluated expression, a physical address interpretation, and whether the expression is TRUE or FALSE. %@NL@% Strings enclosed in quotation marks are echoed to the screen. %@NL@% The expression evaluator provides support for three types of addresses: real mode (%selector:offset), protected mode (#selector:offset), and physical address (%@AB@%DWORD)%@AE@%. The %@AB@%&%@AE@%, %@AB@%#%@AE@%, and %@AB@%%%@AE@% characters override the current address type, allowing selectors to be used in real mode, segments to be used in protected mode, and so on. The %@AB@%%%@AE@% character converts other addresses to physical addresses. %@NL@% %@TH: 53 2269 02 11 32 33 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%expr%@AE@% Specifies any combination of numbers, addresses, and operators. If %@AI@%expr%@AE@% is not specified, this command will print help messages. The following key words can be used with the expression: Key Word Description %@AI@%reg%@AE@% Returns the value of %@AI@%reg%@AE@%, where %@AI@%reg%@AE@% is one of the following registers: AX, BX, CX, DX, SI, DI, BP, DS, ES, SS, CS, SP, or IP FLG Returns the value of the flags GDTB Returns the value of the GDT base as a physical address GDTL Returns the value of the GDT limit IDTB Returns the value of the IDT base as a physical address IDTL Returns the value of the IDT limit TR Returns the value of the TR register LDTR Returns the value of the LDTR register MSW Returns the value of the MSW register The @ character can be used with any of the register names to ensure that the expression evaluator interprets the name as a register instead of a symbol (for example, @AX is the same as AX).%@AI@%string%@AE@% Specifies a sequence of characters enclosed in single or double quotation marks.%@TE: 53 2269 02 11 32 33 @% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% ?%(#001F:0220) %@AE@% This example looks up selector 1F's physical address in the current LDT and adds 220 to it. %@NL@% %@AS@% ? ds:si+bx%@AE@% This example displays the value of the expression DS:SI + BX. The debugger returns a display similar to the following: %@NL@% %@AS@% 2038:4278 540557944T 40160411700Q 0100001001111000Y 'X' %0245F8 TRUE%@AE@% %@AS@% ? 3*4%@AE@% This example displays the value of the arithmetic expression 3*4. The debugger returns the following display: %@NL@% %@AS@% 0CH 12T 14Q 00001100Y '.' %00000C TRUE%@AE@% %@AS@% bp1 100 "r;d 200;? 'BP 1 REACHED'"%@AE@% This example is used in a %@AB@%bp%@AE@% (Set Breakpoint) command to announce a breakpoint number. %@NL@% %@2@%%@CR:C6A00090011 @%%@AB@%? ─ Display Help Menu%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% ?%@AE@% The %@AB@%?%@AE@% command displays a list of commands and syntax recognized by the debugger. %@NL@% %@2@%%@CR:C6A00090012 @%%@AB@%.? ─ Display External Commands%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% .?%@AE@% The %@AB@%.?%@AE@% command displays a list of external commands. These commands are part of the debugger, but are specific to the environment in which the debugger is running. %@NL@% %@2@%%@CR:C6A00090013 @%%@AB@%.b ─ Set COM Port Baud Rate%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% .b baud-rate «port-addr»%@AE@% The %@AB@%.b%@AE@% command sets the baud rate for the debugging port (COM2). %@NL@% %@TH: 17 1090 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%baud-rate%@AE@% Specifies one of the following values: 150, 300, 600, 1200, 2400, 4800, 9600, or 19200. Since the default radix for the debugger is 16, you must include a "t" after the number to indicate decimal values. %@AI@%port-addr%@AE@% Can be 1 for COM1, 2 for COM2; anything else is taken as a base port address. During initialization, if there is no COM2, the debugger checks for COM1 and then any other COM port address in the ROM data area, and uses it as the console. %@TE: 17 1090 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% #.b 1200t%@AE@% This example sets the baud rate to 1200. %@NL@% %@2@%%@CR:C6A00090014 @%%@AB@%.df ─ Display Global Free List%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% .df%@AE@% The %@AB@%.df%@AE@% command displays a list of the free global memory objects in the global heap. The list has the following form:%@CR:C6A00090015 @%%@CR:C6A00090016 @%%@NL@% %@AS@% address: size owner «chain»%@AE@% The %@AI@%address%@AE@% field specifies the selector of the memory in standard mode. In 386 enhanced mode, the %@AI@%address%@AE@% field specifies physical and heap addresses. %@NL@% The %@AI@%size%@AE@% field specifies the size in paragraphs (multiples of 16 bytes) of the object in standard mode. In 386 enhanced mode, the %@AI@%size%@AE@% field specifies the size of the object in bytes. %@NL@% The %@AI@%owner%@AE@% field always specifies that the module is free. %@NL@% The %@AI@%chain%@AE@% field specifies the previous and next addresses in the LRU list. %@AB@%WDEB386%@AE@% displays the addresses only if the segment is moveable and discardable. %@NL@% %@2@%%@CR:C6A00090017 @%%@AB@%.dg ─ Display Global Heap%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00090018 @%%@AE@%%@EH@%%@NL@% %@AS@% .dg «object»%@AE@% The %@AB@%.dg%@AE@% command displays a list of the global memory objects in the global heap. %@NL@% %@TH: 7 463 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%object%@AE@% Specifies the first object to be listed. The %@AI@%object%@AE@% parameter can be a handle, selector, or (in 386 enhanced mode) a heap address.%@TE: 7 463 02 34 42 @% The list has the following form:%@CR:C6A00090019 @%%@NL@% %@AS@% address: size segment-type owner «handle flags chain»%@AE@% The %@AI@%address%@AE@% field specifies the selector of the memory in standard mode. In 386 enhanced mode, the %@AI@%address%@AE@% field specifies physical and heap addresses. %@NL@% The %@AI@%size%@AE@% field specifies the size in paragraphs (multiples of 16 bytes) of the object in standard mode. In 386 enhanced mode, the %@AI@%size%@AE@% field specifies the size of the object in bytes. %@NL@% The %@AI@%segment-type%@AE@% field specifies the type of object. The type can be any one of the following: %@NL@% %@AB@%Segment Type%@AE@% %@AB@%Meaning%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%CODE%@AE@% Segment contains program code. %@AB@%DATA%@AE@% Segment contains program data and possible stack and local heap data. %@AB@%FREE%@AE@% Segment belongs to pool of free memory objects ready for allocation by an application. %@AB@%PRIV%@AE@% Segment contains private data. %@AB@%SENTINAL%@AE@% Segment marks the beginning or end of the global heap. The %@AI@%owner%@AE@% field specifies the module name of the application or library that allocated the memory object. The name "pdb" is used for memory objects that represent program descriptor blocks. These blocks contain execution information about applications.%@CR:C6A00090020 @%%@NL@% The %@AI@%handle%@AE@% field specifies the handle of the global memory object. If %@AB@%WDEB386%@AE@% displays no handle, the segment is fixed. %@NL@% The %@AI@%flags%@AE@% field specifies the following: %@NL@% %@AB@%Flag%@AE@% %@AB@%Meaning%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% D The segment is moveable and discardable. L The segment is locked. If the segment is locked, the lock count appears to the right of the flag. If %@AB@%WDEB386%@AE@% displays a handle, but no flag, the segment is moveable but nondiscardable. %@NL@% The %@AI@%chain%@AE@% field specifies the previous and next addresses in the LRU list. %@AB@%WDEB386%@AE@% displays the addresses only if the segment is moveable and discardable (the D flag). %@NL@% %@2@%%@CR:C6A00090021 @%%@AB@%.dh ─ Display Local Heap%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00090022 @%%@AE@%%@EH@%%@NL@% %@AS@% .dh%@AE@% The %@AB@%.dh%@AE@% command displays a list of the local memory objects in the local heap (if any) belonging to the current data segment. The command uses the current value of the DS register to locate the data segment and check for a local heap. The list of memory objects has the following form:%@CR:C6A00090023 @%%@NL@% %@AS@% offset: size { BUSY | FREE }%@AE@% The %@AI@%offset%@AE@% field specifies the address offset from the beginning of the data segment to the local memory object. %@NL@% The %@AI@%size%@AE@% field specifies the size of the object in bytes. %@NL@% If %@AB@%BUSY%@AE@% is given, the object has been allocated and is currently in use. If %@AB@%FREE%@AE@% is given, the object is in the pool of free objects ready to be allocated by the application. A special memory object, %@AB@%SENTINAL%@AE@%, may also be displayed. %@NL@% %@2@%%@CR:C6A00090024 @%%@AB@%.dm ─ Display Global Module List%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00090025 @%%@AE@%%@EH@%%@NL@% %@AS@% .dm%@AE@% The %@AB@%.dm%@AE@% command displays a list of the global modules in the global heap. The list has the following form:%@CR:C6A00090026 @%%@NL@% %@AS@% module-handle module-type module-name file-name%@AE@% The %@AI@%module-handle%@AE@% field specifies the handle of the module. The %@AI@%module-type%@AE@% field specifies either a dynamic-link library (DLL) or the name of the application you are debugging. The %@AI@%module-name%@AE@% field specifies the name of the module. The %@AI@%file-name%@AE@% field specifies the name of the file from which you loaded the application. %@NL@% %@2@%%@CR:C6A00090027 @%%@AB@%.dq ─ Dump Task Queue%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00090028 @%%@CR:C6A00090029 @%%@AE@%%@EH@%%@NL@% %@AS@% .dq%@AE@% The %@AB@%.dq%@AE@% command displays a list containing information about the various task queues supported by the system. The list has the following form: %@NL@% %@AS@% task-descriptor-block stack-segment:stack-pointer number-of-events %@AS@%priority internal-messaging-information module%@AE@% The %@AI@%task-descriptor-block%@AE@% field specifies the selector or segment address. The task descriptor block is identical to the "pdb."%@CR:C6A00090030 @%%@CR:C6A00090031 @%The %@AI@%stack-segment:stack-pointer%@AE@% field specifies the stack segment and pointer. The %@AI@%number-of-events%@AE@% field specifies the number of events waiting for the segment. The %@AI@%priority%@AE@% field specifies the priority of the segment. The %@AI@%internal-messaging-information%@AE@% field specifies information about internal messages. The %@AI@%module%@AE@% field specifies the module name. %@NL@% %@2@%%@CR:C6A00090032 @%%@AB@%.du ─ Display Global LRU List%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00090033 @%%@CR:C6A00090034 @%%@AE@%%@EH@%%@NL@% %@AS@% .du%@AE@% The %@AB@%.du%@AE@% command displays a list of the least-recently-used (LRU) global memory objects in the global heap. The list has the following form: %@NL@% %@AS@% address: size segment-type owner «handle flags chain»%@AE@% The %@AI@%address%@AE@% field specifies the selector of the memory in standard mode. In 386 enhanced mode, the %@AI@%address%@AE@% field specifies physical and heap addresses. %@NL@% The %@AI@%size%@AE@% field specifies the size in paragraphs (multiples of 16 bytes) of the object in standard mode. In 386 enhanced mode, the %@AI@%size%@AE@% field specifies the size of the object in bytes. %@NL@% The %@AI@%segment-type%@AE@% field specifies the type of object. The type can be any one of the following: %@NL@% %@AB@%Segment Type%@AE@% %@AB@%Meaning%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%CODE%@AE@% Segment contains program code. %@AB@%DATA%@AE@% Segment contains program data and possible stack and local heap data. %@AB@%FREE%@AE@% Segment belongs to pool of free memory objects ready for allocation by an application. %@AB@%PRIV%@AE@% Segment contains private data. %@AB@%SENTINAL%@AE@% Segment marks the beginning or end of the global heap. The %@AI@%owner%@AE@% field specifies the module name of the application or library that allocated the memory object. The name "pdb" is used for memory objects that represent program descriptor blocks. These blocks contain execution information about applications.%@CR:C6A00090035 @%%@NL@% The %@AI@%handle%@AE@% field specifies the handle of the global memory object. %@NL@% The %@AI@%flags%@AE@% field specifies D, which means the segment is moveable and discardable. %@NL@% The %@AI@%chain%@AE@% field specifies the previous and next addresses in the LRU list. %@NL@% %@2@%%@CR:C6A00090036 @%%@AB@%.reboot ─ Reboot Target System%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% .reboot%@AE@% The %@AB@%.reboot%@AE@% command causes the target system to reboot. %@NL@% %@2@%%@CR:C6A00090037 @%%@AB@%bc ─ Clear Breakpoints%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% bc {list | *}%@AE@% The %@AB@%bc%@AE@% command removes one or more defined breakpoints. %@NL@% %@TH: 9 534 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%list%@AE@% Specifies any combination of integer values in the range 0-9. If you specify %@AI@%%@AE@% %@AI@%list%@AE@%, the debugger removes the specified breakpoints.* Clears all breakpoints.%@TE: 9 534 02 34 42 @% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% bc 0 4 8%@AE@% Removes breakpoints 0, 4, and 8. %@NL@% %@AS@% bc *%@AE@% Removes all breakpoints. %@NL@% %@2@%%@CR:C6A00090038 @%%@AB@%bd ─ Disable Breakpoints%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% bd {list | *}%@AE@% The %@AB@%bd%@AE@% command temporarily disables one or more breakpoints. To restore breakpoints disabled by the %@AB@%bd%@AE@% command, use the %@AB@%be%@AE@% (Enable Breakpoints) command. %@NL@% %@TH: 9 538 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%list%@AE@% Specifies any combination of integer values in the range 0-9. If you specify %@AI@%%@AE@% %@AI@%list%@AE@%, the debugger disables the specified breakpoints.* Disables all breakpoints.%@TE: 9 538 02 34 42 @% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% bd 0 4 8%@AE@% Disables breakpoints 0, 4, and 8. %@NL@% %@AS@% bd *%@AE@% Disables all breakpoints. %@NL@% %@2@%%@CR:C6A00090039 @%%@AB@%be ─ Enable Breakpoints%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% be {list | *}%@AE@% The %@AB@%be%@AE@% command restores (enables) one or more breakpoints that have been temporarily disabled by a %@AB@%bd%@AE@% (Disable Breakpoints) command. %@NL@% %@TH: 9 536 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%list%@AE@% Specifies any combination of integer values in the range 0-9. If you specify %@AI@%%@AE@% %@AI@%list%@AE@%, the debugger enables the specified breakpoints. * Enables all breakpoints.%@TE: 9 536 02 34 42 @% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% be 0 4 8%@AE@% Enables breakpoints 0, 4, and 8. %@NL@% %@AS@% be *%@AE@% Enables all breakpoints. %@NL@% %@2@%%@CR:C6A00090040 @%%@AB@%bl ─ List Breakpoints%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% bl%@AE@% The %@AB@%bl%@AE@% command lists current information about all breakpoints created by the%@AB@% bp %@AE@%(Set Breakpoints) command. %@NL@% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% If no breakpoints are currently defined, the debugger displays nothing. Otherwise, the breakpoint number, enabled status, breakpoint address, number of passes remaining, initial number of passes (in parentheses), and any optional debugger commands to be executed when the breakpoint is reached are displayed on the screen, as in the following example: %@NL@% %@AS@% 0 e 04BA:0100 %@AS@% 4 d 04BA:0503 4 (10) %@AS@% 8 e 0D2D:0001 3 (3) "R;DB DS:SI" %@AS@% 9 e xxxx:0012%@AE@% In this example, breakpoints 0 and 8 are enabled (e), while 4 is disabled (d). Breakpoint 4 had an initial pass count of 10 and has 4 remaining passes to be taken before the breakpoint. Breakpoint 8 had an initial pass count of 3 and must make all 3 passes before it halts execution and forces the debugger to execute the optional debugger commands enclosed in quotation marks. Breakpoint 0 shows no initial pass count, which means it was set to 1. %@NL@% Breakpoint 9 shows a virtual breakpoint (a breakpoint set in a segment that has not been loaded into memory). %@NL@% %@2@%%@CR:C6A00090041 @%%@AB@%bp ─ Set Breakpoints%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% bp«n» addr «passcnt» «"cmds"»%@AE@% The %@AB@%bp%@AE@% command creates a software breakpoint at an address. During program execution, software breakpoints stop program execution and force the debugger to execute the default or optional command string. Unlike breakpoints created by the %@AB@%g%@AE@% (Go) command, software breakpoints remain in memory until you remove them with the %@AB@%bc %@AE@%(Clear Breakpoints) command or temporarily disable them with the%@AB@% bd%@AE@% (Disable Breakpoints) command. %@NL@% The debugger allows up to 10 software breakpoints (0-9). If you specify more than 10 breakpoints, the debugger returns a "Too Many Breakpoints" message. The %@AI@%addr%@AE@% parameter is required for all new breakpoints. %@NL@% %@TH: 23 1428 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%n%@AE@% Specifies which breakpoint is being created. No space is allowed between the %@AB@%bp%@AE@% and %@AI@%n%@AE@%. If %@AI@%n%@AE@% is omitted, the first available breakpoint number is used. %@AI@%addr%@AE@% Specifies any valid instruction address (the first byte of an instruction opcode).%@AI@%passcnt%@AE@% Specifies the number of times the breakpoint is to be ignored before being executed. It can be any 16-bit value.%@AI@%cmds%@AE@% Specifies an optional list of debugger commands to be executed in place of the default command when the breakpoint is reached. You must enclose optional commands in quotation marks, and separate optional commands with semicolons (;).%@TE: 23 1428 02 34 42 @% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% bp 123%@AE@% The first example creates a breakpoint at address CS:123. %@NL@% %@AS@% bp8 400:23 "db DS:SI"%@AE@% This example creates breakpoint 8 at address 400:23 and executes a %@AB@%db%@AE@% (Display Bytes) command. %@NL@% %@AS@% bp 100 10 "r;c100 L 100 300"%@AE@% This example creates a breakpoint at address 100 in the current CS selector and displays the registers before comparing a block of memory. The breakpoint is ignored 16 (10H) times before being executed. %@NL@% %@2@%%@CR:C6A00090042 @%%@AB@%c ─ Compare Memory%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% c range addr%@AE@% The %@AB@%c%@AE@% command compares one memory location against another memory location. %@NL@% If the two memory areas are identical, the debugger displays nothing and returns the debugger prompt. Differences, when they exist, are displayed as follows: %@NL@% %@AS@% addr1 byte1 byte2 addr2%@AE@% %@TH: 9 536 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%range%@AE@% Specifies the block of memory that is to be compared with a block of memory starting at %@AI@%addr%@AE@%. %@AI@%addr%@AE@% Specifies the starting address of the second block of memory.%@TE: 9 536 02 34 42 @% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% The following two commands have the same effect. Each compares the block of memory from 100H to 1FFH with the block of memory from 300H to 3FFH: %@NL@% %@AS@% c100 1FF 300%@AE@% This first example specifies a %@AI@%range%@AE@% with a starting address of 100H and an ending address of 1FFH. This block of memory is compared with a block of memory of the same size starting at 300H. %@NL@% %@AS@% c100 L 100 300%@AE@% The second example compares the same block of memory, but specifies the %@AI@%range%@AE@% by using the%@AB@% L%@AE@% (length) option. %@NL@% %@2@%%@CR:C6A00090043 @%%@AB@%d ─ Display Memory%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% d «range»%@AE@% The%@AB@% d%@AE@% command displays the contents of memory at a given address or in a range of addresses. The%@AB@% d%@AE@% command displays one or more lines, depending on the %@AI@%range%@AE@% given. Each line displays the address of the first item displayed. The command always displays at least one value. The memory display is in the format defined by a previously executed %@AB@%db%@AE@% (Display Bytes), %@AB@%dd%@AE@% (Display Doublewords), or %@AB@%dw%@AE@% (Display Words) command. Each subsequent %@AB@%d%@AE@% (typed without parameters) displays the bytes immediately following those last displayed. %@NL@% %@TH: 9 656 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%range%@AE@% Specifies the range of addresses to display. If you omit %@AI@%range%@AE@%, the %@AB@%d%@AE@% command displays the next byte of memory after the last one displayed. The %@AB@%d%@AE@% command must be separated by at least one space from any %@AI@%range%@AE@% value. %@TE: 9 656 02 34 42 @% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% d CS:100 L 20%@AE@% This example displays 20H bytes at CS:100. %@NL@% %@AS@% d CS:100 115%@AE@% This example displays all the bytes in the range 100H to 115H in the CS selector. %@NL@% %@2@%%@CR:C6A00090044 @%%@AB@%db ─ Display Bytes%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% db «range»%@AE@% The %@AB@%db%@AE@% command displays the values of the bytes at a given address or in a given range. %@NL@% The display is in two portions: a hexadecimal display (each byte is shown in hexadecimal value) and an ASCII display (the bytes are shown in ASCII characters). Nonprinting characters are denoted by a period (.) in the ASCII portion of the display. Each display line shows 16 bytes, with a hyphen between the eighth and ninth bytes. Each displayed line begins on a 16-byte boundary. %@NL@% %@TH: 8 556 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%range%@AE@% Specifies the range of addresses to display. If you omit %@AI@%range%@AE@%, 128 bytes are displayed beginning at the first address after the address displayed by the previous %@AB@%db%@AE@% command. %@TE: 8 556 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% db CS:100 0A%@AE@% This example displays the lines in the following format: %@NL@% %@AS@% 04BA:0100 54 4F 4D 20 53 . . . 45 52 TOM SAWYER%@AE@% Each line of the display begins with an address, incremented by 10H from the address on the previous line. %@NL@% %@2@%%@CR:C6A00090045 @%%@AB@%dd ─ Display Doublewords%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% dd «range»%@AE@% The %@AB@%dd%@AE@% command displays the hexadecimal values of the doublewords at the address specified or in the specified range of addresses. %@NL@% The %@AB@%dd%@AE@% command displays one or more lines, depending on the %@AI@%range%@AE@% given. Each line displays the address of the first doubleword in the line, followed by up to four hexadecimal doubleword values. The hexadecimal values are separated by spaces. The%@AB@% dd%@AE@% command displays values until the end of the %@AI@%range%@AE@% or until the first 32 doublewords have been displayed. %@NL@% Typing %@AB@%dd%@AE@% displays 32 doublewords at the current dump address. For example, if the last byte in the previous%@AB@% dd%@AE@% command was 04BA:0110, the display starts at 04BA:0111. %@NL@% %@TH: 8 567 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%range%@AE@% Specifies the range of addresses to display. If you omit %@AI@%range%@AE@%, 32 %@AB@%DWORD%@AE@%s are displayed beginning at the first address after the address displayed by the previous %@AB@%dd%@AE@% command.%@TE: 8 567 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% dd CS:100 110%@AE@% This example displays the doubleword values from CS:100 to CS:110. The resulting display is similar to the following: %@NL@% %@AS@% 04BA:0100 7473:2041 676E:6972 5405:0104 0A0D:7865 %@AS@% 04BA:0110 0000:002E%@AE@% No more than four values per line are displayed. %@NL@% %@2@%%@CR:C6A00090046 @%%@AB@%dg ─ Display GDT%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% dg«a» «range»%@AE@% The %@AB@%dg%@AE@% command displays the specified range of entries in the GDT (Global Descriptor Table). %@NL@% %@TH: 13 855 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%range%@AE@% Specifies the range of entries in the GDT. If you omit %@AI@%range%@AE@%, the debugger displays the entire contents of the GDT.%@AB@%a%@AE@% Causes all entries in the table to be displayed, not just the valid entries. The default is to display just the valid GDT entries. If the command is passed an LDT selector, it displays LDT and the appropriate LDT entry. %@TE: 13 855 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% dg 0 40%@AE@% This example displays only the valid entries from 0H to 40H in the GDT. The resulting display is similar to the following: %@NL@% %@AS@% 0008 Data Seg Base=01D700 Limit=3677 DPL=0 Present ReadWrite Accessed %@AS@% 0010 TSS Desc Base=007688 Limit=002B DPL=0 Present Busy %@AS@% 0018 Data Seg Base=020D7A Limit=03FF DPL=0 Present ReadWrite %@AS@% 0020 Data Seg Base=000000 Limit=03FF DPL=0 Present ReadWrite %@AS@% 0028 LDT Desc Base=000000 Limit=0000 DPL=0 Present %@AS@% 0030 Data Seg Base=000000 Limit=0000 DPL=0 Present ReadWrite %@AS@% 0040 Data Seg Base=000400 Limit=03BF DPL=3 Present ReadWrite %@AE@% %@2@%%@CR:C6A00090047 @%%@AB@%di ─ Display IDT%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% di«a» «range»%@AE@% The %@AB@%di%@AE@% command displays the specified range of entries in the IDT (Interrupt Descriptor Table). %@NL@% %@TH: 11 683 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%a%@AE@% Causes all entries in the table to be displayed, not just the valid ones. The default is to display just the valid IDT entries.%@AI@%range%@AE@% Specifies the range of entries to be displayed. If you omit %@AI@%range%@AE@%, the debugger displays all IDT entries.%@TE: 11 683 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% di 0 10%@AE@% This command produces a display of valid entries similar to the following: %@NL@% %@AS@% 0000 Int Gate Sel=1418 Offst=03D8 DPL=3 Present %@AS@% 0001 Int Gate Sel=2D38 Offst=0049 DPL=3 Present %@AS@% 0002 Int Gate Sel=1418 Offst=03E4 DPL=3 Present %@AS@% 0003 Int Gate Sel=2D38 Offst=006F DPL=3 Present %@AS@% 0004 Int Gate Sel=1418 Offst=0417 DPL=3 Present %@AS@% 0005 Int Gate Sel=1418 Offst=041D DPL=3 Present %@AS@% 0006 Int Gate Sel=1418 Offst=0423 DPL=3 Present %@AS@% 0007 Int Gate Sel=2D38 Offst=00A3 DPL=3 Present %@AS@% 0008 Int Gate Sel=1418 Offst=042F DPL=3 Present %@AS@% 0009 Int Gate Sel=2D38 Offst=00CA DPL=3 Present %@AS@% 000A Int Gate Sel=2D38 Offst=00D3 DPL=3 Present %@AS@% 000B Int Gate Sel=2D38 Offst=0156 DPL=3 Present %@AS@% 000C Int Gate Sel=2D38 Offst=01A4 DPL=3 Present %@AS@% 000D Int Gate Sel=2D38 Offst=01C6 DPL=3 Present %@AE@% %@2@%%@CR:C6A00090048 @%%@AB@%dl ─ Display LDT%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% dl«a | p | s | h» «range»%@AE@% The %@AB@%dl%@AE@% command displays the specified range of entries in the LDT (Local Descriptor Table). %@NL@% %@TH: 26 1507 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%a%@AE@% Causes all entries in the table to be displayed, not just the valid ones. The default is to display just the valid LDT entries. If the command is passed a GDT selector, it displays GDT and the appropriate GDT entry. %@AB@%p%@AE@% Causes private segment selectors to be displayed. %@AB@%s%@AE@% Causes shared segment selectors to be displayed.%@AB@%h%@AE@% Causes huge segment selectors to be displayed. To display the huge segment selectors, give the shadow selector followed by the maximum number of selectors reserved for that segment plus 1.%@AI@%range%@AE@% Specifies the range of entries to be displayed. If you omit %@AI@%range%@AE@%, the entire table is displayed.%@TE: 26 1507 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% dla 4 57%@AE@% This example displays all of the LDT entries. The command produces a display similar to the following: %@NL@% %@AS@% 0014 Call Gate Sel=1418 Offst=0417 DPL=0 NotPres WordCount=1D %@AS@% 001C Code Seg Base=051418 Limit=0423 DPL=0 NotPres ExecOnly %@AS@% 0027 Reserved Base=87F000 Limit=FEA5 DPL=3 Present %@AS@% 0034 Code Seg Base=05F000 Limit=1805 DPL=0 NotPres ExecOnly %@AS@% 003C Code Seg Base=05F000 Limit=EF57 DPL=0 NotPres ExecOnly %@AS@% 0047 Code Seg Base=4DC000 Limit=0050 DPL=3 Present ExecOnly %@AS@% 004D Reserved Base=71F000 Limit=F841 DPL=1 NotPres %@AS@% 0057 Code Seg Base=59F000 Limit=E739 DPL=3 Present ExecOnly %@AE@% %@2@%%@CR:C6A00090049 @%%@AB@%dt ─ Display TSS%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% dt «addr»%@AE@% The %@AB@%dt%@AE@% command displays the current TSS (Task State Segment) or the selected TSS if you specify the optional address. %@NL@% %@TH: 7 471 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%addr%@AE@% Specifies the address of the TSS to display. If no %@AI@%addr%@AE@% is given, %@AB@%dt%@AE@% displays the current TSS pointed to by the TR register. %@TE: 7 471 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% dt%@AE@% This example displays the current TSS. The resulting display is similar to the following: %@NL@% %@AS@% AX=0000 BX=0000 CX=0000 DX=0000 SP=0000 BP=0000 SI=0000 %@AS@%DI=0000 %@AS@% IP=0000 CS=0000 DS=0000 ES=0000 SS=0000 NV UP DI PL NZ NA PO NC %@AS@% SS0=0038 SP0=08DE SS1=0000 SP1=0000 SS2=0000 SP2=0000 %@AS@% IOPL=0 LDTR=0028 LINK=0000%@AE@% %@2@%%@CR:C6A00090050 @%%@AB@%dw ─ Display Words%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% dw «range»%@AE@% The %@AB@%dw%@AE@% command displays the hexadecimal values of the words at a given address or in a given range of addresses. %@NL@% The command displays one or more lines, depending on the %@AI@%range%@AE@% given. Each line displays the address of the first word in the line, followed by up to eight hexadecimal word values. 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. %@NL@% Typing %@AB@%dw%@AE@% displays 64 words at the current dump address. If the last word in the previous %@AB@%dw%@AE@% command was displayed at address 04BA:0110, the next display will start at 04BA:0112. %@NL@% %@TH: 8 552 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%range%@AE@% Specifies the range of addresses to display. If you omit %@AI@%range%@AE@%, 64 words are displayed beginning at the first address after the address displayed by the previous %@AB@%dw%@AE@% command.%@TE: 8 552 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% dw CS:100 110%@AE@% This example displays the word values from CS:100 to CS:110, resulting in a display similar to the following: %@NL@% %@AS@% 04BA:0100 2041 7473 6972 676E 0104 5404 7865 0A0D %@AS@% 04BA:0110 002E%@AE@% %@2@%%@CR:C6A00090051 @%%@AB@%e ─ Enter Byte%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% e addr «list»%@AE@% The %@AB@%e%@AE@% command enters byte values into memory at a specified address. You can specify the new values on the command line, or let the debugger prompt you for values. If the debugger uses a prompt, it displays the address and its contents and then waits for you to perform one of the following actions: %@NL@% ■ Replace a byte value with a value you type. Type the value after the current value. If the byte you type is an illegal hexadecimal value or contains more than two digits, the system does not echo the illegal or extra character. %@NL@% ■ Press the SPACEBAR to advance to the next byte. To change the value, type the new value after the current value. If, when you press the SPACEBAR, you move beyond an 8-byte boundary, the 80386 Debugger starts a new display line with the address displayed at the beginning. %@NL@% ■ Type a hyphen (-) to return to the preceding byte. If you decide to change a byte before the current position, typing the hyphen returns the current position to the previous byte. When you type the hyphen, a new line is started with its address and byte value displayed. %@NL@% ■ Press ENTER to terminate the %@AB@%e%@AE@% command. You can press ENTER at any byte position. %@TH: 11 678 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%addr%@AE@% Specifies the address of the first byte to be entered.%@AI@%list%@AE@% Specifies the byte values used for replacement. These values are inserted automatically. If an error occurs when you are using the list form of the command, no byte values are changed.%@TE: 11 678 02 34 42 @% %@NL@% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% eCS:100 %@AS@% 04BA:0100 EB.%@AE@% This example prompts you to change the value EB at CS:100. To step through the subsequent bytes without changing values, press the SPACEBAR. %@NL@% %@AS@% 04BA:0100 EB.41 10. 00. BC.%@AE@% In this example, the SPACEBAR is pressed three times. %@NL@% To return to a value at a previous address, type a hyphen. %@NL@% %@AS@% 04BA:0100 EB.41 10. 00. BC.- %@AS@% 04BA:0102 00.- %@AS@% 04BA:0101 10.%@AE@% This example returns to the address CS:101. %@NL@% %@2@%%@CR:C6A00090052 @%%@AB@%f ─ Fill Memory%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% f range list%@AE@% The %@AB@%f%@AE@% command fills the addresses in a specified range with the values in the specified list. %@NL@% %@TH: 17 1214 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%range%@AE@% Specifies the range of addresses to be filled. If %@AI@%range%@AE@% contains more bytes than the number of values in %@AI@%list%@AE@%, the debugger uses %@AI@%list%@AE@% repeatedly until all bytes in %@AI@%range%@AE@% are filled. If any of the memory in %@AI@%range%@AE@% is not valid (bad or nonexistent), an error will occur in all succeeding locations. %@AI@%list%@AE@% Specifies the list of values to fill the given %@AI@%range%@AE@%. If %@AI@%list%@AE@% contains more values than the number of bytes in %@AI@%range%@AE@%, the debugger ignores the extra values in %@AI@%list%@AE@%. %@TE: 17 1214 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% f04BA:100 L 100 42 45 52 54 41%@AE@% This example fills memory locations 04BA:100 through 04BA:1FF with the bytes specified, repeating the five values until it has filled all 100H bytes. %@NL@% %@2@%%@CR:C6A00090053 @%%@AB@%g ─ Go%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% g «=addr «addr...»»%@AE@% The %@AB@%g%@AE@% command executes the program currently in memory. If you type the %@AB@%g%@AE@% command by itself, the current program executes as if it had run outside the debugger. If you specify %@AB@%=%@AE@%%@AI@%addr%@AE@%, execution begins at the specified address. %@NL@% Specifying an optional breakpoint address causes execution to halt at the first address encountered, regardless of the position of the address in the list of addresses that halts execution or program branching. When program execution reaches a breakpoint, the default command string is executed. %@NL@% The stack (SS:SP) must be valid and have six bytes available for this command. The %@AB@%g%@AE@% command uses an %@AB@%IRET%@AE@% instruction to cause a jump to the program under test. The stack is set, and the user flags, CS register, and IP register are pushed on the user stack. (If the user stack is not valid or is too small, the operating environment may crash.) An interrupt code (0CCH) is placed at the specified breakpoint addresses. %@NL@% When the debugger encounters an instruction with the breakpoint code, it restores all breakpoint addresses listed with the %@AB@%g%@AE@% command to their original instructions. If you do not halt execution at one of the breakpoints, the interrupt codes are not replaced with the original instructions. %@NL@% %@TH: 15 990 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%=%@AE@%%@AI@%addr%@AE@% Specifies the address where execution is to begin. The equal sign (=) is needed to distinguish the starting address from the breakpoint address. %@AI@%addr%@AE@% Specifies one or more breakpoint addresses where execution is to halt. You can specify up to 10 breakpoints, but only at addresses containing the first byte of an opcode. If you attempt to set more than 10 breakpoints, an error message will be displayed. %@TE: 15 990 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% gCS:7550%@AE@% This example executes the program currently in memory until address 7550 in the CS selector is executed. The debugger then executes the default command string, removes the INT 3 trap from this address, and restores the original instruction. When you resume execution, the original instruction will be executed. %@NL@% %@2@%%@CR:C6A00090054 @%%@AB@%h ─ Hexadecimal Arithmetic%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% h word word%@AE@% The %@AB@%h%@AE@% command performs hexadecimal arithmetic on the two specified parameters. %@NL@% The debugger adds, subtracts, multiplies, and divides the second parameter and the first parameter, then displays the results on one line. The debugger does 32-bit multiplication and displays the result as doublewords. The debugger displays the result of division as a 16-bit quotient and a 16-bit remainder. %@NL@% %@TH: 3 223 02 19 57 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%word%@AE@% Specifies two 16-bit word parameters.%@TE: 3 223 02 19 57 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% h 300 100%@AE@% This example performs the calculations and displays the following: %@NL@% %@AS@% +0400 -0200 *0000 0003 /0003 0000%@AE@% %@2@%%@CR:C6A00090055 @%%@AB@%i ─ Input Byte%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% i word%@AE@% The %@AB@%i%@AE@% command inputs and displays one byte from a specified port. %@NL@% %@TH: 3 222 02 20 56 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%word%@AE@% Specifies the 16-bit port address.%@TE: 3 222 02 20 56 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% i2F8%@AE@% This example displays the byte at port address 2F8H. %@NL@% %@2@%%@CR:C6A00090056 @%%@AB@%j ─ Conditional Execute%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% j expr «"cmds"»%@AE@% The %@AB@%j%@AE@% command executes the specified commands when the specified expression is TRUE. If %@AI@%expr%@AE@% is FALSE, the debugger continues to the next command line (excluding the commands in %@AI@%cmds%@AE@%). %@NL@% The %@AB@%j%@AE@% command is useful in breakpoint commands to conditionally break execution when an expression becomes true. %@NL@% %@TH: 12 776 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%expr%@AE@% Evaluates to a Boolean TRUE or FALSE.%@AI@%cmds%@AE@% Specifies a list of debugger commands to be executed when %@AI@%expr%@AE@% is TRUE. The list must be enclosed in single or double quotation marks. You must separate optional commands with semicolons (;). You can use a single or NULL command without quotation marks.%@TE: 12 776 02 34 42 @% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% bp 167:1454 "J AX == 0;G"%@AE@% This example causes execution to break if AX does not equal zero when the breakpoint is reached. %@NL@% %@AS@% bp 167:1462 "J BY (DS:SI+3) == 40 'R;G';DG DS"%@AE@% This example displays the registers and continues execution when the byte pointed to by DS:SI +3 is equal to 40H; otherwise, it displays the descriptor table. %@NL@% %@AS@% bp 156:1455 "J (MSW AND 1) == 1 'G'"%@AE@% This example breaks execution when the breakpoint is reached in real mode. %@NL@% %@AS@% bp 156:1455 "J (MSW AND 1) 'G'" %@AE@% This example is a shortcut that produces the same results as the preceding command. %@NL@% %@2@%%@CR:C6A00090057 @%%@AB@%k ─ Backtrace Stack%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00090058 @%%@AE@%%@EH@%%@NL@% %@AS@% k «ss:bp» «cs:ip»%@AE@% This command displays the current stack frame. Each line shows the name of a procedure, its arguments, and the address of the statement that called it. The command displays four 2-byte arguments by default. The %@AB@%ka%@AE@% command changes the number of arguments displayed by this command. %@NL@% Using the %@AB@%k%@AE@% command at the beginning of a function (before the function prolog has been executed) will give incorrect results. The command uses the BP register to compute the current backtrace, and this register is not correctly set for a function until its prolog has been executed.%@CR:C6A00090059 @%%@NL@% %@TH: 4 289 02 17 59 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%ss:bp%@AE@% Specifies an optional stack-frame address.%@AI@%cs:ip%@AE@% Specifies an optional code address.%@TE: 4 289 02 17 59 @% %@2@%%@CR:C6A00090060 @%%@AB@%ka ─ Set Backtrace Arguments%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00090061 @%%@AE@%%@EH@%%@NL@% %@AS@% ka value%@AE@% The %@AB@%ka%@AE@% command sets the number of parameters displayed for all subsequent stack trace commands. The initial default is four. %@NL@% %@TH: 6 399 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%value%@AE@% Specifies the number of parameters to be displayed. The %@AI@%value%@AE@% parameter must be in the range 0 to 31.%@TE: 6 399 02 34 42 @% %@2@%%@CR:C6A00090062 @%%@AB@%kt ─ Backtrace Task Stack%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00090063 @%%@CR:C6A00090064 @%%@AE@%%@EH@%%@NL@% %@AS@% kt «tdb»%@AE@% This command displays the stack frame of the current task or the task specified by %@AI@%tdb%@AE@%. Each line shows the name of a procedure, its arguments, and the address of the statement that called it. The command displays four 2-byte arguments by default. The %@AB@%ka%@AE@% command changes the number of arguments displayed by this command. %@NL@% This command can be combined with the %@AB@%kv%@AE@% command; the syntax for the combined command is %@AB@%kvt%@AE@% «%@AI@%tdb%@AE@%». %@NL@% %@TH: 10 743 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%tdb%@AE@% Specifies the segment address of the program descriptor block for the task to be traced. To obtain the %@AI@%tdb%@AE@% value, use the .%@AB@%dq%@AE@% (Dump Task Queue) command. If %@AI@%%@AE@% %@AI@%tdb%@AE@% is not supplied, the %@AB@%kt%@AE@% command displays the stack frame of the current task. %@CR:C6A00090065 @%%@TE: 10 743 02 34 42 @% %@2@%%@CR:C6A00090066 @%%@AB@%kv ─ Verbose Backtrace Stack%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@CR:C6A00090067 @%%@AE@%%@EH@%%@NL@% %@AS@% kv %@AE@% The %@AB@%kv%@AE@% command displays information that the %@AB@%k %@AE@%(Backtrace Stack) command provides, plus information about stack location and frame pointer values for each frame. %@NL@% %@2@%%@CR:C6A00090068 @%%@AB@%la ─ List Absolute Symbols%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% la%@AE@% The %@AB@%la%@AE@% command lists the absolute symbols in the currently active map. %@NL@% %@2@%%@CR:C6A00090069 @%%@AB@%lg ─ List Groups%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% lg%@AE@% The %@AB@%lg%@AE@% command lists the selector (or segment) and the name of each group in the active map. %@NL@% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% lg%@AE@% This example produces a display similar to the following: %@NL@% %@AS@% #0090:0000 DOSCODE %@AS@% #0828:0000 DOSGROUP %@AS@% #1290:0000 DBGCODE %@AS@% #16C0:0000 DBGDATA %@AS@% #1A38:0000 TASKCODE %@AS@% #1AD8:0000 DOSRING3CODE %@AS@% #1AE0:0000 DOSINITCODE %@AS@% #2018:0000 DOSINITRMCODE %@AS@% #20A8:0000 DOSINITDATA %@AS@% #23F8:0000 DOSMTE %@AS@% #2420:0000 DOSHIGHDATA %@AS@% #28D0:0000 DOSHIGHCODE %@AS@% #3628:0000 DOSHIGH2CODE %@AS@% #0090:0000 DOSCODE%@AE@% %@2@%%@CR:C6A00090070 @%%@AB@%lm ─ List Map%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% lm%@AE@% The %@AB@%lm%@AE@% command lists the symbol files currently loaded and indicates which one is active. %@NL@% The last symbol file loaded is made active by default. Use the %@AB@%w%@AE@% (Change Map) command to change the active file. %@NL@% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% lm%@AE@% This example returns a display similar to the following: %@NL@% %@AS@% COMSAM2D is active. %@AS@% DISK01D.%@AE@% %@2@%%@CR:C6A00090071 @%%@AB@%ln ─ List Near%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% ln «addr»%@AE@% The %@AB@%ln%@AE@% command lists the symbol nearest to the specified address. The command lists the nearest symbol before and after the specified %@AI@%addr%@AE@% parameter. %@NL@% %@TH: 6 374 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%addr%@AE@% Specifies any valid instruction address. The default is the current disassembly address.%@TE: 6 374 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% ln%@AE@% This example displays the nearest symbols before and after the current disassembly address. The output looks like this: %@NL@% %@AS@% 6787 VerifyRamSemAddr + 10 %@AS@% 67AA PutRamSemID - 13%@AE@% %@2@%%@CR:C6A00090072 @%%@AB@%ls ─ List Symbols%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% ls {group-name | name-chars | *}%@AE@% The %@AB@%ls%@AE@% command lists the symbols in the specified group, or names that match the search specification in all groups. Only the * wildcard is accepted and only as the last character (all other characters will be ignored). %@NL@% %@TH: 8 463 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%group-name%@AE@% Names the group that contains the symbols you want to list. %@AI@%name-chars%@AE@% Displays a list of symbols that begin with the specified characters.%@TE: 8 463 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% ls DOSRING3CODE %@AS@% ls vkd* %@AS@% ls vmm_base%@AE@% The first example displays all of the symbols in the DOSRING3CODE group. The debugger displays the symbols in a format similar to the following: %@NL@% %@AS@% 0000 Sigdispatch %@AS@% 001A LibInitDisp%@AE@% The second example displays all of the symbols that start with the first three characters "vkd." This will show the group names as they are searched, similar to the following: %@NL@% %@AS@% GROUP: [0028] CODE %@AS@% 60003A74 VKD_Control_Debug %@AS@% GROUP: [0030] DATA %@AS@% 6001DFFC VKD_CB_Offset %@AS@% GROUP: [0030} IDATA%@AE@% The third example displays the address and group for the symbol "VMM_base." %@NL@% %@2@%%@CR:C6A00090073 @%%@AB@%m ─ Move Memory%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% m range addr%@AE@% The %@AB@%m%@AE@% command moves a block of memory from one memory location to another. %@NL@% Overlapping moves─those where part of the block overlaps some of the current addresses─are always performed without loss of data. Addresses that could be overwritten are moved first. For moves from higher to lower addresses, the sequence of events is first to move the data at the block's lowest address and then to work toward the highest. For moves from lower to higher addresses, the sequence is first to move the data at the block's highest address and then to work toward the lowest. %@NL@% Note that if the addresses in the block being moved will not have new data written to them, the data in the block %@AI@%before the move%@AE@% will remain. The %@AB@%m%@AE@% command copies the data from one area into another, in the sequence described, and writes over the new addresses─hence, the importance of the moving sequence. %@NL@% To review the results of a memory move, use the %@AB@%d%@AE@% (Display Memory) command, specifying the same address you used with the %@AB@%m%@AE@% command. %@NL@% %@TH: 8 443 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%range%@AE@% Specifies the block of memory to be moved.%@AI@%addr%@AE@% Specifies the starting address where the memory is to be relocated.%@TE: 8 443 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% mCS:100 110 CS:500%@AE@% This example first moves address CS:110 to CS:510 and then moves CS:10F to CS:50F, and so on, until CS:100 is moved to CS:500. %@NL@% %@2@%%@CR:C6A00090074 @%%@AB@%o ─ Output to Port%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% o word byte%@AE@% The %@AB@%o%@AE@% command writes a byte to a 16-bit port address. %@NL@% %@TH: 4 306 02 13 63 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%word%@AE@% Specifies the 16-bit port address you are writing to. %@AI@%byte%@AE@% Specifies the 8-bit value to be written to the port.%@TE: 4 306 02 13 63 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% o 2F8 4F%@AE@% This example writes the byte value 4F to output port 2F8. %@NL@% %@2@%%@CR:C6A00090075 @%%@AB@%p ─ Program Trace%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% p«N» «=addr »«count»%@AE@% The %@AB@%p%@AE@% command executes the instruction at a specified address and displays the current values of all the registers and flags (whatever the %@AB@%z%@AE@% command has been set to). It then executes the default command string, if any. %@NL@% The %@AB@%p%@AE@% command is identical to the %@AB@%t%@AE@% (Trace Instructions) command, except that it automatically executes and returns from any calls or software interrupts it encounters. The %@AB@%t%@AE@% command always stops after executing into the call or interrupt, leaving execution control inside the called routine. %@NL@% %@TH: 24 1630 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%N%@AE@% Suppresses the register display so just the assembly line is displayed. The suppression will result only if the default command, %@AB@%z%@AE@%, is set to a normal setting, %@AB@%r%@AE@%.%@AI@%addr%@AE@% Specifies the starting address to begin execution. If you omit the optional %@AI@%addr%@AE@%, execution begins at the instruction pointed to by the CS and IP registers. Use the equal sign (=) only if you specify an %@AI@%addr%@AE@%. %@AI@%count%@AE@% Specifies the number of instructions to execute before halting and executing the default command string. If you specify %@AI@%%@AE@% %@AI@%count%@AE@%, the command continues to execute %@AI@%%@AE@% %@AI@%count%@AE@% instructions before stopping. The command executes the default command string for each instruction before executing the next. %@TE: 24 1630 02 34 42 @% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% p%@AE@% This example executes the instruction pointed to by the current CS and IP register values before it executes the default command string. %@NL@% %@AS@% p=120%@AE@% This example executes the instruction at address CS:120 before it executes the default command string. %@NL@% %@2@%%@CR:C6A00090076 @%%@AB@%r ─ Display Registers%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% r reg =word%@AE@% The %@AB@%r%@AE@% command displays the contents of one or more CPU registers and allows the contents to be changed to new values. If you specify a %@AI@%reg%@AE@% with the %@AB@%r%@AE@% command, the 16-bit value of that register is displayed in hexadecimal followed by a colon (:) prompt on the next line. You can then enter a new %@AI@%word%@AE@% value for the specified register or press ENTER if you do not want to change the register value. %@NL@% If you use %@AB@%f%@AE@% for %@AI@%reg%@AE@%, the debugger displays the flags in a row at the beginning of a new line and displays a hyphen (-) after the last flag. %@NL@% You can type new flag values in any order as alphabetic pairs. You do not have to leave spaces between these values. To exit the %@AB@%r%@AE@% command, press ENTER. Any flags for which you did not specify new values remain unchanged. %@NL@% If you type more than one value for a flag, or if you enter an invalid flag name, the debugger returns a "Bad Flag" error message. In both cases, the flags up to the error in the list are changed; those flags at and after the error are not changed. %@NL@% %@TH: 53 1723 02 11 32 33 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%reg%@AE@% Specifies the register to be displayed. If you omit %@AI@%reg%@AE@%, the debugger displays the contents of all registers and flags along with the next executable instruction.%@AI@%word%@AE@% Specifies the new value for the register. For the Flags register, set or clear a flag by using one of the following names: Flag Name Action OV Overflow set NV Overflow clear DN Direction decrement UP Direction increment EI Interrupt enabled DI Interrupt disabled NG Sign negative PL Sign positive ZR Zero set NZ Zero clear Flag Name Action AC Auxiliary Carry set NA Auxiliary Carry clear PE Parity even PO Parity odd CY Carry set NC Carry clear NT Nested Task toggle on and off%@TE: 53 1723 02 11 32 33 @% For the MSW register, use the following names to set a flag: %@NL@% %@TH: 6 356 02 17 59 @%Flag Name Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%TS Sets the task switch bit.EM Sets the emulation processor extension bit.MP Sets the monitor processor extension bit.PM Sets the protected mode bit.%@TE: 6 356 02 17 59 @% %@3@%%@AB@%Comments%@AE@%%@EH@%%@NL@% Setting the protected-mode bit from within the debugger does %@AI@%not%@AE@% set the target system to run in protected mode. The debugger simulates the setting. To configure the target system to run in protected mode, you would have to set the PM bit in the MSW register and reset the target system to boot in protected mode. %@NL@% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% r%@AE@% This example produces the following display: %@NL@% %@AS@% AX=0698 BX=2008 CX=2C18 DX=18AB SP=1B7A BP=00FF SI=0020 DI=10CD %@AS@% IP=0450 CS=18B0 DS=1BE8 ES=0DA8 SS=0048 NV UP DI PL NZ NA PO NC %@AS@% GDTR=01BE80 3687 IDTR=01F508 03FF TR=0010 LDTR=0028 IOPL=3 MSW=PM %@AS@% 18B0:0450 C3 RET %@AE@% %@AS@% rf%@AE@% This example displays each flag with a two-character alphabetic code. To change any flag, type the opposite two-letter code. The flags are either set or cleared. This example produces a display similar to the following: %@NL@% %@AS@% NV UP DI NG NZ AC PE NC - _%@AE@% To change the value of a flag's setting, enter an opposite setting for the flag you wish to set. %@NL@% %@AS@% NV UP DI NG NZ AC PE NC - PLEICY%@AE@% This example changes the sign flag to positive, enables interrupts, and sets the carry flag. %@NL@% %@AS@% rmsw%@AE@% This example modifies the MSW (Machine Status Word) bits. The debugger displays the status of the MSW register and prints a colon on the next line. %@NL@% %@2@%%@CR:C6A00090077 @%%@AB@%s ─ Search Bytes%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% s range { list | "string" }%@AE@% The %@AB@%s%@AE@% command searches an address range for a specified list of bytes or an ASCII character string. %@NL@% You can include one or more bytes in %@AI@%list%@AE@%, but multiple bytes must be separated by a space or comma. When you search for more than one byte, the command returns only the first address of the byte string. When your %@AI@%list%@AE@% contains only one byte, the debugger displays all addresses of the byte in the %@AI@%range%@AE@%. %@NL@% %@TH: 12 652 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%range%@AE@% Specifies the range of addresses to be searched.%@AI@%list%@AE@% Specifies one or more byte values to search for.%@AI@%string%@AE@% Specifies an ASCII character string to be searched for. The string must be enclosed in quotation marks.%@TE: 12 652 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% sCS:100 110 41%@AE@% This example searches for byte 41 in the range CS:100 to CS:110. If it finds the value, the command produces a display similar to the following: %@NL@% %@AS@% 04BA:0104 %@AS@% 04BA:010D%@AE@% %@2@%%@CR:C6A00090078 @%%@AB@%t ─ Trace Instructions%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% t«N» «=addr» «word»%@AE@% The %@AB@%t%@AE@% command executes one or more instructions along with the default command string, then displays the decoded instruction. If you include an %@AI@%addr%@AE@% parameter, tracing starts at the specified address. Otherwise, the command steps through the next machine instruction and then executes the default command string. %@NL@% The %@AB@%t%@AE@% command uses the hardware trace mode of the Intel microprocessor. Consequently, you can also trace instructions stored in ROM. %@NL@% %@TH: 14 835 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%N%@AE@% Suppresses the register display so just the assembly line is displayed. This works only if the default command, %@AB@%z%@AE@%, is set to %@AB@%r%@AE@% (the normal setting).%@AI@%addr%@AE@% Specifies the instruction address to start tracing. The equal sign (=) is required.%@AI@%word%@AE@% Specifies the number of instructions to execute and trace.%@TE: 14 835 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% t%@AE@% %@AS@% AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 SI=005C DI=0000 %@AS@% IP=011A CS=04BA DS=04BA ES=04BA SS=04BA NV UP DI NG NZ AC PE NC %@AS@% GDTR=01D700 3677 IDTR=020D7A 03FF TR=0010 LDTR=0028 IOPL=3 MSW=PM %@AS@% 04BA:011A CD21 PUSH 21%@AE@% This example traces the current position (04BA:011A) and uses the default command string (%@AB@%r%@AE@% command) to display registers. %@NL@% %@AS@% t=011A 10%@AE@% This command causes the debugger to execute 16 (10H) instructions beginning at 011A in the current selector. The debugger executes and displays the results of the default command string for each instruction. The display scrolls until the last instruction is executed. Use CONTROL+S to stop the display from scrolling, and CONTROL+Q to resume. %@NL@% %@2@%%@CR:C6A00090079 @%%@AB@%u ─ Unassemble Bytes%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% u range%@AE@% The %@AB@%u%@AE@% command disassembles bytes and displays the source statements, with addresses and byte values, that correspond to them. %@NL@% The display of disassembled code looks similar to a code listing for an assembled file. If you type the %@AB@%u%@AE@% command by itself, 20H bytes are disassembled at the first address after the one displayed by the previous %@AB@%u%@AE@% command. %@NL@% %@TH: 7 479 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%range%@AE@% Specifies the range of addresses in which instructions are to be disassembled. If no %@AI@%range%@AE@% is given, the command disassembles the next 20H bytes.%@TE: 7 479 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% uCS:046C%@AE@% This example returns a display similar to the following: %@NL@% %@AS@% 1A60:046C C3 RET %@AS@% 1A60:046D 9A6B3E100D CALL 0D10:3E6B %@AS@% 1A60:0472 33C0 XOR AX,AX %@AS@% 1A60:0474 50 PUSH AX %@AS@% 1A60:0475 9D POPF %@AS@% 1A60:0476 9C PUSHF %@AS@% 1A60:0477 58 POP AX %@AS@% 1A60:0478 2500F0 AND AX,F000 %@AS@% 1A60:047B 3D00F0 CMP AX,F000 %@AS@% 1A60:047E 7508 JNZ 0488 %@AS@% 1A60:0480 689C26 PUSH 269C %@AS@% 1A60:0483 9AF105100D CALL 0D10:05F1 %@AE@% If the bytes in some addresses are altered, the disassembler alters the instruction statements. You can also use the %@AB@%u%@AE@% command for the changed locations, for the new instructions viewed, and for the disassembled code used to edit the source file. %@NL@% %@2@%%@CR:C6A00090080 @%%@AB@%v ─ Set Interrupt Vector Trapping%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% v«1 | 3»%@AE@% The %@AB@%v%@AE@% command is used to specify which privilege rings should have interrupts 1 and 3 trapped. This is useful for allowing the 80386 Debugger to coexist with other debuggers such as the Symbolic Debugger (%@AB@%SYMDEB%@AE@%) and CodeView for Windows (%@AB@%CVW%@AE@%). The 80386 Debugger handles interrupts 1 and 3 which occur in any privilege rings where trapping is enabled, but reflects the interrupts if trapping is disabled, so that the secondary debugger will see them. To use the command, enter v1 or v3 as the command with no parameters. %@AB@%WDEB386%@AE@% then displays the current rings for which trapping is enabled. For example: %@NL@% %@AS@% #v1 %@AS@% Rings trapped for int 1 - 0 1 2 3 V %@AS@% ? +%@AE@% The question mark (?) is displayed to prompt you for changes. The plus sign (+) indicates that you are in enabling mode, so you can just press 0, 1, 2, 3, or V to enable trapping in the required ring. If you need to disable trapping in any rings, then press HYPHEN ( - ); this will change the plus sign to a minus sign, indicating that you are now disabling trapping. Pressing PLUS SIGN ( + ) will get you back into enabling mode. Any number of changes can be made at one time. The current mode is displayed after each change. For example: %@NL@% %@AS@% #v1 %@AS@% Rings trapped for int 1 - 0 2 V %@AS@% ? +1 +3 -2 -%@AE@% This command sequence was created by pressing 1, 3, HYPHEN, 2, and ENTER or the SPACEBAR. It enabled trapping INT 1 instructions in rings 1 and 3 and disabled trapping in ring 2. %@NL@% %@2@%%@CR:C6A00090081 @%%@AB@%vl ─ Display Interrupt Trapping Information%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% vl%@AE@% This command shows which privilege rings have trapping enabled for interrupts 1 and 3. The %@AB@%v%@AE@% command can be used to enable or disable trapping in specific privilege rings. %@NL@% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% vl %@AS@% Rings trapped for int 1 - 0 1 2 3 V %@AS@% Rings trapped for int 3 - 0 1 2 3 V%@AE@% %@2@%%@CR:C6A00090082 @%%@AB@%w ─ Change Map%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% w «map-name»%@AE@% The %@AB@%w%@AE@% command changes the active map file. %@NL@% %@TH: 12 768 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%map-name%@AE@% Specifies the name of the map file you want to make active. Use the %@AB@%lm%@AE@% (List Map) command to display a list of available map files. If %@AI@%map-name%@AE@% is not specified, then the loaded maps are displayed and the user is prompted to select a map by pressing its corresponding option number.%@TE: 12 768 02 34 42 @% %@3@%%@AB@%Examples%@AE@%%@EH@%%@NL@% %@AS@% lm %@AS@% COMSAM2D is active. %@AS@% DISK01D. %@AS@% w DISK01D%@AE@% The first example displays the loaded map files using the %@AB@%lm%@AE@% command, then sets the active map file to DISK01D. %@NL@% %@AS@% W %@AS@% 1. KERNEL %@AS@% 2. Win386 is active %@AS@% activate which map?%@AE@% The second example shows selecting the desired map from the list of available maps. At the prompt, pressing 1 will activate the KERNEL map; pressing 2 will leave the Win386 map activated; pressing the SPACEBAR will leave the current map activated; any other key will be ignored and the debugger will continue to wait for input. %@NL@% %@2@%%@CR:C6A00090083 @%%@AB@%y ─ Debugger Option Command%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% y [? | 386env | dislwr | regterse | codebytes | symaddrs]%@AE@% This command allows the debugger configuration to be changed. The %@AB@%?%@AE@% option prints the current options supported. The %@AB@%y%@AE@% command by itself prints the current state of the options. The %@AB@%y%@AE@% and a flag name sets or toggles an options flag. %@NL@% %@AS@% 386env - 32 bit environment (toggles) %@AS@% dislwr - lower case disassembly (toggles) %@AS@% regterse - terse register set (toggles) %@AS@% codebytes - terse instruction disassembly (toggles) %@AS@% symaddrs - symbols and addresses (toggles)%@AE@% All these flags toggle their state when set and are printed only when the option is on. %@NL@% The %@AB@%386env%@AE@% flag controls the size of addresses and registers, when displayed. When this option is on, addresses, registers, etc., are printed in 32-bit formats; otherwise they are printed in 16-bit formats. This flag has nothing to do with the CPU (286/386) the debugger is running on, only the display sizes. %@NL@% The %@AB@%dislwr%@AE@% flag controls the disassembler's lowercase option. When the flag is on, disassembly is in lowercase. %@NL@% The %@AB@%regterse%@AE@% flag controls the number of registers that are displayed in the register dump command. In the 386 environment (%@AB@%386env%@AE@% on), when the %@AB@%regterse%@AE@% flag is on, only the first three lines are displayed (instead of the normal six-line-plus disassembly line display). In the 286 environment (%@AB@%386env%@AE@% off), only the first two lines of the normal three-line display (plus the disassembly line) are printed. %@NL@% The %@AB@%codebytes%@AE@% flag controls the display of the actual code bytes when disassembling. %@NL@% The %@AB@%symaddrs%@AE@% flag controls showing just a symbol name or symbol name and address when disassembling. %@NL@% %@2@%%@CR:C6A00090084 @%%@AB@%z ─ Zap Embedded INT 1 and INT 3 Instructions%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% z%@AE@% Zaps the current INT 3 or the previous INT 1 instruction, by replacing the instruction bytes with NOP instructions. This allows the user to avoid INT 1 or INT 3 instructions that were assembled into the executable file from breaking into the debugger more than once. %@NL@% %@2@%%@CR:C6A00090085 @%%@AB@%zd ─ Execute Default Command String%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% zd%@AE@% The %@AB@%zd%@AE@% command executes the default command string. %@NL@% The default command string is initially set to the %@AB@%r%@AE@% (Display Registers) command by the debugger. The default command string is executed every time a breakpoint is encountered during program execution or whenever a %@AB@%p%@AE@% (Program Trace) or %@AB@%t%@AE@% (Trace Instructions) command is executed. %@NL@% Use the %@AB@%zl%@AE@% command to display the default command string and the %@AB@%zs%@AE@% command to change the default command string. %@NL@% %@2@%%@CR:C6A00090086 @%%@AB@%zl ─ Display Default Command String%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% zl%@AE@% The %@AB@%zl%@AE@% command displays the default command string. %@NL@% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% zl %@AS@% "R"%@AE@% This example displays the default command string. %@NL@% %@2@%%@CR:C6A00090087 @%%@AB@%zs ─ Change Default Command String%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@3@%%@AB@%Syntax%@AE@%%@EH@%%@NL@% %@AS@% zs "string"%@AE@% The %@AB@%zs%@AE@% command lets you change the default command string. %@NL@% %@TH: 8 536 02 34 42 @%Parameter Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AI@%string%@AE@% Specifies the new default command string. The string must be enclosed in single or double quotation marks. You must separate the debugger commands within the string with semicolons.%@TE: 8 536 02 34 42 @% %@3@%%@AB@%Example%@AE@%%@EH@%%@NL@% %@AS@% zs "r;c100 L 100 300"%@AE@% This example changes the current default command string to an %@AB@%r%@AE@% (Display Register) command followed by a %@AB@%c%@AE@% (Compare Memory) command. %@NL@% %@AS@% zs "j (by cs:ip) == cc 'g'"%@AE@% This example begins execution whenever an INT 3 instruction is executed in your test program. This will execute a %@AB@%g%@AE@% (Go) command every time an INT 3 instruction is executed. %@NL@% You can use %@AB@%zs%@AE@% to set up a watchpoint as follows: %@NL@% %@AS@% zs "j (wo 40:1234) == 0eeed;t"%@AE@% This command traces until the word at 40:1234 is %@AI@%not%@AE@% equal to 0EEED. This won't work if you are tracing through the mode switching code in DOS or other sections of code that can't be traced. %@NL@% %@2@%%@CR:C6A00090088 @%%@AB@%9.6 386 Enhanced Windows Environment Commands%@AE@%%@EH@%%@NL@% These commands are specific to the operating environment of Windows running in 386 enhanced mode. These commands are always dot commands, and are in addition to the common commands documented in the previous section. %@NL@% All of these commands are listed when the %@AB@%.?%@AE@% command is executed. %@NL@% %@TH: 120 7389 02 34 42 @%Command Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%.DG%@AE@% Calls Windows to dump its global heap when Windows is installed.%@AB@%.DF%@AE@% Calls Windows to dump its free list when Windows is installed. %@AB@%.DL%@AE@% Calls Windows to dump the LRU list when Windows is installed. %@AB@%.VM%@AE@% Displays the status of the current virtual machine (VM). Status information includes reentry count, VM handle, critical section state, client registers, and top entries from the client's stack.%@AB@%.VC%@AE@% Displays the standard fields of the current VM's control block.%@AB@%.VH%@AE@% Displays the current VM's handle.%@AB@%.VR%@AE@% Displays the current VM's client registers, if the debugger is in protected mode.%@AB@%.VS%@AE@% Displays the current VM's virtual mode stack, if the debugger is in protected mode.%@AB@%.VL%@AE@% Displays a list of all valid VM handles.%@AB@%.T%@AE@% Toggles the fault logging flag. When fault logging is turned on, all system faults (hardware interrupts, general protection faults, page faults, illegal instruction faults, and so on) are logged, with the registers at the time of the fault, and so on. This list of logged faults can then be viewed with the %@AB@%.S%@AE@%, %@AB@%.SS,%@AE@% or %@AB@%.SL%@AE@% commands.%@AB@%.S%@AE@% [%@AI@%item_num%@AE@%] Displays fault logging information in a single line-condensed form. If an %@AI@%%@AE@% %@AI@%item_num%@AE@% parameter is given, then the list starts with the specified log item; otherwise it starts with the last (most recent) log item. The list is displayed from most recent to less recent order. It displays item number, fault number, VM handle at the time of fault, critical section state, client's CS:IP; and, in the case of general protection faults, the executed instruction. The display will look like the following: %@AS@%= 00003BB8: 000D 60441000 00 01 %@AE@% %@AS@%02B7:23F5 INT 2A 00008002%@AE@% The first number (00003BB8) is the log item number. The second number (000D) is the fault (interrupt) number (0Dh = General Protection). The next number (60441000) is the VM handle of the VM interrupted. The next two numbers (00) and (01) are the critical section claim counts at the start and end of the fault handling. So, in this example, the critical section was unclaimed on entry, but the fault handler claimed it before exiting. The next number (02B7:23F5) is the client's CS:IP at the time of the interrupt. (INT 2A) is the instruction that the client attempted to execute, causing the protection fault. The last number (00008002) is the value of EAX register. This number is given since it is commonly used for software interrupt function number selection, and since all software interrupts done in virtual 8086 mode will show in this log. This allows the programmer to see the most about each fault in a single line. When the faulting instruction is an IN or OUT instruction, DX and EAX will be displayed as appropriate. After each screenful of display, the debugger pauses, waiting for the user to press a key to continue. Pressing ESCAPE or CONTROL+C aborts any further listing. This command clears the fault logging flag, to disable further logging.%@AB@%.SL%@AE@% [%@AI@%item_num%@AE@%] Displays complete fault logging information. If a log item number is specified, then just the one fault's information is displayed, starting with the condensed line, then the register state at the start of the fault, and then the register state at the end. If no item number is specified, then all log items are displayed, starting with the last log item. This list shows the log number, fault number, VM handle, client registers, and instruction (if the item is the end-of-fault item.) Screen handling is performed exactly as in the %@AB@%.S%@AE@% command.%@AB@%.DS%@AE@% Dumps the protected-mode stack and displays near code segment labels (if available) next to each%@AB@% DWORD%@AE@% from the stack.%@TE: 120 7389 02 34 42 @% The following %@AB@%M%@AE@%%@AI@%x%@AE@% commands are for debugging the 386-enhanced-mode Windows environment memory manager. They are probably of little use to other programmers. %@NL@% %@TH: 45 2449 02 34 42 @%Command Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%.MH%@AE@% [%@AI@%handle%@AE@%] Displays the 386-enhanced-mode Windows heap information about a specific handle, if specified; otherwise global information is displayed.%@AB@%.MM%@AE@% [%@AI@%handle%@AE@%] Displays the 386-enhanced-mode Windows memory information, such as free and locked pages, if no handle is specified. Otherwise, it displays information about the memory handle such as size and linear address.%@AB@%.MV%@AE@% Displays the memory handles that are allocated to the current VM.%@AB@%.MS PFT%@AE@%%@AI@%addr%@AE@% Displays PFT (paged memory) information.%@AB@%.MF%@AE@% Displays the current free list.%@AB@%.MI%@AE@% Displays instanced data regions.%@AB@%.VMM%@AE@% This command displays a menu of subcommands. Pressing a single character selects and executes the listed command.%@AB@%.device-name%@AE@% This command calls the indicated virtual device so that it can dump information relevant for debugging it.%@AB@%.LQ%@AE@% Displays queue outs from the most recent.%@AB@%.ML%@AE@% %@AI@%lin_addr%@AE@% Displays page-table information for the given linear address.%@AB@%.MP%@AE@% %@AI@%phys_addr%@AE@% Displays all linear addresses that map the given physical address.%@AB@%.MD%@AE@% Changes the debug MONO paging display.%@AB@%MO%@AE@% Schedules a page-out event of all present pages that are not locked.%@TE: 45 2449 02 34 42 @% %@2@%%@CR:C6A00090089 @%%@AB@%9.7 Summary%@AE@%%@EH@%%@NL@% The 80386 Debugger is a tool that lets you debug Windows applications in protected (standard or 386 enhanced) mode on systems with an 80386 CPU. It offers more advanced debugging features not available in CodeView for Windows, but lacks %@AB@%CVW%@AE@%'s more convenient user interface. %@NL@% For more information related to the 80386 Debugger, see the following: %@NL@% %@AB@%Topic%@AE@% %@AB@%Reference%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Programming Windows applications %@AI@%Guide to Programming%@AE@% System requirements %@AI@%Installation and Update Guide%@AE@% %@CR:C6A00100001 @%%@1@%%@AB@%Chapter 10 Monitoring Messages: Spy%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Microsoft Windows Spy (%@AB@%SPY%@AE@%) monitors system messages sent to a specified application window. Spy records the messages and displays them on a specified device.%@CR:C6A00100002 @%%@CR:C6A00100003 @%%@NL@% Spy is useful for verifying that the messages you think a window is receiving are being received. It is also helpful for examining the values of message parameters. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%If you are using CodeView for Windows to debug your application, you can use %@AI@%CodeView instead of Spy to trace messages.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% This chapter describes the following: %@NL@% ■ Displaying messages%@NL@% ■ Choosing options%@NL@% ■ Choosing a window%@NL@% ■ Turning Spy on and off %@NL@% %@2@%%@CR:C6A00100004 @%%@AB@%10.1 Displaying Messages%@AE@%%@EH@%%@NL@% To watch messages, do the following:%@CR:C6A00100005 @%%@NL@% 1. Choose the Options menu to display the Options dialog box and select the following: ■ The kind of message you want to watch%@NL@% ■ The output device to which you want messages to go%@NL@% ■ Whether you want Spy to display messages synchronously or asynchronously%@NL@% %@NL@% 2. Select the window whose messages you want to watch by choosing the Window command from the Window menu.%@NL@% 3. Click the window you want to watch. To stop watching messages, choose the Spy Off command from the Spy menu.%@NL@% Figure 10.1 illustrates the Spy window. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@2@%%@CR:C6A00100006 @%%@AB@%10.2 Choosing Options%@AE@%%@EH@%%@NL@% The Options menu displays a dialog box that offers you the following choices: %@NL@% ■ The kind of message you want to watch%@NL@% ■ The output device to which you want samples to go%@NL@% ■ Whether or not Spy sends samples to the output device synchronously or asynchronously%@NL@% The following sections describe how to choose these options. %@NL@% %@3@%%@CR:C6A00100007 @%%@AB@%10.2.1 Choosing Messages%@AE@%%@EH@%%@NL@% The Options menu displays a dialog box that offers the following choices:%@CR:C6A00100008 @%%@NL@% %@AB@%Message%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Mouse Mouse-related messages, such as WM_MOUSEMOVE and WM_SETCURSOR. Input Input-related messages, such as WM_CHAR and WM_COMMAND. System System-wide messages, such as WM_ENDSESSION and WM_TIMECHANGE. %@AB@%Message%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Window Window manager messages, such as WM_SIZE and WM_SHOWWINDOW. Init Initialization messages, such as WM_INITMENU and WM_INITDIALOG. Clipboard Clipboard messages, such as WM_RENDERFORMAT. Other Messages other than the types explicitly listed. DDE Dynamic Data Exchange messages, such as WM_DDE_REQUEST. Non Client Windows nonclient messages, such as WM_NCDESTROY and WM_NCHITTEST. By default, Spy monitors all messages.%@CR:C6A00100009 @%%@CR:C6A00100010 @%%@CR:C6A00100011 @%%@CR:C6A00100012 @%%@CR:C6A00100013 @%%@CR:C6A00100014 @%%@NL@% %@3@%%@CR:C6A00100015 @%%@AB@%10.2.2 Choosing the Output Device%@AE@%%@EH@%%@NL@% You can specify that Spy send messages to the following output devices:%@CR:C6A00100016 @%%@NL@% %@AB@%Device%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Window Spy displays messages in the Spy window. You can specify how many messages Spy stores in its buffer. By default, it stores 100 lines of messages which you can view by scrolling through the Spy window. Com1 Spy sends messages to the COM1 port. File Spy sends messages to the specified file. The default output file is SPY.OUT. %@3@%%@CR:C6A00100017 @%%@AB@%10.2.3 Choosing Frequency of Output%@AE@%%@EH@%%@NL@% The following options specify whether Spy sends messages to the output device as Spy receives them, or queues messages before sending them:%@CR:C6A00100018 @%%@NL@% %@AB@%Option%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Synchronous Spy displays messages as it receives them. Asynchronous Spy queues messages for display. By default, Spy sends messages synchronously.%@CR:C6A00100019 @%%@NL@% %@2@%%@CR:C6A00100020 @%%@AB@%10.3 Choosing a Window: The Window Menu%@AE@%%@EH@%%@NL@% After specifying message options, use the Window menu to choose the window you want Spy to watch. The Window menu contains the following commands:%@CR:C6A00100021 @%%@CR:C6A00100022 @%%@NL@% %@AB@%Command%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Window... Specifies the window that Spy watches. When you choose the Window... command, Spy displays a dialog box that contains information for the window in which the cursor is located. As you move the cursor from window to window, the following information changes: ■ Window─Handle to the window ■ Class─Window class ■ Module─Program that created the window ■ Parent─Handle to the parent window and the name of the program that created the parent window ■ Rect─Upper-right and lower-left coordinates of the window and the window size in screen coordinates ■ Style─Style bits of the window under the cursor, the principal style of the window, and an identifier, if the window is a child window. The principal style can be WS_POPUP, WS_ICONIC, WS_OVERLAPPED, or WS_CHILD. All Windows Specifies that Spy watches all windows. Choose the All Windows command again to direct Spy to stop watching all windows. Clear Window Clears the Spy window of messages. %@2@%%@CR:C6A00100023 @%%@AB@%10.4 Turning Spy On and Off: The Spy Menu%@CR:C6A00100024 @%%@AE@%%@EH@%%@NL@% After selecting a window to monitor, turn Spy on by clicking the window and choosing OK in the dialog box. %@NL@% To stop monitoring messages, or to resume monitoring messages, or to exit Spy, use the Spy menu. The Spy menu contains the following commands: %@NL@% %@AB@%Command%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Spy On/Off Starts and stops message monitoring. Exit Exits Spy. About Spy... Provides information about the version of Spy you are using. %@2@%%@CR:C6A00100025 @%%@AB@%10.5 Summary%@AE@%%@EH@%%@NL@% Spy is a tool that lets you monitor messages sent to a specified window. For more information about topics related to Spy, see the following: %@NL@% %@AB@%Topic%@AE@% %@AB@%Reference%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Input messages %@AI@%Guide to Programming%@AE@%: Chapter 4, "Keyboard and Mouse Input" %@AI@%%@AE@% Message syntax and content %@AI@%Reference, Volume 1%@AE@%: Chapter 6, "Messages Directory" %@AI@%%@AE@% %@CR:C6A00110001 @%%@1@%%@AB@%Chapter 11 Viewing the Heap: Heap Walker%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Microsoft Windows Heap Walker (%@AB@%HEAPWALK%@AE@%) lets you examine the global heap, the system memory that DOS reserves for Windows use. The utility displays information about memory segments, or objects. Heap Walker is useful for analyzing the effects your application has when it allocates objects in the global heap.%@CR:C6A00110002 @%%@CR:C6A00110003 @%%@NL@% This chapter describes the following topics: %@NL@% ■ How Heap Walker views memory%@NL@% ■ The Heap Walker window%@NL@% ■ Using Heap Walker commands to examine the global heap %@NL@% %@2@%%@CR:C6A00110004 @%%@AB@%11.1 How Heap Walker Views Memory%@AE@%%@EH@%%@NL@% Heap Walker displays the global heap when Windows is running in either protected or real mode. The heap differs from one mode to the other. The following sections describe the differences. %@NL@% %@3@%%@CR:C6A00110005 @%%@AB@%11.1.1 Viewing the Heap in Protected Mode%@AE@%%@EH@%%@NL@% If Windows is running in protected (standard or 386 enhanced) mode, the heap is an area of memory that starts above DOS, TSR, and system drivers. %@NL@% When viewing the heap in protected mode, Heap Walker identifies objects by selector. The CPU uses selectors to indirectly specify memory addresses.%@CR:C6A00110006 @%%@NL@% %@3@%%@CR:C6A00110007 @%%@AB@%11.1.2 Viewing the Heap in Real Mode%@AE@%%@EH@%%@NL@% If Windows is running in real mode, the heap can consist of one of the following:%@CR:C6A00110008 @%%@NL@% ■ The heap that starts above DOS, TSR programs, and system drivers, and ends at the top of DOS memory.%@NL@% ■ The heap that Windows uses in real mode plus expanded memory that Windows can map into the 1-megabyte address space. Windows accesses this area of memory using handles to appropriate segments. This access mechanism, called the Expanded Memory Specification (EMS), is transparent to an application.%@CR:C6A00110009 @% %@CR:C6A00110010 @%%@NL@% %@2@%%@CR:C6A00110011 @%%@AB@%11.2 The Heap Walker Window%@AE@%%@EH@%%@NL@% Figure 11.1 illustrates the Heap Walker window after the user has executed a Walk command.%@CR:C6A00110012 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% By default, Heap Walker displays all global objects in the area of memory below the EMS line, starting at the bottom of the heap. To display objects in the heap that includes expanded memory, use the EMS menu described in Table 11.2, "Walk Commands." %@NL@% Whether you examine the heap below the line or the EMS heap, Heap Walker displays the following information about each object:%@CR:C6A00110013 @%%@NL@% ■ ADDR (real mode only)─Segment of the object arena header; the object starts one paragraph later.%@NL@% ■ SLCT (protected mode only)─Selector of the object.%@NL@% ■ HANDL─Handle of the memory object.%@NL@% ■ SIZE─Size of the object, in bytes.%@NL@% ■ LOCK─Lock count of the object.%@NL@% ■ FLAG─"D" if the object is discardable; "S" if it is shareable.%@NL@% ■ OWNER-NAME─Owner of the object.%@NL@% ■ OBJ-TYPE─Type of the object. %@NL@% ■ ADD-INFO─Additional information that describes the kind of resource objects allocated.%@NL@% %@2@%%@CR:C6A00110014 @%%@AB@%11.3 Using Heap Walker Commands%@AE@%%@EH@%%@NL@% Heap Walker commands let you do the following: %@NL@% ■ Perform file operations%@NL@% ■ Walk the heap %@NL@% ■ Sort memory objects %@NL@% ■ Show objects %@NL@% ■ Allocate part or all of the heap%@NL@% ■ Add the size of selected memory objects %@NL@% The following sections describe Heap Walker commands. %@NL@% %@3@%%@CR:C6A00110015 @%%@AB@%11.3.1 Performing File Operations: The File Menu%@AE@%%@EH@%%@NL@% Table 11.1 describes Heap Walker commands that perform basic file operations.%@CR:C6A00110016 @%%@CR:C6A00110017 @%%@CR:C6A00110018 @%%@NL@% Table 11.1 File Operation Commands %@TH: 16 857 02 34 42 @%Command Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Save Saves the current listing of objects on the heap to a HWG.TXT file. Heap Walker writes the first listing you save to file HWG00.TXT, and numbers subsequent saves consecutively (HWG00.TXT, HWG01.TXT).Exit Exits Heap Walker.About Heap Walker Displays information about the current version of Heap Walker.%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 16 857 02 34 42 @% When saving a list of current objects to a file, Heap Walker dumps the heap that is displayed on the screen as well as the following information, from left to right: %@NL@% ■ The module name%@NL@% ■ The number of discardable segments loaded in memory%@NL@% ■ The number of bytes that the discardable segments occupy%@NL@% ■ The number of bytes that nondiscardable segments occupy in memory%@NL@% ■ The total number of bytes that the module occupies in memory%@NL@% %@3@%%@CR:C6A00110019 @%%@AB@%11.3.2 Walking the Heap: The Walk and EmsWalk Menus%@AE@%%@EH@%%@NL@% Table 11.2 describes commands for walking the heap.%@CR:C6A00110020 @%%@CR:C6A00110021 @%%@CR:C6A00110022 @%%@NL@% Table 11.2 Walk Commands %@TH: 10 644 02 34 42 @%Command Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Walk Heap Displays objects on the heap below the EMS line (real mode only if EMS is present). Each display line identifies one global object. If the heap does not have EMS or the heap is in protected mode, this command displays the entire heap.%@TE: 10 644 02 34 42 @% Table 11.2 Walk Commands (continued) %@TH: 44 2570 02 34 42 @%Command Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Walk LRU List Displays only discardable objects. The Heap Walker lists objects from the least recently used to the most recently used. The object at the top of the list has been least recently used and, therefore, is most eligible for discarding. Walk Free List Displays only free blocks of memory.GC(0) and Walk Performs a global compact, asking for zero bytes, then displays the heap.GC(-1) and Walk Attempts to throw out all discardable objects and then displays the heap.GC(-1) and Hit A: Attempts to throw out all discardable objects, then accesses drive A. Used to test critical error handling. Set Swap Area Resets the code fence. The code fence defines an area of memory reserved for discardable code. Segmentation Test Dumps the heap to a file called HWG00.TXT and does a global compact (-1). Heap Walker numbers files consecutively in subsequent dumps. This command is available whenever Heap Walker is in the system and EMS memory is not installed, even if Heap Walker is not the active application. Specified application Walks the heap of a specified application using the Expanded Memory Specification. An EMS walk comprises relevant objects in memory above the EMS line and below 1-megabyte.. This command is available only in real mode for systems with EMS installed. %@CR:C6A00110023 @%%@CR:C6A00110024 @%%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 44 2570 02 34 42 @% %@3@%%@CR:C6A00110025 @%%@AB@%11.3.3 Sorting Memory Objects: The Sort Menu%@AE@%%@EH@%%@NL@% Heap Walker lets you sort memory objects in a variety of ways. Table 11.3 describes Heap Walker sort commands.%@CR:C6A00110026 @%%@CR:C6A00110027 @%%@CR:C6A00110028 @%%@NL@% Table 11.3 Sort Commands %@TH: 15 598 02 34 42 @%Command Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Address (real mode only) Sorts by address.Selector (protected mode only) Sorts by selector.Module Sorts by module name.Size Sorts by object size.Label Segments Substitutes segment names for segment numbers.%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 15 598 02 34 42 @% %@3@%%@CR:C6A00110029 @%%@AB@%11.3.4 Displaying Memory Objects: The Object Menu%@AE@%%@EH@%%@NL@% Heap Walker lets you view objects selectively. Table 11.4 describes commands to control and display memory objects.%@CR:C6A00110030 @%%@CR:C6A00110031 @%%@CR:C6A00110032 @%%@CR:C6A00110033 @%%@NL@% Table 11.4 Memory Object Commands %@TH: 53 2677 02 34 42 @%Command Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Show Displays the contents of a selected object in hexadecimal and ASCII format.Show Bits Displays the bitmap (if any) of a selected graphics device interface (GDI) object such as a font or cursor.Discard Discards a selected object. Oldest Marks a selected object as the next candidate for discarding.Newest Marks a selected object as the last candidate for discarding.LocalWalk Displays the local heap of the currently selected object. The object must be a data segment. The local walk window shows the following: OFFSET─The offset from the DS register of the object SIZE─Size in bytes of the object MOV/FIX─Indicates whether the object is moveable or fixed FLAGS─Indicates whether or not an object is discardable OBJ TYPE─Object type Windows allocates the first object in the local heap, so there are always at least two objects in a local heap. LocalWalk has a File menu with a Save command that saves to a file named HWL00.TXT. Heap Walker numbers files consecutively on subsequent dumps (HWL00.TXT, HWL01.TXT).LC(-1) and LocalWalk Compacts the selected local heap, then displays the heap. LocalWalk has a Save command that saves to a file named HWL00.TXT. Heap Walker numbers files consecutively on subsequent dumps (HWL00.TXT, HWL01.TXT).%@TE: 53 2677 02 34 42 @% Table 11.4 Memory Object Commands (continued) %@TH: 11 701 02 34 42 @%Command Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%GDI LocalWalk Displays the GDI local heap and provides information on the objects in the heap. LocalWalk has a Save command that saves to a file named HWL00.TXT. Heap Walker numbers files consecutively on subsequent dumps (HWL00.TXT, HWL01.TXT).%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 11 701 02 34 42 @% %@3@%%@CR:C6A00110034 @%%@AB@%11.3.5 Allocating Memory: The Alloc Menu%@AE@%%@EH@%%@NL@% Heap Walker lets you allocate part or all of memory. Table 11.5 describes commands that allocate memory.%@CR:C6A00110035 @%%@CR:C6A00110036 @%%@CR:C6A00110037 @%%@CR:C6A00110038 @%%@NL@% Table 11.5 Memory Allocation Commands %@TH: 39 2009 02 34 42 @%Command Action%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Allocate all of memory Allocates all free memory. This command is useful for testing out-of-memory conditions in applications. Free allocated memory Frees memory allocated by the Allocate all of memory command. Free 1K Frees 1K of memory. Applies only to memory allocated by the Allocate all of memory command.Free 2K Frees 2K of memory. Applies only to memory allocated by the Allocate all of memory command.Free 5K Frees 5K of memory. Applies only to memory allocated by the Allocate all of memory command.Free 10K Frees 10K of memory. Applies only to memory allocated by the Allocate all of memory command.Free 25K Frees 25K of memory. Applies only to memory allocated by the Allocate all of memory command.Free 50K Frees 50K of memory. Applies only to memory allocated by the Allocate all of memory command.Free XK Frees a specified number of kilobytes of memory. Heap Walker displays a dialog box that lets you specify the number.%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@TE: 39 2009 02 34 42 @% %@3@%%@CR:C6A00110039 @%%@AB@%11.3.6 Determining Memory Size: The Add! Menu%@AE@%%@EH@%%@NL@% Heap Walker lets you determine the total size of selected memory objects. To add the total number of bytes of selected objects, choose the Add! menu. The menu is a command that displays the number of selected segments and total segment size in a dialog box.%@CR:C6A00110040 @%%@CR:C6A00110041 @%%@CR:C6A00110042 @%%@NL@% %@2@%%@CR:C6A00110043 @%%@AB@%11.4 Suggestions for Using Heap Walker%@AE@%%@EH@%%@NL@% One error that frequently occurs in applications is the failure to free memory objects once they are no longer needed. This can cause Windows to fail when one of its data segments grows beyond the 64K limit. %@NL@% You can use Heap Walker to help determine if your application is not freeing memory objects. Heap Walker lets you view changes in the size of all Windows data segments, allowing you to observe the effect your application has on these segments. %@NL@% To check how your application changes the size of the Windows data segments, follow these steps: %@NL@% 1. Make sure that your application does not generate fatal exits.%@NL@% 2. Start the debugging version of Windows, making sure that all the values for settings in the [kernel] section of WIN.INI are correct.%@NL@% 3. Immediately start Heap Walker and note the sizes of the GDI and USER data segments. This establishes the baseline against which you can compare the size of the data segments later.%@NL@% 4. Select the Object GDI LocalWalk(DATASEG) menu option to display a window that lists the different objects in the GDI data segment. Select the Save! menu option of this window to copy this list to a file; the file will also contain a summary of GDI objects.%@NL@% 5. Run your application and exercise it fully over a long period of time, noting the changes in the size of the GDI and USER data segments which Heap Walker displays as your application runs. While your application is running, repeat step 4 a number of times to take "snapshots" of the effect your application has on the GDI data segment.%@NL@% 6. Close your application, take a final "snapshot" of the GDI data segment, and note the total sizes of the GDI and USER data segments.%@NL@% As you analyze the data that you've recorded, you should look for GDI objects that your application creates but does not delete when they are no longer needed. %@NL@% You should also check the size of the USER data segment before and after you run your application. While it is normal for the USER data segment to be a little larger after your application has run once, it should not grow larger after you have run your application additional times. If it does, your application probably is calling the %@AB@%MakeProcInstance%@AE@% function without calling %@AB@%FreeProcInstance%@AE@% to free the procedure-instance address when it is no longer needed. %@NL@% %@2@%%@CR:C6A00110044 @%%@AB@%11.5 Summary%@AE@%%@EH@%%@NL@% Heap Walker is a tool that lets you examine objects on the global heap. For more information on the heap, see Chapter 15, "Memory Management," and Chapter 16, "More Memory Management," in%@AI@% Guide to Programming. %@AE@%%@NL@% %@CR:C6A00120001 @%%@1@%%@AB@%Chapter 12 Moving Memory: Shaker%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% The Microsoft Windows Shaker (%@AB@%SHAKER%@AE@%) lets you see the effect of memory movement on your application. Shaker randomly allocates and frees chunks of global memory with the intention of forcing the system to relocate moveable data or code segments in your application. %@NL@% Shaker is useful for making sure that no problems occur when memory moves.%@CR:C6A00120002 @%%@CR:C6A00120003 @%%@CR:C6A00120004 @%%@NL@% This chapter describes commands you use to allocate and free global memory. %@NL@% %@2@%%@CR:C6A00120005 @%%@AB@%12.1 Using Shaker%@AE@%%@EH@%%@NL@% To use Shaker, select the parameters you want and start Shaker. You select parameters and start or stop Shaker with the following commands on the menu bar: %@NL@% %@AB@%Command%@AE@% %@AB@%Function%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Parameter Displays a dialog box that lets you specify the following parameters: ■ Allocation Granularity─Sets the minimum size of the objects to be allocated. Each object is some multiple of this size; for example, if the granularity is 128, Shaker allocates objects that have byte sizes of 128, 256, 384, and so on. The smaller the granularity, the more likely it is that the allocated objects will fit in the spaces between global objects. %@CR:C6A00120006 @% %@CR:C6A00120007 @%%@CR:C6A00120008 @% ■ Time Interval─Sets the time interval, in system-timer ticks, between allocations. Shaker allocates a new object after each interval elapses. If the maximum number of objects has been allocated, it reallocates one it had previously allocated. ■ Max Objects─Sets the maximum number of objects to be allocated. Display Displays or removes the display of object handles and allocation sizes. %@AB@%Command%@AE@% %@AB@%Function%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Start Starts the allocation. Stop Stops the allocation. Step Allocates one object and stops. This command can be used when Shaker is otherwise stopped.%@CR:C6A00120009 @% %@2@%%@CR:C6A00120010 @%%@AB@%12.2 Summary%@AE@%%@EH@%%@NL@% Shaker is a tool that shows you the effect of memory movement on your application. For more information on memory management, see Chapter 15, "Memory Management," and Chapter 16, "More Memory Management," in %@AI@% Guide to %@AI@%Programming%@AE@%. %@NL@% %@CR:C6A00130001 @%%@1@%%@AB@%Chapter 13 Analyzing CPU Time: Profiler%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Microsoft Windows Profiler (%@AB@%PROFILER%@AE@%) is an analytical tool that helps you optimize the performance of Windows applications. Profiler lets you sample the amount of time Windows spends executing sections of code.%@CR:C6A00130002 @%%@NL@% This chapter describes the following topics: %@NL@% ■ An overview of Profiler%@NL@% ■ Preparing to run Profiler%@NL@% ■ Using Profiler functions%@NL@% ■ Sampling code%@NL@% ■ Displaying samples%@NL@% Profiler analyzes applications running with Windows in real mode or in 386 enhanced mode; it cannot analyze applications running with Windows in standard mode. If you are analyzing Windows applications in real mode, you use Profiler differently than if you are analyzing applications running with Windows in 386 enhanced mode. Section 13.4, "Sampling Code," discusses the differences. Profiler does not support Windows running in standard mode. %@NL@% %@2@%%@CR:C6A00130003 @%%@AB@%13.1 Overview of Profiler%@AE@%%@EH@%%@NL@% Profiler contains the following: %@NL@% ■ A sampling utility%@NL@% ■ A reporting utility%@NL@% ■ A set of functions that you call from your application%@NL@% The sampling utility gathers information about the time spent between adjacent labels, and records memory addresses of code. If the application you are profiling runs with Windows in real mode, the sampling utility is PROF.COM. To run the Profiler you invoke PROF.COM, which in turns invokes Windows. %@NL@% If the application you are profiling runs with Windows in 386 enhanced mode, the sampling utility is a special device driver, VPROD.386. To run Profiler, first install VPROD.386, and then run Windows directly. %@NL@% Profiler stores the information it gathers in a buffer. It writes the buffer to disk when Windows terminates, producing a CSIPS.DAT file and a SEGENTRY.DAT file in the directory that was your current directory when you started Windows. The CSIPS.DAT file contains statistical samplings of the code segment (CS), instruction pointer (IP) registers. The SEGENTRY.DAT file contains information about the movement of code segments. Because code segments can be located at different physical addresses during the execution of the program, information in both the CSIPS.DAT and SEGENTRY.DAT files are required to prepare the profiling report. %@CR:C6A00130004 @% %@CR:C6A00130005 @% %@CR:C6A00130006 @% %@CR:C6A00130007 @%%@NL@% After the sampling utility has finished gathering information, the reporting utility, SHOWHITS.EXE, organizes and displays the results.%@CR:C6A00130008 @%%@NL@% Profiler's functions let you start and stop examining code, manage the output of code samples, and get information about Profiler. All applications that Profiler examines must include two functions that start and stop the sampling of code. Other Profiler functions are optional. %@NL@% %@2@%%@CR:C6A00130009 @%%@AB@%13.2 Preparing to Run Profiler%@AE@%%@EH@%%@NL@% To profile a Windows application in real mode, you need an IBM PC/AT(R) or PS/2(R) compatible system because Profiler uses the AT CMOS clock chip to time sampling intervals. The utility will not run on standard PC and PC/XT(tm) systems. %@NL@% To profile an application running with Windows in 386 enhanced mode, use any system capable of running Windows in 386 enhanced mode.%@CR:C6A00130010 @%%@CR:C6A00130011 @%%@NL@% In addition to ensuring that your system is compatible with Profiler, you must do the following: %@NL@% 1. Ensure that the Windows directory is defined in your PATH environment variable.%@NL@% 2. Include in your application at least two mandatory Profiler functions, %@AB@%ProfStart%@AE@% and %@AB@%ProfStop%@AE@%. %@NL@% %@STUB@% %@AB@%ProfStart%@AE@% indicates when you want Profiler to start sampling code; %@AB@%ProfStop%@AE@% indicates when you want Profiler to stop sampling. Other functions are optional.%@NL@% 3. Compile your application and link the compiled code with the standard Windows libraries. Use the %@AB@%LINK /m%@AE@% option to prepare a .MAP file. This file is required by the %@AB@%MAPSYM%@AE@% utility.%@CR:C6A00130012 @%%@NL@% 4. Use %@AB@%MAPSYM%@AE@% to produce an application symbol (.SYM) file.%@NL@% %@2@%%@CR:C6A00130013 @%%@AB@%13.3 Using Profiler Functions%@AE@%%@EH@%%@NL@% In addition to the mandatory %@AB@%ProfStart%@AE@% and %@AB@%ProfStop%@AE@% functions, Profiler includes functions that determine if Profiler is installed, specify a rate for sampling, and control the output buffer. %@NL@% The way you use the Profiler functions depends on whether your application runs in real mode or in 386 enhanced mode.%@CR:C6A00130014 @%%@NL@% If your application runs with Windows in real mode and you want to override the standard sampling rate or the amount of data that the Profiler writes to disk, you can use either command line options when invoking the Profiler or Profiler functions. For information on using command line options, see Section 13.4, "Sampling Code." %@NL@% If your application runs with Windows in 386 enhanced mode and you want to specify nondefault values, you must use Profiler functions. You cannot change default values when invoking the utility.%@CR:C6A00130015 @%%@CR:C6A00130016 @%%@NL@% The sections that follow describe Profiler functions. %@NL@% %@3@%%@CR:C6A00130017 @%%@AB@%13.3.1 Starting and Stopping Sampling: The ProfStart and ProfStop Functions%@AE@%%@EH@%%@NL@% Use the %@AB@%ProfStart%@AE@% and%@AB@% ProfStop%@AE@% functions for each section of code that you want to sample. Deciding where to call%@AB@% ProfStart%@AE@% and %@AB@%ProfStop%@AE@% is important. You should avoid sampling when your application calls Windows functions that yield to other applications. For example, sampling a function such as %@AB@%GetMessage%@AE@% could cause Profiler to collect data on applications other than your own. %@CR:C6A00130018 @% %@CR:C6A00130019 @% %@CR:C6A00130020 @%%@CR:C6A00130021 @%%@NL@% The following example illustrates when to call %@AB@%ProfStart%@AE@% and %@AB@%ProfStop%@AE@%: %@NL@% %@AS@% #include "windows.h" %@AS@% #include "hello.h" %@AS@% . %@AS@% . %@AS@% . %@AS@% void HelloPaint( hDC ) %@AS@% HDC hDC; %@AS@% { %@AS@% int i, j; %@AS@% %@AS@% ProfStart();%@AE@% %@AS@% for(i = 1; i <= 3; i++) %@AS@% for(j = 1; j <= 20; j++) %@AS@% { %@AS@% TextOut( hDC, %@AS@% (short)(i * 120), %@AS@% (short)(j * 12), %@AS@% (LPSTR)szMessage, %@AS@% (short)MessageLength ); %@AS@% } %@AS@% ProfStop(); %@AS@% } %@AS@% . %@AS@% . %@AS@% .%@AE@% In this example, the Profiler %@AB@%ProfStart%@AE@% and %@AB@%ProfStop%@AE@% functions specify that Profiler sample the application's %@AB@%HelloPaint%@AE@% function. Profiler samples only the nested loops that include the call to the %@AB@%TextOut%@AE@% function. %@NL@% %@3@%%@CR:C6A00130022 @%%@AB@%13.3.2 Checking if Profiler Is Installed: The ProfInsChk Function%@AE@%%@EH@%%@NL@% To determine if Profiler is installed, use the %@AB@%ProfInsChk%@AE@% function. %@AB@%ProfInsChk%@AE@% has the following syntax: %@NL@% %@AS@% int FAR PASCAL ProfInsChk(void)%@AE@% The function returns the following values: %@NL@% ■ 0 if Profiler is not installed %@NL@% ■ 1 if the Windows real-mode Profiler is installed%@NL@% ■ 2 if the Windows 386-enhanced-mode Profiler is installed%@NL@% If Profiler is not installed, the system ignores other Profiler function calls.%@CR:C6A00130023 @%%@CR:C6A00130024 @%%@NL@% %@3@%%@CR:C6A00130025 @%%@AB@%13.3.3 Setting the Sampling Rate: The ProfSampRate Function%@AE@%%@EH@%%@NL@% To set the rate of code sampling, use the %@AB@%ProfSampRate%@AE@% function. %@AB@%ProfSampRate%@AE@% has the following syntax: %@CR:C6A00130026 @%%@NL@% %@AS@% void FAR PASCAL ProfSampRate(int,int)%@AE@% The first parameter specifies the sampling rate of Profiler if the application is running with Windows in real mode. The value of the first parameter ranges from 1 to 13, indicating the following sampling rates:%@CR:C6A00130027 @%%@CR:C6A00130028 @%%@NL@% %@AB@%Numeric Value%@AE@% %@AB@%Sampling Rate%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% 1 122.070 microseconds 2 244.141 microseconds 3 488.281 microseconds 4 976.562 microseconds 5 1.953125 milliseconds 6 3.90625 milliseconds 7 7.8125 milliseconds 8 15.625 milliseconds 9 31.25 milliseconds 10 62.5 milliseconds 11 125 milliseconds 12 250 milliseconds 13 500 milliseconds The second parameter defines sampling rates if Profiler is analyzing an application running with Windows in 386 enhanced mode. The value of the second parameter can range from 1 to 1000, specifying the sampling rate in milliseconds. %@NL@% For Windows in real mode the initial rate is 5 (1.953125 milliseconds) or what you specify when invoking PROF.COM. %@NL@% For Windows in 386 enhanced mode, the default rate is 2 milliseconds. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%Profiler selects only the parameter appropriate for the version of Windows %@AI@%used. If your application runs with Windows in real mode, Profiler reads %@AI@%only the first parameter; if your application runs with Windows in 386 %@AI@%enhanced mode, Profiler reads only the second. %@CR:C6A00130029 @%%@CR:C6A00130030 @%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00130031 @%%@AB@%13.3.4 Managing Output: The ProfClear, ProfFlush, and ProfSetup Functions%@AE@%%@EH@%%@NL@% To manage the output of samples that Profiler gathers, use the %@AB@%ProfClear%@AE@%,%@AB@% %@AB@%ProfFlush%@AE@%, and%@AB@% ProfSetup%@AE@% functions. %@AB@%ProfClear%@AE@% discards all samples currently in the sampling buffer.%@AB@% ProfFlush%@AE@% flushes the sampling buffer to disk, provided that samples do not exceed the limit you define.%@CR:C6A00130032 @%%@CR:C6A00130033 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% IMPORTANT %@AI@%Use %@AB@%ProfFlush%@AE@%%@AI@% sparingly because it can distort the performance of your %@AI@%application. Additionally, do not call the function when DOS may be %@AI@%unstable, as in interrupt handling.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% The %@AB@%ProfSetup%@AE@% function lets you specify the size of the output buffer and the amount of samples written to disk. %@AB@%ProfSetup%@AE@% is available only to applications running with Windows in 386 enhanced mode. %@NL@% If your application runs with Windows in real mode, you must specify the size of the output buffer and the size of sampling data when you invoke Profiler. %@NL@% The syntax of %@AB@%ProfSetup%@AE@% is as follows: %@NL@% %@AS@% void FAR PASCAL ProfSetup(int, int)%@AE@% The first parameter specifies the size of the output buffer in kilobytes (K), from 1 to 1064. The default value is 64. %@NL@% The second parameter controls how much sampling data Profiler writes to disk. Default value is the size of the output buffer in kilobytes. A value of 0 specifies unlimited sampling data. %@NL@% The following example uses %@AB@%ProfSetup%@AE@% to specify values for the size of the output buffer and the amount of samples written to disk. It also calls %@AB@%ProfSampRate%@AE@% to change the default sampling rate. %@NL@% %@AS@% BOOL HelloInit( hInstance ) %@AS@% HANDLE hInstance; %@AS@% { %@AS@% PWNDCLASS pHelloClass; %@AS@% . %@AS@% . %@AS@% .%@AE@% %@AS@% int PASCAL WinMain( hInstance, hPrevInstance, lpszCmdLine, cmdShow ) %@AS@% HANDLE hInstance, hPrevInstance; %@AS@% LPSTR lpszCmdLine; %@AS@% int cmdShow; %@AS@% { %@AS@% MSG msg; %@AS@% HWND hWnd; %@AS@% HMENU hMenu; %@AS@% . %@AS@% . %@AS@% . %@AS@% ProfSetup(100,0); %@AS@% ProfSampRate(4,1); %@AS@% . %@AS@% . %@AS@% .%@AE@% In this example, the %@AB@%ProfSetup%@AE@% function changes the default sample buffer size from 64K to 100K and specifies that Profiler write an unlimited amount of data to disk. The function applies only if the application is running with Windows in 386 enhanced mode. The %@AB@%ProfSampRate%@AE@% function changes default sampling rates to 1 millisecond in 386 enhanced mode.%@CR:C6A00130034 @%%@NL@% If the application runs with Windows in real mode, Profiler ignores the %@AB@%ProfSetup%@AE@% call. The %@AB@%ProfSampRate%@AE@% function changes default sampling rates to 976.562 microseconds in real mode. %@NL@% %@3@%%@CR:C6A00130035 @%%@AB@%13.3.5 Stopping Profiler: The ProfFinish Function%@AE@%%@EH@%%@NL@% To stop Profiler, use the %@AB@%ProfFinish%@AE@% function. %@AB@%ProfFinish%@AE@% stops sampling and flushes the output buffer to disk. If your application is running with Windows in 386 enhanced mode, %@AB@%ProfFinish%@AE@% also frees the buffer for system use.%@CR:C6A00130036 @%%@CR:C6A00130037 @%%@NL@% If you do not call %@AB@%ProfFinish%@AE@%, the output buffer automatically flushes to disk when you terminate Windows. %@NL@% If you are profiling more than one instance of the same application, calling the %@AB@%ProfFinish%@AE@% function will stop Profiler for all instances of the application. %@NL@% %@2@%%@CR:C6A00130038 @%%@AB@%13.4 Sampling Code%@AE@%%@EH@%%@NL@% The method you use to sample code depends on the version of Windows your application runs with. If your application runs with Windows in real mode, you invoke the PROF.COM program, which loads and runs Windows. If your application runs with Windows in 386 enhanced mode, you first install VPROD.386, a virtual device driver, and then run Windows directly. %@NL@% In real mode, the Profiler output buffer is limited to 64K. In 386 enhanced mode, your application can call %@AB@%ProfSetup%@AE@% to set the size of the output buffer up to 1064K. %@NL@% Both sampling methods use memory that is otherwise available to Windows. Therefore, using Profiler may decrease the performance of the application you are analyzing. You can reduce the amount of memory used by specifying a small output buffer. However, a small output buffer may cause sample loss. %@NL@% Profiler can write samples to disk only when Windows indicates it is safe to do so. When the sampling buffer fills, Profiler ignores additional samples until the buffer is flushed to disk. To minimize sample loss, either increase the buffer size or periodically call the %@AB@%ProfFlush%@AE@% function.%@CR:C6A00130039 @%%@CR:C6A00130040 @%%@CR:C6A00130041 @%%@CR:C6A00130042 @%%@CR:C6A00130043 @%%@CR:C6A00130044 @%%@NL@% The following sections describe features specific to Windows in real mode, and Windows in 386 enhanced mode.%@CR:C6A00130045 @%%@CR:C6A00130046 @%%@CR:C6A00130047 @%%@NL@% %@3@%%@CR:C6A00130048 @%%@AB@%13.4.1 Sampling Applications in Windows Real Mode%@AE@%%@EH@%%@NL@% To profile applications running with Windows in real mode, use the PROF.COM utility. %@NL@% The syntax for invoking PROF.COM is as follows: %@NL@% %@AS@% PROF «-tn» [[-cn» «-ln» «-d» «program arguments»%@AE@% The KERNEL.EXE file must be in the current directory or in the current PATH environment. The following describes the command line options: %@NL@% %@AB@%Option%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% -%@AB@%t%@AE@%%@AI@%n%@AE@% Specifies the intervals at which Profiler samples code. For values of %@AI@%n%@AE@%, see the description of real-mode Windows arguments to the %@AB@%ProfSampRate%@AE@% function in Section 13.3.3, "Setting the Sampling Rate: The ProfSampRate Function." -%@AB@%c%@AE@%%@AI@%n%@AE@% Specifies the size of the output buffer in kilobytes. The value of %@AI@%n%@AE@% can range from 1 to 64 (default buffer size is 64K). -%@AB@%l%@AE@%%@AI@%n%@AE@% Limits the total size of samples written to disk. If this option is not specified, the default is the size of the output buffer. -%@AB@%d%@AE@% Specifies that the program being analyzed runs with DOS, not Windows. %@AB@%Option%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AI@%program arguments%@AE@% Names the program and arguments, if any, that Profiler loads and runs. You would typically place arguments, such as the name of the application you are running, on the Windows command line. If specified, the name must include an extension. When profiling Windows applications, this parameter should be the name of the Windows program, typically WIN.COM. %@CR:C6A00130049 @% %@CR:C6A00130050 @% %@CR:C6A00130051 @% %@3@%%@CR:C6A00130052 @%%@AB@%13.4.2 Sampling Applications in Windows 386 Enhanced Mode%@AE@%%@EH@%%@NL@% The PROF.COM command line options are not available when you profile applications that run with Windows in 386 enhanced mode. Instead, you add the Profiler functions to your source code to get equivalent results. %@NL@% To profile applications that run with Windows in 386 enhanced mode, do the following:%@CR:C6A00130053 @%%@NL@% 1. Install the VPROD.386 driver by adding the following to the [386enh] section of your SYSTEM.INI file:%@CR:C6A00130054 @%%@CR:C6A00130055 @%%@CR:C6A00130056 @%%@CR:C6A00130057 @% %@AS@% DEVICE=VPROD.386%@AE@% %@NL@% 2. Run Windows in 386 enhanced mode.%@NL@% 3. Run the application you want to profile.%@NL@% 4. When you have finished profiling your application, remove the VPROD.386 entry from your SYSTEM.INI file.%@NL@% %@2@%%@CR:C6A00130058 @%%@AB@%13.5 Displaying Samples: SHOWHITS.EXE%@AE@%%@EH@%%@NL@% Use a DOS application, SHOWHITS.EXE, to display data that the Profiler gathers. This reporting utility reads CSIPS.DAT, SEGENTRY.DAT, and .SYM files, and organizes and displays the data. The sampling utility places the CSIPS.DAT and SEGENTRY.DAT files in the current directory. To ensure that SHOWHITS can locate these files, either run SHOWHITS from the same directory, or else specify full pathnames for the CSIPS.DAT and SEGENTRY.DAT files. If the .SYM files are not in the current directory, then use the %@AB@%-i%@AE@% option to specify the directory or directories containing the symbols files.%@CR:C6A00130059 @%%@CR:C6A00130060 @%%@CR:C6A00130061 @%%@NL@% SHOWHITS.EXE reads .SYM files to match instruction pointer samples with global symbols in the application. When you run SHOWHITS.EXE the utility searches for .SYM files that contain symbolic names identical to the names of modules that Profiler sampled. If the sampled program is written in the C language, the symbolic names are typically function names. If the sampled program is written in assembly language, the symbolic names can be either procedure names or %@AB@%PUBLIC%@AE@% symbols within procedures. %@NL@% SHOWHITS.EXE reports the number of times sampling occurred between adjacent symbols. %@NL@% The syntax for invoking SHOWHITS.EXE is as follows: %@NL@% %@AS@% SHOWHITS «-r|3» «-ipath [-ipath«...»»» «csips_file» «segentry_file»%@AE@% The following describes SHOWHITS.EXE options: %@NL@% %@AB@%Option%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% -%@AB@%r%@AE@% The Profiler was run in real mode (PROF.COM). SHOWHITS uses the KERNEL.SYM Windows kernel symbol file. -%@AB@%3%@AE@% The Profiler was run in 386 enhanced mode (VPROD.386). SHOWHITS uses the KRNL386.SYM Windows kernel symbol file. -%@AB@%i%@AE@%%@AI@%path%@AE@% The %@AI@%path%@AE@% option specifies one or more directories to search for .SYM files. The default is the current directory. SHOWHITS.EXE loads all .SYM files in the specified directories, regardless of their relevance to the application you are profiling. %@AI@%csips_file%@AE@% Specifies the full pathname of the CSIPS.DAT file. If not specified, SHOWHITS.EXE looks for the file in the current directory. %@AI@%segentry file%@AE@% Specifies the full pathname of the SEGENTRY.DAT file. If not specified, SHOWHITS.EXE looks for the file in the current directory. If you do not supply the %@AB@%-r%@AE@% or%@AB@% -3%@AE@% option, SHOWHITS.EXE will prompt you for the mode. %@NL@% SHOWHITS.EXE displays information about hits, which are instruction pointer samples, into the following four categories:%@CR:C6A00130062 @%%@CR:C6A00130063 @%%@CR:C6A00130064 @%%@CR:C6A00130065 @%%@NL@% %@AB@%Category%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Unrecognized A list of instruction pointers that segments occur within segments for which there are no symbols of module names. Unrecognized segments are typically code for device drivers, TSR programs, and other code that Windows does not use. %@AB@%Category%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Known segments The number of hits that occur within known modules. Hits on known segments typically include counts for the application and counts for Windows modules such as KERNEL, GDI, and DISPLAY. Profiler also counts hits in DOS and the ROM BIOS. In addition to display hits, SHOWHITS.EXE lists the total number of hits and the segment's percentage of total hits. Breakdown A detailed breakdown of the hits between labels of the modules for which SHOWHITS.EXE finds .SYM files. SHOWHITS.EXE also displays the total number of hits and the percentage of the total number. Summary A list of the top 10 hits. The following example illustrates a display:%@CR:C6A00130066 @%%@NL@% %@AS@% Here are the Hits for Unrecognized Segments %@AS@% %@AS@% Here are the Hits for Known Segments %@AS@% %@AS@% 0.3% 3 Hits on SYSTEM-0 %@AS@% 0.5% 5 Hits on HELLO-0 %@AS@% 76.5% 786 Hits on DISPLAY-0 %@AS@% 11.3% 116 Hits on GDI-0 %@AS@% 11.5% 118 Hits on KERNEL-0 %@AS@% %@AS@% 1028 TOTAL HITS %@AS@% %@AS@% %@AS@% HELLO!_TEXT %@AS@% %@AS@% 0.4% 4 Hits between labels _HelloPaint and _HelloInit %@AS@% 0.1% 1 Hits between labels __cintDIV and __fptrap %@AS@% %@AS@% Profiler Summary (Top 10 Hits): %@AS@% %@AS@% 0.4% 4 HELLO! _TEXT! _HelloPaint - _HelloInit %@AS@% 0.1% 1 HELLO! _TEXT! __cintDIV - __fptrap%@AE@% %@2@%%@CR:C6A00130067 @%%@AB@%13.6 Summary%@AE@%%@EH@%%@NL@% Profiler is a tool that lets you determine the amount of time Windows spends executing sections of code. For more information about Profiler functions, see %@AI@%Reference, Volume 1%@AE@%: Chapter 4, "Functions Directory."%@AI@% %@AE@%%@NL@% %@CR:C6A00140001 @%%@1@%%@AB@%Chapter 14 Analyzing Swaps: Swap%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Microsoft Windows Swap (%@AB@%SWAP%@AE@%) is a tool that lets you analyze the calls, swaps, discards, and returns that occur when your Windows application runs. Swap includes a utility that records swapping information and another utility that displays the information to a standard output device.%@CR:C6A00140002 @%%@CR:C6A00140003 @%%@NL@% Swap is useful for determining the number of procedure calls that occur across segment boundaries. You can optimize the performance of your application by reducing the number of calls across boundaries. %@NL@% This chapter describes the following topics: %@NL@% ■ Preparing to run Swap%@NL@% ■ Running Swap%@NL@% ■ Displaying swapping information %@NL@% %@2@%%@CR:C6A00140004 @%%@AB@%14.1 Preparing to Run Swap%@AE@%%@EH@%%@NL@% Before running Swap, do the following: %@NL@% ■ Ensure that you have the necessary Swap files.%@NL@% ■ Place the %@AB@%SwapRecording%@AE@% function in your application.%@NL@% %@3@%%@CR:C6A00140005 @%%@AB@%14.1.1 Files You Need to Run Swap%@AE@%%@EH@%%@NL@% To run Swap, you need the following files: %@NL@% ■ SKERNEL.EXE─Windows uses this file instead of KERNEL.EXE as part of the debugging version of Windows. The SKERNEL.EXE file produces a data file named SWAPPRO.DAT, which contains information about the swapping behavior of your application. SKERNEL.EXE runs only when Windows is in real mode.%@CR:C6A00140006 @%%@NL@% ■ Application .SYM files─Swap requires symbol files for the modules of your application that you want to analyze. To create symbol files, first link the program using the%@AB@% /map%@AE@% option, and then run the %@AB@%MAPSYM%@AE@% utility.%@CR:C6A00140007 @%%@NL@% ■ SWAP.EXE─This file uses the SWAPPRO.DAT file to produce a report of swapping behavior.%@CR:C6A00140008 @%%@NL@% Swap also includes the optional SKERNEL.SYM file, which provides a listing of symbols in SKERNEL.EXE.%@CR:C6A00140009 @%%@NL@% %@3@%%@CR:C6A00140010 @%%@AB@%14.1.2 Using the SwapRecording Function%@AE@%%@EH@%%@NL@% Place the %@AB@%SwapRecording%@AE@% function in your application to indicate when to start and stop recording swapping behavior. The syntax of the function is as follows:%@CR:C6A00140011 @%%@NL@% %@AS@% SwapRecording(value)%@AE@% The %@AI@%value%@AE@% parameter specifies whether Swap begins or stops analyzing swapping behavior, as follows: %@NL@% %@TH: 11 565 02 34 42 @%Value Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%0 Specifies that Swap stop analyzing.1 Specifies that Swap record calls, discards, and swap returns.2 Specifies that Swap record calls, discards, swap returns, and all calls through thunks.%@TE: 11 565 02 34 42 @% %@2@%%@CR:C6A00140012 @%%@AB@%14.2 Running Swap%@AE@%%@EH@%%@NL@% To run Swap, do the following: %@NL@% 1. Make a backup copy of the KERNEL.EXE file in your Windows system directory by copying or renaming it. %@NL@% 2. Copy SKERNEL.EXE in the Windows development tools directory (named \WINDEV by default at installation) to the Windows system directory.%@NL@% 3. Start Windows in real mode (WIN /R) and run the application you want to analyze.%@NL@% 4. Exit from Windows.%@NL@% 5. Run SWAP.EXE.%@NL@% 6. When you are finished, be sure to restore the original KERNEL.EXE in your Windows system directory. %@NL@% The following command invokes SWAP.EXE: %@NL@% %@AS@% SWAP [-Ipath[;path...» [-Fswapfile] %@AS@%[-Mmodule[:segment][;module[:segment]...»%@AE@% Command line options are as follows:%@CR:C6A00140013 @%%@NL@% %@AB@%Option%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%-I%@AE@% Specifies one or more directory pathnames containing the symbol files of the modules to be analyzed. %@AB@%-F%@AE@% Specifies the pathname of the data collection file. %@AB@%-M%@AE@%%@AI@%module%@AE@% Specifies the application module that Swap analyzes. %@AI@%segment%@AE@% Specifies the segment that Swap analyzes. %@3@%%@CR:C6A00140014 @%%@AB@%14.2.1 Specifying a Symbol-File Path%@AE@%%@EH@%%@NL@% By default, Swap searches for all required symbol files in the current directory. To evaluate data in symbol files located in other directories, specify the pathnames with the %@AB@%-I%@AE@% option. The pathnames must be separated by semicolons. %@NL@% For example, the following command line specifies that symbol files reside in the \PRE\SYSTEM and \TEST\SWAP directories: %@NL@% %@AS@% SWAP -I\pre\system;\test\swap%@AE@% %@3@%%@CR:C6A00140015 @%%@AB@%14.2.2 Specifying a Pathname for the Data Collection File%@AE@%%@EH@%%@NL@% By default, Swap searches for the SWAPPRO.DAT file in the current directory. If you rename the data collection file or place it somewhere other than the current directory, use the %@AB@%-F%@AE@% option. %@NL@% For example, the following command line specifies that the data collection file, named SWAPREC, resides in directory TMP: %@NL@% %@AS@% SWAP -F\TMP\SWAPREC%@AE@% %@3@%%@CR:C6A00140016 @%%@AB@%14.2.3 Specifying a Module and Segment%@AE@%%@EH@%%@NL@% If the data collection file contains a large amount of data, Swap takes a long time processing the module and symbol names. To reduce the time, use the %@AB@%-M%@AE@% option to limit the number of modules and segments for which Swap prepares output.%@CR:C6A00140017 @%%@NL@% The following example specifies that Swap display only records that contain the _FONTRES segment of the GDI: %@NL@% %@AS@% SWAP -MGDI:_FONTRES%@AE@% You can list multiple segments or module/segment pairs by separating them on the command line with semicolons. The following example specifies that Swap display records that contain the _FONTRES segment of the GDI and any segment of USER: %@NL@% %@AS@% SWAP -MGDI:_FONTRES;USER %@AE@% %@2@%%@CR:C6A00140018 @%%@AB@%14.3 Displaying Output%@AE@%%@EH@%%@NL@% Swap displays records of swapping behavior on standard output devices. Use DOS commands to direct output to either a file or a screen. %@NL@% Swap records information in columns of ASCII text separated by tabs. The format is suitable for reading into spreadsheet programs such as Microsoft Excel.%@CR:C6A00140019 @%%@NL@% Swap displays information from left to right as follows: %@NL@% %@AB@%Column%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Type The kind of event that occurred. The event can be one of the following: ■ CALL─A normal call through a thunk. ■ SWAP─A call through a thunk that caused a swap. ■ DISCARD─Discard of a segment. If the discard was the result of a swap, then the discard records occur after the swap record. ■ RETURN─Return that caused a swap in the caller. Time The relative time that the event occurred, in milliseconds. Resolution is 1/18.2 seconds. The first event is always 0. Segment (1st) One of the following:%@CR:C6A00140020 @% ■ If CALL or SWAP, the segment being called. ■ If DISCARD, the segment being discarded. ■ If RETURN, the segment being returned to. If the module name appears in parentheses, Swap could not find the .SYM file for the module. Offset (1st) One of the following: ■ If CALL or SWAP, the offset into the segment being called. ■ If RETURN, the offset into the segment being returned to. ■ If DISCARD, this field is blank. Segment (2nd) One of the following: ■ If CALL or SWAP, the segment that did the calling. %@AB@%Column%@AE@% %@AB@%Description%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% ■ If DISCARD, this field is blank. ■ If RETURN, this field is blank. If the module name appears in parentheses, Swap could not find the .SYM file for the module. Offset (2nd) One of the following: ■ If CALL or SWAP, the offset into the segment that did the calling. ■ If RETURN, this field is blank. ■ If DISCARD, this field is blank. %@2@%%@CR:C6A00140021 @%%@AB@%14.4 Summary%@AE@%%@EH@%%@NL@% Swap is a tool that lets you analyze the swapping behavior of Windows applications. For more information about memory management, see Chapter 15, "Memory Management," and Chapter 16, "More Memory Management," in %@AI@%Guide%@AE@% %@AI@%to %@AI@%Programming%@AE@%. %@NL@% %@CR:C6A-Part 04 @%%@1@%%@AB@%PART IV Help Tools%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Part 4 provides a guideline for authors and developers of Help systems for Microsoft Windows applications. It also defines some specific rules that must be adhered to when creating a Help system for any single application. For that reason, some sections include step-by-step procedures, while other sections suggest general methods. %@NL@% To illustrate concepts and procedures, several chapters use sample screens and text from the on-line Help in Helpex, a Windows application supplied in your Software Development Kit. If you want to study this material in greater detail, you can use the Helpex system as a working model. %@NL@% %@CR:C6A00150001 @%%@1@%%@AB@%Chapter 15 Providing Help: The Help System%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% A Help system provides users with online information about an application. Creating the system requires the efforts of both a Help writer and a Help programmer. The Help writer plans, writes, codes, builds, and keeps track of Help topic files, which are text files that describe various aspects of the application. The Help programmer ensures that the Help system works properly with the application.%@NL@% This chapter describes the following topics: %@NL@% ■ Creating the Help system%@NL@% ■ How Help appears to the user%@NL@% ■ How Help appears to the Help writer%@NL@% ■ How Help appears to the Help programmer%@NL@% This chapter and those that follow assume you are familiar with Microsoft Windows Help. The chapters use examples from a sample application called Helpex, provided on the SDK Sample Source Code disk. If you are unfamiliar with Windows Help, take a moment to run the Helpex sample application and use Helpex Help. %@NL@% %@2@%%@CR:C6A00150002 @%%@AB@%15.1 Creating a Help System: The Development Cycle%@AE@%%@EH@%%@NL@% The creation of a Help system for a Windows application comprises the following major tasks:%@CR:C6A00150003 @%%@NL@% 1. Gathering information for the Help topics.%@NL@% 2. Planning the Help system.%@NL@% %@STUB@% Chapter 16, "Planning the Help System," describes considerations you should keep in mind when planning your Help system.%@NL@% 3. Writing the text for the Help topics. %@NL@% 4. Entering all required control codes into the text files. %@NL@% %@STUB@% Control codes determine how the user can move around the Help system. Section 15.3, "How Help Appears to the Writer," includes an example of several control codes. Chapter 17, "Creating the Help Topic Files," describes the codes in detail.%@NL@% 5. Creating a project file for the build. %@NL@% %@STUB@% The Help project file provides information that the Help Compiler needs to build a Help resource file. Chapter 18, "Building the Help File," describes the Help project file.%@NL@% 6. Building the Help resource file.%@NL@% %@STUB@% The Help resource file is a compiled version of the topic files the writer creates. Chapter 18, "Building the Help File," describes how to compile a Help resource file.%@NL@% 7. Testing and debugging the Help system.%@NL@% 8. Programming the application so that it can access Windows Help.%@NL@% The following flow diagram shows the general work flow in the conception and development of the Help system.%@CR:C6A00150004 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@2@%%@CR:C6A00150005 @%%@AB@%15.2 How Help Appears to the User%@CR:C6A00150006 @%%@AE@%%@EH@%%@NL@% To the user, the Help system appears to be part of the application, and is made up of text and graphics displayed in the Help window in front of the application. Figure 15.2 illustrates the Help window that appears when the user asks for help with copying text in Helpex. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% The Help window displays one sample Help topic, a partial description of how to perform one task. In Figure 15.2 the first sentence includes a definition of the word "clipboard." By pressing the mouse button when the cursor is on the word (denoted by dotted underlined text), the user can read the definition, which appears in an overlapping box as long as the mouse button is held down.%@CR:C6A00150007 @%%@NL@% Cross-references to related topics are called jumps. By clicking on a jump term for a related topic (denoted by underlined text), the user changes the content of the Help window to a description of the new topic or command. Figure 15.2 includes a look-up to the definition of "clipboard." %@NL@% %@2@%%@CR:C6A00150008 @%%@AB@%15.3 How Help Appears to the Help Writer%@AE@%%@EH@%%@NL@% To the writer, the Help system is a group of topic files, which are text files that include special codes. Figure 15.3 illustrates the source text that corresponds to the topic shown in Figure <$R[C#1]>.2.%@CR:C6A00150009 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% To create this topic, the Help writer describes the task, formats the text, and inserts codes using strikethrough text, underlined text, and footnotes. In place of strikethrough, the writer can use double underlining if the word processor does not support strikethrough formatting. Footnotes in the text contain linking information required by the Help Compiler. Chapter 16, "Planning the Help System," discusses formatting considerations. Chapter 17, "Creating the Help Topic Files," describes how to create topics and enter the special codes that the Help system uses.%@CR:C6A00150010 @%%@NL@% %@2@%%@CR:C6A00150011 @%%@AB@%15.4 How Help Appears to the Help Programmer%@AE@%%@EH@%%@NL@% To the programmer, Windows Help is a stand-alone Windows application which the user can run like any other application. Your application can call the %@AB@%WinHelp%@AE@% function to ask Windows to run the Help application and specify which topic to display in the Help window.%@CR:C6A00150012 @%%@NL@% See Chapter 18, "Building the Help File," for details about the Help application programming interface (API). %@NL@% %@2@%%@CR:C6A00150013 @%%@AB@%15.5 Summary%@AE@%%@EH@%%@NL@% The Help system is made up of topics linked via hypertext. The topics and links appear differently on the screen to the user than they do in a topic file to the writer. To the programmer, Help is a stand-alone application.%@CR:C6A00150014 @%%@NL@% For more information about related topics, see the following: %@NL@% %@TH: 4 337 02 22 54 @%Topic Reference%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Coding Help topics %@AI@%Tools%@AE@%: Chapter 17, "Creating the Help Topic Files"Compiling Help files %@AI@%Tools%@AE@%: Chapter 18, "Building the Help File"%@CR:C6A00150015 @%%@TE: 4 337 02 22 54 @% %@CR:C6A00160001 @%%@1@%%@AB@%Chapter 16 Planning the Help System%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% The initial task for the Help writer is to develop a plan for creating the system. This chapter discusses planning the Help system for a particular application. %@NL@% The chapter covers the following topics: %@NL@% ■ Developing a plan%@NL@% ■ Determining the topic file structure%@NL@% ■ Designing the visual appearance of Help topics %@NL@% %@2@%%@CR:C6A00160002 @%%@AB@%16.1 Developing a Plan%@AE@%%@EH@%%@NL@% Before you begin writing Help topics using the information you have gathered, you and the other members of the Help team should develop a plan that addresses the following issues:%@CR:C6A00160003 @%%@NL@% ■ The audience for your application%@NL@% ■ The content of the Help topics%@NL@% ■ The structure of topics%@NL@% ■ The use of context-sensitive topics%@NL@% You might want to present your plan in a design document that includes an outline of Help information, a diagram of the structure of topics, and samples of the various kinds of topics your system will include. Keep in mind that contextsensitive Help requires increased development time, especially for the application programmer. %@NL@% %@3@%%@CR:C6A00160004 @%%@AB@%16.1.1 Defining the Audience%@AE@%%@EH@%%@NL@% The audience you address determines what kind of information you make available in your Help system and how you present the information.%@CR:C6A00160005 @%%@NL@% Users of Help systems might be classified as follows: %@NL@% %@AB@%User%@AE@% %@AB@%Background%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Computer novice Completely new to computing. Application novice Some knowledge of computing, but new to your kind of application. For example, if you are providing Help for a spreadsheet program, the application novice might be familiar only with word-processing packages. Application Knowledgeable about your kind of intermediate application. Application expert Experienced extensively with your type of application. Keep in mind that one user may have various levels of knowledge. For example, the expert in word processors may have no experience using spreadsheets.%@CR:C6A00160006 @%%@NL@% %@3@%%@CR:C6A00160007 @%%@AB@%16.1.2 Planning the Content of the Help System%@AE@%%@EH@%%@NL@% You should create topics that are numerous enough and specific enough to provide your users with the help they need.%@CR:C6A00160008 @%%@CR:C6A00160009 @%%@NL@% Novice users need help learning tasks and more definitions of terms. More sophisticated users occasionally seek help with a procedure or term, but most often refresh their memory of commands and functions. The expert user tends only to seek help with command or function syntax, keyboard equivalents and shortcut keys. %@NL@% There are no rules for determining the overall content of your Help system. If you are providing Help for all types of users, you will want to document commands, procedures, definitions, features, functions, and other relevant aspects of your application. If you are providing help for expert users only, you might want to omit topics that describe procedures. Let your audience definition guide you when deciding what topics to include. %@NL@% Keep in mind that the decision to implement context-sensitive Help is an important one. Context-sensitive Help demands a close working relationship between the Help author and the application programmer, and will therefore increase the development time necessary to create a successful Help system. %@NL@% %@3@%%@CR:C6A00160010 @%%@AB@%16.1.3 Planning the Structure of Help Topics%@AE@%%@EH@%%@NL@% Many Help systems structure topics hierarchically. At the top of the hierarchy is an index or a table of contents, or both. The index and table of contents list individual topics or categories of topics available to the user.%@CR:C6A00160011 @%%@NL@% Topics themselves can be related hierarchically. Each successive step takes the user one level down in the hierarchy of the Help system until the user reaches topic information. The hierarchical relationship of Help topics determines in part how the user navigates through the Help system. Figure 16.1 illustrates a possible hierarchy: %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% Helpex contains an index that lists several categories of topics. Each category includes a secondary index, which lists topics in the category, and the topics themselves. %@NL@% Moving from the index to a topic, the user goes from the general to the specific. %@NL@% The hierarchical structure provides the user a point of reference within Help. Users are not constrained to navigate up and down the hierarchy; they can jump from one topic to another, moving across categories of topics. The effect of jumps is to obscure hierarchical relationships. For example, the Windows Help application contains a search feature that lets the user enter a key word into a dialog box and search for topics associated with that key word. The Help application then displays a list of titles to choose from in order to access information that relates to the key word. %@NL@% Because users often know which feature they want help with, they can usually find what they want faster using the search feature than they can by moving through the hierarchical structure. For more information about the search feature, see Section 17.3.4, "Assigning Key Words." %@NL@% In addition to ordering topics hierarchically, you can order them in a logical sequence that suits your audience. The logical sequence, or "browse sequence," lets the user choose the Browse button to move from topic to topic. Browse sequences are especially important for users who like to read several related topics at once, such as the topics covering the commands on the File menu. For more information about browse sequences, see Chapter 17, "Creating the Help Topic Files." %@NL@% Whichever structure you decide to use, try to minimize the number of lists that users must traverse in order to obtain information. Also, avoid making users move through many levels to reach a topic. Most Help systems function quite well with only two or three levels.%@CR:C6A00160012 @%%@NL@% %@3@%%@CR:C6A00160013 @%%@AB@%16.1.4 Displaying Context-Sensitive Help Topics%@AE@%%@EH@%%@NL@% Windows Help supports context-sensitive Help. When written in conjunction with programming of the application, context-sensitive Help lets the user press F1 in an open menu to get help with the selected menu item. Alternatively, the user can press SHIFT+F1 and then click on a screen region or command to get help on that item.%@CR:C6A00160014 @%%@CR:C6A00160015 @%%@NL@% For example, if the user presses SHIFT+F1, then clicks on the maximize icon when using the sample application Helpex, the Help system displays the information illustrated in Figure 16.2: %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% Developing context-sensitive Help requires coordination between the Help writer and the application programmer so that Help and the application pass the correct information back and forth.%@CR:C6A00160016 @%%@CR:C6A00160017 @%%@NL@% To plan for context-sensitive Help, the Help author and the application programmer should agree on a list of context numbers. Context numbers are arbitrary numbers that correspond to each menu command or screen region in the application, and are used to create the links to the corresponding Help topics. You can then enter these numbers, along with their corresponding context-string identifiers, in the Help project file, which the Help Compiler uses to build a Help resource file. Section 18.1, "Creating the Help Project File," provides details on how to create a Help project file. %@NL@% The context numbers assigned in the Help project file must correspond to the context numbers that the application sends at run time to invoke a particular topic. See Section 18.9, "Programming the Application to Access Help," for more information on assigning context numbers. %@NL@% If you do not explicitly assign context numbers to topics, the Help Compiler generates default values by converting topic context strings into context numbers. See Section 18.6, "Mapping Context-Sensistive Topics: The Map Section," for more information on context-sensitive Help and context strings.%@CR:C6A00160018 @%%@CR:C6A00160019 @%%@NL@% To manage context numbers and file information, you might want to create a Help tracker to list the context numbers for your context-sensitive topics. See Section 17.5.1, "Creating the Help Tracker," for information about using a tracker.%@CR:C6A00160020 @%%@CR:C6A00160021 @%%@NL@% %@2@%%@CR:C6A00160022 @%%@AB@%16.2 Determining the Topic File Structure%@AE@%%@EH@%%@NL@% The Help file structure remains essentially the same for all applications even though the context and number of topic files differ. Topic files are segmented into the different topics by means of page breaks. When you build the Help system, the compiler uses these topic files to create the information displayed for the user in the application's Help window.%@CR:C6A00160023 @%%@CR:C6A00160024 @%%@NL@% Figure 16.3 shows this basic file structure. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@3@%%@CR:C6A00160025 @%%@AB@%16.2.1 Choosing a File Structure for Your Application%@AE@%%@EH@%%@NL@% When choosing a file structure for your Help system, consider the scope and content of the Help system you are planning. For example, you could place all Help topics in a single large topic file. Or, you could place each Help topic in a separate file. Neither of these file structures is generally acceptable. An enormous single file or too many individual files can present difficulties during the creation of the Help resource file.%@CR:C6A00160026 @%%@CR:C6A00160027 @%%@NL@% The number of topics relates to the number of features covered by the Help system. Consequently, you cannot make extensive changes to one without making changes to the other. For instance, if a number of additional product features are added to Help, then additional topics must be created to accommodate the new information. %@NL@% Figure 16.4 illustrates the file structure of a possible Help system. The number of topics and topic files is limited to simplify the diagram and more clearly show the concept of linking the topics together through jumps, shown in the figure as arrows. The figure is not intended to show the number of files that can be included in the Help file system. Moreover, the figure does not show how topic files are ordered using the browse feature.%@CR:C6A00160028 @%%@CR:C6A00160029 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@2@%%@CR:C6A00160030 @%%@AB@%16.3 Designing the Appearance of Help Topics%@AE@%%@EH@%%@NL@% How the information in the Help window appears to the user is primarily a function of the layout of the Help topic. The Windows Help application supports a number of text attributes and graphic images you can use to design your Help window. %@NL@% This section provides general guidelines for designing a window and describes fonts and graphic images that Windows Help supports. %@NL@% %@3@%%@CR:C6A00160031 @%%@AB@%16.3.1 Layout of the Help Text%@AE@%%@EH@%%@NL@% Help text files are not limited to plain, unformatted text. You can use different fonts and point sizes, include color and graphics to emphasize points, present information in tables, indent paragraphs to present complex information, and use a variety of other visual devices to present your information.%@CR:C6A00160032 @%%@CR:C6A00160033 @%%@NL@% Research on screen format and Help systems has produced general guidelines for presenting information to users. Section 16.5, "Summary," lists some sources of this research. The following list summarizes the findings of these studies. %@NL@% %@TH: 82 4691 02 34 42 @%Design Issue Guideline%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Language Use language appropriate for the audience you have defined. Language that is too sophisticated for your audience can frustrate users by requiring them to learn the definition of unfamiliar terms and concepts.Amount of text Use a minimum of text. Studies indicate that reading speed decreases by 30 percent when users read online text rather than printed text. Minimal, concise text helps users compensate for the decreased reading speed.Paragraph length Use short paragraphs. Online users become overloaded with text more easily than do readers of printed material. Breaking your text into short paragraphs helps avoid this problem.%@CR:C6A00160034 @%White space Use it to help group information visually. White space is important to making online text more readable. Use it liberally, while also considering the overall size that a topic will occupy on the screen. Users tend to think there is more information on a screen than exists. For example, if the ratio of white space to text is 50:50, users perceive the ratio to be 40:60. Highlighting Use highlighting techniques judiciously. Windows Help provides a variety of highlighting devices, such as font sizes, font types, and color. Using a few devices can help users find information quickly. Using many devices will decrease the effectiveness of your visual presentation and frustrate users. As with print-based documentation, use only one or two fonts at a time.Graphics and icons Use graphics to support the explanation of visual events. Windows Help supports the use of bitmapped graphic images. Use appropriate images to help explain the function of icons and screen elements in your application. Remember that graphics will draw the user's eye before the accompanying text. Be sure to crop your images to remove distracting information. Use color images only if you are certain that all your users' systems have color capability. As with context-sensitive Help, consider the additional time necessary to create accurate and meaningful graphic images.Design consistency Be rigorously consistent in your design. Users expect the appearance of Help topics to be the same, regardless of the information presented. Consistent titling, highlighting, fonts, and positioning of text in the window is essential to an effective Help system.%@CR:C6A00160035 @%%@TE: 82 4691 02 34 42 @% Figure 16.5 illustrates a Help window that follows these design principles. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@3@%%@CR:C6A00160036 @%%@AB@%16.3.2 Type Fonts and Sizes%@AE@%%@EH@%%@NL@% The Windows Help application can display text in any font and size available to the system. When the topic files are passed to the build process, the Help Compiler attempts to use the fonts and sizes found in the topic files. If a font or point size cannot be matched exactly when the Help file is displayed by Windows Help, the closest available font and size on the user's system will be used.%@CR:C6A00160037 @%%@NL@% Windows ships with only certain fonts in specific font sizes. If you write Help files using these fonts and sizes, the displayed Help file will closely match the printed word-processed file. Because fonts other than those shipped with Windows may not be available on users' machines, you might want to limit your font selection to the shipped Windows fonts. %@NL@% The fonts included with Windows are: %@NL@% ■ Courier 10,12,15%@NL@% ■ Helv 8,10,12,14,18,24%@NL@% ■ Modern%@NL@% ■ Roman%@NL@% ■ Script%@NL@% ■ Symbol 8,10,12,14,18,24%@NL@% ■ Tms Rmn 8,10,12,14,18,24%@CR:C6A00160038 @%%@NL@% Figure 16.6 illustrates a Help window with Helv-font text: %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% Since Windows Help supports any Windows font, special symbols such as arrows can be included in your topics by using the Symbol font, as shown in Figure 16.7: %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@3@%%@CR:C6A00160039 @%%@AB@%16.3.3 Graphic Images%@AE@%%@EH@%%@NL@% The Windows Help application allows you to embed graphics in the Help file. Graphics can be placed and displayed anywhere on the page. Text can appear next to the graphic, as shown in Figure 16.8:%@CR:C6A00160040 @%%@CR:C6A00160041 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% Color graphic images can be included, provided you use only the available Windows system colors. If you use graphics tools that support an enhanced color palette to create or capture images, these images may not always display with the intended colors. And since you cannot control the color capabilities on a user's machine, you might want to limit your graphic images to black and white bitmaps. %@NL@% Keep in mind that graphics are most effective when they contribute to the learning process. Graphics not tied to the information are usually distracting rather than helpful and should be avoided. See Section 17.4, "Inserting Graphic Images," for more information on placing graphics into your Help files.%@CR:C6A00160042 @%%@NL@% %@2@%%@CR:C6A00160043 @%%@AB@%16.4 Summary%@AE@%%@EH@%%@NL@% This chapter described how to plan a Help system, including defining the audience, planning the content, implementing context-sensitive Help, structuring topic files, and designing the layout of Help topics. %@NL@% For additional information about planning your Help system, see the following: %@NL@% %@AB@%Topic%@AE@% %@AB@%Reference%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Creating topic files %@AI@%Tools%@AE@%: Chapter 17, "Creating the Help Topic Files" Screen design Bradford, Annette Norris. "Conceptual Differences Between the Display Screen and the Printed Page." %@AI@%Technical %@AE@% %@AI@%Communication%@AE@% (Third Quarter 1984): 13-16 Galitz, Wilbert O. %@AI@%Handbook of Screen %@AE@% %@AI@%Format%@AE@% %@AI@%Design.%@AE@% 3d ed. Wellesley, MA: QED Information Sciences, Inc., 1989 Houghton, Raymond C., Jr. "Online Help Systems: A Conspectus." %@AI@%Communications %@AE@% %@AI@%of the ACM%@AE@% 27(February 1984): 126-133 Queipo, Larry. "User Expectations of Online Information." %@AI@%IEEE Transactions on %@AE@% %@AI@%Professional Communications%@AE@% PC 29(December 1986): 11-15 %@CR:C6A00170001 @%%@1@%%@AB@%Chapter 17 Creating the Help Topic Files%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Probably the most time-consuming task in developing a Help system for your application is creating the Help topic files from which you compile the Help system. Help topic files are text files that define what the user sees when using the Help system. The topic files can define various kinds of information, such as an index to information on the system, a list of commands, or a description of how to perform a task. %@NL@% Creating topic files entails writing the text that the user sees when using Help, and entering control codes that determine how the user can move from one topic to another. %@NL@% This chapter describes the following topics: %@NL@% ■ Choosing an authoring tool%@NL@% ■ Structuring Help topic files%@NL@% ■ Coding Help topic files%@NL@% ■ Managing Help topic files %@NL@% %@2@%%@CR:C6A00170002 @%%@AB@%17.1 Choosing an Authoring Tool%@AE@%%@EH@%%@NL@% To write your text files, you will need a Rich Text Format (RTF) editor, which lets you create the footnotes, underlined text, and strikethrough or double-underlined text that indicate the control codes. These codes are described in Section 17.3, "Coding Help Topic Files." Your choices include, but are not limited to:%@CR:C6A00170003 @%%@NL@% ■ Microsoft Word for Windows, version 1.0.%@NL@% ■ Microsoft Word for the PC, version 5.0.%@NL@% ■ Microsoft Word for the Macintosh, version 3.0 or 4.0.%@NL@% ■ Other word processors that support RTF.%@NL@% Microsoft Word's RTF capability allows you to insert the coded text required to define Help terms, such as jumps, key words, and definitions. If you choose an editor other than one of the Microsoft Word products, make sure it will create Help files that work as you intend. %@NL@% %@2@%%@CR:C6A00170004 @%%@AB@%17.2 Structuring Help Topic Files%@AE@%%@EH@%%@NL@% A Help topic file typically contains multiple Help topics. To identify each topic within a file:%@CR:C6A00170005 @%%@NL@% ■ Topics are separated by hard page breaks.%@NL@% ■ Each topic accessible via a hypertext link must have a unique identifier, or context string.%@NL@% ■ Each topic can have a title.%@NL@% ■ Each topic can have a list of key words associated with it.%@NL@% ■ Each topic can have a build-tag indicator.%@NL@% ■ Any topic can have an assigned browse sequence.%@NL@% Figure 17.1 illustrates part of the topic file that contains descriptions of how to perform tasks using the sample application Helpex. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% For information about inserting page breaks between topics, see the documentation for the editor you are using. For information about assigning context strings and titles to topics, see the following sections. %@NL@% %@2@%%@CR:C6A00170006 @%%@AB@%17.3 Coding Help Topic Files%@AE@%%@EH@%%@NL@% The Help system uses control codes for particular purposes:%@CR:C6A00170007 @%%@CR:C6A00170008 @%%@NL@% %@AB@%Control Code%@AE@% %@AB@%Purpose%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Asterisk (*) footnote Build tag─Defines a tag that specifies topics the compiler conditionally builds into the system. Build tags are optional, but they must appear first in a topic when they are used. Pound sign (#) footnote Context string─Defines a context string that uniquely identifies a topic. Because hypertext relies on links provided by context strings, topics without context strings can only be accessed using key words or browse sequences. Dollar sign ($) footnote Title─Defines the title of a topic. Titles are optional. Letter "K" footnote Key word─Defines a key word the user uses to search for a topic. Key words are optional. Plus sign (+) footnote Browse sequence number─Defines a sequence that determines the order in which the user can browse through topics. Browse sequences are optional. However, if you omit browse sequences, the Help window will still include the Browse buttons, but they will be grayed. Strikethrough or Cross-reference─Indicates the text the double-underlined text user can choose to jump to another topic. Underlined text Definition─Specifies that a temporary or "look-up" box be displayed when the user holds down the mouse button or ENTER key. The box can include such information as the definition of a word or phrase, or a hint about a procedure. Hidden text Cross-reference context string─Specifies the context string for the topic that will be displayed when the user chooses the text that immediately precedes it. If you are using build tags, footnote them at the very beginning of the topic. Place other footnotes in any order you want. For information about assigning specific control codes, see the following sections. %@NL@% %@3@%%@CR:C6A00170009 @%%@AB@%17.3.1 Assigning Build Tags%@CR:C6A00170010 @%%@AE@%%@EH@%%@NL@% Build tags are strings that you assign to a topic in order to conditionally include or exclude that topic from a build. Each topic can have one or more build tags. Build tags are not a necessary component of your Help system. However, they do provide a means of supporting different versions of a Help system without having to create different source files for each version. Topics without build tags are always included in a build. %@NL@% You insert build tags as footnotes using the asterisk (*). When you assign a build tag footnote to a topic, the compiler includes or excludes the topic according to build information specified in the %@AB@%BUILD%@AE@% option and [BuildTags] section of the Help project file. For information about the %@AB@%BUILD %@AE@%option, the [BuildTags] section and the Help project file, see Chaper 18, "Building the Help File."%@CR:C6A00170011 @%%@NL@% To assign a build tag to a topic: %@NL@% 1. Place the cursor at the beginning of the topic heading line, so that it appears before all other footnotes for that topic.%@NL@% 2. Insert the asterisk (*) as a footnote reference mark.%@NL@% %@STUB@% Note that a superscript asterisk ( * ) appears next to the heading. %@NL@% 3. Type the build tag name as the footnote. %@NL@% %@STUB@% Be sure to allow only a single space between the asterisk (*) and the build tag. %@NL@% Build tags can be made up of any alphanumeric characters. The build tag is not case-sensitive. The tag may not contain spaces. You can specify multiple build tags by separating them with a semicolon, as in the following example: %@NL@% %@AS@% * AppVersion1; AppVersion2; Test_Build%@AE@% Including a build tag footnote with a topic is equivalent to setting the tag to true when compared to the value set in the project file. The compiler assumes all other build tags to be false for that topic. After setting the truth value of the build tag footnotes, the compiler evaluates the build expression in the Options section of the Help project file. Note that all build tags must be declared in the project file, regardless of whether a given conditional compilation declares the tags. If the evaluation results in a true state, the compiler includes the topic in the build. Otherwise, the compiler omits the topic. %@NL@% The compiler includes in all builds topics that do not have a build tag footnote regardless of the build tag expressions defined in the Help project file. For this reason, you may want to use build tags primarily to exclude specific topics from certain builds. If the compiler finds any build tags not declared in the Help project file, it displays an error message. %@NL@% By allowing conditional inclusion and exclusion of specific topics, you can create multiple builds using the same topic files. This saves time and effort for the Help development team. It also means that you can develop Help topics that will help you maintain a higher level of consistency across your product lines.%@CR:C6A00170012 @%%@NL@% %@3@%%@CR:C6A00170013 @%%@AB@%17.3.2 Assigning Context Strings%@AE@%%@EH@%%@NL@% Context strings identify each topic in the Help system. Each context string must be unique. A given context string may be assigned to only one topic within the Help project; it cannot be used for any other topic.%@CR:C6A00170014 @%%@NL@% The context string provides the means for creating jumps between topics or to display look-up boxes, such as word and phrase definitions. Though not required, most topics in the Help system will have context-string identifiers, Topics without context strings may not be accessed through hypertext jumps. However, topics without context-string identifiers can be accessed through browse sequences or key-word searches, if desired. It is up to the Help writer to justify the authoring of topics that can be accessed only in these manners. For information about assigning jumps, see Section 17.3.6, "Creating Cross-References Between Topics." For information about assigning browse sequences, see Section 17.3.5, "Assigning Browse Sequence Numbers." For information about assigning key words, see Section 17.3.4, "Assigning Key Words." %@NL@% To assign a context string to a Help topic: %@NL@% 1. Place the cursor to the left of the topic heading.%@NL@% 2. Insert the pound sign (#) as the footnote reference mark.%@NL@% %@STUB@% Note that a superscript pound sign ( # ) appears next to the heading. %@NL@% 3. Type the context string as the footnote. %@NL@% %@STUB@% Be sure to allow only a single space between the pound sign (#) and the string. %@NL@% %@STUB@% Context strings are not case-sensitive. %@NL@% Valid context strings may contain the alphabetic characters A-Z, the numeric characters 0-9, and the period (.) and underscore (_) characters. The following example shows the context string footnote that identifies a topic called "Opening an Existing Text File": %@NL@% %@AS@% #OpeningExistingTextFile%@AE@% Although a context string has a practical limitation of about 255 characters, there is no good reason for approaching this value. Keep the strings sensible and short so that they're easier to enter into the text files.%@CR:C6A00170015 @%%@NL@% %@3@%%@CR:C6A00170016 @%%@AB@%17.3.3 Assigning Titles%@AE@%%@EH@%%@NL@% Title footnotes perform the following functions within the Help system:%@CR:C6A00170017 @%%@NL@% ■ They appear on the Bookmark menu.%@NL@% ■ They appear in the "Topics found " list that results from a key-word search. (Topics that do not have titles, but are accessible via key words are listed as >>Untitled Topic<< in the Topics found list.)%@NL@% Although not required, most topics have a title. You might not assign a title to topics containing low-level information that Help's search feature, look-up boxes and system messages do not access. %@NL@% To assign a title to a topic:%@CR:C6A00170018 @%%@NL@% 1. Place the cursor to the left of the topic heading.%@NL@% 2. Insert a footnote with a dollar sign ($) as the footnote reference mark.%@NL@% %@STUB@% Note that a superscript dollar sign ( $ ) appears next to the heading. %@NL@% 3. Type the title as the footnote. %@NL@% %@STUB@% Be sure to allow only a single space between the dollar sign ($) and the title.%@NL@% The following is an example of a footnote that defines the title for a topic: %@NL@% %@AS@% $ Help Keys%@AE@% When adding titles, keep in mind the following restrictions: %@NL@% %@TH: 15 770 02 34 42 @%Item Restrictions%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Characters Titles can be up to 128 characters in length. The Help compiler truncates title strings longer than 128 characters. The help system displays titles in a list box when the user searches for a key word or enters a bookmark.Formatting Title footnote entries cannot be formatted.%@CR:C6A00170019 @%%@TE: 15 770 02 34 42 @% %@3@%%@CR:C6A00170020 @%%@AB@%17.3.4 Assigning Key Words%@AE@%%@EH@%%@NL@% Help allows the user to search for topics with the use of key words assigned to the topics. When the user searches for a topic by key word, Help matches the user-entered word to key words assigned to specific topics. Help then lists matching topics by their titles in the Search dialog box. Because a key-word search is often a fast way for users to access Help topics, you'll probably want to assign key words to most topics in your Help system.%@CR:C6A00170021 @%%@CR:C6A00170022 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%You should specify a key-word footnote only if the topic has a title %@AI@%footnote since the title of the topic will appear in the search dialog when %@AI@%the user searches for the key word.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% To assign a key word to a topic: %@NL@% 1. Place the cursor to the left of the topic heading.%@NL@% 2. Insert an uppercase K as the footnote reference mark.%@NL@% %@STUB@% Note that a superscript K ( K ) appears next to the heading.%@NL@% 3. Type the key word, or key words, as the footnote. %@NL@% %@STUB@% Be sure to allow only a single space between the K and the first key word.%@NL@% %@STUB@% If you add more than one key word, separate each with a semicolon.%@NL@% The following is an example of key words for a topic: %@NL@% %@AS@% K open;opening;text file;ASCII;existing;text only;documents;%@AE@% Whenever the user performs a search on any of these key words, the corresponding titles appear in a list box. More than one topic may have the same key word. %@NL@% When adding key words, keep in mind the following restrictions:%@CR:C6A00170023 @%%@CR:C6A00170024 @%%@NL@% %@TH: 21 1059 02 34 42 @%Item Restrictions%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%Characters Key words can include any ANSI character, including accented characters. The maximum length for key words is 255 characters. A space imbedded in a key phrase is considered to be a character, permitting phrases to be key words.Phrases Help searches for any word in the specified phrase.Formatting Key words are unformatted.Case sensitivity Key words are not case-sensitive.Punctuation Except for semicolon delimiters, you can use punctuation. %@CR:C6A00170025 @%%@CR:C6A00170026 @%%@TE: 21 1059 02 34 42 @% %@4@%%@AB@%Creating Multiple Key-Word Tables%@AE@%%@EH@%%@NL@% Multiple key-word tables are useful to allow a program to look up topics that are defined in alternate key-word tables. You can use an additional key-word table to allow users familiar with key words in a different application to discover the matching key words in your application. %@NL@% Authoring additional key-word tables is a two-part process. First, the %@AB@%MULTIKEY%@AE@% option must be placed in the [Options] section of the project file. For information on the%@AB@% MULTIKEY%@AE@% option, see Section 18.4.8, "Multiple Key-Word Tables: The Multikey Option." %@NL@% Second, the topics to be associated with the additional key-word table must be authored and labeled. Footnotes are assigned in the same manner as the normal key-word footnotes, except that the letter specified with the%@AB@% %@AB@%MULTIKEY%@AE@% option is used. With this version of the Help Compiler, the key-word footnote used is case-sensitive. Therefore, care should be taken to use the same case, usually uppercase, for your key-word footnote. Be sure to associate only one topic with a key word. Help does not display the normal search dialog box for a multiple key-word search. Instead it displays the first topic found with the specified key word. If you want the topics in your additional key-word table to appear in the normal Help key-word table, you must also specify a "K" footnote and the given key word. %@NL@% The application you are developing Help for can then display the Help topic associated with a given string in a specified key-word table. Key words are sorted without regard to case for the key-word table. For information on the parameters passed by the application to call a topic found in alternate key-word table, see Section 18.9.4, "Accessing Additional Key-Word Tables."%@CR:C6A00170027 @%%@CR:C6A00170028 @%%@NL@% %@3@%%@CR:C6A00170029 @%%@AB@%17.3.5 Assigning Browse Sequence Numbers%@AE@%%@EH@%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%In this version of Help, topics defined in browse sequences are accessed %@AI@%using the Browse buttons at the top of the Help window. Future versions of %@AI@%Help will not normally display browse buttons for the user. However, if your %@AI@%Help resource file includes browse sequences authored in the format %@AI@%described here, these versions will support the feature by automatically %@AI@%displaying browse buttons for the user. %@CR:C6A00170030 @%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% The Browse >> and Browse browse sequence." A browse sequence is determined by sequence numbers, established by the Help writer. %@NL@% To build browse sequences into the Help topics, the writer must: %@NL@% 1. Decide which topics should be grouped together and what order they should follow when viewed as a group. %@NL@% %@STUB@% Help supports multiple, discontiguous sequence lists.%@NL@% 2. Code topics to implement the sequence. %@NL@% %@4@%%@AB@%Organizing Browse Sequences%@AE@%%@EH@%%@NL@% When organizing browse sequences, the writer must arrange the topics in an order that will make sense to the user. Topics can be arranged in alphabetical order within a subject, in order of difficulty, or in a sensible order that seems natural to the application. The following example illustrates browse sequences for the menu commands used in a given application. The Help writer has subjectively defined the order that makes the most sense from a procedural point of view. You may, of course, choose a different order.%@CR:C6A00170031 @%%@NL@% %@AS@% SampleApp Commands %@AS@% File Menu - commands:005 %@AS@% New Command - file_menu:005 %@AS@% Open Command - file_menu:010 %@AS@% Save Command - file_menu:015 %@AS@% Save As Command - file_menu:020 %@AS@% Print Command - file_menu:025 %@AS@% Printer Setup Command - file_menu:030 %@AS@% Exit Command - file_menu:035 %@AS@% Edit Menu - commands:010 %@AS@% Undo Command - edit_menu:025 %@AS@% Cut Command - edit_menu:015 %@AS@% Copy Command - edit_menu:010 %@AS@% Paste Command - edit_menu:020 %@AS@% Clear Command - edit_menu:005 %@AS@% Select All Command - edit_menu:030 %@AS@% Word Wrap Command - edit_menu:035 %@AS@% Type Face Command - edit_menu:040 %@AS@% Point Size Command - edit_menu:045 %@AS@% Search Menu - commands:015 %@AS@% Find Command - search_menu:005 %@AS@% Find Next Command - search_menu:010 %@AS@% Previous Command - search_menu:015 %@AS@% Window Menu - commands:020 %@AS@% Tile Command - window_menu:005 %@AS@% Cascade Command - window_menu:010 %@AS@% Arrange Icons Command - window_menu:015 %@AS@% Close All Command - window_menu:020 %@AS@% Document Names Command - window_menu:025%@AE@% Each line consists of a sequence list name followed by a colon and a sequence number. The sequence list name is optional. If the sequence does not have a list name, as in the following example, the compiler places the topic in a "null" list: %@NL@% %@AS@% Window Menu - 120%@AE@% Note that the numbers used in the browse sequence example begin at 005 and advance in increments of 005. Generally, it is good practice to skip one or more numbers in a sequence so you can add new topics later if necessary. Skipped numbers are of no conseqence to the Help Compiler; only their order is significant.%@CR:C6A00170032 @%%@NL@% Sequence numbers establish the order of topics within a browse sequence list. Sequence numbers can consist of any alphanumeric characters. During the compiling process, strings are sorted using the ASCII sorting technique, not a numeric sort. %@NL@% Both the alphabetic and numeric portions of a sequence can be several characters long; however, their lengths should be consistent throughout all topic files. If you use only numbers in the strings make sure the strings are all the same length; otherwise a higher sequence number could appear before a lower one in certain cases. For example, the number 100 is numerically higher than 99, but 100 will appear before 99 in the sort used by Help, because Help is comparing the first two digits in the strings. In order to keep the topics in their correct numeric order, you would have to make 99 a three-digit string: 099. %@NL@% %@4@%%@AB@%Coding Browse Sequences%@AE@%%@EH@%%@NL@% After determining how to group and order topics, code the sequence by assigning the appropriate sequence list name and number to each topic, as follows:%@CR:C6A00170033 @%%@NL@% 1. Place the cursor to the left of the topic heading.%@NL@% 2. Insert the plus sign (+) as the footnote reference mark.%@NL@% %@STUB@% Note that a superscript plus sign ( + ) appears next to the heading.%@NL@% 3. Type the sequence number using alphanumeric characters.%@NL@% For example, the following footnote defines the browse sequence number for the Edit menu topic in the previous browse sequence example: %@NL@% %@AS@% + commands:010%@AE@% While it may be easier to list topics within the file in the same order that they appear in a browse sequence, it is not necessary. The compiler orders the sequence for you.%@CR:C6A00170034 @%%@NL@% %@3@%%@CR:C6A00170035 @%%@AB@%17.3.6 Creating Cross-References Between Topics%@AE@%%@EH@%%@NL@% Cross-references, or "jumps," are specially-coded words or phrases that are linked to other topics. Although you indicate jump terms with strikethrough or double-underlined text in the topic file, they appear underlined in the Help window. In addition, jump terms appear in color on color systems. For example, the strikethrough text (double-underlined in Word for Windows) New Command appears as %@AU@%New Command%@AE@% in green text to the user.%@CR:C6A00170036 @%%@NL@% To code a word or phrase as a jump in the topic file : %@NL@% 1. Place the cursor at the point in the text where you want to enter the jump term.%@CR:C6A00170037 @%%@CR:C6A00170038 @%%@CR:C6A00170039 @%%@NL@% 2. Select the strikethrough (or double-underline) feature of your editor.%@NL@% 3. Type the jump word or words in strikethrough mode.%@NL@% 4. Turn off strikethrough and select the editor's hidden text feature.%@NL@% 5. Type the context string assigned to the topic that is the target of the jump. %@NL@% When coding jumps, keep in mind that: %@NL@% ■ No spaces can occur between the strikethrough (or double-underlined) text and the hidden text. %@NL@% ■ Coded spaces before or after the jump term are not permitted.%@NL@% ■ Paragraph marks must be entered as plain text.%@NL@% %@3@%%@CR:C6A00170040 @%%@AB@%17.3.7 Defining Terms%@AE@%%@EH@%%@NL@% Most topic files contain words or phrases that require further definition. To get the definition of a word or phrase, the user first selects the word and then holds down the mouse button or ENTER key, causing the definition to appear in a box within the Help window. The Help writer decides which words to define, considering the audience that will be using the application and which terms might already be familiar.%@CR:C6A00170041 @%%@CR:C6A00170042 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The look-up feature need not be limited to definitions. With the capability %@AI@%to temporarily display information in a box, you might want to show a hint %@AI@%about a procedure, or other suitable information for the user.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% Defining a term requires that you: %@NL@% ■ Create a topic that defines the term.%@NL@% %@STUB@% The definition topic must include a context string. See Section 17.3.2, "Assigning Context Strings."%@NL@% ■ Provide a cross-reference for the definition topic whenever the term occurs.%@NL@% %@STUB@% You don't need to define the same word multiple times in the same topic, just its first occurrence. Also, consider the amount of colored text you are creating in the Help window.%@NL@% %@STUB@% See the following "Coding Definitions" section.%@NL@% %@4@%%@AB@%Creating Definition Topics%@AE@%%@EH@%%@NL@% You can organize definition topics any way you want. For example, you can include each definition topic in the topic file that mentions the term. Or you can organize all definitions in one topic file and provide the user with direct access to it. Helpex uses the latter method, with all definitions residing in the TERMS.RTF file. Organizing definition topics into one file provides you with a glossary and lets you make changes easily.%@CR:C6A00170043 @%%@CR:C6A00170044 @%%@NL@% %@4@%%@AB@%Coding Definitions%@AE@%%@EH@%%@NL@% After creating definition topics, code the terms as they occur, as follows: %@NL@% 1. Place the insertion point where you want to place the term that requires definition.%@NL@% 2. Select the underline feature of your editor.%@NL@% 3. Type the term.%@NL@% 4. Turn off the underline feature, and select the editor's hidden-text feature.%@NL@% 5. Type the context string assigned to the topic that contains the definition of the term.%@NL@% Figure 17.2 includes a definition of the term "Clipboard." %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@2@%%@CR:C6A00170045 @%%@AB@%17.4 Inserting Graphic Images%@AE@%%@EH@%%@NL@% Bitmapped graphic images can be placed in Help topics using either of two methods. If your word processor supports the placement of Windows 2.1 or Windows 3.0 graphics directly into a document, you can simply paste your bitmaps into each topic file. Alternatively, you can save each bitmap in a separate file and specify the file by name where you want it to appear in the Help topic file. The latter method of placing graphics is referred to as "bitmaps by reference." The following sections describe the process of placing bitmaps directly or by reference into your Help topics.%@CR:C6A00170046 @%%@NL@% %@3@%%@CR:C6A00170047 @%%@AB@%17.4.1 Creating and Capturing Bitmaps%@AE@%%@EH@%%@NL@% You can create your bitmaps using any graphical tools, as long as the resulting images can be displayed in the Windows environment. Each graphic image can then be copied to the Windows clipboard. Once on the clipboard, a graphic can be pasted into a graphics editor such as Paint, and modified or cleaned up as needed.%@CR:C6A00170048 @%%@NL@% Windows Help 3.0 supports color bitmaps. However, for future compatibility, you might want to limit graphics to monochrome format. If you are producing monochrome images, you might have to adjust manually the elements of your source graphic that were originally different colors to either black, white, or a pattern of black and white pixels. %@NL@% When you are satisfied with the appearance of your bitmap, you can either save it as a file, to be used as a bitmap by reference, or you can copy it onto the clipboard and paste it into your word processor. If you save the graphic as a file, be sure to specify its size in your graphics editor first, so that only the area of interest is saved for display in the Help window. The tighter you crop your images, the more closely you will be able to position text next to the image. Always save (or convert and save if necessary) graphics in Windows' .BMP format. %@NL@% Bitmap images should be created in the same screen mode that you intend Help to use when topics are displayed. If your Help files will be displayed in a different mode, bitmaps might not retain the same aspect ratio or information as their source images.%@CR:C6A00170049 @%%@NL@% %@3@%%@CR:C6A00170050 @%%@AB@%17.4.2 Placing Bitmaps Using a Graphical Word Processor%@AE@%%@EH@%%@NL@% The easiest way to precisely place bitmaps into Help topics is to use a graphical word processor. Word for Windows supports the direct importation of bitmaps from the clipboard. Simply paste the graphic image where you want it to appear in the Help topic. You can format your text so that it is positioned below or alongside the bitmap. When you save your Help topic file in RTF, the pasted-in bitmap is converted as well and will automatically be included in the Help resource file.%@CR:C6A00170051 @%%@NL@% %@3@%%@CR:C6A00170052 @%%@AB@%17.4.3 Placing Bitmaps by Reference%@AE@%%@EH@%%@NL@% If your word processor cannot import and display bitmaps directly, you can specify the location of a bitmap that you have saved as a file. To insert a bitmap reference in the Help topic file, insert one the following statements where you want the bitmap to appear in the topic: %@NL@% {%@AB@%bmc%@AE@% %@AI@%filename%@AE@%.bmp} {%@AB@%bml%@AE@% %@AI@%filename%@AE@%.bmp} {%@AB@%bmr%@AE@% %@AI@%filename%@AE@%.bmp} %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%Do not specify a full path for %@AI@%filename%@AE@%%@AI@%. If you need to direct the compiler %@AI@%to a bitmap in a location other than the root directory for the build, %@AI@%specify the absolute path for the bitmap in the [Bitmaps] section of the %@AI@%project file.%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% The argument %@AB@%bmc%@AE@% stands for "bitmap character," indicating that the bitmap referred to will be treated the same as a character placed in the topic file at the same location on a line. Text can precede or follow the bitmap on the same line, and line spacing will be determined based upon the size of the characters (including the bitmap character) on the line. Do not specify negative line spacing for a paragraph with a bitmap image, or the image may inadvertently overwrite text above it when it is displayed in Help. When you use the argument %@AB@%bmc%@AE@%, there is no automatic text wrapping around the graphic image. Text will follow the bitmap, positioned at the baseline.%@CR:C6A00170053 @%%@NL@% The argument %@AB@%bml%@AE@% specifies that the bitmap appear at the left margin, with text wrapping automatically along the right edge of the image. The argument %@AB@%bmr%@AE@% specifies that the bitmap appear at the right margin, with text to its left. Bitmap filenames must be the same as those listed in the [Bitmaps] section of the Help project file. The [Bitmaps] section is described in Chapter 18, "Building the Help File." %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%Multiple references to a bitmap of the same name refer to the same bitmap %@AI@%when the Help file is displayed. This means that bitmap references can be %@AI@%repeated in your Help system without markedly increasing the size of the %@AI@%Help resource file.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% Figure 17.3 shows the placement of three bitmaps with related text in a topic as displayed in Help. %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@2@%%@CR:C6A00170054 @%%@AB@%17.5 Managing Topic Files%@AE@%%@EH@%%@NL@% Help topic files can be saved in the default word-processor format or in RTF. If you always save your files in RTF, and later need to make a change, the word processor may take additional time to interpret the format as it reloads the file. If you anticipate making numerous changes during Help development, you might want to minimize this delay by saving topic files in both default and RTF formats, with different file extensions to distinguish them. The compiler needs only the RTF files, and you will have faster access to the source files for changes. On a large project, this practice can save a considerable amount of development time.%@CR:C6A00170055 @%%@NL@% %@3@%%@CR:C6A00170056 @%%@AB@%17.5.1 Keeping Track of Files and Topics%@AE@%%@EH@%%@NL@% It is important to keep track of all topic files for the following reasons:%@CR:C6A00170057 @%%@NL@% ■ To ensure that no topics are left out of the build process%@NL@% ■ To ensure that each topic has been assigned a unique context string%@NL@% ■ To double-check browse sequencing within general and specific lists%@NL@% ■ To show key-word and title matches%@NL@% ■ To allow writers to see where the text for each of the topics is located%@NL@% ■ To keep track of changes to files and the current status%@NL@% ■ To track any other aspect of the Help development process that you think essential%@NL@% At a minimum, writers must keep track of their own topic files, and must pass the filenames to the person who is responsible for creating the Help project file. %@NL@% %@3@%%@CR:C6A00170058 @%%@AB@%17.5.2 Creating a Help Tracker%@AE@%%@EH@%%@NL@% While it is important that you track topic files throughout the development cycle, the tracking tool can be anything that suits your needs. You can maintain a current list of topics in an ASCII text file, in a Microsoft Excel worksheet (if available), or in another format.%@CR:C6A00170059 @%%@NL@% When you or another writer creates or revises a topic, you should update the Help tracking file to reflect the change. The contents of the tracking file are not rigidly defined, but should contain entries for filename, context string, title, browse sequence, and key words. If your application makes use of the context-sensitive feature of Help, you may want to keep track of the context-sensitive information as well. This entry is necessary only if you are assigning context numbers to topics in the Help project file. You can also include optional information, such as date created, date modified, status, and author, if you want to keep track of all aspects of the Help development process. How you organize this information is entirely up to you. %@NL@% The following sample text file and worksheet illustrate how the tracker might be organized for the Help system topics. The examples show both Help menu and context-sensitive Help entries for the topic files. Typically, the same topics that the user accesses when choosing commands from the Help menus can be accessed by the context-sensitive Help feature. The topics with entries in the context ID column are used for context-sensitive help as well as for the Help menus. Notice that some topics have more than one context-sensitive help number. This enables the topic to be displayed when the user clicks on different regions of the screen.%@CR:C6A00170060 @%%@CR:C6A00170061 @%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% Of course, you are free to keep track of the topic files you produce in a manner different from either of these two examples. %@NL@% %@2@%%@CR:C6A00170062 @%%@AB@%17.6 Summary%@AE@%%@EH@%%@NL@% This chapter described how to write, code, and keep track of Help topic files. For information about building a Help file, see Chapter 18, "Building the Help File." %@NL@% %@CR:C6A00180001 @%%@1@%%@AB@%Chapter 18 Building the Help File%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% After the topic files for your Help system have been written, you are ready to create a Help project file and run a build to test the Help file. The Help project file contains all information the compiler needs to convert help topic files into a binary Help resource file.%@CR:C6A00180002 @%%@NL@% You use the Help project file to tell the Help Compiler which topic files to include in the build process. Information in the Help project file also enables the compiler to map specific topics to context numbers (for the context-sensitive portion of Help). %@NL@% After you have compiled your Help file, the development team programs the application so the user can access it. %@NL@% The chapter describes the following: %@NL@% ■ Creating a Help project file%@NL@% ■ Compiling the Help file%@NL@% ■ Programming the application to access Help %@NL@% %@2@%%@CR:C6A00180003 @%%@AB@%18.1 Creating the Help Project File%@AE@%%@EH@%%@NL@% You use the Help project file to control how the Help Compiler builds your topic files. The Help project file can contain up to six sections that perform the following functions:%@CR:C6A00180004 @%%@NL@% %@TH: 24 1271 02 34 42 @%Section Function%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%[Files] Specifies topic files to be included in the build. This section is mandatory.[Options] Specifies the level of error reporting, topics to be included in the build, the directory in which to find the files, and the location of your Help index. This section is optional.[BuildTags] Specifies valid build tags. This section is optional.[Alias] Assigns one or more context strings to the same topic. This section is optional.[Map] Associates context strings with context numbers. This section is optional.[Bitmaps] Specifies bitmap files to be included in the build. This section is optional.%@TE: 24 1271 02 34 42 @% You can use any ASCII text editor to create your Help project file. The extension of a Help project file is .HPJ. If you do not use the extension .HPJ on the %@AB@%HC%@AE@% command line, the compiler looks for a project file with this extension before loading the file. The .HLP output file will have the same name as the .HPJ file.%@CR:C6A00180005 @%%@NL@% The order of the various sections within the Help project file is arbitrary, with one exception: under all circumstances an [Alias] section must precede the [Map] section (if an [Alias] section is used). %@NL@% Section names are placed within square brackets using the following syntax: %@NL@% %@AS@% [section-name]%@AE@% You can use a semicolon to indicate a comment in the project file. The compiler ignores all text from the semicolon to the end of the line on which it occurs. %@NL@% %@2@%%@CR:C6A00180006 @%%@AB@%18.2 Specifying Topic Files: The Files Section%@AE@%%@EH@%%@NL@% Use the [Files] section of the Help project file to list all topic files that the Help Compiler should process to produce a Help resource file. A Help project file must have a [Files] section.%@CR:C6A00180007 @%%@NL@% The following sample shows the format of the [Files] section: %@NL@% %@AS@% [FILES] %@AS@% HELPEX.RTF ;Main topics for HelpEx application %@AS@% TERMS.RTF ;Lookup terms for HelpEx appliction%@AE@% Using the path defined in the %@AB@%ROOT%@AE@% option, the Help Compiler finds and processes all files listed in this section of the Help project file. If the file is not on the defined path and cannot be found, the compiler generates an error. For more information about the %@AB@%ROOT%@AE@% option, see Section 18.4.3, "Specifying the Root Directory: The Root Option." %@NL@% You can include files in the build process using the C %@AB@%#include%@AE@% directive command. %@NL@% The %@AB@%#include%@AE@% directive uses the following syntax: %@NL@% %@AS@% #include <filename>%@AE@% You must include the angle brackets around the filename. The pound sign ( # ) must be the first character in the line. The filename must specify a complete path, either the path defined by the %@AB@%ROOT %@AE@%option or an absolute directory path to the file. %@NL@% You may find it easier to create a text file that lists all files in the Help project and include that file in the build, as in this example: %@NL@% %@AS@% [FILES] %@AS@% #include <hlpfiles.inc>%@AE@% %@2@%%@CR:C6A00180008 @%%@AB@%18.3 Specifying Build Tags: The BuildTags Section%@AE@%%@EH@%%@NL@% If you code build tags in your topic files, use the [BuildTags] section of the Help project file to define all the valid build tags for a particular Help project. The [BuildTags] section is optional.%@CR:C6A00180009 @%%@NL@% The following example shows the format of the [BuildTags] section in a sample Help project file: %@NL@% %@AS@% [BUILDTAGS] %@AS@% WINENV ;topics to include in Windows build %@AS@% DEBUGBUILD ;topics to include in debugging build %@AS@% TESTBUILD ;topics to include in a mini-build for testing%@AE@% The [BuildTags] section can include up to 30 build tags. The build tags are not case-sensitive and may not contain space characters. Only one build tag is allowed per line in this section. The compiler will generate an error message if anything other than a comment is listed after a build tag in the [BuildTags] section. %@NL@% For information about coding build tags in topic files, see Section 17.3.3, "Assigning Build Tags."%@CR:C6A00180010 @%%@NL@% %@2@%%@CR:C6A00180011 @%%@AB@%18.4 Specifying Options: The Options Section%@AE@%%@EH@%%@NL@% Use the [Options] section of the Help project file to specify the following options:%@CR:C6A00180012 @%%@NL@% %@TH: 29 1401 02 34 42 @%Option Meaning%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%%@AB@%BUILD%@AE@% Determines what topics the compiler includes in the build.%@AB@%COMPRESS%@AE@% Specifies compression of the Help resource file.%@AB@%FORCEFONT%@AE@% Specifies the creation of a Help resource file using only one font.%@AB@%INDEX%@AE@% Specifies the context string of the Help index.%@AB@%MAPFONTSIZE%@AE@% Determines the mapping of specified font sizes to different sizes.%@AB@%MULTIKEY%@AE@% Specifies alternate key-word mapping for topics.%@AB@%ROOT%@AE@% Designates the directory to be used for the Help build.%@AB@%TITLE%@AE@% Specifies the title shown for the Help system.%@AB@%WARNING%@AE@% Indicates the kind of error message the compiler reports.%@TE: 29 1401 02 34 42 @% These options can appear in any order within the [Options] section. The [Options] section is not required. %@NL@% Detailed explanations of the available options follow.%@CR:C6A00180013 @%%@NL@% %@3@%%@CR:C6A00180014 @%%@AB@%18.4.1 Specifying Error Reporting: The Warning Option%@AE@%%@EH@%%@NL@% Use the %@AB@%WARNING%@AE@% option to specify the amount of debugging information that the compiler reports. The %@AB@%WARNING%@AE@% option has the following syntax:%@CR:C6A00180015 @%%@NL@% %@AS@% WARNING = level%@AE@% You can set the %@AB@%WARNING%@AE@% option to any of the following levels: %@NL@% %@TH: 9 472 02 34 42 @%Level Information Reported%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%1 Only the most severe warnings.2 An intermediate level of warnings. 3 All warnings. This is the default level if no %@AB@%WARNING%@AE@% option is specified.%@TE: 9 472 02 34 42 @% The following example specifies an intermediate level of error reporting: %@NL@% %@AS@% [OPTIONS] %@AS@% WARNING=2%@AE@% The compiler reports errors to the standard output file, typically the screen. You may want to redirect the errors to a disk file so that you can browse it when you are debugging the Help system. The following example shows the redirection of compiler screen output to a file. %@NL@% %@AS@% HC HELPEX > errors.out%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% HINT %@AI@%Use the DOS CONTROL+PRINT SCREEN%@AI@% accelerator key before you begin your %@AI@%compilation to echo errors which appear on the screen to your printer. Type %@AI@%CONTROL+PRINT SCREEN%@AE@%%@AI@% again to stop sending information to the printer.%@CR:C6A00180016 @%%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00180017 @%%@AB@%18.4.2 Specifying Build Topics: The Build Option%@AE@%%@EH@%%@NL@% If you have included build tags in your topic files, use the %@AB@%BUILD%@AE@% option to specify which topics to conditionally include in the build. If your topic files have no build tags, omit the %@AB@%BUILD%@AE@% option from the [Options] section.%@CR:C6A00180018 @%%@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%All build tags must be listed in the [BuildTags] section of the project %@AI@%file, regardless whether or not a given conditional compilation declares the %@AI@%tags.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% See Chapter 17, "Creating the Help Topic Files," for information on assigning build tags to topics in the Help topic files. %@NL@% The %@AB@%BUILD%@AE@% option line uses the following syntax: %@NL@% %@AS@% BUILD = expression%@AE@% %@AB@%BUILD%@AE@% expressions cannot exceed 255 characters in length, and must be entered on only one line. %@AB@%BUILD%@AE@% expressions use Boolean logic to specify which topics within the specified Help topic files the compiler will include in the build. The tokens of the language are: %@NL@% %@TH: 7 339 02 24 52 @%Token Description%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%<tag> Build tag( ) Parentheses& AND operator| OR operator~ NOT operator%@TE: 7 339 02 24 52 @% The compiler evaluates all build expressions from left to right. The operators have the following precedence:%@CR:C6A00180019 @%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% 1. ( ) 2. ~ 3. & 4. | For example, if you coded build tags called WINENV, APP1, and TEST_BUILD in your topic files, you could include one of the following build expressions in the [Options] section: %@NL@% %@AB@%Build Expression%@AE@% %@AB@%Topics Built%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% BUILD = WINENV Only topics that have the WINENV tag BUILD = WINENV & APP1 Topics that have both the WINENV and APP1 tags BUILD = WINENV | APP1 Topics that have either the WINENV tag or the APP1 tag BUILD = (WINENV | APP1) & Topics that have either the WINENV or TESTBUILD the APP1 tags and that also have the TESTBUILD tag BUILD =~ APP1 Topics that do not have a APP1 tag%@CR:C6A00180020 @% %@3@%%@CR:C6A00180021 @%%@AB@%18.4.3 Specifying the Root Directory: The Root Option%@AE@%%@EH@%%@NL@% Use the %@AB@%ROOT%@AE@% option to designate the root directory of the Help project. The compiler searches for files in the specified root directory.%@CR:C6A00180022 @%%@NL@% The %@AB@%ROOT%@AE@% option uses the following syntax: %@NL@% %@AS@% ROOT = pathname%@AE@% For example, the following root option specifies that the root directory is \BUILD\TEST on drive D: %@NL@% %@AS@% [OPTIONS] %@AS@% ROOT=D:\BUILD\TEST%@AE@% The %@AB@%ROOT%@AE@% option allows you to refer to all relative paths off the root directory of the Help project. For example, the following entry in the [Files] section refers to a relative path off the root directory: %@NL@% %@AS@% TOPICS\FILE.RTF%@AE@% To refer to a file in a fixed location, independent of the project root, you must specify a fully qualified or "absolute" path, including a drive letter, if necessary, as in the following line: %@NL@% %@AS@% D:\HELPTEST\TESTFILE.RTF%@AE@% If you do not include the %@AB@%ROOT%@AE@% option in your Help project file, all paths are relative to the current DOS directory.%@CR:C6A00180023 @%%@NL@% %@3@%%@CR:C6A00180024 @%%@AB@%18.4.4 Specifying the Index: The Index Option%@AE@%%@EH@%%@NL@% Use the %@AB@%INDEX%@AE@% option to identify the context string of the Help index. Because the Index button gives the user access to the index from anywhere in the Help system, you will probably not want to author terms to jump to the index. Users access this general index either from the Help menu of the application or by choosing the Index button from the Help window.%@CR:C6A00180025 @%%@NL@% Assigning a context string to the index topic in the [Options] section lets the compiler know the location of the main index of Help topics for the application's Help file. If you do not include the %@AB@%INDEX%@AE@% option in the [Options] section, the compiler assumes that the first topic it encounters is the index. %@NL@% The %@AB@%INDEX%@AE@% option uses the following syntax: %@NL@% %@AS@% INDEX = context-string%@AE@% The context string specified must match the context string you assigned to the Help index topic. In the following example, the writer informs the compiler that the context string of the Help index is "main_index": %@NL@% %@AS@% [OPTIONS] %@AS@% INDEX=main_index%@AE@% For information about assigning context strings, see Section 17.3.2, "Assigning Context Strings."%@CR:C6A00180026 @%%@NL@% %@3@%%@CR:C6A00180027 @%%@AB@%18.4.5 Assigning a Title to the Help System: The Title Option%@AE@%%@EH@%%@NL@% You can assign a title to your Help system with the %@AB@%TITLE%@AE@% option. The title appears in the title bar of the Help window with the word "Help" automatically appended, followed by the DOS filename of the Help resource file.%@CR:C6A00180028 @%%@NL@% The %@AB@%TITLE%@AE@% option uses the following syntax: %@NL@% %@AS@% TITLE = Help-system-title-name%@AE@% Titles are limited to 32 characters in length. If you do not specify a title using the %@AB@%TITLE%@AE@% option, only the word Help followed by the Help system filename will be displayed in the title bar. Because the compiler always inserts the word Help, you should keep in mind not to duplicate it in your title.Title option %@NL@% %@3@%%@CR:C6A00180029 @%%@AB@%18.4.6 Converting Fonts: The Forcefont Option%@AE@%%@EH@%%@NL@% You can use the %@AB@%FORCEFONT%@AE@% option to create a Help resource file that is made up of only one typeface or font. This is useful if you must compile a Help system using topic files that include fonts not supported by your users' systems.%@CR:C6A00180030 @%%@NL@% The %@AB@%FORCEFONT%@AE@% option uses the following syntax: %@NL@% %@AS@% FORCEFONT = fontname%@AE@% The %@AI@%fontname%@AE@% parameter is any Windows system font. Windows ships with the following fonts and sizes: %@NL@% ■ Courier 10,12,15 %@NL@% ■ Helv 8,10,12,14,18,24 %@NL@% ■ Modern %@NL@% ■ Roman %@NL@% ■ Script %@NL@% ■ Symbol 8,10,12,14,18,24 %@NL@% ■ Tms Rmn 8,10,12,14,18,24%@NL@% Font names must be spelled the same as they are in the Fonts dialog box in Control Panel. Font names do not exceed 20 characters in length. If you designate a font that is not recognized by the compiler, an error message is generated and the compilation continues using the default Helv font. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The %@AI@%fontname%@AE@%%@AI@% used in the %@AE@%%@AI@%%@AB@%FORCEFONT%@AE@%%@AE@%%@AI@% option cannot contain spaces. Therefore, %@AI@%Tms Rmn font cannot be used with %@AE@%%@AI@%%@AB@%FORCEFONT%@AE@%%@AE@%%@AI@%.%@CR:C6A00180031 @%%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00180032 @%%@AB@%18.4.7 Changing Font Sizes : The Mapfontsize Option%@AE@%%@EH@%%@NL@% The font sizes specified in your topic files can be mapped to different sizes using the %@AB@%MAPFONTSIZE%@AE@% option. In this manner, you can create and edit text in a size chosen for easier viewing in the topic files and have them sized by the compiler for the actual Help display. This may be useful if there is a large size difference between your authoring monitor and your intended display monitor.%@CR:C6A00180033 @%%@NL@% The %@AB@%MAPFONTSIZE%@AE@% option uses the following syntax: %@NL@% %@AS@% MAPFONTSIZE = m[-n]:p%@AE@% The %@AI@%m%@AE@% parameter is the size of the source font, and the %@AI@%p%@AE@% parameter is the size of the desired font for the Help resource file. All fonts in the topic files that are size %@AI@%m%@AE@% are changed to size %@AI@%p%@AE@%. The optional parameter %@AI@%n%@AE@% allows you to specify a font range to be mapped. All fonts in the topic files falling between %@AI@%m%@AE@% and %@AI@%n%@AE@%, inclusive, are changed to size %@AI@%p%@AE@%. The following examples illustrate the use of the %@AB@%MAPFONTSIZE%@AE@% option: %@NL@% %@AS@% MAPFONTSIZE=12-24:16 ;make fonts from 12 to 24 come out 16. %@AS@% MAPFONTSIZE=8:12 ;make all size 8 fonts come out size 12.%@AE@% Note that you can map only one font size or range with each %@AB@%MAPFONTSIZE%@AE@% statement used in the Options section. If you use more than one %@AB@%MAPFONTSIZE%@AE@% statement, the source font size or range specified in subsequent statements cannot overlap previous mappings. For instance, the following mappings would generate an error when the compiler encountered the second statement: %@NL@% %@AS@% MAPFONTSIZE=12-24:16 MAPFONTSIZE=14:20%@AE@% Because the second mapping shown in the first example contains a size already mapped in the preceding statement, the compiler will ignore the line. There is a maximum of five font ranges that can be specified in the project file.%@CR:C6A00180034 @%%@NL@% %@3@%%@CR:C6A00180035 @%%@AB@%18.4.8 Multiple Key-Word Tables: The Multikey Option%@AE@%%@EH@%%@NL@% The %@AB@%MULTIKEY%@AE@% option specifies a character to be used for an additional key-word table.%@CR:C6A00180036 @%%@NL@% The %@AB@%MULTIKEY%@AE@% option uses the following syntax: %@NL@% %@AS@% MULTIKEY = footnote-character%@AE@% The %@AI@%footnote-character%@AE@% parameter is the case-sensitive letter to be used for the key-word footnote. The following example illustrates the enabling of the letter L for a key word-table footnote: %@NL@% %@AS@% MULTIKEY=L%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%You must be sure to limit your key word-table footnotes to one case, usually %@AI@%uppercase. In the previous example, topics with the footnote L would have %@AI@%their key words incorporated into the additional key word table, whereas %@AI@%those assigned the letter l would not.%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% You may use any alphanumeric character for a key-word table except "K" and "k" which are reserved for Help's normal key-word table. There is an absolute limit of five key-word tables, including the normal table. However, depending upon system configuration and the structure of your Help system, a practical limit of only two or three may actually be the case. If the compiler cannot create an additional table, the excess table is ignored in the build.%@CR:C6A00180037 @%%@NL@% %@3@%%@CR:C6A00180038 @%%@AB@%18.4.9 Compressing the File: The Compress Option%@AE@%%@EH@%%@NL@% You can use the %@AB@%COMPRESS%@AE@% option to reduce the size of the Help resource file created by the compiler. The amount of file compression realized will vary according to the number, size and complexity of topics that are compiled. In general, the larger the Help files, the more they can be compressed.%@CR:C6A00180039 @%%@NL@% The %@AB@%COMPRESS%@AE@% option uses the following syntax: %@NL@% %@AS@% COMPRESS = TRUE | FALSE%@AE@% Because the Help application can load compressed files quickly, there is a clear advantage in creating and shipping compressed Help files with your application. Compiling with compression turned on, however, may increase the compile time, because of the additional time required to assemble and sort a key-phrase table. Thus, you may want to compile without compression in the early stages of a project. %@NL@% The %@AB@%COMPRESS%@AE@% option causes the compiler to compress the system by combining repeated phrases found within the source file(s). The compiler creates a phrase-table file with the .PH extension if it does not find one already in existence. If the compiler finds a file with the .PH extension, it will use the file for the current compilation. This is in order to speed compression when not a lot of text has changed since the last compilation. %@NL@% Deleting the key-phrase file before each compilation will prevent the compiler from using the previous file. Maximum compression will result only by forcing the compiler to create a new phrase table.%@CR:C6A00180040 @%%@NL@% %@2@%%@CR:C6A00180041 @%%@AB@%18.5 Specifying Alternate Context Strings: The Alias Section%@AE@%%@EH@%%@NL@% Use the [Alias] section to assign one or more context strings to the same topic alias. Because context strings must be unique for each topic and cannot be used for any other topic in the Help project, the [Alias] section provides a way to delete or combine Help topics without recoding your files. The [Alias] section is optional.%@CR:C6A00180042 @%%@CR:C6A00180043 @%%@NL@% For example, if you create a topic that replaces the information in three other topics, and you delete the three, you will have to search through your files for invalid cross-references to the deleted topics. You can avoid this problem by using the [Alias] section to assign the name of the new topic to the deleted topics. The [Alias] section can also be used when your application program has multiple context identifiers for which you have only one topic. This can be the case with context-sensitive Help. %@NL@% Each expression in the [Alias] section has the following format: %@NL@% %@AI@%context_string%@AE@%=%@AI@%alias%@AE@% %@NL@% In the alias expression the %@AI@%alias%@AE@% parameter is the alternate string, or alias name, and the %@AI@%context_string%@AE@% parameter is the context string identifying a particular topic. An alias string has the same format and follows the same conventions as the topic context string. That is, it is not case-sensitive and may contain the alphabetic characters A-Z, numeric characters 0-9, and the period and underscore characters. %@NL@% The following example illustrates an [Alias] section: %@NL@% %@AS@% [ALIAS] %@AS@% sm_key=key_shrtcuts %@AS@% cc_key=key_shrtcuts %@AS@% st_key=key_shrtcuts ;combined into keyboard shortcuts topic %@AS@% clskey=us_dlog_bxs %@AS@% maakey=us_dlog_bxs ;covered in using dialog boxes topic %@AS@% chk_key=dlogprts %@AS@% drp_key=dlogprts %@AS@% lst_key=dlogprts %@AS@% opt_key=dlogprts %@AS@% tbx_key=dlogprts ;combined into parts of dialog box topic %@AS@% frmtxt=edittxt %@AS@% wrptxt=edittxt %@AS@% seltxt=edittxt ;covered in editing text topic%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%You can use alias names in the [Map] section of the Help project file. If %@AI@%you do, however, the [Alias] section must precede the [Map] section.%@CR:C6A00180044 @%%@CR:C6A00180045 @%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00180046 @%%@AB@%18.6 Mapping Context-Sensitive Topics: The Map Section%@AE@%%@EH@%%@NL@% If your Help system supports context-sensitive Help, use the [Map] section to associate either context strings or aliases to context numbers. The context number corresponds to a value the parent application passes to the Help application in order to display a particular topic. This section is optional.%@CR:C6A00180047 @%%@CR:C6A00180048 @%%@NL@% When writing the [Map] section, you can do the following: %@NL@% ■ Use either decimal or hexadecimal numbers formatted in standard C notation to specify context numbers.%@NL@% ■ Assign no more than one context number to a context string or alias.%@NL@% %@STUB@% Assigning the same number to more than one context string will generate a compiler error. %@NL@% ■ Separate context numbers and context strings by an arbitrary amount of white space using either space characters or tabs.%@NL@% You can use the C %@AB@%#include%@AE@% directive to include other files in the mapping. In addition, the Map section supports an extended format that lets you include C files with the .H extension directly. Entries using this format must begin with the %@AB@%#define%@AE@% directive and may contain comments in C format, as in this example:%@CR:C6A00180049 @%%@CR:C6A00180050 @%%@NL@% %@AS@% #define context_string context_number /* comment */%@AE@% The following example illustrates several formats you can use in the [Map] section: %@NL@% %@AS@% [MAP] %@AS@% " %@AS@% Edit_Window 0x0001 %@AS@% Control_Menu 0x0002 %@AS@% Maximize_Icon 0x0003 %@AS@% Minimize_Icon 0x0004 %@AS@% Split_Bar 0x0005 %@AS@% Scroll_Bar 0x0006 %@AS@% Title_Bar 0x0007 %@AS@% Window_Border 0x0008 %@AS@% %@AS@% dcmb_scr 30 ; Document Control-menu Icon %@AS@% dmxi_scr 31 ; Document Maximize Icon %@AS@% dmni_scr 32 ; Document Minimize Icon %@AS@% dri_scr 33 ; Document Restore Icon %@AS@% dtb_scr 34 ; Document Title Bar %@AS@% %@AS@% %@AS@% #define vscroll 0x010A /* Vertical Scroll Bar */ %@AS@% #define hscroll 0x010E /* Horizontal Scroll Bar */ %@AS@% #define scrollthm 0x0111 /* Scroll Thumb */ %@AS@% #define upscroll 0x0112 /* Up Scroll Arrow */ %@AS@% #define dnscroll 0x0113 /* Down Scroll Arrow */ %@AS@% %@AS@% %@AS@% #include <sample.h>%@AE@% In the example:%@CR:C6A00180051 @%%@CR:C6A00180052 @%%@NL@% " The first eight entries give hexadecimal equivalents for the context numbers.%@NL@% The next five entries show decimal context numbers.%@NL@% The next five entries show how you might include topics defined in a C include file.%@NL@% This entry shows a C %@AB@%#include%@AE@% directive for some generic topics.%@NL@% If context numbers use the %@AB@%#define%@AE@% directive, and the file containing the %@AB@%#define%@AE@% statements is included in both the application code and the Help file, then updates made to the context numbers by the application programmers will automatically be reflected in the next Help build. %@NL@% You can define the context strings listed in the [Map] section either in a Help topic or in the [Alias] section. The compiler generates a warning message if a context string appearing in the [Map] section is not defined in any of the topic files or in the [Alias] section. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%If you use an alias name, the [Alias] section must precede the [Map] section %@AI@%in the Help project file. %@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% For more information about context-sensitive Help, see Section 16.2.5, "Displaying Context-Sensitive Help Topics."%@CR:C6A00180053 @%%@CR:C6A00180054 @%%@NL@% %@2@%%@CR:C6A00180055 @%%@AB@%18.7 Including Bitmaps by Reference: The Bitmaps Section%@AE@%%@EH@%%@NL@% If your Help system uses bitmaps by reference, the filenames of each of the bitmaps must be listed in the [Bitmaps] section of the project file. The following example illustrates the format of the [Bitmaps] section.%@CR:C6A00180056 @%%@CR:C6A00180057 @%%@NL@% %@AS@% [BITMAPS] %@AS@% DUMP01.BMP %@AS@% DUMP02.BMP %@AS@% DUMP03.BMP %@AS@% c:\PROJECT\HELP\BITMAPS\DUMP04.BMP%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%The [Bitmaps] section uses the same rules as the [Files] section for %@AI@%locating bitmap files. %@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@2@%%@CR:C6A00180058 @%%@AB@%18.8 Compiling Help Files%@AE@%%@EH@%%@NL@% After you have created a Help project file, you are ready to build a Help file using the Help Compiler. The compiler generates the binary Help resource file from the topic files listed in the Help project file. When the build process is complete, your application can access the Help resource file that results.%@CR:C6A00180059 @%%@CR:C6A00180060 @%%@NL@% Before initiating a build operation to create the Help file, consider the locations of the following files: %@NL@% ■ The Help Compiler, HC.EXE. The compiler must be in a directory from which it can be executed. This could be the current working directory, on the path set with the PATH environment variable, or a directory specified by a full pathname, as follows: %@AS@% C:\BIN\HC HELPEX.HPJ%@AE@% %@NL@% ■ The Help project file, %@AI@%filename%@AE@%.HPJ. The project file can be located either in the current directory or specified by a path, as follows:%@CR:C6A00180061 @%%@CR:C6A00180062 @% %@AS@% C:\BIN\HC D:\MYPROJ\HELPEX.HPJ%@AE@% %@NL@% ■ The topic files named in the Help project file, saved as RTF. The topic files may be located in the current working directory, a subdirectory of the current working directory specified in the [Files] section, or the location specified in the Root option.%@NL@% ■ Files included with the %@AB@%#include%@AE@% directive in the Help project file. Since the %@AB@%#include%@AE@% directive can take pathnames, then any number of places will work for these files.%@NL@% ■ All bitmap files listed by reference in the topic files.%@NL@% You must also place any files named in an %@AB@%#include%@AE@% directive in the path of the project root directory or specify their path using the %@AB@%ROOT %@AE@%option. The compiler searches only the directories specified in the Help project file. For information about the %@AB@%ROOT%@AE@% option, see Section 18.4.3, "Specifying the Root Directory: The Root Option." %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%If you use a RAM drive for temporary files (set with the DOS environment %@AI@%variable TMP), it must be large enough to hold the compiled Help resource %@AI@%file. If your Help file is larger than the size of the available RAM drive, %@AI@%the compiler will generate an error message and the compilation will be %@AI@%aborted. %@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00180063 @%%@AB@%18.8.1 Using the Help Compiler%@AE@%%@EH@%%@NL@% To run the Help Compiler, use the %@AB@%HC%@AE@% command. There are no options for %@AB@%HC%@AE@%. All options are specified in the Help project file.%@CR:C6A00180064 @%%@CR:C6A00180065 @%%@NL@% The %@AB@%HC%@AE@% command uses the following syntax: %@NL@% %@AS@% HC filename.HPJ%@AE@% As the compiler program runs, it displays sequential periods on the screen, indicating its progress in the process. Error messages are displayed when each error condition is encountered. When the Help Compiler has finished compiling, it writes a Help resource file with an .HLP extension in the current directory and returns to the DOS prompt. The Help resource file that results from the build has the same name as does the Help project file. %@NL@% Compiler errors and status messages can be redirected to a file using standard DOS redirection syntax. This is useful for a lengthy build where you may not be monitoring the entire process. The redirected file is saved as a text file that can be viewed with any ASCII editor.%@CR:C6A00180066 @%%@CR:C6A00180067 @%%@NL@% %@2@%%@CR:C6A00180068 @%%@AB@%18.9 Programming the Application to Access Help%@AE@%%@EH@%%@NL@% The application-development team must program the application so that the user can access the Windows Help application and your Help file. The Help application is a stand-alone Windows application, and your application can ask Windows to run the Help application and specify the topic that Help is to show the user. To the user, Help appears to be part of your application, but it acts like any other Windows application.%@CR:C6A00180069 @%%@NL@% %@3@%%@CR:C6A00180070 @%%@AB@%18.9.1 Calling WinHelp from an Application%@AE@%%@EH@%%@NL@% An application makes a Help system available to the user by calling the %@AB@% %@AB@%WinHelp%@AE@% function.%@CR:C6A00180071 @%%@NL@% The %@AB@%WinHelp%@AE@% function uses the following syntax: %@NL@% %@AS@% BOOL WinHelp (hWnd, lpHelpFile, wCommand, dwData)%@AE@% The %@AI@%hWnd%@AE@% parameter identifies the window requesting Help. The Windows Help application uses this identifier to keep track of which applications have requested Help. %@NL@% The %@AI@%lpHelpFile%@AE@% parameter specifies the name (with optional directory path) of the Help file containing the desired topic. %@NL@% The %@AI@%wCommand%@AE@% parameter specifies either the type of search that the Windows Help application is to use to locate the specified topic, or that the application no longer requires Help. It may be set to any one of the following values:%@CR:C6A00180072 @%%@NL@% %@TH: 23 1116 02 34 42 @%Value Meaning%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%HELP_CONTEXT Displays Help for a particular topic identified by a context number.HELP_HELPONHELP Displays the Using Help index topic.HELP_INDEX Displays the main Help index topic.HELP_KEY Displays Help for a topic identified by a key word.HELP_MULTIKEY Displays Help for a topic identified by a key word in an alternate key-word table.HELP_QUIT Informs the Help application that Help is no longer needed. If no other applications have asked for Help, Windows closes the Help application.HELP_SETINDEX Displays a designated Help index topic. %@TE: 23 1116 02 34 42 @% The %@AI@%dwData%@AE@% parameter specifies the topic for which the application is requesting Help. The format of %@AI@%dwData%@AE@% depends upon the value of %@AI@%wCommand%@AE@% passed when your application calls %@AB@%WinHelp%@AE@%. The following list describes the format of %@AI@%dwData%@AE@% for each value of %@AI@%wCommand%@AE@%.%@CR:C6A00180073 @%%@NL@% %@TH: 25 1192 02 34 42 @%wCommand Value dwData Format%@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@%HELP_CONTEXT An unsigned long integer containing the context number for the topic. Instead of using HELP_INDEX, HELP_CONTEXT can use the value -1.HELP_HELPONHELP Ignored.HELP_INDEX Ignored.HELP_KEY A long pointer to a string which contains a key word for the desired topic.HELP_MULTIKEY A long pointer to the %@AB@%MULTIKEYHELP%@AE@% structure, as defined in WINDOWS.H. This structure specifies the table footnote character and the key word.HELP_QUIT Ignored.HELP_SETINDEX An unsigned long integer containing the context number for the topic. %@TE: 25 1192 02 34 42 @% Because it can specify either a context number or a key word, %@AB@%WinHelp%@AE@% supports both context-sensitive and topical searches of the Help file. %@NL@% ────────────────────────────────────────────────────────────────────────────%@NL@% NOTE %@AI@%To ensure that the correct index remains set, the application should call %@AB@%WinHelp%@AE@%%@AI@% with wCommand%@AE@%%@AI@% set to HELP_SETINDEX (with dwData%@AE@%%@AI@% specifying the %@AI@%corresponding context identifier) following each call to %@AE@%%@AI@%%@AB@%WinHelp%@AE@%%@AE@%%@AI@% with a %@AI@%command set to HELP_CONTEXT. HELP_INDEX should never be used with %@AI@%HELP_SETINDEX.%@CR:C6A00180074 @%%@AE@%%@AE@% ────────────────────────────────────────────────────────────────────────────%@NL@% %@3@%%@CR:C6A00180075 @%%@AB@%18.9.2 Getting Context-Sensitive Help%@AE@%%@EH@%%@NL@% Context-sensitive Help should be made available when a user wants to learn about the purpose of a particular window or control. For example, the user might pull down the File menu, select the Open command (by using the DIRECTION keys), and then press F1 to get Help for the command.%@CR:C6A00180076 @%%@CR:C6A00180077 @%%@NL@% Implementing certain types of context-sensitive help requires advanced programming techniques. The Helpex sample application illustrates the use of two techniques. These techniques are described in the following sections. %@NL@% %@4@%%@AB@%Shift+F1 Support%@AE@%%@EH@%%@NL@% To implement a SHIFT+F1 mode, such as in Microsoft Excel or Microsoft Word for Windows, Helpex responds to the SHIFT+F1 accelerator key by calling %@AB@%SetCursor%@AE@% to change the shape of the cursor to an arrow pointer supplemented by a question mark.%@CR:C6A00180078 @%%@CR:C6A00180079 @%%@NL@% %@AS@% case WM_KEYDOWN: %@AS@% if (wParam == VK_F1) { %@AS@% %@AS@% /* If Shift-F1, turn help mode on and set help cursor */ %@AS@% %@AS@% if (GetKeyState(VK_SHIFT)) { %@AS@% bHelp = TRUE; %@AS@% SetCursor(hHelpCursor); %@AS@% return (DefWindowProc(hWnd, message, wParam, lParam)); %@AS@% } %@AS@% %@AS@% /* If F1 without shift, then call up help main index topic */ %@AS@% else { %@AS@% WinHelp(hWnd,szHelpFileName,HELP_INDEX,0L); %@AS@% } %@AS@% } %@AS@% %@AS@% else if (wParam == VK_ESCAPE && bHelp) { %@AS@% %@AS@% /* Escape during help mode: turn help mode off */ %@AS@% bHelp = FALSE; %@AS@% SetCursor((HCURSOR)GetClassWord(hWnd,GCW_HCURSOR)); %@AS@% } %@AS@% %@AS@% break;%@AE@% As long as the user is in Help mode (that is, until he clicks the mouse or hits Escape), Helpex responds to WM_SETCURSOR messages by resetting the cursor to the arrow and question mark combination. %@NL@% %@AS@% %@AS@% case WM_SETCURSOR: %@AS@% /* In help mode it is necessary to reset the cursor in response */ %@AS@% /* to every WM_SETCURSOR message.Otherwise, by default, Windows */ %@AS@% /* will reset the cursor to that of the window class. */ %@AS@% %@AS@% if (bHelp) { %@AS@% SetCursor(hHelpCursor); %@AS@% break; %@AS@% } %@AS@% return (DefWindowProc(hWnd, message, wParam, lParam)); %@AS@% break; %@AS@% %@AS@% case WM_INITMENU: %@AS@% if (bHelp) { %@AS@% SetCursor(hHelpCursor); %@AS@% } %@AS@% return (TRUE);%@AE@% When the user is in SHIFT+F1 Help mode and clicks the mouse button, Helpex will receive a WM_NCLBUTTONDOWN message if the click is in a nonclient area of the application window. By examining the %@AI@%wParam%@AE@% value of this message, the program can determine which context ID to pass to %@AB@%WinHelp%@AE@%.%@CR:C6A00180080 @%%@CR:C6A00180081 @%%@NL@% %@AS@% %@AS@% case WM_NCLBUTTONDOWN: %@AS@% /* If we are in help mode (Shift+F1) then display context- */ %@AS@% /* sensitive help for nonclient area. */ %@AS@% %@AS@% if (bHelp) { %@AS@% dwHelpContextId = %@AS@% (wParam == HTCAPTION)?(DWORD)HELPID_TITLE_BAR: %@AS@% (wParam == HTSIZE)? (DWORD)HELPID_SIZE_BOX: %@AS@% (wParam == HTREDUCE)? (DWORD)HELPID_MINIMIZE_ICON: %@AS@% (wParam == HTZOOM)? (DWORD)HELPID_MAXIMIZE_ICON: %@AS@% (wParam == HTSYSMENU)?(DWORD)HELPID_SYSTEM_MENU: %@AS@% (wParam == HTBOTTOM)? (DWORD)HELPID_SIZING_BORDER: %@AS@% (wParam == HTBOTTOMLEFT)? (DWORD)HELPID_SIZING_BORDER: %@AS@% (wParam == HTBOTTOMRIGHT)?(DWORD)HELPID_SIZING_BORDER: %@AS@% (wParam == HTTOP)?(DWORD)HELPID_SIZING_BORDER: %@AS@% (wParam == HTLEFT)?(DWORD)HELPID_SIZING_BORDER: %@AS@% (wParam == HTRIGHT)?(DWORD)HELPID_SIZING_BORDER: %@AS@% (wParam == HTTOPLEFT)?(DWORD)HELPID_SIZING_BORDER: %@AS@% (wParam == HTTOPRIGHT)? (DWORD)HELPID_SIZING_BORDER: %@AS@% (DWORD)0L; %@AS@% %@AS@% if (!((BOOL)dwHelpContextId)) %@AS@% return (DefWindowProc(hWnd, message, wParam, lParam)); %@AS@% bHelp = FALSE; %@AS@% WinHelp(hWnd,szHelpFileName,HELP_CONTEXT,dwHelpContextId); %@AS@% break; %@AS@% } %@AS@% %@AS@% return (DefWindowProc(hWnd, message, wParam, lParam));%@AE@% %@4@%%@AB@%F1 Support%@AE@%%@EH@%%@NL@% Context-sensitive F1 support for menus is relatively easy to implement in your application. If a menu is open and the user presses F1 while one of the menu items is highlighted, Windows sends a WM_ENTERIDLE message to the application to indicate that the system is going back into an idle state after having determined that F1 was not a valid key stroke for choosing a menu item. You can take advantage of this idle state by looking at the keyboard state at the time of the WM_ENTERIDLE message.%@CR:C6A00180082 @%%@CR:C6A00180083 @%%@NL@% If the F1 key is down, then you can simulate the user's pressing the ENTER key by posting a WM_KEYDOWN message using VK_RETURN. You don't really want your application to execute the menu command. What you do is set a flag (bHelp=TRUE) so that when you get the WM_COMMAND message for the menu item, you don't execute the command. Instead, the topic for the menu item is displayed by Windows Help. %@NL@% The following code samples illustrate F1 sensing for menu items.%@CR:C6A00180084 @%%@CR:C6A00180085 @%%@CR:C6A00180086 @%%@CR:C6A00180087 @%%@NL@% %@AS@% %@AS@% case WM_ENTERIDLE: %@AS@% if ((wParam == MSGF_MENU) && (GetKeyState(VK_F1) & 0x8000)) { %@AS@% bHelp = TRUE; %@AS@% PostMessage(hWnd, WM_KEYDOWN, VK_RETURN, 0L); %@AS@% } %@AS@% break;%@AE@% %@AS@% %@AS@% case WM_COMMAND: %@AS@% /* Was F1 just pressed in a menu, or are we in help mode */ %@AS@% /* (Shift+F1)? */ %@AS@% %@AS@% if (bHelp) { %@AS@% dwHelpContextId = %@AS@% (wParam == IDM_NEW)?(DWORD)HELPID_FILE_NEW: %@AS@% (wParam == IDM_OPEN)? (DWORD)HELPID_FILE_OPEN: %@AS@% (wParam == IDM_SAVE)? (DWORD)HELPID_FILE_SAVE: %@AS@% (wParam == IDM_SAVEAS)? (DWORD)HELPID_FILE_SAVE_AS: %@AS@% (wParam == IDM_PRINT)?(DWORD)HELPID_FILE_PRINT: %@AS@% (wParam == IDM_EXIT)? (DWORD)HELPID_FILE_EXIT: %@AS@% (wParam == IDM_UNDO)? (DWORD)HELPID_EDIT_UNDO: %@AS@% (wParam == IDM_CUT)?(DWORD)HELPID_EDIT_CUT: %@AS@% (wParam == IDM_CLEAR)?(DWORD)HELPID_EDIT_CLEAR: %@AS@% (wParam == IDM_COPY)? (DWORD)HELPID_EDIT_COPY: %@AS@% (wParam == IDM_PASTE)?(DWORD)HELPID_EDIT_PASTE: %@AS@% (DWORD)0L; %@AS@% %@AS@% if (!dwHelpContextId) %@AS@% { Messagebox( hWnd, "Help not available for Help %@AS@%Menu item", "Help Example", MB_OK %@AS@%return (DefWindowProc(hWnd, message, wParam, lParam)); %@AS@% }%@AE@% %@AS@% bHelp = FALSE; %@AS@% WinHelp(hWnd,szHelpFileName,HELP_CONTEXT,dwHelpContextId); %@AS@% break; %@AS@% }%@AE@% Detecting F1 in dialog boxes is somewhat more difficult than in menus. You must install a message filter, using the WH_MSGFILTER option of the %@AB@%SetWindowsHook%@AE@% function. Your message filter function responds to WM_KEYDOWN and WM_KEYUP messages for VK_F1 when they are sent to a dialog box, as indicated by the MSGF_DIALOGBOX code. By examining the message structure passed to the filter, you can determine the context of the F1 help─what the dialog box is, and the specific option or item. You should not call %@AB@%WinHelp%@AE@% while processing the filtered message, but rather post an application-defined message to your application to call %@AB@%WinHelp%@AE@% at the first available opportunity.%@CR:C6A00180088 @%%@CR:C6A00180089 @%%@CR:C6A00180090 @%%@CR:C6A00180091 @%%@NL@% %@3@%%@CR:C6A00180092 @%%@AB@%18.9.3 Getting Help on an Item Listed on the Help Menu%@AE@%%@EH@%%@NL@% Sometimes users may want information about a general concept in the application rather than about a particular control or window. In these cases, the application should provide Help for a particular topic that is identified by a key word rather than a context identifier.%@CR:C6A00180093 @%%@CR:C6A00180094 @%%@NL@% For example, if the Help file for your application contains a topic that describes how the keyboard is used, you could place a "Keyboard" item in your Help menu. Then, when the user selects that item, your application would call %@AB@%WinHelp%@AE@% and request that topic: %@NL@% %@AS@% case IDM_HELP_KEYBOARD: %@AS@% WinHelp (hWnd, lpHelpFile, HELP_KEY, (LPSTR) "Keyboard"); %@AS@% break;%@AE@% %@3@%%@CR:C6A00180095 @%%@AB@%18.9.4 Accessing Additional Key-Word Tables%@AE@%%@EH@%%@NL@% Your application may have commands or terms that correspond to terms in a similar, but different, application. Given a key word, the application can call %@AB@%WinHelp%@AE@% and look up topics defined in an alternate key-word table. This Multikey functionality is accessed through the %@AB@%WinHelp%@AE@% hook with the %@AI@%wCommand%@AE@% parameter set to HELP_MULTIKEY.%@CR:C6A00180096 @%%@CR:C6A00180097 @%%@NL@% You specify the footnote character for the alternate key-word table, and the key word or phrase, via a %@AB@%MULTIKEYHELP%@AE@% structure which is passed as the %@AI@%dwData%@AE@% parameter in the call to %@AB@%WinHelp%@AE@%. This structure is defined in WINDOWS.H as: %@NL@% %@AS@% typedef struct tag MULTIKEYHELP { %@AS@% WORD mdSize; %@AS@% BYTE mkKeyList; %@AS@% BYTE szKeyPhrase[1]; %@AS@% } MULTIKEYHELP;%@AE@% The following table lists the format of the fields of the %@AB@%MULTIKEYHELP%@AE@% structure: %@NL@% %@AB@%Parameter%@AE@% %@AB@%Format%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% %@AB@%mkSize%@AE@% The size of the structure, including the key word (or phrase) and the associated key-table letter. %@AB@%mkKeyList%@AE@% A single character which defines the footnote character for the alternate key-word table to be searched. %@AB@%szKeyPhrase%@AE@% A null-terminated key word or phrase to be looked up in the alternate key-word table. The following example illustrates a key-word search for the word "frame" in the alternate key-word table designated with the footnote character "L": %@NL@% %@AS@% MULTIKEYHELP mk; %@AS@% char szKeyword[]="frame"; %@AS@% mk.mkSize=sizeof(MULTIKEYHELP)+(WORD)lstrlen(szKeyword); %@AS@% mk.mkKeylist="L"; %@AS@% mk.szKeyphrase=szKeyword; %@AS@% WinHelp(hWnd,lpHelpfile,HELP_MULTIKEY,(LPSTR)&mk);%@AE@% %@3@%%@CR:C6A00180098 @%%@AB@%18.9.5 Canceling Help%@AE@%%@EH@%%@NL@% The Windows Help application is a shared resource that is available to all Windows applications. In addition, since it is a stand-alone application, the user can execute it like any other application. As a result, your application has limited control over the Help application. While your application cannot directly close the Help application window, your application can inform the Help application that Help is no longer needed. Before closing its main window, your application should call %@AB@%WinHelp%@AE@% with the %@AI@%wCommand%@AE@% parameter set to HELP_QUIT, as shown in the following example, to inform the Help application that your application will not need it again.%@CR:C6A00180099 @%%@NL@% %@AS@% case WM_DESTROY: %@AS@% WinHelp (hWnd, lpHelpFile, HELP_QUIT, NULL); %@AE@% An application that has called %@AB@%WinHelp%@AE@% at some point during its execution must call %@AB@%WinHelp%@AE@% with the %@AI@%wCommand%@AE@% parameter set to HELP_QUIT before the application exits from WinMain (typically during the WM_DESTROY message processing). %@NL@% If an application opens more than one Help file, then it must call %@AB@%WinHelp%@AE@% to quit help for each file. %@NL@% If an application or DLL has opened a Help file but no longer wants the associated instance of the Help engine (WINHELP.EXE) to remain active, then the application or DLL should call %@AB@%WinHelp%@AE@% with the %@AI@%wCommand%@AE@% parameter set to HELP_QUIT to destroy the instance of the Help engine. %@NL@% Under no circumstances should an application or DLL terminate without calling %@AB@%WinHelp%@AE@% for any of the opened Help files. A Help file is opened if any other %@AB@%WinHelp%@AE@% call has been previously made using the Help filename. %@NL@% The Windows Help application does not exit until all windows that have called %@AB@%WinHelp%@AE@% have called it with %@AI@%wCommand%@AE@% set to HELP_QUIT. If an application fails to do so, then the Help application will continue running after all applications that requested Help have terminated.%@CR:C6A00180100 @%%@NL@% %@2@%%@CR:C6A00180101 @%%@AB@%18.10 Summary%@AE@%%@EH@%%@NL@% This chapter described how to create a Help project file, build the Help resource file, and program your application to access Help. For more information, see the following: %@NL@% %@AB@%Topic%@AE@% %@AB@%Reference%@AE@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% Planning a Help system %@AI@%Tools%@AE@%: Chapter 16, "Planning the Help System" Writing Help topics %@AI@%Tools%@AE@%: Chapter 17, "Creating the Help Topic Files" %@CR:C6A00190001 @%%@1@%%@AB@%Chapter 19 Help Examples and Compiler Error Messages%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────────%@AE@%%@NL@% The first part of this chapter contains several examples of Help source files and their corresponding topics as displayed in Help. Each example shows a topic (or part of a topic) as it appears to the Help writer in the RTF-capable word processor and as it appears to the user in the Help window. You can use these examples as guides when creating your own topic files. The examples should help you predict how a particular topic file created in a word processor will appear to the user. %@NL@% The second part of this chapter contains a list of Help Compiler error messages. Each message is shown as it appears when the compiler encounters the specific error. A short explanation accompanies each message to aid you in solving the problem in your Help system. Preceding the error message listing is a short description of the error reporting behavior of the Help Compiler. Understanding how the compiler reports and reacts to errors will help you to debug your Help files.%@CR:C6A00190002 @%%@NL@% %@2@%%@CR:C6A00190003 @%%@AB@%19.1 Help Topic Examples%@AE@%%@EH@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% <$R> %@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% %@AU@%(This figure may be found in the printed book).%@AE@%%@NL@% The following is the Helpex (sample Help) project file: %@NL@% %@AS@% [OPTIONS] %@AS@% ROOT=c:\help %@AS@% INDEX=main_index %@AS@% TITLE=Help Example %@AS@% COMPRESS=true %@AS@% %@AS@% [FILES] %@AS@% helpex.rtf ; jump topics %@AS@% terms.rtf ; look-up terms %@AS@% %@AS@% [MAP] %@AS@% main_index 0xFFFF %@AS@% #define HELPID_EDIT_CLEAR 100 %@AS@% #define HELPID_EDIT_COPY 101 %@AS@% #define HELPID_EDIT_CUT 102 %@AS@% #define HELPID_EDIT_PASTE 103 %@AS@% #define HELPID_EDIT_UNDO 104 %@AS@% #define HELPID_FILE_EXIT 200 %@AS@% #define HELPID_FILE_NEW 201 %@AS@% #define HELPID_FILE_OPEN 202 %@AS@% #define HELPID_FILE_PRINT 203 %@AS@% #define HELPID_FILE_SAVE 204 %@AS@% #define HELPID_FILE_SAVE_AS 205 %@AS@% #define HELPID_EDIT_WINDOW 300 %@AS@% #define HELPID_MAXIMIZE_ICON 301 %@AS@% #define HELPID_MINIMIZE_ICON 302 %@AS@% #define HELPID_SPLIT_BAR 303 %@AS@% #define HELPID_SIZE_BOX 304 %@AS@% #define HELPID_SYSTEM_MENU 305 %@AS@% #define HELPID_TITLE_BAR 306 %@AS@% #define HELPID_SIZING_BORDER 307%@AE@% %@2@%%@CR:C6A00190004 @%%@AB@%19.2 Help Compiler Error Messages%@AE@%%@EH@%%@NL@% The Help Compiler displays messages when it encounters errors in building the Help resource file. Errors during processing of the project file are numbered beginning with the letter P and appear as in the following examples:%@CR:C6A00190005 @%%@CR:C6A00190006 @%%@NL@% %@AS@% Error P1025: line...7 of filename.HPJ : Section heading sectionname %@AS@%unrecognized.%@AE@% %@AS@% Warning P1039: line...38 of filename.HPJ : [BUILDTAGS] section missing.%@AE@% Errors which occur during processing of the RTF topic file(s) are numbered beginning with the letter R and appear as in the following examples: %@NL@% %@AS@% Error R2025: File environment error.%@AE@% %@AS@% Warning R2501: Using old key-phrase table.%@AE@% Whenever possible, the compiler will display the topic number and/or filename that contains the error. Though topics are not numbered, the topic number given with an error message refers to that topic's sequential position in your RTF file (first, second, etc.). These numbers may be identical to the page number shown by your word processor, depending on the number of lines you have assigned to the hypothetical printed page. Remember that topics are separated by hard page breaks, even though there is no such thing as a "page" in the Help system. %@NL@% Messages beginning with the word "Error" are fatal errors. Errors are always reported, and no usable Help resource file will result from the build. Messages beginning with the word "Warning" are less serious in nature. A build with warnings will produce a valid Help resource file which will load under Windows, but the file may contain operational errors. You can specify the amount of warning information to be reported by the compiler. See section 17.4.1, "Specifying Error Reporting: The Warning Option," for more information on choosing warning levels to be displayed.%@CR:C6A00190007 @%%@CR:C6A00190008 @%%@NL@% The compiler's reaction to an error is described for each error in the listing that follows. During processing of the project file, the compiler ignores lines that contain errors and attempts to continue with the build. This means that errors encountered early in a build may result in many more errors being reported as the build continues. Similarly, errors during processing of the RTF topic files will be reported and if not serious, the compiler will continue with the build. A single error condition in the topic file may result in more than one error message being reported by the compiler. For instance, a misidentified topic will cause an error to be reported every time jump terms refer to the correct topic identifier. Such a mistake is easily rectified by simply correcting the footnote containing the wrong context string. %@NL@% %@3@%%@CR:C6A00190009 @%%@AB@%19.2.1 Errors During Processing of Project File%@AE@%%@EH@%%@NL@% %@AB@%P1001%@AE@% Unable to read file %@AI@%filename%@AE@%. The file specified in the project file is unreadable. This is a DOS file error. %@AB@%P1003%@AE@% Invalid path specified in Root option. The path specified by the Root option cannot be found. The compiler uses the current working directory. %@AB@%P1005%@AE@% Path and filename exceed limit of 79 characters. The absolute pathname, or the combined root and relative pathname, exceed the DOS limit of 79 characters. The file is skipped. %@AB@%P1007%@AE@% Root path exceeds maximum limit of 66 characters. The specified root pathname exceeds the DOS limit of 66 characters. The pathname is ignored and the compiler uses the current working directory. %@AB@%P1009%@AE@% [FILES] section missing. The [Files] section is required. The compilation is aborted. %@AB@%P1011%@AE@% Option %@AI@%optionname%@AE@% previously defined. The specified option was defined previously. The compiler ignores the attempted redefinition.%@CR:C6A00190010 @%%@CR:C6A00190011 @% %@AB@%P1013%@AE@% Project file extension cannot be .HLP. You cannot specify that the compiler use a project file with the .HLP extension. Normally, project files are given the .HPJ extension. %@AB@%P1015%@AE@% Unexpected end-of-file. The compiler has unexpectedly come to the end of the project file. There might be an open comment in the project file or an included file. %@AB@%P1017%@AE@% Parameter exceeds maximum length of 128 characters. An option, context name or number, build tag, or other parameter on the specified line exceeds the limit of 128 characters. The line is ignored. %@AB@%P1021%@AE@% Context number already used in [MAP] section. The context number on the specified line in the project file was previously mapped to a different context string. The line is ignored. %@AB@%P1023%@AE@% Include statements nested too deeply. The %@AB@%#include%@AE@% statement on the specified line has exceeded the maximum of five include levels. %@AB@%P1025%@AE@% Section heading %@AI@%sectionname%@AE@% unrecognized. A section heading that is not supported by the compiler has been used. The line is skipped. %@AB@%P1027%@AE@% Bracket missing from section heading %@AI@%%@AE@% %@AI@%sectionname%@AE@%. The right bracket (]) is missing from the specified section heading. Insert the bracket and compile again. %@AB@%P1029%@AE@% Section heading missing. The section heading on the specified line is not complete. This error is also reported if the first entry in the project file is not a section heading. The compiler continues with the next line. %@AB@%P1030%@AE@% Section %@AI@%sectionname%@AE@% previously defined.%@CR:C6A00190012 @%%@CR:C6A00190013 @% A duplicate section has been found in the project file. The lines under the duplicated section heading are ignored and the compiler continues from the next valid section heading. %@AB@%P1031%@AE@% Maximum number of build tags exceeded. The maximum number of build tags that can be defined is 30. The excess tags are ignored. %@AB@%P1033%@AE@% Duplicate build tag in [BUILDTAGS] section. A build tag in the [BuildTags] section has been repeated unnecessarily %@AB@%P1035%@AE@% Build tag length exceeds maximum. The build tag on the specified line exceeds the maximum of 32 characters. The compiler skips this entry. %@AB@%P1037%@AE@% Build tag %@AI@%tagname%@AE@% contains invalid characters. Build tags can contain only alphanumeric characters or the underscore (_) character. The line is skipped. %@AB@%P1039%@AE@% [BUILDTAGS] section missing. The %@AB@%BUILD%@AE@% option declared a conditional build, but there is no [BuildTags] section in the project file. All topics are included in the build. %@AB@%P1043%@AE@% Too many tags in Build expression. The Build expression on the specified line has used more than the maximum of 20 build tags. The compiler ignores the line. %@AB@%P1045%@AE@% [ALIAS] section found after [MAP] section. When used, the [Alias] section must precede the [Map] section in the project file. The [Alias] section is skipped otherwise. %@AB@%P1047%@AE@% Context string %@AI@%contextname%@AE@% already assigned an alias. You cannot do: a=b then a=c (A context string can only have one alias.) The specified context string has previously been aliased in the [Alias] section. The attempted reassignment on this line is ignored.%@CR:C6A00190014 @%%@CR:C6A00190015 @% %@AB@%P1049%@AE@% Alias string aliasname already assigned. You cannot do: a=b then b=c (You can't alias an alias.) An alias string cannot, in turn, be assigned another alias. %@AB@%P1051%@AE@% Context string %@AI@%contextname%@AE@% cannot be used as alias string. You cannot do: a=b then c=a A context string that has been assigned an alias cannot be used later as an alias for another context string. %@AB@%P1053%@AE@% Maximum number of font ranges exceeded. The maximum number of font ranges that can be specified is five. The rest are ignored. %@AB@%P1055%@AE@% Current font range overlaps previously defined range. A font size range overlaps a previously defined mapping. Adjust either font range to remove any overlaps. The second mapping is ignored. %@AB@%P1056%@AE@% Unrecognized font name in Forcefont option. A font name not supported by the compiler has been encountered. The font name is ignored and the compiler uses the default Helv font. %@AB@%P1057%@AE@% Font name too long. Font names cannot exceed 20 characters. The font is ignored. %@AB@%P1059%@AE@% Invalid multiple-key syntax. The syntax used with a %@AB@%MULTIKEY%@AE@% option is unrecognized. See Chapter 18, "Building the Help File," for the proper syntax. %@AB@%P1061%@AE@% Character already used. The specified key word-table identifier is already in use. Choose another character.%@CR:C6A00190016 @%%@CR:C6A00190017 @% %@AB@%P1063%@AE@% Characters 'K' and 'k' cannot be used. These characters are reserved for Help's normal key-word table. Choose another character. %@AB@%P1065%@AE@% Maximum number of keyword tables exceeded. The limit of five key-word tables has been exceeded. Reduce the number. The excess tables are ignored. %@AB@%P1067%@AE@% Equal sign missing. An option is missing its required equal sign on the specified line. Check the syntax for the option. %@AB@%P1069%@AE@% Context string missing. The line specified is missing a context string before an equal sign. %@AB@%P1071%@AE@% Incomplete line in %@AI@%sectionname%@AE@% section. The entry on the specified line is not complete. The line is skipped. %@AB@%P1073%@AE@% Unrecognized option in [OPTIONS] section. An option has been used that is not supported by the compiler. The line is skipped. %@AB@%P1075%@AE@% Invalid build expression. The syntax used in the build expression on the specified line contains one or more logical or syntax errors. %@AB@%P1077%@AE@% Warning level must be 1, 2, or 3. The %@AB@%WARNING%@AE@% reporting level can only be set to 1, 2, or 3. The compiler will default to full reporting (level 3). %@AB@%P1079%@AE@% Invalid compression option. The %@AB@%COMPRESS%@AE@% option can only be set to TRUE or FALSE. The compilation continues without compression. %@AB@%P1081%@AE@% Invalid title string. The %@AB@%TITLE%@AE@% option defines a string that is null or contains more than 32 characters. The title is truncated.%@CR:C6A00190018 @%%@CR:C6A00190019 @% %@AB@%P1083%@AE@% Invalid context identification number. The context number on the specified line is null or contains invalid characters. %@AB@%P1085%@AE@% Unrecognized text. The unrecognizable text that follows valid text in the specified line is ignored. %@AB@%P1086%@AE@% Invalid font-range syntax. The font-range definition on the specified line contains invalid syntax. The compiler ignores the line. Check the syntax for the %@AB@%MAPFONTSIZE%@AE@% option. %@AB@%P1089%@AE@% Unrecognized sort ordering. You have specified an ordering that is not supported by the compiler. Contact Microsoft Product Support Services for clarification of the error. %@3@%%@CR:C6A00190020 @%%@AB@%19.2.2 Errors During Processing of RTF Topic Files%@AE@%%@EH@%%@NL@% %@AB@%R2001%@AE@% Unable to open bitmap file %@AI@%filename%@AE@%. The specified bitmap file is unreadable. This is a DOS file error.%@CR:C6A00190021 @%%@CR:C6A00190022 @% %@AB@%R2003%@AE@% Unable to include bitmap file %@AI@%filename%@AE@%. The specified bitmap file could not be found or is unreadable. This is a DOS file error or an out-of-memory condition. %@AB@%R2005%@AE@% Disk full. The Help resource file could not be written to disk. Create more space on the destination drive. %@AB@%R2009%@AE@% Cannot use reserved DOS device name for file %@AI@%filename%@AE@%. A file has been referred to as COM1, LPT2, PRN, etc. Rename the file. %@AB@%R2013%@AE@% Output file %@AI@%filename%@AE@% already exists as a directory. There is a subdirectory in the Help project root with the same name as the desired Help resource file. Move or rename the subdirectory. %@AB@%R2015%@AE@% Output file %@AI@%filename%@AE@% already exists as read-only. The specified filename cannot be overwritten by the Help resource file because the file has a read-only attribute. Rename the project file or change the file's attribute. %@AB@%R2017%@AE@% Path for file %@AI@%filename%@AE@% exceeds limit of 79 characters. The absolute pathname, or the combined root and relative pathname, to the specified file exceed the DOS limit of 79 characters. The file is ignored. %@AB@%R2019%@AE@% Cannot open file %@AI@%filename%@AE@%. The specified file is unreadable. This is a DOS file error. %@AB@%R2021%@AE@% Cannot find file %@AI@%filename%@AE@%. The specified file could not be found or is unreadable. This is a DOS file error or an out-of-memory condition. %@AB@%R2023%@AE@% Not enough memory to build Help file. To free up memory, unload any unneeded applications, device drivers, and memory-resident programs.%@CR:C6A00190023 @%%@CR:C6A00190024 @% %@AB@%R2025%@AE@% File environment error. The compiler has insufficient available file handles to continue. Increase the values for FILES= and BUFFERS= in your CONFIG.SYS file and reboot. %@AB@%R2027%@AE@% Build tag %@AI@%tagname%@AE@% not defined in [BUILDTAGS] section of project file. The specified build tag has been assigned to a topic, but not declared in the project file. The tag is ignored for the topic. %@AB@%R2033%@AE@% Context string in Map section not defined in any topic. There are one or more context strings defined in the project file that the compiler could not find topics for. %@AB@%R2035%@AE@% Build expression missing from project file. The topics have build tags, but there is no Build= expression in the project file. The compiler includes all topics in the build. %@AB@%R2037%@AE@% File %@AI@%filename%@AE@% cannot be created, due to previous error(s). The Help resource file could not be created because the compiler has no topics remaining to be processed. Correct the errors that preceded this error and recompile. %@AB@%R2039%@AE@% Unrecognized table formatting in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The compiler ignores table formatting that is unsupported in Help. Reformat the entries as linear text if possible. %@AB@%R2041%@AE@% Jump %@AI@%context_string%@AE@% unresolved in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The specified topic contains a context string that identifies a nonexistent topic. Check spelling, and that the desired topic is included in the build. %@AB@%R2043%@AE@% Hotspot text cannot spread over paragraphs. A jump term spans two paragraphs. Remove the formatting from the paragraph mark.%@CR:C6A00190025 @%%@CR:C6A00190026 @% %@AB@%R2045%@AE@% Maximum number of tab stops reached in topic %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The limit of 32 tab stops has been exceeded in the specified topic. The default stops are used after the 32nd tab. %@AB@%R2047%@AE@% File %@AI@%filename%@AE@% not created. There are no topics to compile, or the build expression is false for all topics. There is no Help resource file created. %@AB@%R2049%@AE@% Context string text too long in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. Context string hidden text cannot exceed 64 characters. The string is ignored. %@AB@%R2051%@AE@% File %@AI@%filename%@AE@% is not a valid RTF topic file. The specified file is not an RTF file. Check that you have saved the topic as RTF from your word processor. %@AB@%R2053%@AE@% Font %@AI@%fontname%@AE@% in file %@AI@%filename%@AE@% not in RTF font table. A font not defined in the RTF header has been entered into the topic. The compiler uses the default system font. %@AB@%R2055%@AE@% File %@AI@%filename%@AE@% is not a usable RTF topic file. The specified file contains a valid RTF header, but the content is not RTF or is corrupted. %@AB@%R2057%@AE@% Unrecognized graphic format in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The compiler supports only Windows bitmaps. Check that metafiles or Macintosh formats have not been used. The graphic is ignored. %@AB@%R2059%@AE@% Context string identifier already defined in topic %@AI@%topicnumber%@AE@% of file %@AI@%%@AE@% %@AI@%filename%@AE@%. There is more than one context-string identifier footnote for the specified topic. The compiler uses the identifier defined in the first # footnote.%@CR:C6A00190027 @%%@CR:C6A00190028 @% %@AB@%R2061%@AE@% Context string %@AI@%contextname%@AE@% already used in file %@AI@%filename%@AE@%. The specified context string was previously assigned to another topic. The compiler ignores the latter string and the topic has no identifier. %@AB@%R2063%@AE@% Invalid context-string identifier for topic %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The context-string footnote contains nonalphanumeric characters or is null. The topic is not assigned an identifier. %@AB@%R2065%@AE@% Context string defined for index topic is unresolved. The index topic defined in the project file could not be found. The compiler uses the first topic in the build as the index. %@AB@%R2067%@AE@% Footnote text too long in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. Footnote text cannot exceed the limit of 1000 characters. The footnote is ignored. %@AB@%R2069%@AE@% Build tag footnote not at beginning of topic %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The specified topic contains a buildtag footnote that is not the first character in the topic. The topic is not assigned a build tag. %@AB@%R2071%@AE@% Footnote text missing in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The specified topic contains a footnote that has no characters. %@AB@%R2073%@AE@% Keyword string is null in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. A key-word footnote exists for the specified topic, but contains no characters. %@AB@%R2075%@AE@% Keyword string too long in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The text in the key-word footnote in the specified topic exceeds the limit of 255 characters. The excess characters are ignored. %@AB@%R2077%@AE@% Keyword(s) defined without title in topic %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. Key word(s) have been defined for the specified topic, but the topic has no title assigned. Search Topics Found displays Untitled Topic< for the topic.%@CR:C6A00190029 @%%@CR:C6A00190030 @% %@AB@%R2079%@AE@% Browse sequence string is null in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The browse-sequence footnote for the specified topic contains no sequence characters. %@AB@%R2081%@AE@% Browse sequence string too long in topic %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The browse-sequence footnote for the specified topic exceeds the limit of 128 characters. The sequence is ignored. %@AB@%R2083%@AE@% Missing sequence number in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. A browse-sequence number ends in a colon (:) for the specified topic. Remove the colon, or enter a "minor" sequence number. %@AB@%R2085%@AE@% Sequence number already defined in topic %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. There is already a browse-sequence footnote for the specified topic. The latter sequence is ignored. %@AB@%R2087%@AE@% Build tag too long. A build tag for the specified topic exceeds the maximum of 32 characters. The tag is ignored for the topic. %@AB@%R2089%@AE@% Title string null in topic %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The title footnote for the specified topic contains no characters. The topic is not assigned a title. %@AB@%R2091%@AE@% Title too long in topic %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. The title for the specified topic exceeds the limit of 128 characters. The excess characters are ignored. %@AB@%R2093%@AE@% Title titlename in topic %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@% used previously. The specified title has previously been assigned to another topic. %@CR:C6A00190031 @%%@CR:C6A00190032 @% %@AB@%R2095%@AE@% Title defined more than once in topic %@AI@%%@AE@% %@AI@%topicnumber%@AE@% of file %@AI@%filename%@AE@%. There is more than one title footnote in the specified topic. The compiler uses the first title string. %@AB@%R2501%@AE@% Using old key-phrase table. Maximum compression can only result by deleting the .PH file before each recompilation of the Help topics. %@AB@%R2503%@AE@% Out of memory during text compression. The compiler encountered a memory limitation during compression. Compilation continues with the Help resource file not compressed. Unload any unneeded applications, device drivers, and memory-resident programs. %@AB@%R2505%@AE@% File environment error during text compression. The compiler has insufficient available file handles for compression. Compilation continues with the Help resource file not compressed. Increase the values for FILES= and BUFFERS= in your CONFIG.SYS file and reboot. %@AB@%R2507%@AE@% DOS file error during text compression. The compiler encountered a problem accessing a disk file during compression. Compilation continues with the Help resource file not compressed. %@AB@%R2509%@AE@% Error during text compression. One of the three compression errors─R2503, R2505, or R2507─has occurred. Compilation continues with the Help resource file not compressed. %@AB@%R2701%@AE@% Internal error. Contact Microsoft Product Support Services for clarification of the error. %@AB@%R2703%@AE@% Internal error. Contact Microsoft Product Support Services for clarification of the error. %@AB@%R2705%@AE@% Internal error. Contact Microsoft Product Support Services for clarification of the error.%@CR:C6A00190033 @% %@CR:C6A00190034 @% %@AB@%R2707%@AE@% Internal error. Contact Microsoft Product Support Services for clarification of the error. %@AB@%R2709%@AE@% Internal error. Contact Microsoft Product Support Services for clarification of the error.%@CR:C6A00190035 @% %@CR:C6A00190036 @% %@CR:GeneralIndex@% %@1@%%@AB@%INDEX%@AE@%%@EH@%%@NL@% %@AB@%────────────────────────────────────────────────────────────────────────── { } (brackets), in symbol map display%@BO: 5dffd@% { } (curly braces), as document convention%@BO: acc7@% ( ) (parentheses), as document convention%@BO: 9ea9@% " " (quotation marks), as document convention%@BO: ac17@% -? option%@BO: 1cab1@% * (asterisk) wildcard character%@BO: 5ebd4@%%@BO: 64f19@%%@BO: 7225b@% with commands%@BO: 71e51@% @ (at symbol), with commands%@BO: 65002@% : (colon), use of with doubleword values%@BO: 6d471@% , (comma), as parameter separator%@BO: 13eba@% $ (dollar sign), as symbol with commands%@BO: 65002@% - (hyphen), as SYMDEB option designator%@BO: 5c450@% . (period), as ASCII value%@BO: 69bfd@% + (plus sign), as filename separator%@BO: 13bd5@% ? (question mark), with commands%@BO: 64f19@%%@BO: 71e51@% ; (semicolon), in SYMDEB command list%@BO: 5c31d@%%@BO: 6914b@% / (slash), as SYMDEB option designator%@BO: 5c450@% _ (underscore), with commands%@BO: 64f19@% | (vertical bar), as document convention%@BO: a9f4@% . . . (ellipses), as document convention%@BO: a57c@% {{ }} (double brackets), as document convention%@BO: a7d9@% %@2@%%@AB@% A%@AE@%%@EH@%%@NL@% Address arguments, SYMDEB%@BO: 65577@%%@BO: 66362@% Allocating memory%@BO: 96391@%%@BO: 980b4@% Allocation granularity%@BO: 980b4@% ANSI character set%@BO: 39526@% Applications and creating import libraries%@BO: 12f54@% and linking files%@BO: f836@%%@BO: 1383a@% and starting SYMDEB%@BO: 5ee16@% building%@BO: 8d63@% C language%@BO: c0a9@% compiling options for%@BO: d47a@% development options for%@BO: e4df@% executable%@BO: f836@% memory model for%@BO: dab7@% memory movement in%@BO: 97ad6@% module-definition (.DEF) files for%@BO: 11818@% optimizing performance of%@BO: 9eeca@% passing to Windows%@BO: 5cee3@% resource script (.RC) file%@BO: 27307@% startup routines for%@BO: 165fc@% Arguments address%@BO: 65577@%%@BO: 66362@% SYMDEB command%@BO: 62ce9@%%@BO: 6448f@%%@BO: 64f19@% ASCII byte values, displaying%@BO: 697a5@% characters, displaying%@BO: 697a5@% strings, entering into memory%@BO: 6cd6d@% Assembling instruction mnemonics%@BO: 6714f@% Assembly-language symbol files%@BO: 58c05@% Asterisk (*) wildcard character%@BO: 5ebd4@%%@BO: 639de@%%@BO: 7225b@% with commands%@BO: 71e51@% At symbol (@), with commands%@BO: 65002@% %@2@%%@AB@% B%@AE@%%@EH@%%@NL@% Binary resource file%@BO: 913a@% Bitmap (.BMP) files %@AI@%see also%@AE@% Bitmaps%@NL@% and File menu%@BO: 20b17@% and Image menu%@BO: 20e65@% and SDKPAINT process%@BO: 1f5b2@% creating%@BO: 21bce@% described%@BO: 1f93b@% working with colors%@BO: 249c2@% BITMAP resource statement%@BO: 18971@% Bitmaps %@AI@%see also%@AE@% Bitmap (.BMP) files%@NL@% creating%@BO: 21a67@% described%@BO: 1f93b@% editing colors for%@BO: 2549c@% editing%@BO: 216c6@%%@BO: 23ddc@% opaque color options%@BO: 249c2@% using colors with%@BO: 21bce@%%@BO: 23a83@% %@AB@%Bold text%@AE@%, as document convention%@BO: 9d83@% Braces, curly ({ }), as document convention%@BO: acc7@% Brackets ({ }), in symbol map display%@BO: 5dffd@% Brackets, double ({{ }}), as document convention%@BO: a75c@% Breakpoints "sticky", defined%@BO: 68cca@% clearing%@BO: 68318@% disabling%@BO: 686b1@% immediate%@BO: 5d55c@% interrupt key%@BO: 5fd0f@% restoring disabled%@BO: 687bb@% setting%@BO: 5fa48@%%@BO: 68cca@% virtual%@BO: 5fa48@% Byte values displaying 4-byte values as hexadecimal%@BO: 69cf0@% displaying hexadecimal and ASCII values%@BO: 69a02@% searching for%@BO: 70981@% %@2@%%@AB@% C%@AE@%%@EH@%%@NL@% C Compiler default option%@BO: e94e@% options (table)%@BO: d2ab@%%@BO: d47a@% versions supported by Windows%@BO: c0a9@% C language applications%@BO: c0a9@% libraries%@BO: f19b@%%@BO: 165fc@% C run-time libraries%@BO: 165fc@%%@BO: 16c58@% Callback function%@BO: f19b@% CAPITAL LETTERS, SMALL, as document convention%@BO: adf2@% Character information%@BO: 34b21@% Character mapping%@BO: 374f5@% Character window clearing%@BO: 3649b@% described%@BO: 347ee@% Character-viewing window%@BO: 34a3b@% Characters adding columns to%@BO: 3545c@% adding rows to%@BO: 3545c@% canceling changes to%@BO: 3703e@% changing character pixels%@BO: 351b8@% changing width of%@BO: 366c8@% deleting columns from%@BO: 35ae1@% deleting rows from%@BO: 35ae1@% displayed in Font Editor window%@BO: 345ed@% editing blocks of pixels%@BO: 35d6a@% editing%@BO: 34ddc@%%@BO: 3562a@% first of font%@BO: 37a44@% last of font%@BO: 37cd0@% pasting to and from Clipboard%@BO: 36418@% width restriction of%@BO: 36c7b@% Check box control%@BO: 2ce85@% Choosing messages%@BO: 9173f@% CL command%@BO: d47a@% CL Compiler %@AI@%see%@AE@% C Compiler%@NL@% Clearing breakpoints%@BO: 68318@% CODE statement%@BO: 10443@% Code, instruction%@BO: 70d58@% CodeView for Windows (CVW) application development option for%@BO: e4df@% breakpoints examples of%@BO: 4eb51@% on lines, functions, and addresses%@BO: 4d518@% on values%@BO: 4dc9d@% on Windows messages%@BO: 4e3dd@% removing%@BO: 4db7b@% calling functions%@BO: 53033@% commands Help on CVW commands%@BO: 45dd2@% new, in CVW%@BO: 3c634@% compared with CodeView for DOS%@BO: 3bd6d@% SYMDEB%@BO: 3b583@% compiling source code for use with%@BO: 3dd3a@% continuous execution%@BO: 4cdbc@% controlling program execution%@BO: 4c7c3@% customizing%@BO: 5429c@% debugging multiple instances of an application%@BO: 3efa6@% described%@BO: 3a59b@%%@BO: 3a7d8@% display windows adjusting%@BO: 43926@% described%@BO: 428e6@% opening%@BO: 42f6b@% selecting%@BO: 431d7@% using multiple Source windows%@BO: 52e05@% using the mouse with%@BO: 43547@% displaying memory dereferencing memory handles%@BO: 4b27a@% in the Memory window%@BO: 49285@% live expressions%@BO: 4a975@% local and global memory objects%@BO: 4991d@% register contents%@BO: 4b92f@% displaying variables arrays and structures%@BO: 47303@%%@BO: 47989@%%@BO: 47b10@%%@BO: 484a7@% expressions%@BO: 46e5a@% single values%@BO: 462af@%%@BO: 46ce9@% summarized%@BO: 45f52@% using the Quick Watch command%@BO: 486ed@% ending%@BO: 5262a@% Help in CVW%@BO: 45e31@% interrupting a session%@BO: 5046b@% menus%@BO: 43dc6@%%@BO: 44911@% preparing Windows applications%@BO: 3e1c2@% recording session information%@BO: 4212e@% redirecting input and output%@BO: 53d9b@% register variables%@BO: 53a0a@% requirements for use%@BO: 3afe6@% restarting%@BO: 529f5@% secondary monitor, setting up%@BO: 3cb1a@% setting breakpoints%@BO: 4d037@% single-step execution described%@BO: 4ca33@% stepping%@BO: 4f8c0@% tracing%@BO: 4f9db@% starting a CVW session%@BO: 3e3ac@% tracing program execution. See single-step execution.%@BO: 4f9db@% Windows messages%@BO: 48bf9@% undefined pointers%@BO: 537a4@% values, changing for program data%@BO: 4c13d@% for variables, memory locations and registers%@BO: 4c6d5@% windows-specific features%@BO: 3c7a3@% Colon (:), use of with doubleword values%@BO: 6d471@% Colors and bitmaps%@BO: 23ddc@% dithered%@BO: 23a83@% inverse%@BO: 24532@% opaque%@BO: 24358@% screen%@BO: 24417@% true%@BO: 23d1a@% Combo box control%@BO: 2d798@% Comma (, ), as parameter separator%@BO: 13eba@% Command arguments, SYMDEB%@BO: 62ce9@%%@BO: 6448f@%%@BO: 64f19@% Comparing bytes in memory locations%@BO: 69249@% Compiler options memory-model%@BO: d880@% recommended for dynamic-link libraries%@BO: eff1@% Windows applications%@BO: d2ab@% CompilersC Compiler %@AI@%see%@AE@% Resource Compiler%@NL@% CONTROL+C key%@BO: 5d71a@% CONTROL+S%@AI@% key%@AE@%%@ACKC6A00080034 @% Controls changing identifiers%@BO: 2eff5@% changing styles of%@BO: 2f18c@% changing text%@BO: 2f498@% custom%@BO: 29740@%%@BO: 29e79@%%@BO: 2dd86@% displaying information about%@BO: 2b6ca@% positions of%@BO: 2b6ca@% predefined identifiers%@BO: 29580@% symbolic names of%@BO: 28d60@% temporary%@BO: 29cc9@% Copying dialog-box controls%@BO: 2f86d@% file or disk contents into memory%@BO: 6f07a@% CPU registers, displaying contents of%@BO: 706ec@% Creating cursor (.CUR) files%@BO: 227d7@% cursors%@BO: 227d7@% icon (.ICO) files%@BO: 2228f@% import libraries%@BO: 12f54@% map files%@BO: 57967@% module-definition (.DEF) files%@BO: f971@%%@BO: 1020e@%%@BO: 11423@%%@BO: 116bc@%%@BO: 120e6@%%@BO: 12b53@% resource script (.RC) files%@BO: 17ccd@%%@BO: 18801@% symbol files%@BO: 57967@% Windows applications%@BO: 8d63@% Curly braces ({ }), as document convention%@BO: acc7@% Cursor (.CUR) files and File menu%@BO: 20b17@% and Image menu%@BO: 20e65@% and SDKPAINT process%@BO: 1f5b2@% creating%@BO: 227d7@% described%@BO: 1fb2e@% working with colors%@BO: 24ae5@% CURSOR resource statement%@BO: 18971@% Cursor %@AI@%see also%@AE@% Cursor (.CUR) files%@NL@% creating%@BO: 2202a@%%@BO: 227d7@% cursor images, and creating icons%@BO: 25fdc@% defining%@BO: 24126@% displaying%@BO: 1fcfd@%%@BO: 2066e@% editing%@BO: 2400c@% hotspot%@BO: 215a1@%%@BO: 25ce4@% inverse colors with%@BO: 25061@% opaque color options%@BO: 24ae5@% screen colors with%@BO: 24c5c@% with clipboard%@BO: 262db@% with color%@BO: 24358@% Custom control%@BO: 2dd86@% Custom controls%@BO: 298e6@%%@BO: 29a0d@% %@2@%%@AB@% D%@AE@%%@EH@%%@NL@% -D option%@BO: 1b3ff@% DATA statement%@BO: 1057f@% Debugging toolsCodeView for Windows (CVW) Spy %@AI@%see%@AE@% Symbolic Debugger (SYMDEB) %@NL@% Debugging adding line-number information%@BO: e4df@% entering into memory;ASCII strings%@BO: 6cd6d@% in protected mode. See CodeView for Windows(CVW)%@BO: 3a7d8@% in real mode. See Symbolic Debugger (SYMDEB)%@BO: 56efd@% .DEF file %@AI@%see%@AE@% Module-definition (.DEF) files%@NL@% Defining macros%@BO: 6f856@% Deleting dialog-box controls%@BO: 2fae7@% DESCRIPTION statement%@BO: 105dd@% Dialog boxes adding group marker to%@BO: 3047c@% controls changing order of%@BO: 30bee@% editing%@BO: 2c648@% using custom%@BO: 29740@%%@BO: 29c08@% creating new%@BO: 27307@%%@BO: 2c648@% defining styles of%@BO: 312b9@% deleting group marker from%@BO: 3079f@% editing canceling edits%@BO: 31867@% include files%@BO: 31d78@%%@BO: 32622@%%@BO: 32b0a@%%@BO: 32e2b@%%@BO: 333e7@%%@BO: 336ec@% methods of%@BO: 2888a@% modifying%@BO: 27391@% moving between resources%@BO: 31976@% opening existing%@BO: 2c599@% renaming%@BO: 311b2@% resizing%@BO: 30fdb@% setting memory flags for%@BO: 3145b@% Dialog Editor controls, groups of moving%@BO: 2eb4d@%%@BO: 2fdd3@% specifying%@BO: 3047c@% controls, order of%@BO: 30bee@% described%@BO: 27307@% dialog unit%@BO: 2bd04@% editing include files%@BO: 333e7@% group marker%@BO: 3047c@% mouse requirement for%@BO: 275d2@% opening dialog boxes%@BO: 2c486@% include files%@BO: 2c17f@% resource files%@BO: 2c027@% sizing handle%@BO: 2ec95@% tab stop for%@BO: 308aa@% toolbox described%@BO: 2b461@% enabling%@BO: 2e053@% using Clipboard format%@BO: 31c78@% window%@BO: 29fc4@% working with files dialog script%@BO: 276f4@%%@BO: 2824a@% include%@BO: 27baf@%%@BO: 28d60@%%@BO: 2c17f@% resource%@BO: 279d6@%%@BO: 2888a@%%@BO: 2bf48@% Dialog script (.DLG) files%@BO: 276f4@%%@BO: 27d74@% Dialog unit, described%@BO: 2bd04@% Dialog-box controls adding custom%@BO: 2e4f4@% standard%@BO: 2df55@% custom%@BO: 2dd86@% defining symbolic names for%@BO: 32f69@% deleting%@BO: 2fae7@% duplicating%@BO: 2f86d@% identifiers for changing%@BO: 2eff5@% input focus specifying%@BO: 30125@% using tab stops%@BO: 308aa@% moving groups of%@BO: 2fdd3@% individual%@BO: 2e8fe@% resizing%@BO: 2ec95@% static text%@BO: 2d402@% styles, changing%@BO: 2f18c@% text, changing%@BO: 2f498@% types of check box%@BO: 2ce85@% combo box%@BO: 2d798@% edit%@BO: 2d2b0@% frame%@BO: 2d8de@% group box%@BO: 2d55b@% horizontal scroll bar%@BO: 2d0b0@% icon%@BO: 2db36@% list box%@BO: 2d67b@% push button%@BO: 2c94e@% radio button%@BO: 2cb88@% rectangle%@BO: 2dc2c@% vertical scroll bar%@BO: 2d0b0@% Directives, resource%@BO: 18801@% Disabling breakpoints%@BO: 6856c@% Displaying ASCII characters within a given range%@BO: 697a5@% CPU registers, contents of%@BO: 7063f@% cursor hotspot%@BO: 215a1@% expression, value of%@BO: 72a06@% hexadecimal values of bytes in given range%@BO: 69a02@% of doublewords%@BO: 69cf0@% of words%@BO: 6c834@% instruction code%@BO: 70d58@% instructions, of program being debugged%@BO: 71320@% list of global free memory objects in global heap%@BO: 69f8b@%%@BO: 79d9d@% global memory objects in global heap%@BO: 6a1dc@%%@BO: 7a16b@% global modules in global heap%@BO: 6b378@%%@BO: 7b3aa@% local memory objects in local heap%@BO: 6acf2@%%@BO: 7af51@% LRU global memory objects%@BO: 6bf9f@%%@BO: 7bb7a@% SYMDEB commands and operators%@BO: 7277d@% long floating-point numbers%@BO: 6b124@% memory objects%@BO: 954b1@% memory, contents of%@BO: 694d4@% one byte from the input port%@BO: 6e67a@% short floating-point numbers%@BO: 6bb1f@% source line actual program%@BO: 711d9@%%@BO: 715cc@% current%@BO: 72b18@% stack frame current%@BO: 6e82d@%%@BO: 852ae@%%@BO: 85764@% for a specified task%@BO: 6eb8a@%%@BO: 85a9e@% stack location and frame-pointer values%@BO: 6eed8@%%@BO: 860a8@% statements, of program being debugged%@BO: 714f8@% sum and difference of two hexadecimal numbers%@BO: 6e50a@% symbol map information%@BO: 71bd1@% symbol maps%@BO: 5ddd1@% symbols%@BO: 5e808@% task-queue information%@BO: 6b6a7@%%@BO: 7b6ea@% ten-byte floating-point numbers%@BO: 6bd69@% variables%@BO: 5ffac@% DLLs %@AI@%see%@AE@% Dynamic-link libraries%@NL@% Document conventions%@BO: 9d83@%%@BO: 9ea9@%%@BO: a149@%%@BO: a21c@%%@BO: a33c@%%@BO: a57c@%%@BO: a7d9@%%@BO: a9f4@%%@BO: ac17@%%@BO: acc7@%%@BO: adf2@% Dollar sign ($), with commands%@BO: 65002@% DOS commands CL%@BO: d47a@% command processor%@BO: 733b5@% exit%@BO: 733b5@% mode%@BO: 59428@% RC%@BO: 1aa71@% Double brackets ({{ }}), as document convention%@BO: a75c@% Doubleword values%@BO: 6d471@% Dynamic-link Libraries (DLLs) custom control%@BO: 298e6@% Dynamic-link libraries (DLLs) module-definition (.DEF) files, requirements%@BO: 120e6@% options for compiling%@BO: eff1@%%@BO: f4e1@% written in C language, requirements%@BO: f19b@% %@2@%%@AB@% E%@AE@%%@EH@%%@NL@% -E option%@BO: 1bc93@% Echoing comment on output devices%@BO: 734c7@% Edit control%@BO: 2d2b0@% Editing canceling dialog box edits%@BO: 31867@% dialog box controls%@BO: 2c648@% dialog box%@BO: 27307@% include files%@BO: 333e7@% Ellipses, as document convention horizontal%@BO: a57c@% vertical%@BO: a33c@% EMS (Expanded Memory Specification) defined%@BO: 9350c@% walking%@BO: 94f7f@% Enabling breakpoints%@BO: 687bb@% Enabling toolbox%@BO: 2e053@% Epilog (Windows)%@BO: f19b@% Executable files%@BO: 1740b@% Executing instructions%@BO: 70163@%%@BO: 711d9@% macros%@BO: 6f856@% Execution control%@BO: 6e423@%%@BO: 703e5@%%@BO: 711d9@%%@BO: 733b5@% EXETYPE statement%@BO: 106b4@% EXETYPE WINDOWS statement%@BO: 11818@%%@BO: 1245f@% Expanded Memory Specification %@AI@%see%@AE@% EMS%@NL@% Exported function%@BO: f19b@% EXPORTS statement%@BO: 1090d@%%@BO: 12363@% Expressions displaying value of%@BO: 72a06@% SYMDEB commands%@BO: 665df@% %@2@%%@AB@% F%@AE@%%@EH@%%@NL@% Fatal exit message%@BO: 60d2e@% -Fe option%@BO: 1b499@% File headers, executable%@BO: 1740b@% Filenames, setting for load and write commands%@BO: 6fbd9@% Files dialog script (.DLG)%@BO: 276f4@%%@BO: 27d74@% executable file headers%@BO: 1740b@% icon (.ICO)%@BO: 1f5b2@%%@BO: 1fb2e@%%@BO: 20b17@%%@BO: 20e65@%%@BO: 2228f@%%@BO: 24a7e@% include (.H)%@BO: 27baf@%%@BO: 28d60@% loading%@BO: 6f55b@% module-definition (.DEF)%@BO: 1027c@% resource (.R)%@BO: 279d6@%%@BO: 2888a@% resource script (.RC)%@BO: 17ccd@%%@BO: 27307@% symbol%@BO: 57720@% Filling addresses in a given range%@BO: 6df29@% Floating-point numbers%@BO: 6b25b@%%@BO: 6bc57@%%@BO: 6bd69@% Floating-point values%@BO: 6d73d@%%@BO: 6d9b8@% -Fo option%@BO: 1b440@%%@BO: 1dc08@% Font Editor adding columns to a character%@BO: 3545c@% rows to a character%@BO: 3545c@% canceling changes%@BO: 370c8@% changing character pixels%@BO: 351b8@% character width%@BO: 366c8@%%@BO: 374f5@% font file header information%@BO: 3827f@% character information display%@BO: 34b21@% character window clearing%@BO: 3649b@% described%@BO: 347ee@% character-viewing window%@BO: 34a3b@% Clipboard characters, using%@BO: 36418@% deleting columns from characters%@BO: 35ae1@% rows from characters%@BO: 35ae1@% described%@BO: 33eeb@% editing blocks of pixels%@BO: 35d6a@% characters%@BO: 34ddc@%%@BO: 3562a@%%@BO: 35ae1@% fixed-pitch font%@BO: 37dcc@% Font Editor window%@BO: 345ed@% font family names%@BO: 39720@% font window%@BO: 34bfd@% mouse requirement for%@BO: 3420f@% opening fonts%@BO: 343a3@% resizing fonts%@BO: 374f5@% variable-pitch font%@BO: 37dcc@% window%@BO: 345ed@% Font EditorFonts %@AI@%see also%@AE@% Pixels%@NL@% Font file header, editing%@BO: 3827f@% FONT resource statement%@BO: 18971@% Fonts break character of%@BO: 391a6@% canceling changes to%@BO: 36dc2@%%@BO: 370c8@% copyright of%@BO: 385ce@% creating%@BO: 33f1e@%%@BO: 345ed@%%@BO: 34ddc@%%@BO: 351b8@%%@BO: 3545c@%%@BO: 3562a@%%@BO: 36418@%%@BO: 36814@%%@BO: 36c7b@% default character of%@BO: 38fda@% editing%@BO: 374f5@%%@BO: 37a44@%%@BO: 38136@%%@BO: 38fda@% face name of%@BO: 3847c@% filename of%@BO: 384d9@% first character of%@BO: 37a44@% font character set%@BO: 39526@% font face name %@AI@%vs%@AE@%. filename%@BO: 3827f@% font families%@BO: 39720@% font file header%@BO: 3827f@%%@BO: 38fda@% height of ascent%@BO: 387f8@% character pixel%@BO: 3768f@% height%@BO: 374f5@% last character of%@BO: 37cd0@% leading of external%@BO: 38bbe@% internal%@BO: 38e08@% nominal point size of%@BO: 386b1@% nominal resolution of horizontal%@BO: 38930@% vertical%@BO: 38894@% opening, in Font Editor%@BO: 343a3@% options strikeout%@BO: 39c2a@% underline%@BO: 39b41@% pitches of%@BO: 37dcc@% saving changes to%@BO: 36dc2@% types of fixed-pitch%@BO: 37dcc@% raster%@BO: 3412b@% variable-pitch%@BO: 36b2e@%%@BO: 37dcc@% vector%@BO: 3412b@% weights of%@BO: 38136@% width of fixed-pitch%@BO: 3788d@% variable-pitch%@BO: 37768@% Frame control%@BO: 2d8de@% Functions callback%@BO: f19b@% exported%@BO: f19b@%%@BO: 1740b@% imported%@BO: 1740b@% WinMain%@BO: 5fb2e@% %@2@%%@AB@% G%@AE@%%@EH@%%@NL@% GDI library, symbol files%@BO: 5c8bb@% Global heap allocating memory to examine%@BO: 96391@% defining displayed objects%@BO: 954b1@% displaying lists of free global memory objects in%@BO: 69f8b@%%@BO: 79d9d@% global memory objects in%@BO: 6a26e@%%@BO: 7a411@% global modules in%@BO: 6b40d@%%@BO: 7b44b@% LRU global memory objects in%@BO: 6bf9f@%%@BO: 7bb7a@% protected mode%@BO: 93249@% real mode%@BO: 9334b@%%@BO: 9350c@% saving lists of objects on%@BO: 93ca8@% sorting displayed objects%@BO: 9510c@% total size of examined objects%@BO: 96d66@% viewing%@BO: 92ee7@% walking EMS%@BO: 94f7f@% walking%@BO: 942e4@% Group box control%@BO: 2d55b@% Group marker adding%@BO: 3047c@% deleting%@BO: 3079f@% %@2@%%@AB@% H%@AE@%%@EH@%%@NL@% .H file %@AI@%see%@AE@% Include (.H) files%@NL@% -H option%@BO: 1cab1@% Heap Walker allocating memory examined by%@BO: 96391@% defining objects displayed by%@BO: 954b1@% described%@BO: 92ee7@% displaying selected objects%@BO: 942e4@% file operation commands%@BO: 93ca8@% information displayed by%@BO: 937b4@% memory allocation commands%@BO: 96391@% memory object commands%@BO: 954b1@% saving object lists%@BO: 93ca8@% sorting displayed objects%@BO: 9510c@% total size of objects examined by%@BO: 96d66@% window%@BO: 935fc@% HEAPSIZE statement%@BO: 10a02@% Height, font%@BO: 374f5@% Help compiler%@BO: b925a@%%@BO: b94a7@%%@BO: b9bc7@%%@BO: b9f26@% Help graphics%@BO: a7d98@%%@BO: a80ed@% bitmaps creating, capturing%@BO: afa51@%%@BO: afef6@% placing%@BO: b015f@%%@BO: b07e0@% Help Project file accessing from an application%@BO: ba165@% Alias section%@BO: b7686@%%@BO: b7e0b@% Bitmaps section%@BO: b8edd@% bitmaps, including by reference%@BO: b8edd@% Build option%@BO: b4374@%%@BO: b4914@%%@BO: b4d2b@% Build Tags section%@BO: b30d8@%%@BO: b33f2@% compiling%@BO: b925a@%%@BO: b94a7@%%@BO: b9bc7@%%@BO: b9f26@% Compress option%@BO: b6fd6@%%@BO: b749c@% context strings, alternate%@BO: b7686@%%@BO: b7e0b@% context-sensitive Help%@BO: bb44e@%%@BO: bb6be@%%@BO: bbeba@%%@BO: bc93d@%%@BO: bd31c@% context-sensitive topics%@BO: b8066@%%@BO: b83f2@%%@BO: b8838@%%@BO: b8d83@% creating%@BO: b2104@%%@BO: b2789@% F1 support%@BO: bc743@%%@BO: bc93d@%%@BO: bd31c@% Files section%@BO: b2a9d@% Forcefont option%@BO: b5be0@%%@BO: b5fc4@% Index option%@BO: b53c5@%%@BO: b5728@% keyword table, accessing%@BO: bd863@% Map section%@BO: b8066@%%@BO: b83f2@%%@BO: b8838@%%@BO: b8d83@% Mapfontsize option%@BO: b6270@%%@BO: b6860@% Multikey option%@BO: b6943@%%@BO: b6e5c@% on Help menu item%@BO: bd4c5@% Options section%@BO: b34d0@%%@BO: b3afd@% Root option%@BO: b4e46@%%@BO: b51ec@% Title option%@BO: b58b3@% Warning option%@BO: b3c0e@%%@BO: b41a1@% Help system %@AI@%see also%@AE@% Help%@NL@% appearance to programmer%@BO: a2f58@% appearance to user%@BO: a25a6@%%@BO: a28df@% appearance to writer%@BO: a2b20@%%@BO: a2dc6@% calling WinHelp%@BO: ba25c@%%@BO: ba546@%%@BO: baaf7@%%@BO: bb292@% development cycle described%@BO: a1fa6@%%@BO: a2528@% graphics. See Help graphics%@BO: a7d98@% hypertext links summarized%@BO: a30e9@% topics. See Help topics%@BO: a3e4c@% Help text fonts%@BO: a789e@%%@BO: a7b0c@% layout%@BO: a62a3@%%@BO: a6946@%%@BO: a75c7@% Help tools %@AI@%see%@AE@% Help%@NL@% Help topic files authoring tool%@BO: a8de2@% browse sequence numbers%@BO: ad2cd@%%@BO: ad76f@%%@BO: adeac@%%@BO: ae30f@%%@BO: ae5a0@% build tags%@BO: aa061@%%@BO: aa40f@%%@BO: aac72@% context strings%@BO: aad89@%%@BO: ab534@% control codes%@BO: a9473@% cross references%@BO: ae89a@% definitions%@BO: aed21@%%@BO: af31b@% graphics%@BO: af875@% jumps%@BO: ae89a@% key words%@BO: abf56@%%@BO: ac475@%%@BO: ac8aa@%%@BO: ad012@% managing%@BO: b0f06@% title footnotes%@BO: ab5a0@%%@BO: ab7e6@%%@BO: abd31@% tracking%@BO: b0fa7@%%@BO: b19a0@% Help topics content%@BO: a3e4c@% context-sensitivity%@BO: a4eef@%%@BO: a50dd@%%@BO: a55c7@%%@BO: a56e1@% cross-references%@BO: ae7ad@% definitions%@BO: aed21@%%@BO: af31b@% file structure%@BO: a5899@%%@BO: a5b64@%%@BO: a5e93@% files. See Help topic files%@BO: a90b5@% jumps%@BO: ae89a@% structure of%@BO: a441b@%%@BO: a4d25@% text. See Help text%@BO: a62a3@% Help Tracker%@BO: b1409@%%@BO: b19a0@% Help audience definition%@BO: a38dc@%%@BO: a3d79@% cancelling%@BO: be237@%%@BO: be7ae@% compiler error messages%@BO: bf7e5@%%@BO: bfe17@%%@BO: c0930@%%@BO: c155b@%%@BO: c2246@%%@BO: c2cfc@%%@BO: c382e@%%@BO: c3e7c@%%@BO: c4a86@%%@BO: c5730@%%@BO: c63a0@%%@BO: c71fc@%%@BO: c7db4@%%@BO: c89f0@% context-sensitive%@BO: a4eef@%%@BO: a50dd@%%@BO: a55c7@%%@BO: a56e1@%%@BO: bb44e@%%@BO: bb6be@%%@BO: bbeba@%%@BO: bc93d@%%@BO: bd31c@% control codes%@BO: a9473@% error messages%@BO: bf7e5@%%@BO: bfe17@%%@BO: c0930@%%@BO: c155b@%%@BO: c2246@%%@BO: c2cfc@%%@BO: c382e@%%@BO: c3e7c@%%@BO: c4a86@%%@BO: c5730@%%@BO: c63a0@%%@BO: c71fc@%%@BO: c7db4@%%@BO: c8a4e@% F1 support%@BO: bc743@%%@BO: bc93d@%%@BO: bd31c@% file structure%@BO: a5899@%%@BO: a5b64@%%@BO: a5e93@% file. See Help Project file%@BO: b1d92@% key words%@BO: abf56@%%@BO: ac475@%%@BO: ac8aa@%%@BO: ad012@% keyword table, accessing%@BO: bd863@% on Help menu item%@BO: bd4c5@% planning overview%@BO: a3601@% topic files examples%@BO: bef1b@% links summarized%@BO: a3284@% Hexadecimal values of bytes in the given range%@BO: 69a02@% of double words%@BO: 69cf0@% of floating-point numbers in the given range%@BO: 6b25b@%%@BO: 6bc57@% of words in the given range%@BO: 6c929@% Hits, defined%@BO: 9e0b0@% Hotspot, cursor defining%@BO: 25ce4@% displaying%@BO: 215a1@% Hyphen (-), as SYMDEB option designator%@BO: 5c450@% %@2@%%@AB@% I%@AE@%%@EH@%%@NL@% -I option%@BO: 1b593@%%@BO: 1df17@%%@BO: 1e3bf@% Icon (.ICO) files and File menu%@BO: 20b17@% and Image menu%@BO: 20e65@% and SDKPAINT process%@BO: 1f5b2@% creating%@BO: 2228f@% described%@BO: 1fb2e@% working with colors%@BO: 24a7e@% Icon control%@BO: 2db94@% ICON resource statement%@BO: 18971@% Icons %@AI@%see also%@AE@% Icon (.ICO) files%@NL@% colors with%@BO: 23a83@% creating, with cursor images%@BO: 25fdc@% editing colors for%@BO: 2549c@% editing%@BO: 23f19@% inverse colors with%@BO: 25061@% opaque color options%@BO: 24a7e@% screen colors with%@BO: 24c5c@% Identifiers, dialog-box control%@BO: 2eff5@% Immediate breakpoint%@BO: 5d4d8@% IMPLIB utility%@BO: 12b53@% IMPORTS statement%@BO: 10cba@%%@BO: 12b53@% Include (.H) files creating%@BO: 32622@% editing%@BO: 32e2b@%%@BO: 333e7@% loading%@BO: 32b0a@% saving%@BO: 336ec@% working with%@BO: 28c34@% Input focus, dialog-box control%@BO: 30125@% Input port%@BO: 6e67a@% Input, redirecting input commands%@BO: 72c3a@% Instruction code, displaying%@BO: 70d58@% Interrupt key%@BO: 5fd0f@% %@AI@%Italic text%@AE@%, as document convention%@BO: a149@% %@2@%%@AB@% K%@AE@%%@EH@%%@NL@% -K option%@BO: 1c1c9@% Kernel library, symbol files%@BO: 5c8bb@% Keys CONTROL+C%@BO: 5d71a@% CONTROL+S%@AI@%%@AE@%%@ACKC6A00080033 @% SCROLL LOCK%@BO: 5d36a@% SYS REQ%@BO: 5d4d8@% %@2@%%@AB@% L%@AE@%%@EH@%%@NL@% -L option%@BO: 1b8a2@% Leading%@BO: 38bbe@%%@BO: 38e08@% LIBRARY statement%@BO: 10d94@%%@BO: 121cc@% Library symbol files%@BO: 5c8b9@%%@BO: 5c8ba@%%@BO: 5c8bb@% -LIM 32 option%@BO: 1b900@% Linker command options described%@BO: 143a0@%%@BO: 14f7a@%%@BO: 159eb@%%@BO: 15f3f@% not allowed%@BO: 1622b@% not recommended%@BO: 1622b@% creating import libraries%@BO: 12f54@% LINK command, using%@BO: 1388e@% linking applications files%@BO: 1383a@% dynamic-link libraries%@BO: f836@%%@BO: 120e6@%%@BO: 1253d@%%@BO: 1274b@%%@BO: 12f54@% module-definition (.DEF) files%@BO: f836@% source files%@BO: f836@% Windows applications%@BO: 13611@% module-definition (.DEF) files creating for applications%@BO: 11423@%%@BO: 116bc@% creating for libraries%@BO: 116bc@%%@BO: 120e6@%%@BO: 12b53@% importing dynamic-link libraries%@BO: 12cf6@% module statements%@BO: 1027c@%%@BO: 116bc@% requirements for creating%@BO: f971@% Linking %@AI@%see%@AE@% Linker%@NL@% List box control%@BO: 2d67b@% Listing breakpoint information%@BO: 68a2d@% Loading files%@BO: 6f55b@% logical records%@BO: 6f55b@% Local heap%@BO: 6ae1e@%%@BO: 7b087@% Logical records, loading%@BO: 6f55b@% %@2@%%@AB@% M%@AE@%%@EH@%%@NL@% -M option%@BO: 1bb66@% Macro defining%@BO: 6f856@% executing%@BO: 6f856@% Managing output%@BO: 9b123@% Map files%@BO: 13d33@%%@BO: 57967@%%@BO: 57d29@% Maps %@AI@%see%@AE@% Symbol maps%@NL@% MAPSYM program creating symbol files%@BO: 57967@% sample symbol file%@BO: 58a25@%%@BO: 58f4a@% MASM assembler%@BO: 923d@% Math coprocessor/emulator, with Windows%@BO: 170d8@% Memory flags, setting dialog box%@BO: 3145b@% Memory models%@BO: dab7@%%@BO: 16751@% Memory comparing bytes in memory locations%@BO: 69249@% copying file or disk contents into%@BO: 6f07a@% determining size%@BO: 96d66@% displaying contents of within a given range%@BO: 694d4@% entering ASCII strings into%@BO: 6cd6d@% byte values into%@BO: 6cfce@% doubleword values into%@BO: 6d2ca@% long floating-point values into%@BO: 6d596@% short floating-point values into%@BO: 6d80d@% ten-byte real values into%@BO: 6da8b@% values into%@BO: 6ca11@% word values into%@BO: 6dcf7@% moving blocks of%@BO: 6f67b@% testing movable%@BO: 97ad6@% Menu bar%@BO: 2a027@% Messages choosing%@BO: 9173f@% fatal-exit%@BO: 60d2e@% information Spy monitors%@BO: 9173f@% memory-allocation%@BO: 5f1e5@% monitoring%@BO: 908ec@%%@BO: 9173f@% Microsoft QuickC%@BO: c0a9@%%@BO: f971@% Mnemonics, instruction%@BO: 67323@% Mode display%@BO: 2b2e1@% Module statements %@AI@%see%@AE@% Module-definition (.DEF) files%@NL@% Module-definition ( DEF) files for applications described%@BO: 11818@% Module-definition (.DEF) files creating%@BO: 1020e@%%@BO: 11423@%%@BO: 120e6@%%@BO: 12b53@% described%@BO: 9191@%%@BO: 1020e@% for applications described%@BO: 11423@% sample file%@BO: 11817@%%@BO: 11818@%%@BO: 12013@% for dynamic-link libraries described%@BO: 120e6@% sample file%@BO: 1253d@% linking applications%@BO: 13e65@% module statements list%@BO: 1027c@% required%@BO: 116bc@% Monitor, secondary, for debugging%@BO: 5975f@% %@AS@%Monospaced type%@AE@%, as document convention%@BO: a21c@% Moving blocks of memory%@BO: 6f67b@% MS-DOS %@AI@%see%@AE@% DOS commands%@NL@% %@2@%%@AB@% N%@AE@%%@EH@%%@NL@% NAME statement%@BO: 10e36@%%@BO: 11818@% Naming modules%@BO: 11818@% symbol files%@BO: 5ca2f@%%@BO: 5db90@% Non-maskable interrupts%@BO: 5b5ec@% Notational conventions%@BO: 98c4@%%@BO: adf2@% %@2@%%@AB@% O%@AE@%%@EH@%%@NL@% OEM character set%@BO: 39526@% Oil can%@BO: 22c80@% Optimization toolsHeap Walker Profiler Shaker %@AI@%see%@AE@% Swap%@NL@% Options compiler application development%@BO: e2b2@%%@BO: eab9@% dynamic-link library%@BO: eb88@%%@BO: f4e1@% memory-model%@BO: d880@%%@BO: e148@% LINK command described%@BO: 143a0@%%@BO: 14f7a@%%@BO: 159eb@%%@BO: 15f3f@% options not allowed%@BO: 1622b@% options not recommended%@BO: 16333@% option designator%@BO: 5c450@% RC command line%@BO: 1d234@% Resource Compiler (table)%@BO: 1b0fa@% SYMDEB%@BO: 5a414@%%@BO: 5ab08@%%@BO: 5ba4a@% Output device, choosing (Spy)%@BO: 9173f@% Output port sending bytes to%@BO: 6ffbd@% Output redirecting output commands%@BO: 72e3c@% suspending and restoring%@BO: 5d36a@% %@2@%%@AB@% P%@AE@%%@EH@%%@NL@% -P option%@BO: 1bf68@% Packed structure%@BO: d2ab@% Paintbrush%@BO: 22c80@% Parentheses ( ), as document convention%@BO: 9ea9@% PC-DOS %@AI@%see%@AE@% DOS commands%@NL@% Period (.), as ASCII value%@BO: 69bfd@% Pixels adding rows or columns of%@BO: 3562a@% changing character%@BO: 351b8@% copying to Clipboard%@BO: 36418@% deleting rows or columns of%@BO: 35ae1@% pasting from Clipboard%@BO: 36418@% selecting and changing blocks of%@BO: 35d6a@% Plus sign (+), as filename separator%@BO: 13bd5@% Preprocessor, defining names for%@BO: 1d44f@% PROF.COM program%@BO: 9c31d@% Profiler checking if installed%@BO: 9a5ec@% described%@BO: 988c3@%%@BO: 99128@% displaying samples%@BO: 9e0b0@% ensuring compatibility with your system%@BO: 99839@% functions%@BO: 99a5d@%%@BO: 99f55@%%@BO: 9a5ec@%%@BO: 9b123@%%@BO: 9bd38@% managing output (example)%@BO: 9baa9@% sampling real-mode Windows applications%@BO: 9c31d@%%@BO: 9cf0e@% setting rate of%@BO: 9a7eb@% starting and stopping%@BO: 99f55@% Windows 386 enhanced mode applications%@BO: 9c433@%%@BO: 9d187@% starting and stopping%@BO: 9bd38@% Program descriptor block (pdb)%@BO: 6a852@%%@BO: 6b878@%%@BO: 6c631@%%@BO: 6eb8a@%%@BO: 7aaa9@%%@BO: 7b8cb@%%@BO: 7c2d6@%%@BO: 85a9e@% Program execution%@BO: 703e5@%%@BO: 711d9@%%@BO: 733b5@% Program input and output, redirecting%@BO: 72c3a@% Programming tools %@AI@%see%@AE@% Tools%@NL@% Programs CL%@BO: c0a9@% RC%@BO: 1a75b@% setting arguments for program execution%@BO: 6fbd9@% Prolog (Windows)%@BO: f19b@% Protected mode debugging in. See CodeView for Windows(CVW)%@BO: 3a7d8@% Public symbols%@BO: 58d23@% Push button control%@BO: 2c94e@% %@2@%%@AB@% Q%@AE@%%@EH@%%@NL@% Question mark (?), with commands%@BO: 64f19@%%@BO: 71e51@% Quitting SYMDEB%@BO: 60a35@% Quotation marks (" "), as document convention%@BO: ac17@% %@2@%%@AB@% R%@AE@%%@EH@%%@NL@% -R option%@BO: 1b18c@%%@BO: 1d352@% Radio button control%@BO: 2cb88@% Raster fonts%@BO: 3412b@% RC command%@BO: 1cdc6@% RC Compiler described%@BO: 1a75b@% RC compiler options (table)%@BO: 1b0fa@% .RC file %@AI@%see%@AE@% Resource script (.RC) files%@NL@% Real mode debugging in. See Symbolic Debugger (SYMDEB)%@BO: 56efd@% Real-mode Windows applications%@BO: 99128@%%@BO: 99500@%%@BO: 99c88@%%@BO: 9aed0@%%@BO: 9c31d@% REC command%@BO: 1aa71@% Rectangle control%@BO: 2dc2c@% Redirecting program input and output%@BO: 72c3a@%%@BO: 73023@% Registers, CPU, displaying contents of%@BO: 706ec@% Reporting utility%@BO: 991f6@%%@BO: 9d56d@% .RES file %@AI@%see%@AE@% Resource (.RES) files%@NL@% Resource (.RES) files%@BO: 1f5b2@%%@BO: 2864e@% Resource Compiler described%@BO: 1a75b@% RC command line options%@BO: 1d234@% Resource directives%@BO: 18801@% Resource editorsDialog Editor Font Editor %@AI@%see%@AE@% SDKPaint%@NL@% Resource script (.RC) files .RC extension%@BO: 183d6@% and Dialog Editor%@BO: 2824a@% creating%@BO: 17ccd@%%@BO: 18801@% described%@BO: 908f@%%@BO: 17ccd@%%@BO: 18801@% for applications%@BO: 1a4b3@% resource statements%@BO: 18801@%%@BO: 18971@% Resource statements %@AI@%see%@AE@% Resource script (.RC) files%@NL@% Resources defining%@BO: 17ccd@% dialog box%@BO: 27307@% %@2@%%@AB@% S%@AE@%%@EH@%%@NL@% Sampling buffer%@BO: 99f55@% displaying samples%@BO: 9d56d@%%@BO: 9e0b0@% minimizing loss when sampling buffer fills%@BO: 9c31d@% real-mode Windows applications%@BO: 9c31d@%%@BO: 9cf0e@% setting rate of code%@BO: 9a7eb@% standard-mode Windows applications%@BO: 9cf0e@% starting and stopping%@BO: 99f55@% utilities for%@BO: 99128@%%@BO: 9c31d@%%@BO: 9d187@% Windows 386 enhanced mode applications%@BO: 9c433@%%@BO: 9d116@% Scroll bar control%@BO: 2d0b0@% SCROLL LOCK key%@BO: 5d36a@% SDKPaint .DAT file, described%@BO: 1fcfd@% color palette, described%@BO: 23ddc@%%@BO: 2400c@% converting files%@BO: 217cf@% cursor hotspot defining%@BO: 25ce4@% showing the current%@BO: 25ce4@% described%@BO: 1f1f6@% loading images into%@BO: 229f2@% menu commands (list)%@BO: 20847@%%@BO: 20e65@% tools, described (table)%@BO: 22c80@% transferring images to and from clipboard%@BO: 25f18@% window, described%@BO: 2075c@% working with colors customizing the color palette%@BO: 252ba@% editing colors%@BO: 2549c@% inverse colors%@BO: 25061@% loading a customized palette%@BO: 25a14@% opaque colors%@BO: 248c0@% saving a palette%@BO: 25850@% screen colors%@BO: 24c5c@% true colors%@BO: 23d1a@% types of%@BO: 23a83@%%@BO: 24358@% Secondary monitor, setting up for debugging%@BO: 5975f@% SEGMENTS statement%@BO: 10ee4@% Selected Item Status window%@BO: 2b6ca@% Semicolon ( ), in SYMDEB command list%@BO: 5c31d@% Serial port%@BO: 59210@% Setting active symbol maps and/or segments%@BO: 72360@% breakpoint address%@BO: 678e5@% breakpoints%@BO: 5fa48@%%@BO: 68cca@% display mode%@BO: 70bc1@% filenames for load and write commands%@BO: 6fbd9@% program arguments for program execution%@BO: 6fbd9@% Shaker allocation granularity%@BO: 980b4@% commands (list)%@BO: 985d7@% described%@BO: 97ad6@% SHOWHITS.EXE utility described%@BO: 9d56d@%%@BO: 9e0b0@% sample display%@BO: 9e8db@% SKERNEL.EXE file%@BO: 9f376@% SKERNEL.SYM file%@BO: 9f58b@% Slash (/), as SYMDEB option designator%@BO: 5c450@% SMALL CAPTIAL LETTERS, as document convention%@BO: adf2@% Sorting memory objects%@BO: 9510c@% Source file, compiling%@BO: e148@% Source lines, displaying%@BO: 711d9@% Spy choosing a window%@BO: 91ef5@% choosing options message type%@BO: 91116@%%@BO: 9173f@% output device%@BO: 91834@% output frequency%@BO: 91c4e@%%@BO: 91e07@% described%@BO: 908ec@% starting%@BO: 90c10@% turning on and off%@BO: 92730@% Stack frame%@BO: 6eaa0@%%@BO: 6edb8@%%@BO: 8551c@%%@BO: 85f9f@% Stack probes%@BO: e4df@% STACK statement%@BO: 12b53@% STACKSIZE statement%@BO: 10fe8@% Starting applications with Windows%@BO: 5ee16@% Statements CODE%@BO: 10443@% DATA%@BO: 1057f@% DESCRIPTION%@BO: 105dd@% EXETYPE WINDOWS%@BO: 11818@%%@BO: 1245f@% EXETYPE%@BO: 106b4@% EXPORTS%@BO: 1090d@%%@BO: 12363@% HEAPSIZE%@BO: 10a02@% IMPORTS%@BO: 10cba@%%@BO: 12b53@% LIBRARY%@BO: 10d94@%%@BO: 121cc@% NAME%@BO: 10e36@%%@BO: 11818@% SEGMENTS%@BO: 10ee4@% STACK%@BO: 12b53@% STACKSIZE%@BO: 10fe8@% STUB%@BO: 11150@% Static text control%@BO: 2d402@% Static variables%@BO: 5ffac@% STUB statement%@BO: 11150@% Styles dialog box%@BO: 312b9@% dialog-box control%@BO: 2f18c@% SWAP.EXE file%@BO: 9f50c@% Swap command line options%@BO: 9fcfe@% described%@BO: 9eeca@% output format%@BO: a08d5@%%@BO: a0dd2@% reducing processing time%@BO: a0582@% starting and stopping%@BO: 9f6bd@% .SYM files%@BO: 9f499@% Symbol files for assembly-language applications%@BO: 58c05@% for C-language applications%@BO: 5872e@% library%@BO: 5c8b9@%%@BO: 5c8ba@%%@BO: 5c8bb@% loading%@BO: 5c6e6@% naming%@BO: 5ca2f@%%@BO: 5db90@% setting up%@BO: 57720@% Symbol maps defined%@BO: 5d8da@% displaying symbols%@BO: 5e808@% listing%@BO: 5ddd1@% opening%@BO: 5dffd@%%@BO: 5e5db@% using symbols from%@BO: 5e67d@% Symbolic Debugger (SYMDEB) and IBM-compatible computers%@BO: 5bf81@% application development option for%@BO: e4df@% arguments address (list)%@BO: 65577@%%@BO: 66362@% command (list)%@BO: 62ce9@%%@BO: 6448f@%%@BO: 64f19@% commands canceling current%@BO: 5d71a@% command options%@BO: 59ded@%%@BO: 5b2a3@%%@BO: 5c31d@% executing at startup%@BO: 5c31d@% list of%@BO: 60f40@%%@BO: 62ac5@% redirect input and output%@BO: 73023@% set source mode%@BO: 70bc1@% debugging terminal remote%@BO: 59210@% secondary%@BO: 59bc7@% described%@BO: 57275@% displaying application source statements%@BO: 6069c@% variables%@BO: 5ffac@% expressions (list)%@BO: 665df@% for Assembly-language applications%@BO: 58c05@% for C-language applications%@BO: 5872e@% loading macro definitions%@BO: 5b2a3@% messages fatal exit%@BO: 60d2e@% memory-allocation%@BO: 5f1e5@% option designator%@BO: 5c450@% option%@BO: 5a414@%%@BO: 5ab08@%%@BO: 5ba4a@% passing control to command.com%@BO: 733b5@% preparing symbol files for%@BO: 57720@% quitting%@BO: 60a35@% redirecting output from%@BO: 5a6e4@% returning control to DOS%@BO: 704d6@% setting breakpoints%@BO: 5fa48@% memory-allocation reporting level%@BO: 5b071@% special keys%@BO: 5d177@% specifying symbol files%@BO: 5c6e6@% starting applications%@BO: 5ee16@% starting%@BO: 59ca2@% suspending and restoring output%@BO: 5d36a@% symbol maps opening%@BO: 5e5db@% using symbols from%@BO: 5e67d@% working with%@BO: 5d8da@%%@BO: 5ddd1@%%@BO: 5dffd@% terminating%@BO: 704d6@% use of, with Windows%@BO: 59ded@%%@BO: 5a39a@%%@BO: 5ba4a@%%@BO: 5c8bb@%%@BO: 5cee3@%%@BO: 5d71a@% Symbolic Debugger(SYMDEB) debugging terminal secondary%@BO: 5975f@% Symbols declaring public%@BO: 58d23@% displaying%@BO: 5e808@% SYS REQ key%@BO: 5d4d8@% %@2@%%@AB@% T%@AE@%%@EH@%%@NL@% Tab stop, setting for dialog-box control%@BO: 308aa@% Task descriptor block%@BO: 6b878@%%@BO: 7b8cb@% Task queue, displaying information about%@BO: 6b6a7@%%@BO: 7b6ea@% Terminal remote, for debugging%@BO: 5929c@% secondary, for debugging%@BO: 5975f@% Terminating SYMDEB%@BO: 704d6@% Text editors creating applications%@BO: 8e6a@% creating resource script files%@BO: 18600@% Text, changing%@BO: 2f498@% Toolbox described%@BO: 2b461@% enabling%@BO: 2e053@% Tools %@AI@%see%@AE@% Help.%@NL@% compilers. See C Compiler; Resource Compiler%@BO: 7be6@% debugging tools. See CodeView for Windows ; Spy; Symbolic Debugger%@BO: 7be6@% linkers. See Linker%@BO: 7be6@% optimization tools. See Heap Walker; Profiler; Shaker; Swap%@BO: 7be6@% resource editors. See Dialog Editor; Font Editor; SDKPaint%@BO: 7be6@% Turning off stack probes%@BO: eab9@% %@2@%%@AB@% U%@AE@%%@EH@%%@NL@% Underscore (_), with commands%@BO: 64f19@% User library, symbol files%@BO: 5c8bb@% User-defined resource statement%@BO: 18971@% Utilities %@AI@%see%@AE@% Tools%@NL@% %@2@%%@AB@% V%@AE@%%@EH@%%@NL@% -V option%@BO: 1e677@% Variable-pitch fonts%@BO: 34e91@%%@BO: 37dcc@% Variables displaying%@BO: 5ffac@% static%@BO: 5ffac@% Vector fonts%@BO: 3412b@% Vertical bar (|), as document convention%@BO: a9f4@% Virtual breakpoint, defined%@BO: 68bec@% VPROD.386 device driver%@BO: 9d187@% %@2@%%@AB@% W%@AE@%%@EH@%%@NL@% Walking the heap%@BO: 942e4@% Width, font%@BO: 36814@%%@BO: 374f5@% Wildcard character (*), with SYMDEB commands%@BO: 64f19@%%@BO: 7225b@% Window, monitoring messages to%@BO: 91ef5@% Windows 386 enhanced mode applications using PROFILER with%@BO: 99128@%%@BO: 99500@%%@BO: 99c88@% Using PROFILER with%@BO: 9a6dc@% using PROFILER with%@BO: 9d187@% Windows 386 mode applications using PROFILER with%@BO: 9aed0@% Windows applications compiler option, example%@BO: d712@% creating%@BO: 8d63@% Windows enhanced mode applications using PROFILER with%@BO: 9c433@% Windows version stamp%@BO: 1a929@% Windows epilog%@BO: f19b@% fatal exit message%@BO: 60d2e@% import libraries%@BO: 12f54@% prolog%@BO: f19b@% WinMain function%@BO: 5fb2e@% Writing to logical records on disk%@BO: 7173b@% to named files%@BO: 7173b@% %@2@%%@AB@% X%@AE@%%@EH@%%@NL@% -X option%@BO: 1b75a@%%@BO: 1e3bf@%