Environment and Tools

Microsoft MASM

Assembly-Language Development System Version 6.1 For MS-DOS and Windows Operating Systems

Microsoft Corporation

Filename: LMAETTTL.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 4 Page: 1 of 1 Printed: 10/09/00 03:00 PM

Information in this document is subject to change without notice. Companies, names, and data used in examples herein are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation.
1992 Microsoft Corporation. All rights reserved.

Microsoft, MS, MS-DOS, XENIX, CodeView, and QuickC are registered trademarks and Windows and Windows NT are trademarks of Microsoft Corporation in the USA and other countries. U.S. Patent No. 4955066 IBM is a registered trademark of International Business Machines Corporation. Intel is a registered trademark of Intel Corporation. UNIX is a registered trademark of American Telephone and Telegraph Company. BRIEF is a registered trademark of SDC Software Partners II L.P. Printed in the United States of America.

Document No. DB35751-1292

Filename: LMAETCPY.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 4 Page: 2 of 1 Printed: 10/09/00 02:53 PM

Contents

iii

Contents Overview
Introduction
......................................................... xxi

Part 1 The Programmers WorkBench Chapter 1 Introducing the Programmers WorkBench . . . . . . . . . . . . . . . . . . . . 3 Chapter 2 Quick Start. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Chapter 3 Managing Multimodule Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Chapter 4 User Interface Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Chapter 5 Advanced PWB Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Chapter 6 Customizing PWB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Chapter 7 Programmers WorkBench Reference . . . . . . . . . . . . . . . . . . . . . . . 131 Part 2 The CodeView Debugger Chapter 8 Getting Started with CodeView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 9 The CodeView Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 10 Special Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 11 Using Expressions in CodeView . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 12 CodeView Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 319 351 375 393

Part 3 Compiling and Linking Chapter 13 Linking Object Files with LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 Chapter 14 Creating Module-Definition Files . . . . . . . . . . . . . . . . . . . . . . . . . . 491 Chapter 15 Using EXEHDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 Part 4 Utilities Chapter 16 Managing Projects with NMAKE . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 17 Managing Libraries with LIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 18 Creating Help Files with HELPMAKE . . . . . . . . . . . . . . . . . . . . . Chapter 19 Browser Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 20 Using Other Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 581 593 615 631

Part 5 Using Help Chapter 21 Using Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663 Appendixes Appendix A Appendix B Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 3 of 1 Printed: 10/09/00 02:54 PM

iv

Contents

Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 4 of 2 Printed: 10/09/00 02:54 PM

Contents

Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Scope and Organization of This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii Microsoft Support Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii Support Services Within the United States . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii Support Services Worldwide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii

Part 1 The Programmers WorkBench

Chapter 1 Introducing the Programmers WorkBench . . . . . . . . . . . . . . . . . . . . . . . Whats in Part 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conventions in the Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4 4 5

Chapter 2 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 The PWB Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 The Microsoft Advisor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Entering Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Saving a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Indenting Text with PWB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Opening an Existing File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Copying, Pasting, and Deleting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Single-Module Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Setting Build Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Setting Other Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Building the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Fixing Build Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Running the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Debugging the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Using CodeView to Isolate an Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Working Through a Program to Debug it . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Examining Memory in the Memory Window . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Where to Go from Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Chapter 3 Managing Multimodule Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Multimodule Program Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Opening the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 5 of 3 Printed: 10/09/00 02:54 PM

vi

Contents

Contents of a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dependencies in a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Multimodule Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Project Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Existing Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding and Deleting a Project File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Assembler and Linker Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Options for Individual Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Program Build Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Extending a PWB Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Non-PWB Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where to Go from Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 4 User Interface Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting PWB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . From the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Windows Operating System Program Manager. . . . . . . . . . . . . . . . Using the Windows Operating System File Manager . . . . . . . . . . . . . . . . . . . . The PWB Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executing Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Choosing Menu Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shortcut Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 5 Advanced PWB Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Searching with PWB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Searching by Visual Inspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Find Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

38 39 40 40 41 42 44 46 49 51 52 55 56 57 57 57 58 59 59 64 64 64 65 66 66 67 68 69 70 70 70 71 72 72 77 77 78 79 82

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 6 of 4 Printed: 10/09/00 02:54 PM

Contents

vii

Using the Source Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Advanced Browser Database Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Executing Functions and Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Executing Functions and Macros by Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Writing PWB Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 When Is a Macro Useful? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Recording Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Flow Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 User Input Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Chapter 6 Customizing PWB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Key Assignments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Colors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Commands to the Run Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How PWB Handles Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Autoloading Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TOOLS.INI File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOLS.INI Statement Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Current Status File CURRENT.STS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Project Status Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 7 Programmers WorkBench Reference . . . . . . . . . . . . . . . . . . . . . . . . . PWB Command Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Menus and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Default Key Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Note on Available Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cursor-Movement Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined PWB Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Switches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Extension Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filename-Parts Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Boolean Switch Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Browser Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 109 112 114 115 118 120 121 122 124 127 128 129 131 131 132 135 139 140 144 207 244 246 247 248 286 287

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 7 of 5 Printed: 10/09/00 02:54 PM

viii

Contents

Part 2 The CodeView Debugger

Chapter 8 Getting Started with CodeView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing Programs for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Programming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debugging Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Identifying the Bug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locating the Bug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting up CodeView. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CodeView Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring CodeView with TOOLS.INI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CodeView TOOLS.INI Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Management and CodeView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The CodeView Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Leaving CodeView. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command-Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The CURRENT.STS State File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 9 The CodeView Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The CodeView Display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Window Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Status Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CodeView Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Use CodeView Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Source Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Watch Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Command Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Local Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Register Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The 8087 Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Memory Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Help Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CodeView Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Edit Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Search Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Run Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Data Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Options Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 293 294 295 297 297 298 299 300 301 302 308 308 309 310 316 319 319 320 320 321 321 321 324 324 326 328 329 330 330 332 332 332 334 335 336 338 342

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 8 of 6 Printed: 10/09/00 02:54 PM

Contents

ix

The Calls Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 The Windows Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 The Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Chapter 10 Special Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debugging in the Windows Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparing CVW with CV. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing to Run CVW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting a Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CVW Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CVW Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debugging P-Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P-Code Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . P-Code Debugging Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remote Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remote Monitor Command-Line Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting a Remote Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 11 Using Expressions in CodeView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Line Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Address Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Choosing an Expression Evaluator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the C and C++ Expression Evaluators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unsupported Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restrictions and Special Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Context Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Numeric Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . String Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Symbol Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using C++ Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ambiguous References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors, Destructors, and Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . 351 351 351 352 353 357 360 363 364 365 365 367 367 368 370 371 375 375 376 377 378 379 380 381 381 381 382 382 384 385 385 386 386 386 386 387

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 9 of 7 Printed: 10/09/00 02:54 PM

Contents

Overloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operator Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debugging Assembly Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Register Indirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Register Indirection with Displacement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Address of a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PTR Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Array and Structure Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

388 388 389 389 390 391 391 391 392 392

Chapter 12 CodeView Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 CodeView Command Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 CodeView Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

Part 3 Compiling and Linking

Chapter 13 Linking Object Files with LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LINK Output Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LINK Syntax and Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The objfiles Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The exefile Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The mapfile Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The libraries Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The deffile Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Input with LINK Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Input in a Response File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LINK Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /ALIGN Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /BATCH Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /CO Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /CPARM Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /DOSSEG Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /DSALLOC Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /DYNAMIC Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 457 458 459 460 461 462 463 463 466 467 468 469 469 471 471 472 472 473 473 474 475 475

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 10 of 8 Printed: 10/09/00 02:54 PM

Contents

xi

The /EXEPACK Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /FARCALL Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /HELP Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /HIGH Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /INFO Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /LINE Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /MAP Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /NOD Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /NOE Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /NOFARCALL Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /NOGROUP Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /NOI Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /NOLOGO Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /NONULLS Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /NOPACKC Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /NOPACKF Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /OLDOVERLAY Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /ONERROR Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /OV Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /PACKC Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /PACKD Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /PACKF Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /PAUSE Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /PCODE Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /PM Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /Q Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /r Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /SEG Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /STACK Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /TINY Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /W Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The /? Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Options with the LINK Environment Variable . . . . . . . . . . . . . . . . . . . . Setting the LINK Environment Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Behavior of the LINK Environment Variable . . . . . . . . . . . . . . . . . . . . . . . . . Clearing the LINK Environment Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . .

475 476 477 477 477 478 478 479 479 479 480 480 480 480 481 481 481 481 482 482 483 484 484 485 485 485 486 486 487 487 488 488 488 488 489 489

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 11 of 9 Printed: 10/09/00 02:54 PM

xii

Contents

LINK Temporary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 LINK Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 Chapter 14 Creating Module-Definition Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MS-DOS Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Module Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The NAME Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The LIBRARY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The DESCRIPTION Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The STUB Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The APPLOADER Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The EXETYPE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The PROTMODE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The REALMODE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The STACKSIZE Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The HEAPSIZE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The CODE Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The DATA Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The SEGMENTS Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CODE, DATA, and SEGMENTS Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . The OLD Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The EXPORTS Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The IMPORTS Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The FUNCTIONS Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The INCLUDE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reserved Words. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 15 Using EXEHDR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running EXEHDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The EXEHDR Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXEHDR Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executable-File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXEHDR Output: MS-DOS Executable File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXEHDR Output: Segmented-Executable File . . . . . . . . . . . . . . . . . . . . . . . . . . . DLL Header Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Segment Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 491 491 492 492 492 493 494 495 496 496 497 498 498 499 500 500 500 501 501 502 503 505 505 506 508 510 510 513 513 513 514 515 516 518 519 520

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 12 of 10 Printed: 10/09/00 02:54 PM

Contents

xiii

Exports Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXEHDR Output: Verbose Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MS-DOS Header Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . New .EXE Header Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Relocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

520 521 521 521 523 523

Part 4 Utilities
Chapter 16 Managing Projects with NMAKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running NMAKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command-Line Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NMAKE Command File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TOOLS.INI File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Contents of a Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Special Characters as Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Long Filenames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Description Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dependency Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Targets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dependents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exit Codes from Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filename-Parts Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inline Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User-Defined Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Special Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Substitution Within Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Substitution Within Predefined Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Environment-Variable Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inherited Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Precedence Among Macro Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 527 528 529 529 533 534 535 535 536 536 537 537 538 538 542 543 543 544 545 546 547 550 551 554 554 560 561 561 563 563

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 13 of 11 Printed: 10/09/00 02:54 PM

xiv

Contents

Inference Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inference Rule Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inference Rule Search Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User-Defined Inference Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined Inference Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inferred Dependents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Precedence Among Inference Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Directives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dot Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preprocessing Directives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sequence of NMAKE Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A Sample NMAKE Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NMAKE Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 17 Managing Libraries with LIB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running LIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The LIB Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LIB Command Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The LIB Response File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying LIB Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Library File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LIB Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LIB Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Cross-reference Listing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Output Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LIB Exit Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 18 Creating Help Files with HELPMAKE . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running HELPMAKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Elements of a Help Source File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining a Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Links to Other Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formatting Topic Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

563 564 565 566 567 569 570 570 570 572 576 578 580 581 581 582 582 582 583 583 584 584 586 590 590 591 592 593 594 595 595 597 598 599 599 600 600 601 604

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 14 of 12 Printed: 10/09/00 02:54 PM

Contents

xv

Dot and Colon Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other Help Text Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rich Text Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Minimally Formatted ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Context Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 19 Browser Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Database Building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing to Build a Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How BSCMAKE Builds a Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods for Increasing Efficiency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BSCMAKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Requirements for BSCMAKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The BSCMAKE Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BSCMAKE Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Response File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BSCMAKE Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SBRPACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of SBRPACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The SBRPACK Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SBRPACK Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CREF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using CREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Difference from Previous Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 20 Using Other Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CVPACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of CVPACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The CVPACK Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CVPACK Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H2INC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic H2INC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H2INC Syntax and Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Converting Data and Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Converting Function Prototypes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary of H2INC-Recognized Keywords and Pragmas. . . . . . . . . . . . . . IMPLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Import Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The IMPLIB Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RM, UNDEL, and EXP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

605 609 609 612 613 615 616 616 616 617 618 618 619 620 622 623 623 624 624 626 626 626 629 631 631 632 632 633 633 634 635 638 648 651 652 652 653 653 654

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 15 of 13 Printed: 10/09/00 02:54 PM

xvi

Contents

Overview of the Backup Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The RM Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The UNDEL Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The EXP Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WX/WXServer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running WX/WXServer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

654 654 655 656 657 657

Part 5 Using Help

Chapter 21 Using Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of the Microsoft Advisor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Navigating Through the Microsoft Advisor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Mouse and the F1 Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Hyperlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Help Windows and Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Different Types of Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Different Help Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Help in PWB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening a Help File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using QuickHelp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the /Help Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the QH Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Help Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Many Help Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663 663 664 665 666 666 667 669 672 673 673 674 675 676 676 679 680

Appendixes
Appendix A Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error Message Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BSCMAKE Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CodeView C/C++ Expression Evaluator Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . CodeView Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CVPACK Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXEHDR Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Math Coprocessor Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H2INC Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HELPMAKE Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IMPLIB Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 685 688 692 700 716 720 722 724 761 767

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 16 of 14 Printed: 10/09/00 02:54 PM

Contents

xvii

LIB Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LINK Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ML Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NMAKE Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SBRPACK Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix B Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regular-Expression Summaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UNIX Regular-Expression Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tagged Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tagged Expressions in Build:Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Justifying Tagged Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non-UNIX Regular-Expression Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non-UNIX Matching Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

769 775 798 828 840 842 845 845 848 850 852 852 853 854 855

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 17 of 15 Printed: 10/09/00 02:54 PM

xviii

Contents

Figures and Tables

Figures Figure 2.1 Figure 0.1 Figure 0.2 Figure 0.3 Figure 0.4 Figure 0.5 Figure 0.6 Figure 0.7 Figure 0.8 Figure 0.9 Figure 0.10 Figure 0.11 Figure 0.12 Figure 0.13 Figure 0.14 Figure 0.15 Figure 0.16 Figure 0.17 Figure 0.18 Tables Table 0.1 Table 0.2 Table 0.3 Table 0.4 Table 0.5 Table 0.6 Table 0.7 Table 0.8 Table 0.9 Table 0.10 Table 0.11 Table 0.12 Table 0.13 Table 0.14 PWB Display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 The SHOW Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 The PWB Build Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 User Interface Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Window Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Status Bar Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 PWB Menu Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Dialog Box Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Key Box and Check Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Regular Expression Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Complex Regular Expression Example . . . . . . . . . . . . . . . . . . . . . . . 84 How PWB Displays Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Arranged Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Vertical Tiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 Horizontal Tiling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 CodeView Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 Format for a Segmented-Executable File . . . . . . . . . . . . . . . . . . . . 516 NMAKE Description Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 Microsoft Advisor Global Contents Screen. . . . . . . . . . . . . . . . . . 664 File Menu and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Edit Menu and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search Menu and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Project Menu and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Run Menu and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Browse Menu and Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Window Menu and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help Menu and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Default Key Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cursor-Movement Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Color Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PWB Color Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 133 133 134 134 134 135 135 136 140 145 208 252 254

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 18 of 16 Printed: 10/09/00 02:54 PM

Contents

xix

Table 0.1 Table 0.2 Table 0.1 Table 0.1 Table 0.1 Table 0.2 Table 0.1 Table 0.1 Table 0.2 Table 0.2 Table 0.3 Table 0.4 Table 0.5 Table 0.6 Table A.1 Table A.2 Table .1 Table .2 Table .3 Table .4 Table .5 Table .6 Table .7 Table .8

CodeView TOOLS.INI Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CodeView Command-Line Options . . . . . . . . . . . . . . . . . . . . . . . . . Moving Around with the Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Register Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CodeView Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . Module Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined Inference Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Binary Operators for Preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . Formatting Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dot and Colon Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RTF Formatting Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Microsoft Product Context Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . Standard h. Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error Codes Listed by Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error Codes Listed by Error Code Range . . . . . . . . . . . . . . . . . . . . UNIX Regular-Expression Summary. . . . . . . . . . . . . . . . . . . . . . . . . UNIX Predefined Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CodeView Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non-UNIX Regular-Expression Summary . . . . . . . . . . . . . . . . . . . . Non-UNIX Predefined Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . UNIX Regular-Expression Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined Regular Expressions and Definitions . . . . . . . . . . . . . . . Non-UNIX Regular Expression Syntax. . . . . . . . . . . . . . . . . . . . . . .

302 310 323 377 395 398 493 567 574 605 606 610 613 614 686 687 845 846 847 847 848 848 853 854

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 19 of 17 Printed: 10/09/00 02:54 PM

Contents

xx

Filename: LMAETTOC.DOC Project: Template: FRONTA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 20 of 18 Printed: 10/09/00 02:54 PM

xxi

Introduction

Microsoft Macro Assembler (MASM) includes a full set of development tools editor, compiler, linker, debugger, and browser for writing, compiling, and debugging your programs. You can work within the Microsoft Programmers WorkBench (PWB) integrated environment, or you can use the tools separately to develop your programs. Environment and Tools describes the following development tools:
u

The Programmers WorkBench (PWB). PWB is a comprehensive tool for application development. Within its environment is everything you need to create, build, browse, and debug your programs. Its macro language gives you control over not only editing but also build operations and other PWB functions. The Microsoft CodeView debugger. This is a diagnostic tool for finding errors in your programs. Two versions of CodeView are described: one for MS-DOS and one for Microsoft Windows . Each CodeView version has specialized commands for its operating environment, as well as other commands for examining code and data, setting breakpoints, and controlling your programs execution. LINK, the Microsoft Segmented-Executable Linker. The linker combines object files and libraries into an executable file, either an application or a dynamic-link library (DLL). EXEHDR, the Microsoft EXE File Header Utility. EXEHDR displays and modifies the contents of an executable-file header. NMAKE, the Microsoft Program Maintenance Utility. NMAKE simplifies project maintenance. Once you specify which project files depend on others, you can use NMAKE to automatically execute the commands that will update your project when any file has changed. LIB, the Microsoft Library Manager. LIB creates and maintains standard libraries. With LIB, you can create a library file and add, delete, and replace modules.

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 21 of 1 Printed: 10/09/00 02:57 PM

xxii

Environment and Tools

u

HELPMAKE, the Microsoft Help File Maintenance Utility. HELPMAKE creates and maintains Help files. You can use HELPMAKE to create a Help file or to customize the Microsoft Help files. BSCMAKE, the Microsoft Browser Database Maintenance Utility, and SBRPACK, the Microsoft Browse Information Compactor. BSCMAKE creates browser files for use with the PWB Source Browser. SBRPACK compresses the files that are used by BSCMAKE.

Environment and Tools also describes these special-purpose utilities:

u

H2INC, the Microsoft C Header Translation Utility. H2INC translates C header files into MASM-compatible include files. CVPACK, the Microsoft Debugging Information Compactor. CVPACK compresses the size of debugging information in an executable file. IMPLIB, the Microsoft Import Library Manager. IMPLIB creates an import library that resolves external references from a Windows-based application to a DLL. RM, the Microsoft File Removal Utility; UNDEL, the Microsoft File Undelete Utility; and EXP, the Microsoft File Expunge Utility. These utilities manage, delete, and recover backup files.

Scope and Organization of This Book

This book has five parts and five appendixes to give you complete information about PWB, CodeView, and the utilities included with MASM. Part 1 is a brief PWB tutorial and comprehensive reference. The first three chapters introduce PWB and provide a tutorial that describes the features of the integrated environment and how to use them. Chapters 4, 5, and 6 contain detailed information on the interface, advanced PWB techniques, and customization. Chapter 7 contains a complete reference to PWBs default keys and all functions, predefined macros, and switches. Part 2 provides full information on the Microsoft CodeView debugger. Chapter 8 tells how to prepare programs for debugging, how to start CodeView, and how to customize CodeViews interface and memory usage. Chapter 9 describes the environment, including the CodeView menu commands and the format and use of each CodeView window. Chapter 10 explains how to use expressions, including the C and C++ expression evaluators. Chapter 11 describes techniques for debugging Windows-based programs. Chapter 12 contains a complete reference to CodeView commands. The chapters in Parts 3 and 4 describe the utilities. These chapters are principally for command-line users. Even if youre using PWB, however, you may find the detailed information in Parts 3 and 4 helpful for a better

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 22 of 2 Printed: 10/09/00 02:57 PM

Introduction

xxiii

understanding of how each tool contributes to the program development process. Part 3 provides information about compiling and linking your program. LINK command-line syntax and options are covered in Chapter 13. The contents and use of module-definition files are explained in Chapter 14. Chapter 15 describes how to use EXEHDR to examine the file header of a program. Part 4 presents the other utilities. NMAKE, the utility for automating project management, is described in Chapter 16. Chapter 17 covers LIB, used in managing standard libraries. Procedures for using HELPMAKE to create and maintain Help files are in Chapter 18. The tools for creating a browser database are discussed in Chapter 19. Finally, Chapter 20 describes how to use the following special-purpose utilities: H2INC, CVPACK, IMPLIB, RM, UNDEL, and EXP. Part 5 presents the Microsoft Advisor Help system and the QuickHelp program. It describes the structure of the Help files, how to navigate through the Help system, and how to manage Help files. The appendixes provide supplementary information. Appendix A describes error messages. Appendix B describes regular expressions for use in PWB and CodeView.

Microsoft Support Services

Microsoft offers a variety of no-charge and fee-based support options to help you get the most from your Microsoft product. For an explanation of these options, please see one of the following sections:
u

If you are in the United States, see Support Services Within the United States. If you are outside the United States, see Support Services Worldwide.

Support Services Within the United States

If you have a question about Microsoft Macro Assembler (MASM), one of the following resources may help you find an answer:
u

The index in the product documentation and other printed product documentation. Context-sensitive online Help available from the Help menu.

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 23 of 3 Printed: 10/09/00 02:57 PM

xxiv

Environment and Tools

u

The README files that come with your product disks. These files provide general information that became available after the books in the product package were published. Electronic options such as CompuServe forums or bulletin board systems, if available.

If you cannot find the information you need, you can obtain product support through several methods. In addition, you can locate training and consultation services in your area. For information about Microsoft incremental fee-based support service options, call Microsoft Inside Sales at (800) 227-4679, Monday through Friday, between 6:30 a.m. and 5:30 p.m. Pacific time. Note Microsofts support services are subject to Microsofts prices, terms, and conditions in place in each country at the time the services are used.

Microsoft Forums on CompuServe

Microsoft Product Support Services are available on several CompuServe forums. For an introductory CompuServe membership kit specifically for Microsoft users, dial (800) 848-8199 and ask for operator 230. If you are already a CompuServe member, type go microsoft at any ! prompt.

Microsoft Product Support Services

You can reach Microsoft Product Support Services Monday through Friday between 6:00 a.m. and 6:00 p.m. Pacific time.
u

For assistance with Microsoft MASM, dial (206) 646-5109.

When you call, you should be at your computer with Microsoft MASM running and the product documentation at hand. Have your file open and be prepared to give the following information:
u u

u u u

The version of Microsoft MASM you are using. The type of hardware you are using, including network hardware, if applicable. The operating system you are using. The exact wording of any messages that appeared on your screen. A description of what happened and what you were trying to do when the problem occurred. A description of how you tried to solve the problem.

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 24 of 4 Printed: 10/09/00 02:57 PM

Introduction

xxv

Microsoft Product Support for the Deaf and Hard-of-Hearing

Microsoft Product Support Services are available for the deaf and hard-ofhearing Monday through Friday between 6:00 a.m. and 6:00 p.m. Pacific time. Using a special TDD/TT modem, dial (206) 635-4948.

Product Training and Consultation Services

Within the United States, Microsoft offers the following services for training and consultation:

Authorized Training Centers

Microsoft Authorized Training Centers offer several services for Microsoft product users. These include:
u u u

Customized training for users and trainers. Training material development. Consulting services.

For information about the training center nearest you, call Microsoft Consumer Sales at (800) 426-9400 Monday through Friday between 6:30 a.m. and 5:30 p.m. Pacific time.

Consultant Referral Service

Microsofts Consultant Relations Program can refer you to an independent consultant in your area. These consultants are skilled in:
u u u

Macro development and translation. Database development. Custom interface design.

For information about the consultants in your area, call the Microsoft Consultant Relations Program at (800) 227-4679, extension 56042, Monday through Friday between 6:30 a.m. and 5:30 p.m. Pacific time.

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 25 of 5 Printed: 10/09/00 02:57 PM

xxvi

Environment and Tools

Support Services Worldwide

If you are outside the United States and have a question about Microsoft MASM, Microsoft offers a variety of no-charge and fee-based support options. To solve your problem, you can:
u

Consult the index in the product documentation and other printed product documentation. Check context-sensitive online Help available from the Help menu. Check the README files that come with your product disks. These files provide general information that became available after the books in the product package were published. Consult electronic options such as CompuServe forums or bulletin board systems, if available.

u u

If you cannot find a solution, you can receive information on how to obtain product support by contacting the Microsoft subsidiary office that serves your country. Note Microsofts support services are subject to Microsofts prices, terms, and conditions in place in each country at the time the services are used.

Calling a Microsoft Subsidiary Office

When you call, you should be at your computer with Microsoft MASM running and the product documentation at hand. Have your file open and be prepared to give the following information:
u u

u u u

The version of Microsoft MASM you are using. The type of hardware you are using, including network hardware, if applicable. The operating system you are using. The exact wording of any messages that appeared on your screen. A description of what happened and what you were trying to do when the problem occurred. A description of how you tried to solve the problem.

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 26 of 6 Printed: 10/09/00 02:57 PM

Introduction

xxvii

Microsoft subsidiary offices and the countries they serve are listed below.
Area Argentina Telephone Numbers Microsoft de Argentina S.A. Phone: (54) (1) 814-0356 Fax: (54) (1) 814-0372 Microsoft Pty. Ltd. Phone: (61) (02) 870-2200 Fax: (02) 805-1108 Bulletin Board Service: (612) 870-2348 Technical Support: (61) (02) 870-2131 Sales Information Centre: (02) 870-2100 Microsoft Ges.m.b.H. Phone: 0222 - 68 76 07 Fax: 0222 - 68 16 2710 Information: 060 - 89 - 247 11 101 Prices, updates, etc.: 060 - 89 - 3176 1199 CompuServe: msce (Microsoft Central Europe) Technical support: Windows, Windows for Workgroups, Microsoft Mail: 0660 - 65 - 10 Microsoft Excel for Windows, Microsoft Excel for OS/2, PowerPoint for Windows: 0660 - 65 - 11 Word for MS-DOS, Windows Write: 0660 65 - 12 Word for Windows, Word for OS/2: 0660 - 65 - 13 Works for MS-DOS, Works for Windows, Publisher, WorksCalc, WorksText: 0660 - 65 - 14 C PDS, FORTRAN PDS, Pascal, Macro Assembler PDS, QuickC, QuickC for Windows, QuickPascal, QuickAssembler, Profiler: 0660 - 65 - 15 COBOL PDS, Basic PDS, QuickBASIC, Visual Basic: 0660 - 65 - 16 MS-DOS: 0660 - 65 - 17 Macintosh Software: 0660 - 65 - 18 Project for Windows, Project for MS-DOS, Multiplan, Mouse, Flight Simulator, Paintbrush, Chart: 0660 - 67 - 38 FoxPro: 0660 - 67 - 61 See Germany Microsoft NV Phone: 02-7322590 Fax: 02-7351609 Technical Support Bulletin Board Service: 02-7350045 (1200/2400/9600 baud, 8 bits, no parity, 1 stop bit, ANSI terminal emulation) (Dutch speaking) Technical Support: 02-5133274 (English speaking) Technical Support: 02-5023432 (French speaking) Technical Support: 02-5132268 Technical Support Fax: (31) 2503-24304 See Venezuela See Argentina

Australia

Austria

Baltic States Belgium

Bermuda Bolivia

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 27 of 7 Printed: 10/09/00 02:57 PM

xxviii Area Brazil

Environment and Tools Telephone Numbers Microsoft Informatica Ltda. Phone: (55) (11) 530-4455 Fax: (55) (11) 240-2205 Technical Support Phone: (55) (11) 533-2922 Technical Support Fax: (55) (11) 241-1157 Technical Support Bulletin Board Service: (55) (11) 543-9257 Microsoft Canada Inc. Phone: 1 (416) 568-0434 Fax: 1 (416) 568-4689 Technical Support Phone: 1 (416) 568-3503 Technical Support Facsimile: 1 (416) 568-4689 Technical Support Bulletin Board Service: 1 (416) 507-3022 See Venezuela See Venezuela See Argentina See Venezuela Microsoft Denmark AS Phone: (45) (44) 89 01 00 Fax: (45) (44) 68 55 10 See Venezuela Microsoft Limited Phone: (44) (734) 270000 Fax: (44) (734) 270002 Upgrades: (44) (81) 893-8000 Technical Support: Main Line (All Products): (44) (734) 271000 Windows Direct Support Line: (44) (734) 271001 Database Direct Support Line: (44) (734) 271126 MS-DOS 5 Warranty Support: (44) (734) 271900 MS-DOS 5 Fee Support Line: (44) (891) 315500 OnLine Service Assistance: (44) (734) 270374 Bulletin Board Service: (44) (734) 270065 (2400 Baud) Fax Information Service: (44) (734) 270080 Microsoft OY Phone: (358) (0) 525 501 Fax: (358) (0) 522 955 Microsoft France Phone: (33) (1) 69-86-46-46 Telex: MSPARIS 604322F Fax: (33) (1) 64-46-06-60 Technical Support Phone: (33) (1) 69-86-10-20 Technical Support Fax: (33) (1) 69-28-00-28

Canada

Caribbean Countries Central America Chile Colombia Denmark

Ecuador England

Finland

France

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 28 of 8 Printed: 10/09/00 02:57 PM

Introduction Area French Polynesia Germany Telephone Numbers See France Microsoft GmbH Phone: 089 - 3176-0 Telex: (17) 89 83 28 MS GMBH D Fax: 089 - 3176-1000 Information: 0130 - 5099 Prices, updates, etc.: 089 - 3176 1199 Bulletin board, device drivers, tech notes : BTX: microsoft# or *610808000# CompuServe: msce (Microsoft Central Europe) Technical support: Windows, Windows for Workgroups, Microsoft Mail: 089 - 3176 - 1110 Microsoft Excel for Windows, Microsoft Excel for OS/2, PowerPoint for Windows: 089 - 3176 - 1120 Word for MS-DOS, Windows Write: 089 - 3176 - 1130 Word for Windows, Word for OS/2: 089 - 3176 - 1131 Works for MS-DOS, Works for Windows, Publisher, WorksCalc, WorksText: 089 - 3176 - 1140 C PDS, FORTRAN PDS, Pascal, Macro Assembler PDS, QuickC, QuickC for Windows, QuickPascal, QuickAssembler, Profiler: 089 - 3176 - 1150 COBOL PDS, Basic PDS, QuickBASIC, Visual Basic: 089 - 3176 - 1151 MS-DOS: 089 - 3176 - 1152 Macintosh Software: 089 - 3176 - 1160 Project for Windows, Project for MS-DOS, Multiplan, Mouse, Flight Simulator, Paintbrush, Chart: 089 - 3176 - 1170 FoxPro: 089 - 3176 - 1180 Microsoft Hong Kong Limited Technical Support: (852) 804-4222 See England Microsoft Israel Ltd. Phone: 972-3-752-7915 Fax: 972-3-752-7919 Microsoft SpA Phone: (39) (2) 269121 Telex: 340321 I Fax: (39) (2) 21072020 Technical Support: Microsoft Excel for Windows, Project for Windows, Works for Windows: (39) (2) 26901361 Word, Works for MS-DOS: (39) (2) 26901362 Windows, PowerPoint, Publisher, Windows for Workgroups, Works : (39) (2) 26901363 Basic, COBOL, Visual Basic, MS-DOS-based, Fox Products: (39) (2) 26901364 C, FORTRAN, Pascal, Macro Assembler (MASM), and SDKs: (39) (2) 26901354 LAN Manager, SQL Server, Microsoft Mail, Microsoft Mail Gateways: (39) (2) 26901356

xxix

Hong Kong Ireland Israel

Italy

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 29 of 9 Printed: 10/09/00 02:57 PM

xxx Area Japan

Environment and Tools Telephone Numbers Microsoft Company Ltd. Phone: (81) (3) 3363-1200 Fax: (81) (3) 3363-1281 Technical Support: MS-DOS-based Applications: (81) (3) 3363-0160 Windows-based Applications: (81) (3) 3363-5040 Language Products (Microsoft C, Macro Assembler [MASM], QuickC): (81) (3) 3363-7610 Language Products (Basic, FORTRAN, Visual Basic, Quick Basic): (81) (3) 3363-0170 All Products Technical Support Fax: (81) (3) 3363-9901 Microsoft CH Phone: (82) (2) 552-9505 Fax: (82) (2) 555-1724 Technical Support: (82) (2) 563-9230 See Switzerland (German speaking) Microsoft NV Phone: (32) 2-7322590 Fax: (32) 2-7351609 Technical Support Bulletin Board Service: (31) 2503-34221 (1200/2400/9600 baud, 8 bits, No parity, 1 stop bit, ANSI terminal emulation) (Dutch speaking) Technical Support: (31) 2503-77877 (English speaking) Technical Support: (31) 2503-77853 (French speaking) Technical Support: (32) 2-5132268 Technical Support Fax: (31) 2503-24304 Microsoft Mxico, S.A. de C.V. Phone: (52) (5) 325-0910 Fax: (52) (5) 280-0198 Technical Support: (52) (5) 325-0912 Sales: (52) (5) 325-0911 Microsoft BV Phone: 02503-13181 Fax: 02503-37761 Technical Support Bulletin Board Service: 02503-34221 (1200/2400/9600 baud, 8 bits, No parity, 1 stop bit, ANSI terminal emulation) (Dutch speaking) Technical Support: 02503-77877 (English speaking) Technical Support: 02503-77853 Technical Support Fax: 02503-24304 Technology Link Centre Phone: 64 (9) 358-3724 Fax: 64 (9) 358-3726 Technical Support Applications: 64 (9) 357-5575 See England

Korea

Liechtenstein Luxemburg

Mxico

Netherlands

New Zealand

Northern Ireland

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 30 of 10 Printed: 10/09/00 02:57 PM

Introduction Area Norway Telephone Numbers Microsoft Norway AS Phone: (47) (2) 95 06 65 Fax: (47) (2) 95 06 64 Technical Support: (47) (2) 18 35 00 See Australia See Argentina See Venezuela MSFT, Lda. Phone: (351) 1 4412205 Fax: (351) 1 4412101 See Venezuela Microsoft Taiwan Corp. Phone: (886) (2) 504-3122 Fax: (886) (2) 504-3121 See England See England Microsoft Iberica SRL Phone: (34) (1) 804-0000 Fax: (34) (1) 803-8310 Technical Support: (34) (1) 803-9960 Microsoft AB Phone: (46) (8) 752 56 00 Fax: (46) (8) 750 51 58 Technical Support: Applications: (46) (8) 752 68 50 Development and Network products: (46) (8) 752 60 50 MS-DOS: (46) (071) 21 05 15 (SEK 4.55/min) Sales Support: (46) (8) 752 56 30 Bulletin Board Service: (46) (8) 750 47 42 Fax Information Service: (46) (8) 752 29 00

xxxi

Papua New Guinea Paraguay Peru Portugal

Puerto Rico Republic of China

Republic of Ireland Scotland Spain

Sweden

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 31 of 11 Printed: 10/09/00 02:57 PM

xxxii Area Switzerland

Environment and Tools Telephone Numbers (German speaking) Microsoft AG Phone: 01 - 839 61 11 Fax: 01 - 831 08 69 Infomation: 0049 - 89 - 247 11 101 Prices, updates, etc.: 0049 - 89 - 3176 1199 CompuServe: msce (Microsoft Central Europe) Technical support: Windows, Windows for Workgroups, Microsoft Mail: 01 - 342 - 4085 Microsoft Excel for Windows, Microsoft Excel for OS/2, PowerPoint for Windows: 01 - 342 - 4082 Word for MS-DOS, Windows Write: 01 - 342 - 4083 Word for Windows, Word for OS/2: 01 - 342 - 4087 Works for MS-DOS, Works for Windows, Publisher, WorksCalc, WorksText: 01 - 342 - 4084 C PDS, FORTRAN PDS, Pascal, Macro Assembler PDS, QuickC, QuickC for Windows, QuickPascal, QuickAssembler, Profiler: 01 - 342 - 4036 COBOL PDS, Basic PDS, QuickBASIC, Visual Basic: 01 - 342 - 4086 MS-DOS: 01 - 342 - 2152 Macintosh Software: 01 - 342 - 4081 Project for Windows, Project for MS-DOS, Multiplan, Mouse, Flight Simulator, Paintbrush, Chart : 01 - 342 - 0322 FoxPro: 01 / 342 - 4121 (French speaking) Microsoft SA, office Nyon Phone: 022 - 363 68 11 Fax: 022 - 363 69 11 Technical support: 022 - 738 96 88

Uruguay Venezuela

See Argentina Corporation MS 90 de Venezuela S.A. Phone: 0058.2.914739 Fax: 0058.2.923835 See England Phone: 0058.2.914739 Fax: 0058.2.923835

Wales Venezuela

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 32 of 12 Printed: 10/09/00 02:57 PM

Introduction

xxxiii

Document Conventions
This book uses the following typographic conventions:
Examples README.TXT, COPY, LINK, /CO Description Uppercase (capital) letters indicate filenames, MS-DOS commands, and the commands to run the tools. Uppercase is also used for command-line options, unless the option must be lowercase. Bold letters indicate keywords, library functions, reserved words, and CodeView commands. Keywords are required unless enclosed in double brackets as explained below. Words in italic are placeholders for information that you must supply (for example, a function argument). Items inside double square brackets are optional. Braces and a vertical bar indicate a choice between two or more items. You must choose one of the items unless all the items are also enclosed in double square brackets. This font is used for program examples, user input, program output, and error messages within the text. Three horizontal dots following an item indicate that more items having the same form may follow. Three vertical dots following a line of code indicate that part of the example program has intentionally been omitted.

printf, IMPORT

expression [[option]] {choice1 | choice2}

CL ONE.C TWO.C

Repeating elements...
while( ) { . . . }

F1, ALT+A

Small capital letters indicate the names of keys and key sequences, such as ENTER and CTRL+C. A plus (+) indicates a combination of keys. For example, CTRL+E means to hold down the CTRL key while pressing the E key. The cursor-movement keys on the numeric keypad are called ARROW keys. Individual ARROW keys are referred to by the direction of the arrow on the top of the key (LEFT, RIGHT , UP, DOWN). Other keys are referred to by the name on the top of the key (PGUP , PGDN).

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 33 of 13 Printed: 10/09/00 02:57 PM

xxxiv

Environment and Tools Examples Arg Meta Delete (ALT+A ALT+A SHIFT+DEL) Description A bold series of names followed by a series of keys indicates a sequence of PWB functions that you can use in a macro definition, type in a dialog box, or execute directly by pressing the sequence of keys. In this book, these keys are the default keys for the corresponding functions. Some functions are not assigned to a key, and the word Unassigned appears in the place of a key. In PWB Help, the current key that is assigned to the function is shown. Quotation marks usually indicate a new term defined in the text. Acronyms are usually spelled out the first time they are used.

defined term dynamic-link library (DLL)

Filename: LMAETINT.DOC Project: Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 19 Page: 34 of 14 Printed: 10/09/00 02:57 PM

P A R T

The Programmers WorkBench

Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 Chapter 6 Chapter 7 Introducing the Programmers WorkBench . . . . . . . . . . . . . . . . . . . . 3 Quick Start. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Managing Multimodule Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 User Interface Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Advanced PWB Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Customizing PWB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Programmers WorkBench Reference . . . . . . . . . . . . . . . . . . . . . . . 131

Filename: LMAETP01.DOC Project: Part opening 1 Template: MSGRIDA1.DOT Author: Terri Sharkey Last Saved By: Mike Eddy Revision #: 9 Page: 1 of 1 Printed: 10/09/00 02:56 PM

Filename: LMAETP01.DOC Project: Part opening 1 Template: MSGRIDA1.DOT Author: Terri Sharkey Last Saved By: Mike Eddy Revision #: 9 Page: 2 of 2 Printed: 10/09/00 02:56 PM

C H A P T E R

Introducing the Programmers WorkBench

The Microsoft Programmers WorkBench (PWB) is a powerful tool for application development. PWB combines the following features:
u u

A full-featured programmers text editor. An extensible build engine which allows you to assemble and link your programs using the PWB environment. The build engine can be extended to support any programming tool. Error-message browsing. Once a build completes, you can step through the build messages, fixing errors in your source programs. A Source Browser. When working with large systems, it is often difficult to remember where program symbols are accessed and defined. The Source Browser maintains a database that allows you to go quickly to where a given variable, function, type, class, or macro is defined or referenced. An extensible Help system. The Microsoft Advisor Help system provides a complete reference on using PWB and MASM. You can also write new Help files and seamlessly integrate them into the Help system to document your own library routines or naming conventions. A macro language that can control editing functions, program builds, and other PWB operations.

For increased flexibility, you can write extensions to PWB. These extensions can perform tasks that are inconvenient in the PWB macro language. For example, you can write extensions to perform file translations, source-code formatting, text justification, and so on. As with the macro language, PWB extensions have full access to most PWB capabilities. For information about how to write PWB extensions, see the Microsoft Advisor Help system (choose PWB Extensions from the main Help table of contents). PWB comes with extensions for C/C++, Basic, and Fortran, in addition to assembly language, to facilitate mixed-language programming. To install one of

Filename: LMAETC01.DOC Template: MSGRIDA1.DOT Revision #: 47 Page: 3 of 1

Project: Environment and Tools Author: Cris Morris Last Saved By: Mike Eddy Printed: 10/09/00 02:48 PM

Environment and Tools

these extensions, simply rename its corresponding .XXT file to a .MXT file in the \BIN subdirectory where you installed MASM, as described in Getting Started. Also, because an increasing number of programmers are using C++, the PWB Browser extension supports classes.

Whats in Part 1
This part of the book introduces you to the fundamentals of PWB. Chapter 2, Quick Start, shows you how to use the PWB editor and build a simple singlemodule program from PWB. Chapter 3, Managing Multimodule Programs, expands upon the information you learned in Chapter 2. It teaches you how to build a more complicated program that consists of several modules. You should be able to work through these two chapters in less than three hours. As you work through these chapters, you may want to refer to Chapter 4, User Interface Details, which explains options for starting PWB, briefly describes all of the menu commands, and summarizes how menus and dialog boxes work. The user interface information is presented in one chapter for easy access. Chapter 5, Advanced PWB Techniques, shows how to use the PWB search facilities (including searching with regular expressions), how to use the Source Browser, how to execute functions and macros, and how to write PWB macros. Chapter 6, Customizing PWB, describes how to redefine key assignments, change PWB settings, add commands to the PWB menu, and use the TOOLS.INI initialization file to store startup and configuration information for PWB. Chapter 7, PWB Reference, contains an alphabetical reference to PWB menus, keys, functions, predefined macros, and switches. It contains the essential information you need to know to take the greatest advantage of PWBs richly customizable environment.

Using the Tutorial

You probably want to get right to work with MASM. The tutorial chapters 2 and 3 can help you become productive very quickly. To get the most out of this material, here are a few recommendations:
u

Follow the steps presented in the tutorial. It is always tempting to explore the system and find out more about the product through independent research. However, just as programming requires an orderly sequence of steps, some aspects of PWB also require sequenced actions.

Filename: LMAETC01.DOC Template: MSGRIDA1.DOT Revision #: 47 Page: 4 of 2

Project: Environment and Tools Author: Cris Morris Last Saved By : Mike Eddy Printed: 10/09/00 02:48 PM

Chapter 1 Introducing the Programmers Workbench

u

If you complete a step and something seems wrongfor example, if your screen doesnt match what is in the bookback up and try to find out whats wrong. Troubleshooting tips will help you take corrective actions. When working through this tutorial, consider how you might use these techniques in your own work. PWB is like a full tool chest. You probably wont learn (or even want to learn) all of PWBs capabilities right away. But as time goes on, youll have uses for many of the tools you dont use immediately.

Conventions in the Tutorial

Procedures described in the course of the tutorial are introduced with headings designated by a triangular symbol. A list of the steps making up the procedure then follows. For example: To open a file: 1. From the File menu, choose Open. PWB displays the Open File dialog box. 2. In the File List list box, select the file that you want to open. 3. Choose OK. In procedures, the heading gives you a capsule summary of what the steps will accomplish. Each numbered step is an action you take to complete the procedure. Some steps are followed by an explanation, an illustration, or both.

Filename: LMAETC01.DOC Template: MSGRIDA1.DOT Revision #: 47 Page: 5 of 3

Project: Environment and Tools Author: Cris Morris Last Saved By: Mike Eddy Printed: 10/09/00 02:48 PM

Environment and Tools

Filename: LMAETC01.DOC Template: MSGRIDA1.DOT Revision #: 47 Page: 6 of 4

Project: Environment and Tools Author: Cris Morris Last Saved By : Mike Eddy Printed: 10/09/00 02:48 PM

C H A P T E R

Quick Start

This chapter gets you started with PWB. Youll learn the basics by building and debugging a C-callable routine that generates a 2-byte pseudo-random number. Some of the source code that you will be using is included with the sample programs shipped with MASM 6.1. If you chose not to install the sample code when you set up MASM, run SETUP to install it (see Getting Started for more information). To start PWB in the Windows operating system for this tutorial, double-click the PWB icon in the MASM group. In MS-DOS, type
PWB

at the prompt. To leave PWB at any time: From the File menu, choose Exit, or press

ALT+F4.

The PWB Environment

If this is the first time you have used PWB, you see the menu bar, the status bar, and an empty desktop (assuming a standard installation). If you have used PWB before, it opens the file you last worked with. PWB uses a windowed environment to present information, get information from you, and allow you to edit programs. The environment has the following components:
u u

An editor for writing and revising programs A build engine the part of PWB that helps you assemble, link, and execute your programs from within the environment

Filename: LMAET02A.DOC Template: MSGRIDA1.DOT Revision #: 71 Page: 7 of 1

Project: Author: Harold S. Henry Last Saved By: Mike Eddy Printed: 10/09/00 02:38 PM

Environment and Tools

u u u

A source-code browser Commands for program execution and debugging The Microsoft Advisor Help system

The browser and the Help system are dynamically loaded extensions to the PWB platform. Microsoft languages and the utilities are also supported in PWB by extensions. Other extensions are available, such as the Microsoft Source Profiler. PWB presents all of these components through menus and dialog boxes. The following figure shows some parts of the PWB interface.

Figure 2.1 PWB Display

Chapter 4, User Interface Details, contains a thorough description of these elements and the rest of the PWB environment. Refer to this chapter when you need specific information about an unfamiliar interface element.

The Microsoft Advisor

PWB makes programming easier by providing the Microsoft Advisor Help system, which contains comprehensive information about:
u u

PWB editing functions PWB advanced features

Filename: LMAET02A.DOC Template: MSGRIDA1.DOT Revision #: 71 Page: 8 of 2

Project: Author: Harold S. Henry Last Saved By: Mike Eddy Printed: 10/09/00 02:38 PM

Chapter 2 QuickStart
u u u u u

PWB menus and dialog boxes CodeView debugger Intel 80x86 assembly language MASM 6.1 assembler options Microsoft utilities (such as NMAKE, LINK, and so on)

The Advisor provides context-sensitive Help and general Help. Context-sensitive Help provides information about the menu, dialog box, or language element at the cursor. To see context-sensitive Help, you can simply point to an item on the screen and press either the right mouse button or the F1 key. PWB displays a Help window showing the requested information. You can also get contextsensitive Help and more general Help by using the Help menu. To answer questions of a less specific nature, you can access the Contents screen by choosing Contents from the Help menu or by pressing SHIFT+F1. From the Advisor contents, you can access Help on any other subject in the database. To get started using the Microsoft Advisor: From the Help menu, choose the Help on Help command. Help on Help teaches you how to use the Microsoft Advisor Help system. For more information on using Help, see Chapter 21. To close the Help window: Click the upper-left corner of the Help window (the Close box), press choose Close from the File menu, or press CTRL+F4. Note Click the Close box, choose Close from the File menu, or press to close any open window in PWB.

ESC,

CTRL+F4

The following sections explain basic editing procedures. If youre already familiar with these, you can skip to Opening an Existing File on page 14.

Entering Text
In this section, youll learn basic PWB procedures by entering a simple Ccallable assembly-language routine. To start a new file: 1. Move the mouse cursor (point) to the File menu on the menu bar and click the left button, or press ALT+F from the keyboard. PWB opens the File menu.

Filename: LMAET02A.DOC Template: MSGRIDA1.DOT Revision #: 71 Page: 9 of 3

Project: Author: Harold S. Henry Last Saved By: Mike Eddy Printed: 10/09/00 02:38 PM

10

Environment and Tools

2. Point to the New command and click the left button, or press New. PWB opens a window with the title Untitled.001.

to choose

Pressing the ALT key from the keyboard changes focus to the menu bar, and pressing the highlighted key in a menu name opens that menu. Similarly, within a menu, pressing a key highlighted in one of the commands causes that command to be carried out. Using the keyboard, you can also easily move to the beginning of a file by typing CTRL+HOME, or to the end of a file by typing CTRL+END. Starting with your cursor in the upper-left corner of the edit window, type the following comment line:
; C-CALLABLE PSEUDO-RANDOM NUMBER GENERATOR ROUTINE

Your screen should appear as follows:

Saving a File
Now that youve started entering your program, save your work before proceeding. To save a file: From the File menu, choose Save, or press PWB displays the Save As dialog box.

SHIFT+F2.

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 10 of 4 Printed: 10/09/00 02:38 PM

Chapter 2 QuickStart

11

This dialog box has several options that you use to pass information to PWB. PWB indicates the active option in this case, the File Name text box by highlighting the area in which you can enter text. For more information about dialog boxes, see Chapter 4, User Interface Details. Because you have not yet saved the file, it still has the name Untitled.001. Type ONEOF.ASM in the File Name text box. Then click OK or press ENTER to save the file (if you want, you can first select the directory where the file will be saved, using the Drives / Dirs list box). Note Now that you have named your file, choosing Save from the File menu does not bring up a dialog box. Your file is immediately saved to disk.

Indenting Text with PWB

Most assembly-language programmers format their code in several text columns (for example, a label column, an instruction column, a parameter column, and a comment column). You can create these columns differently in PWB than in other text editors. In PWB, you can move the cursor (point) to any position on the screen and start typing text. PWB will take care of inserting whatever new lines, spaces, or tabs are necessary to place the text in the position you are typing. By setting options, you can determine whether PWB will use spaces or tab characters to create the necessary white space (see How PWB Handles Tabs on page 118).

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 11 of 5 Printed: 10/09/00 02:38 PM

12

Environment and Tools

Type the following comment lines to document the routine:

; unsigned int OneOf ( unsigned int range ) ; ---------------------------------------------------------------; Routine uses a linear congruential method to calculate ; a pseudo-random number, treats the number as a fraction ; between 0 and 1, multiplies it times the range, ; truncates the result to an integer, and returns it. ; ; Algorithm: a[i] = ( ( a[i-1] * b ) + 1 ) mod m ; where b = 4961 and m = 2^16 ; OneOf PROC NEAR C PUBLIC USES bx dx, range:WORD OneOf ENDP

When you enter assembly-language code, you will often be adding a line indented to the same column as the line above. PWB saves you time by automatically indenting new lines when you press the ENTER key.
u

If there is no line or a blank line immediately below the new line, PWB matches the indentation of the line above it. u If there is a line immediately below the new line, PWB matches the indentation of the line below it. Youll now type some text after the line containing the PROC NEAR directive.

To insert space for a new line using a mouse: 1. Position the cursor anywhere past the end of the line containing PROC NEAR. Precise positioning of the cursor is not critical because (by default) PWB trims trailing spaces from the end of your lines. 2. Click the left mouse button. 3. Press ENTER to make a new line. If you are in overtype mode, change to insert mode by pressing the INS key. Otherwise, pressing ENTER simply moves the cursor to the beginning of the next line. PWB displays the letter O on the status bar and shows the cursor as an underscore to signal that you are in overtype mode. To insert the new line using the keyboard: 1. Move the cursor to the line containing the PROC NEAR directive by pressing the UP ARROW key. 2. Press END to move the cursor to the end of the line. 3. Press ENTER to make a new line.

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 12 of 6 Printed: 10/09/00 02:38 PM

Chapter 2 QuickStart

13

Now type the following lines, using the TAB key to indent and space the instructions:
mov mul inc mov mov mul mov ax, 4961 rndPrev ax rndPrev, ax bx, range bx ax, dx ; ; ; ; Load the constant into AX and multiply it by the previous value in the series add one to the product and save it, mod 2^16

; Now load the range argument, ; multiply it times the new number, ; and return the high 16 bits

Your program now looks like this:

Now that you have finished entering the code for the routine, save the file. From the File menu, choose Save, or press SHIFT+F2. Because you have already named and saved the file once before, PWB simply saves it, without bringing up the Save As dialog box. Note You can turn on automatic file saving by setting the Autosave switch to yes with the Editor Settings command on the Options menu. When Autosave is turned on, PWB automatically saves your file before executing certain commands such as running your program or switching to another file. For example, if you run a program that is not yet stabilized, PWB ensures that your file is stored safely in case you have to reboot.

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 13 of 7 Printed: 10/09/00 02:38 PM

14

Environment and Tools

Opening an Existing File

The remainder of this chapter uses a different file, RND.ASM, which you can now open in PWB. This file contains code to let you test the routine you just entered. It has several errors you will correct as you follow the tutorial. To open RND.ASM: 1. From the File menu, choose Open (press PWB displays the Open File dialog box.
ALT+F, O).

PWB uses *.* as the default filename in the File Name text box. This causes PWB to display all files in the current directory in the File List box. If you know the name of the file you want to open, you can replace the *.* by typing the filename into the File Name text box. 2. If you are not in the directory or drive where the sample programs are located, press TAB twice to move to the Drives/Dirs box, or click inside it. The example file, RND.ASM, is located in the \SAMPLES\PWBTUTOR subdirectory of your main MASM directory, if you accepted the default directory suggested by SETUP. The current directory is shown directly beneath the File Name text box. Subdirectories of the current directory are listed in the Drives/Dir box, followed by the available disk drives. Although the box is only large enough to display five entries at a time, you can scroll through the subdirectories or drives to find the one you want by using the DOWN ARROW or PAGE DOWN key, or by using the scroll bar to the right of the box. A directory entry consisting of two periods ( . . ) indicates the parent directory of the one you are currently in. Selecting the . . directory causes you to move one level up your directory tree to the directory immediately

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 14 of 8 Printed: 10/09/00 02:38 PM

Chapter 2 QuickStart

15

above the current directory. For example, if you are in the directory, C:\MASM\SAMPLES, then the . . directory would be C:\MASM. Using the . . entry helps you walk one step at a time along directory paths. Youll notice that the cursor is a blinking underline. That means that although you have selected the list box, you havent yet chosen an item. 3. Use the arrow keys to move to the \SAMPLES\PWBTUTOR subdirectory of your main MASM directory. As you press the arrow keys, youll notice that the cursor changes to a bar that highlights the whole selection. This is called the selection cursor. The text of the selected item also appears in the File Name box. 4. When you have highlighted the drive or directory you want, press ENTER to move there. Using the mouse, you can simply double-click on a directory or drive entry to move to it, without having to go through an intermediate selection step. 5. Use the TAB key or mouse to move to the File List box. 6. Use the arrow keys to move to RND.ASM, or click on it with the left mouse button. 7. When you have highlighted RND.ASM, press ENTER or choose the OK button to accept your selection and open the file. Just as with the directory or drive entries, you can simply double-click on the filename to open it, bypassing the selection step. PWB opens RND.ASM for editing.

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 15 of 9 Printed: 10/09/00 02:38 PM

16

Environment and Tools

Copying, Pasting, and Deleting Text

The RND.ASM code contains a placeholder routine named OneOf, which returns 0. You can now delete it and replace it with the random number routine that you created in the previous section of this tutorial. You have already typed in and saved the OneOf routine in a different file. Rather than type it over again, you can copy and paste it using PWBs clipboard (a temporary storage place for text). To do this, open the Window menu and choose the ONEOF.ASM window (if you no longer have it open, you will need to go back to the directory in which you saved it and open it using the Open command on the File menu). Next, to copy the routine most conveniently, you will change the way text is selected. Three selection modes are available on the Edit menu:
u

Stream mode by default, the editor starts in stream selection mode, which allows selection to begin at any point, and selects all characters in a stream between the beginning and end positions of the cursor. Line mode selects complete lines of text, starting with the entire line on which the cursor begins, and ending with the entire line on which it ends. Box mode allows you to select a rectangular section of text, one corner of which is the starting position of the cursor, and the opposite corner of which is the ending position of the cursor.

The currently active selection mode is marked with a dot on the Edit menu. Clicking on a mode selects it. You can also change modes while selecting text. Just select text by clicking the left mouse button and dragging the mouse. Then, without releasing the left mouse button, press the right mouse button to toggle among the selection modes. In this case, line selection mode is the most convenient. To change the selection mode: From the Edit menu, choose Line Mode. Next, place the cursor on the top line of text for the routine:
; unsigned int OneOf ( unsigned int range )

To select lines of text using the keyboard: Press SHIFT+DOWN ARROW until the cursor is on the line containing ENDP.

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 16 of 10 Printed: 10/09/00 02:38 PM

Chapter 2 QuickStart

17

To select lines of text using the mouse: Hold down the left mouse button and drag the cursor to the line containing ENDP.

To copy and paste the text that has been selected: 1. From the Edit menu, choose Copy. This action places the section of text that has been selected into the clipboard. You can also invoke the copy command using the shortcut key combination CTRL+INS. 2. From the Window menu, choose the RND.ASM window. 3. Go to the place where you want to insert the routine (line 51). Press ALT+A, type 51, then press CTRL+M to jump to line 51. This sequence of keystrokes is pronounced Arg 51 Mark. The PWB function Arg begins an argument (51) that is passed to the Mark function. When you pass a number to Mark, PWB moves the cursor to that line. You can also do this from the menu by typing the line number in the Goto Mark dialog box from the Search menu. The cursor is at the beginning of line 51, exactly where you want to insert the new routine. 4. From the Edit menu, choose Paste, or use the SHIFT+INS shortcut keystroke to paste the contents of the clipboard into that location.

To delete the old placeholder routine: 1. Use the PAGE DOWN key and arrow keys or mouse to move to the first line of the placeholder routine, just below the ENDP line of the inserted routine. 2. Select the six lines of the old routine, using SHIFT+DOWN ARROW or by selecting with the mouse. 3. From the Edit menu, choose Delete, or press DEL. The selected section is deleted. Important If you select an area of text and then type something or otherwise insert text, PWB replaces the selected text (deletes it and substitutes what you are typing or inserting), without saving it on the clipboard. You can recover the text by choosing Undo at once from the Edit menu. In the example above, if you had selected the six lines of old routine before pasting in the new routine, those lines would have been deleted and replaced by the paste operation. You have inserted the new routine into RND.ASM. Save the file by choosing Save from the File menu.

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 17 of 11 Printed: 10/09/00 02:38 PM

18

Environment and Tools

Single-Module Builds
The next step is to assemble and link the RND program to see if it works. Assembling and linking the source files is called building the project. It results in an executable file. A project build can also:
u u u

Create and update the browser database. Create a Windows-based dynamic-link library (DLL). Build a library of routines.

Setting Build Options

Before you build a program, you must tell PWB what kind of file to create by using the commands on the Options menu. Use the commands from the Options menu to specify:
u

The run-time support for your program. This is important for mixed-language program development, where you have some source files in assembler and some in another language. With Basic, for example, the run-time support must be Basics run-time support. The run-time support you choose determines the run-time libraries that are used and the types of target environments that can be supported. Project template. The template describes in detail how PWB is to build a project for a specific type of file (.EXE, .COM, .DLL, .LIB) and the operating environment for the target file (MS-DOS, the Windows operating system, and so on). Either a debug or release build. Debug options normally specify the inclusion of CodeView debugging information, where release options do not. You may want to generate a different listing file for a debug build than for a release build, or you may not want any listing file for one type of build or the other. A build directory. PWB builds your object and executable files in your current directory unless you specify otherwise. (This option is reserved for projects that use explicit project files, which are described in Chapter 3.)

To set the project template for RND.ASM: 1. From the Options menu, choose Set Project Template from the Project Templates cascaded menu.

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 18 of 12 Printed: 10/09/00 02:38 PM

Chapter 2 QuickStart

19

Note that the actual order of the menu items may differ from the illustration because PWBs extensions can be loaded in any order. 2. PWB displays the Set Project Template dialog box.

This dialog box typically has the entries None and Assembler in the Runtime Support list box. If you have installed other languages, their names appear as well. Since the RND program does not require run-time support, leave None selected. 3. Move to the Project Templates list box by clicking in the box, pressing the TAB key the appropriate number of times, or by pressing ALT+T. 4. Select DOS EXE. 5. Choose the OK button to set the new project template.

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 19 of 13 Printed: 10/09/00 02:38 PM

20

Environment and Tools

To set the build options for RND.ASM: 1. From the Options menu, choose Build Options. PWB displays the Build Options dialog box.

2. Turn on Use Debug Options by choosing the Option button or by pressing ALT+D. This option tells PWB that you are building a debugging version of the program. PWB uses debug options when you build or rebuild until you use the Build Options dialog box to choose Use Release Options. 3. Choose the OK button. 4. From the Options menu, choose Languages Options, then choose MASM options from the secondary menu. PWB displays the Macro Assembler Global Options dialog box. 5. Choose Set Debug Options. PWB displays the Macro Assembler Debug Options dialog box. In the Debug Information box, CodeView should already be selected, indicating that the assembler will generate the information that CodeView needs to correlate assembled code with source code. 6. Select Generate Listing File and Include Instruction Timings. This causes the assembler to create a listing file showing you exactly how it assembled your program, and to include in the listing how many clock cycles each instruction will take to execute. 7. Choose the OK button twice. PWB saves all the options that you specify. You dont have to respecify them each time you work on your project. The following illustration shows the three sets of options that PWB maintains for each project. Global options are used for every build. Debug options are

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 20 of 14 Printed: 10/09/00 02:38 PM

Chapter 2 QuickStart

21

used when Use Debug Options is turned on in the Build Options dialog box. Release options are used when Use Release Options is turned on.

Filename: LMAET02A.DOC Project: Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 71 Page: 21 of 15 Printed: 10/09/00 02:38 PM

21

You can set assembler and linker options for both types of builds (debug and release) by using the Language Options commands and the LINK Options command. The Build Options command then determines which type of build, using which set of options, is actually performed when you assemble a file or rebuild the project. Global options, on the other hand, typically include settings for warning level, memory model, and language variant. These are options that do not change between debug and release versions of a project.

Setting Other Options

The Options menu also contains commands that allow you to describe the desired project build more completely. You dont need to change most of these options to build RND.ASM because the default values supplied by the template will work well. The Options menu contains the following commands:
u

MASM Options in the Language Options cascaded menu. These commands let you specify assembler options specific to debug and release builds, and general options common to both types of builds. Using the MASM Global Options dialog box, you can specify memory model, warning level, and so on. If you have more languages installed, their Compiler Options commands also appear in the Languages Options cascaded menu.

Filename: LMAET02B.DOC Template: MSGRIDA1.DOT Revision #: 3 Page: 21 of 1

Project: Author: Mike Eddy Last Saved By: Mike Eddy Printed: 10/09/00 02:37 PM

22

Environment and Tools

u

LINK Options. This command parallels the Compiler Options commands. You can specify options specific to debug or release builds and general options common to both debug and release builds. Use LINK Options to specify items such as stack size and additional libraries. You can also select different libraries for debug and release builds. This is handy if you have special libraries for debugging and fast libraries for release builds.

NMAKE Options. This command lets you specify NMAKE command-line options for all builds. This option is particularly useful if you have an existing makefile that was not created by PWB or if you have modified your PWB project makefile. For more information about these subjects, see Using a Non-PWB Makefile on page 55. CodeView Options. This command allows you to set options for the CodeView debugger.

Building the Program

Now that youve set your options, you can build the program. Note that the sample program contains intentional errors that you will correct. To start the project build: 1. From the Project menu, choose Build. PWB tells you that your build options have changed and asks if you want to Rebuild All. 2. Choose Yes to rebuild your entire project. After the build is completed, PWB displays the following dialog box:

You can choose one of several actions in this dialog box:

u u

View the complete results of the build by opening the Build Results window. Run the program if building in MS-DOS. You can run an MS-DOS program right away if the build succeeds. If the build fails, you should fix the errors before you attempt to run the program.

Filename: LMAET02B.DOC Template: MSGRIDA1.DOT Revision #: 3 Page: 22 of 2

Project: Author: Mike Eddy Last Saved By: Mike Eddy Printed: 10/09/00 02:37 PM

Chapter 2 QuickStart

23

To run a successfully built Windows-based program, you must be running under the Windows operating system, and have started the WXServer program before you start PWB.
u

Debug the program if building in MS-DOS. If the build succeeds but you already know the program is not producing the intended results, you can debug your MS-DOS program using CodeView. To debug a Windows-based program, you should be running under the Windows operating system, and already have the WXServer running when you start PWB or CodeView.

Get Help by choosing the Help button or by pressing F1 (as in every PWB dialog box). Cancel the dialog box. This returns you to normal editing.

Choose View Results to close the dialog box (press ENTER). PWB displays the results of the build so that you can review the build messages or step through them to view the location of each error. The next section describes how to do this.

Fixing Build Errors

For each build, PWB keeps a complete list of build errors and messages in the Build Results window. The RND.ASM program that you just built contains several errors that youll identify and fix in this section. If you want to examine build errors in a specific order, you can do so in the Build Results window by placing the cursor on whatever error you wish to examine, and selecting Goto Error from the Project menu. PWB opens a window onto the appropriate source file and places the cursor on the line at which that error was recognized. When you are finished with each error, selecting the Build Results window from the Window menu will return you to the Build Results window. In many cases, however, you will want to work through the errors one after another. This is the easiest method for fixing the build errors in RND.ASM. To fix errors one after another: 1. From the Project menu, choose Next Error, or press SHIFT+F3. PWB positions the cursor on the location of the first error or warning in your program. In this case, a comma is missing after the 10 at the end of the first line of the banr2 data declaration.

Filename: LMAET02B.DOC Template: MSGRIDA1.DOT Revision #: 3 Page: 23 of 3

Project: Author: Mike Eddy Last Saved By: Mike Eddy Printed: 10/09/00 02:37 PM

24

Environment and Tools

2. Correct the first error by inserting a comma immediately after the 10. 3. From the Project menu, choose Next Error, or press SHIFT+F3. PWB moves the cursor to the location of the second error. Here, "Esc" in the string on the line below the cursor is enclosed in double quotes, and the string itself is also enclosed in double quotes. As a result, the assembler interprets the first set of quotes around Esc as the end of the string, and then does not recognize Esc as a valid instruction or directive. This can be fixed by substituting a pair of single quotes for the pair of double quotes either around the string or around Esc. 4. Fix the error by changing the double quotes ("") around Esc to single quotes (''). Because of this error, the data symbol again was not defined during the first assembly pass, which also meant that the constant lagain could not be evaluated. As a result, two more errors were generated, which can now be ignored. 5. From the Project menu, choose Next Error, or press SHIFT+F3. PWB positions the cursor on the location of the third error, a simple typographical error where the mov instruction was spelled mob. 6. Correct the third error by replacing the b in mob with a v. Now that all the build errors in RND.ASM have been corrected, save the file by choosing Save from the File menu or by pressing SHIFT+F2.

Filename: LMAET02B.DOC Template: MSGRIDA1.DOT Revision #: 3 Page: 24 of 4

Project: Author: Mike Eddy Last Saved By: Mike Eddy Printed: 10/09/00 02:37 PM

Chapter 2 QuickStart

25

Running the Program

The next step is to build and run the program. To run the program: 1. From the Run menu, choose Execute (be sure that you have saved RND.ASM first). PWB detects that youve changed the source and displays a dialog box with the following options:

2. Choose Build Target to build the program. When the build completes, PWB displays the following dialog box:

3. Choose Run Program to run the finished program. When you run it, the RND program will start by asking you to supply a range value between 1 and 65,535. Type 1234 and press ENTER. The program will then ask you to confirm that 1,234 is indeed the correct range. When you type y, the program is supposed to display a list of random numbers within that range. Instead, however, the program restarts when you type y. Something is wrong. To get out of the program and back to PWB, press CTRL+C (in the case of this particular program, you can also use the ESC key to exit when the program asks for confirmation of a range value). Before blanking your programs output, PWB will display the message, Strike any key to continue... so that you can examine the final state of the screen. The following sections describe the process of debugging using the Microsoft CodeView debugger. If youre already familiar with CodeView, skip to Chapter 3, Managing a Multimodule Program.

Filename: LMAET02B.DOC Template: MSGRIDA1.DOT Revision #: 3 Page: 25 of 5

Project: Author: Mike Eddy Last Saved By: Mike Eddy Printed: 10/09/00 02:37 PM

26

Environment and Tools

Debugging the Program

PWB integrates several Microsoft tools to produce a complete development environment. Among those tools are NMAKE, a program maintenance utility, and CodeView, a symbolic debugger. Whenever you build programs using PWB, PWB in turn invokes NMAKE to manage the build process. In the same way, PWB can serve as a gateway to CodeView when you need to debug a program you have built. Earlier, you chose Use Debug Options in the Build Options dialog box. A debug build typically includes the assembler options that generate CodeView information. Therefore, the program is ready to debug with the CodeView debugger.

Using CodeView to Isolate an Error

In addition to the typographical errors that you just corrected, RND.ASM contains a logical error which will prevent it from running properly. You can use CodeView to isolate this error. To start CodeView: From the Run menu, choose Debug. If anything in your program is out of date, PWB asks if you want to build or rebuild the current target. If you modified the source file in any way, PWB considers it out of date relative to the executable file that you built earlier. If this happens, build the program and choose Debug from the Run menu. CodeView now starts, displaying three windows on its main debugging screen.

Filename: LMAET02B.DOC Template: MSGRIDA1.DOT Revision #: 3 Page: 26 of 6

Project: Author: Mike Eddy Last Saved By: Mike Eddy Printed: 10/09/00 02:37 PM

Chapter 2 QuickStart

27

The first thing to do is set up the CodeView screen so that it best suits your way of working. When you leave CodeView, your setup will be saved in CURRENT.STS. The next time you use CodeView, that setup will be restored when the program starts. The right screen layout depends a lot on your work style, and on the project you are working on. In this case, many of CodeViews more advanced features will not be necessary, so we will set up a simple screen. By default, three windows are initially displayed: locals, source1, and command. Close the locals window, since it will not be needed in debugging RND, open a register window and a memory window, and arrange the windows in the screen.

Filename: LMAET02B.DOC Template: MSGRIDA1.DOT Revision #: 3 Page: 27 of 7

Project: Author: Mike Eddy Last Saved By: Mike Eddy Printed: 10/09/00 02:37 PM

28

Environment and Tools

To close a window using the mouse: Click the upper left corner of the window. To close a window using the keyboard: Use the F6 key to move into the window that you want to close. Choose Close from the Windows menu, or press CTRL+F4. To open the Register and Memory windows: 1. From the Windows menu, choose Register, or press ALT+7. The Register window displays the contents of the processors registers, either in Native (8086) mode, or in 32-bit (80386-80486) mode. 2. At the bottom of the Options menu, click Native if it is not already selected. 3. Choose Memory 1 from the Windows menu, or press ALT+F5. Memory windows display the contents of a specified block of memory, so that you can watch changes as your program runs.

To move and size a window using the mouse: 1. To move a window, place the cursor on its top line, not in a corner. Then drag the window to a new location. 2. To size a window, move the cursor to the lower right corner of the window. Then drag the corner to change the windows size.

Filename: LMAET02B.DOC Template: MSGRIDA1.DOT Revision #: 3 Page: 28 of 8

Project: Author: Mike Eddy Last Saved By: Mike Eddy Printed: 10/09/00 02:37 PM

Chapter 2 QuickStart

29

To move and size a window using the keyboard: 1. Using the F6 key, shift focus to the window you want to size. 2. Choose Move or Size from the Windows menu. 3. Use the arrow keys to move or size the window. 4. Press ENTER when you are finished. When you have positioned and sized the windows to your satisfaction, set the source window to show both your source text and the actual instructions assembled by MASM, and set the memory window to stay fully up to date as the program executes.

To display mixed source and assembler output: 1. From the Options menu, choose Source1 Window. CodeView displays the Source1 Window Options dialog box. 2. In the Display box, choose Mixed Source and Assembly. 3. Choose OK.

To set the Memory1 window to be updated frequently: 1. From the Options menu, choose Memory1 Window. CodeView displays the Memory1 Window Options dialog box. 2. Select the Re-evaluate expression always (live) check box. 3. Choose the OK button.

Working Through a Program to Debug it

CodeView has placed you at the programs starting point. The registers are as they would be at that point, and the memory window shows whatever the DS register is pointing to. The instructions that appear at the top of the source window have been created by the .STARTUP directive, as you can see if you scroll up a few lines. CodeView provides various ways to control and examine the execution of a program. The Step command (F10 key) executes the next instruction in the program, and if that instruction is a call, executes the entire called code up through the return. Trace (F8 key), on the other hand, jumps to the called code and traces through it too, one instruction at a time. You can also run the program up to a given point, or set breakpoints at several points. With RND, we will only need to use a few of the possible debugging tools.

Filename: LMAET02B.DOC Template: MSGRIDA1.DOT Revision #: 3 Page: 29 of 9

Project: Author: Mike Eddy Last Saved By: Mike Eddy Printed: 10/09/00 02:37 PM

30

Environment and Tools

To Step through the program: Use the F10 key to step through the first couple of instructions of the .STARTUP code. You will notice that as each instruction is executed, CodeView briefly displays the program output screen, and updates the Register window to show changes in the registers. As the DS register is loaded, the Memory window displays the data segment of the RND program. Stepping is a slow way to move through the program. In many cases, as with RND, you will want to move quickly to the point where the program failed, to see what the matter was. In RND, everything seemed to be working correctly until you entered y to confirm the range.

To run a program up to a given place: 1. Scroll through the code to the comment line:
; Read in a character from the keyboard

Three lines below the comment is a cmp instruction. 2. Place the cursor on the line containing the cmp instruction, either by using the arrow keys or the mouse.

3. Press the F7 key, or by clicking on that line with the right mouse button.

Filename: LMAET02B.DOC Project: Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 3 Page: 30 of 10 Printed: 10/09/00 02:37 PM

Chapter 2 QuickStart

31

CodeView procedes to execute the program up to (but not including) that line. The display switches to the output screen where the program shows its introductory message, then requests a range value. To work through the RND program and find the bug: 1. Type in a range value smaller than 65,535 and press 2. Press y. CodeView returns you to the source window in the debugging screen. The succeeding instructions are designed to recognize an ESC or a y, and are presumably failing in some way, causing the program to start from the beginning. 3. Using the F10 key, step through the various cmp instructions. You will find that the code works as expected, recognizes the y, and proceeds. 4. Go on to the next the next jump or branch. The next possible branch in program execution occurs at the call to OneOf. Although this seems unlikely to be causing the program to start over, it is the next thing to test. 5. Position the cursor on the call instruction, and press either F7 or the right mouse button to execute the program up to that call. So far, so good: the program continues to run as expected. 6. Now press
F10 ENTER.

The program redisplays the range value and asks for confirmation.

to execute the call itself.

Filename: LMAET02B.DOC Project: Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 3 Page: 31 of 11 Printed: 10/09/00 02:37 PM

32

Environment and Tools

The program now erroneously starts over. We now know that the problem must be located in the OneOf routine. 7. Press CTRL+C, then ENTER to get out of the program. 8. Choose Restart from the Run menu to return to the beginning of the program. 9. As you did before, scroll down to where OneOf is called and execute the program up to just before the call. 10. This time, use F8 to trace through the call. You will notice that CodeView now shifts into the called routine, allowing you to step through the OneOf code instruction by instruction. 11. Step or trace through the OneOf routine, using F10 or F8, and look for the problem. You will discover a simple error of omission: the routine has no ret instruction at the end. As a result, execution continues into the succeeding code, which happens to be the .STARTUP code. Having found the problem, you can leave CodeView and return to PWB. 12. From the File menu, select Exit. CodeView closes, saving your settings for next session. 13. From PWB, insert a new line in the RND.ASM file just before the ENDP line of the OneOf routine.

Filename: LMAET02B.DOC Project: Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 3 Page: 32 of 12 Printed: 10/09/00 02:37 PM

Chapter 2 QuickStart

33

14. Type a ret instruction there.

15. Save the corrected file by choosing Save from the File menu, or by pressing SHIFT+F2. 16. Select Execute from the Run menu to rebuild the program and try it again. This time, it should work without problems.

Examining Memory in the Memory Window

In addition to being able to watch the register contents change as your code runs, CodeView lets you see what happens to locations in memory. For example, you may have noticed that OFFSET lnBuf was assembled as hex E4. By setting the memory window at that address, you can watch what happens in the lnBuf buffer as the program formats a line of output. One way to reach that address, since it is fairly close, is to scroll in the memory window until you get to it. However, this is often impractical. To set the address in the Memory Window: 1. From the Options menu, select Memory1 Window. 2. In place of DS:0 in the Address Expression field of the Memory1 Window Options dialog box, type DS:0x00e4. Now, you can step through cycles of a formatting loop and watch the buffer change.

Filename: LMAET02B.DOC Project: Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 3 Page: 33 of 13 Printed: 10/09/00 02:37 PM

34

Environment and Tools

To step through a formatting loop in RND.EXE: 1. In the source window, scroll to the instruction dec bl around line 150, which completes a formatting cycle for a random number. 2. Press F7 or click in that line with the right mouse button. If you know for sure that dec bl is on line 150, you can move to the Command window and type g @150 followed by the ENTER key. This instructs CodeView to execute the program up through line 150 in the source file.

3. While watching the memory window, press F7 again, or click the dec bl instruction again with the right mouse button. As the loop executes again, you can see the memory area change to reflect the new value being formatted into lnBuf. To switch from CodeView back to PWB: Choose Exit from the CodeView File menu.

Where to Go from Here

Now that youve created, built, and debugged a simple program, youve begun to discover the power of PWB. Chapter 3, Managing Multimodule Programs, describes how to create and manage projects with more than one source file.

Filename: LMAET02B.DOC Project: Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 3 Page: 34 of 14 Printed: 10/09/00 02:37 PM

36

Environment and Tools

Filename: LMAET02B.DOC Project: Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 3 Page: 36 of 16 Printed: 10/09/00 02:37 PM

35

C H A P T E R

Managing Multimodule Programs

This chapter expands on the work you did in Chapter 2 and explains how to build and maintain multimodule programs using PWBs integrated projectmanagement facilities. PWB offers an efficient way to manage complex projects. You organize and build your project entirely within PWB, using convenient menus and dialog boxes instead of makefiles or batch files. PWB stores the information needed to build and manage your program in two files, the project makefile and the project status file. These are called the project. When you open the project, PWB automatically configures itself to build your program. To move from one project to another, you close one project and open another.

Multimodule Program Example

In this chapter, youll learn to set up a multimodule project in PWB by building SHOW.EXE, a three-module program. The SHOW program displays text files on character-based screens with MS-DOS. The following modules make up SHOW.EXE:
Module SHOW.ASM PAGER.ASM SHOWUTIL.ASM Function Program driver; contains .STARTUP entry point, and calls all other procedures. Contains procedures for paging through a file and writing text to the screen buffer Contains miscellaneous procedures.

The program also contains a common header file SHOW.INC in addition to these three source modules. Figure 3.1 shows the components of SHOW and how they combine to build the executable file.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 35 of 1 Printed: 10/09/00 02:44 PM

36

Environment and Tools

Figure 3.1

The SHOW Project

To build SHOW.EXE, you need to assemble the three source files and link them together, having specified the assembler and link options that will produce the kind of file you are trying to make. All this build information is stored in the SHOW project make and status files.

Opening the Project

Start by opening the SHOW project. (If you have not started PWB, do so now.) To create a project: 1. From the Project menu, choose New Project. PWB displays the New Project dialog box.

2. Type show in the Project Name text box. 3. Choose Set Project Template. PWB displays the Set Project Template dialog box. 4. Select the following options:

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 36 of 2 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

u u

37

Runtime Support: None. Project Template: DOS EXE.

At this point, the Set Project Template dialog box should appear as follows:

This initial specification tells PWB what kind of executable file you intend to build, and is saved as part of the project. 5. Choose OK to return to the New Project dialog box. In this case, a project makefile, SHOW.MAK, already exists. Since PWB would ordinarily create and save a new makefile at this point, you are now asked whether you want to overwrite the existing file.

6. Choose Yes to overwrite the existing file. PWB saves the new SHOW.MAK and returns to the New Project dialog box. 7. Choose OK. PWB now displays the Edit Project dialog box so that you can add files to your new project.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 37 of 3 Printed: 10/09/00 02:44 PM

38

Environment and Tools

The next section describes the types of files that can be added to the project. The tutorial then continues by listing the example files to add to the list.

Contents of a Project
A project file list can contain the following files:
u u u u u

Source code files (.ASM). Object files (.OBJ) in special cases. Library files (.LIB) for libraries that change. Module-definition files (.DEF) for DLLs. Resource-assembler source files (.RC) for Microsoft Windows-based programs.

These file types are all that are needed to create most MS-DOS and Windowsbased applications. Include files, such as SHOW.INC, need not be listed because PWB automatically adds them when it scans your source files for dependencies. When you select assembler run-time support with a Windows-based project template in the Set Project Template dialog box, PWB automatically specifies standard library files such as LIBW.LIB. Therefore, you need not add standard library files to the project list. To add the SHOW files to your project: 1. Choose the files you want to add to the project from the File List box. In this case, youll add SHOW.ASM, PAGER.ASM, and SHOWUTIL.ASM. These files are located in the \MASM\SAMPLES\SHOW directory. If you installed Microsoft MASM 6.1 in a directory other than MASM, adjust the path accordingly.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 38 of 4 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

39

You can scroll the File List box by clicking the scroll bars or by pressing the arrow keys. 2. For each file, select it and choose Add / Delete to add the file to the Project list box. Or, you can double-click a file to add or remove it from the list. To add all three files at once, you can type *.ASM in the File Name field, press ENTER, and then choose Add All. 3. Choose Save List when you have added all three files. PWB uses the rules in the project template along with the list of files that you just specified to scan the sources for include dependencies and to create the project makefile. This process is described in the next section. Now your project completely describes what you want to build (the project template), the component source files, and the commands used to build the project.

Dependencies in a Project
When you save the project, PWB generates a makefile from the project template, files, and options you specified. This file also contains a list of instructions that are interpreted by NMAKE. In addition, PWB generates the project status file, which saves the project template, the editor state, and the build environment for the project. For more information on the project status file, see Project Status Files on page 129. When you build the project, NMAKE examines the build rules in the project makefile. These are rules that specify targets (such as an object or an executable

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 39 of 5 Printed: 10/09/00 02:44 PM

40

Environment and Tools

file) and the commands required to build them. For example, a rule for making an .OBJ file from an .ASM file can be expressed as follows:
.asm.obj: ML /c $<

To reduce the amount of time builds take, NMAKE assembles or links only the targets that are out-of-date with respect to their corresponding source file. This process is simple if there is a one-to-one correspondence between sources and targets. However, many programs use the INCLUDE directive to include files containing common equates, macros, and other program text. The object files must be made dependent not only on the source file but also on the files that are used by the source file. You dont need to add include (.INC) files to your project. When you save the project, PWB scans your source files looking for INCLUDE directives and builds dependencies on these files. NMAKE will thereafter recompile a source file if you change a file that it includes.

Building a Multimodule Program

Now that the project files are complete, you can build the program in the same way you built the single-module program. To build a multimodule program: 1. You are starting a new project, so you should use debug options for the initial builds. Choose the Use Debug Options button in the Build Options dialog box. 2. From the Project menu, choose Build. PWB displays a dialog box to inform you that build information has changed because you altered the build options. 3. Choose Yes to rebuild your entire project. As the program is built, PWB shows status messages about the progress of the build. When the build completes, a dialog box displays a summary of any errors encountered during the build process. Note The Next Error command on the Project menu works the same for a multimodule build as for a single-module build. Because errors in a multimodule build can occur in different files, PWB automatically switches to the file that contains the error. In some cases, you will want to force a complete rebuild of your project by choosing Rebuild All from the Project menu. The difference between Build and

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 40 of 6 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

41

Rebuild All is that Build compiles and links only out-of-date targets and Rebuild All compiles all targets, regardless of whether they are current.

Running the Program

Now that your program is built, you can test it from PWB. To run SHOW: 1. From the Run menu, choose Program Arguments. 2. Type the name of a text file to pass to the SHOW program. The SHOW.ASM source file is a good file to use. 3. Choose OK to set the program arguments. PWB saves the arguments so that you can run or debug the program many times with the same command line. 4. From the Run menu, choose Execute. SHOW will display the first screen of text in the file you passed to it. You can use the arrow keys and PAGE UP and PAGE DOWN to move around in the text file. Press Q and then any key to return to PWB. You have successfully created a multimodule project, built the program, and run it, all from within the Programmers WorkBench. You can now leave PWB. To leave PWB: From the File menu, choose Exit or press ALT+F4. PWB saves your project and returns to the operating-system prompt. If you started PWB from within the Windows operating system, you will return to the Windows operating system. Creating a PWB project is an important first step. However, most of the time you will be maintaining projects. The next section provides an overview of project maintenance. The tutorial then continues with the SHOW project.

Project Maintenance
Once you have created a project, you may have to change it to reflect the changes in your project organization. You can:
u u u u

Add new file-inclusion directives to your source files. Add new source, object, or library files. Delete obsolete files. Move modules within the list.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 41 of 7 Printed: 10/09/00 02:44 PM

42

Environment and Tools

u u

Change assembler and linker options. Change options for individual modules.

When you add a new INCLUDE directive to a source file, you add a new dependency between files. For the most accurate builds, you need to regenerate include dependencies for the project. To regenerate include dependencies: 1. From the Project menu, choose Edit Project. 2. Select the Set Include Dependencies check box. 3. Choose Save List. PWB regenerates the include dependencies for the entire project and rewrites the project makefile. To add new files to an existing project: 1. From the Project menu, choose Edit Project. 2. For each file that you want to add to the project: u Select the file from the File List box, or type the name of the file in the File Name text box. u Choose the Add / Delete button to add the file. 3. Choose Save List to rewrite the project makefile, set up the dependencies, and add the commands for the new files. To delete files from a project: 1. From the Project menu, choose Edit Project. 2. For each file that you want to remove from the project: u Select the file from the File List box, or type the name of the file in the File Name text box. u Choose the Add / Delete button to remove the file from the list. 3. Choose Save List. With most programming languages, you wont need to move modules within a project. However, some languages or custom projects require files to be in a specific order. If youre programming in Basic, for example, you must place the main module of your program at the top of the list. Unlike other languages, Basic does not define an explicit name where execution begins. Entry to a Basic program is defined by the first file in the list.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 42 of 8 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

43

To move a file to the top of the project file list: 1. From the Project menu, choose Edit Project. 2. Select the file you want to move to the top of the list. 3. Choose the To Top of List button.

Using Existing Projects

Youll now make modifications to the SHOW project that you just created. During a PWB session, the project you open remains open unless you explicitly change it. If you have not already started PWB, you should do so now. In the Windows operating system, double-click the PWB icon in the MASM program group. If you are not compiling from within the Windows operating system, you can start PWB and open the SHOW project from the operating-system command line by typing the command:
PWB /PP SHOW

If the SHOW project is the last project you had open in PWB, type the following command:
PWB /PL

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 43 of 9 Printed: 10/09/00 02:44 PM

44

Environment and Tools

You can set up PWB to reopen the last project automatically at startup by choosing Editor Settings from the Options menu, and then by setting the Boolean switch Lastproject to Yes. If you have already started PWB, open the project now. To open the project from within PWB: 1. From the Project menu, choose Open Project. 2. Choose SHOW.MAK from the File List box or type show in the Project Name text box.

3. Choose OK. When you open the project, PWB restores the projects environment, including:
u

u u u

The window layout with the window style, size, and position for each window. The file historya list of open files for each window and the last cursor position in each file. The last find string. The last replace string. The options that you used for the last find or find-and-replace operation, such as regular expressions. See Using Regular Expressions on page 82 for more information about regular expressions. The project template (for example, DOS EXE) and any customizations you have made to the template such as changing the build type or an assembler or linker option. The command-line arguments for your program.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 44 of 10 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

45

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 45 of 11 Printed: 10/09/00 02:44 PM

46

Environment and Tools

Note PWB can save all environment variables, including PATH, INCLUDE, LIB, and HELPFILES, depending on how the envcursave and envprojsave switches are set. For more information, see Environment Variables on page 127. Also, if you turn the restorelayout switch off, PWB does not restore the window layout, the find strings and options, or the file history of a project. Instead, PWB keeps the current editor state when opening a project.

Adding and Deleting a Project File

As you develop a project, you will occasionally add new modules. The following example presents the steps needed to add a library file to the SHOW project. Note that this procedure is only an example, and in fact, SHOW does not use or require any library support. To add a file to your project: 1. From the Project menu, choose Edit Project. The file and directory navigation lists in this dialog box work in exactly the same way as those in the Open File dialog box. 2. Choose the parent directory symbol (..) in the Drives / Dirs list box to move up the directory tree to the SAMPLES directory. 3. Choose the parent directory symbol (..) again to move up the directory tree to the MASM directory. 4. Choose the LIB directory in the Drives / Dirs list box to move down the tree into the LIB directory.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 46 of 12 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

47

Notice that the directory displayed after the label File List reflects the directory change. 5. Make sure the File Name text box contains *.* or *.LIB. 6. Select LIBW.LIB in the File List box. 7. Choose the Add / Delete button to add the file to the project. LIBW.LIB is being used here as an example of how to add a file to your project. In practice, because it is a system library that will not change, there is no reason to add it. However, if you have a library of your own that is being used by your project, you would add it to the project in this way. 8. Since LIBW.LIB is not a source file and cannot have include dependencies, you can clear the Set Include Dependencies check box. If this check box is selected, PWB regenerates the dependencies for all the files in the project. 9. Choose Save List. LIBW.LIB is now part of the project. Since SHOW is not a program designed to run under Microsoft Windows, you should now delete this library from the project again. To delete a file from your project: 1. From the Project menu, choose Edit Project. 2. In the Edit Project dialog box, you can either select LIBW.LIB in the Project list box and then select Add / Delete, or simply double-click on LIBW.LIB in the Project list box to delete it.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 47 of 13 Printed: 10/09/00 02:44 PM

48

Environment and Tools

Changing Assembler and Linker Options

Up to this point, you have used PWBs default build options for all the examples. These options are sufficient for most cases, but in special cases, you will want to adjust them. When you are debugging a program, you should choose the debug build type. When producing a debug build, the assembler and linker include a good deal of extra information in the program for CodeView to use in debugging. When you are ready to use the program, choose the release build type, so that the extra debugging information is no longer incorporated into the program. To specify whether a build should be for release or debug: 1. From the Options menu, choose Build Options. 2. Choose Use Debug Options or Use Release Options in the Build Options dialog box. 3. Choose OK. When you specify a release build, PWB does not change your debug options. For more information on global options, debug options, and release options, see Setting Build Options on page 18. To change assembler options: 1. From the Language Options cascaded menu on the Options menu, choose MASM Options. The Macro Assembler Global Options dialog box contains a number of options that are common to both the release and debug builds.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 48 of 14 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

49

At the bottom of the dialog box are buttons that set options that are specific to the current type of build (debug or release), and that show the assembler flags corresponding to those options. Default settings were determined when you chose the project template. Note You can choose the Set Debug Options button to view and set the options for debug builds. However, this does not change the type of build that is performed when you build the project. To set the type of build, choose Build Options from the Options menu. 2. Choose Set Debug Options. PWB displays a dialog box in which you can specify debug options.

If you had chosen Set Release Options, PWB would have displayed the same dialog box, so that you could select options for release builds. 3. Choose OK to return to the Macro Assembler Global Options dialog box. 4. Choose OK to save the new assembly options and return to the main PWB screen. To change the linker options: 1. From the Options menu, choose LINK Options. PWB displays the LINK Options dialog box.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 49 of 15 Printed: 10/09/00 02:44 PM

50

Environment and Tools

2. Choose Additional Global Options to review and select additional global link options. PWB displays the Additional Global Link Options dialog box.

3. Choose OK when you are finished to return to the LINK Options dialog box. 4. Choose Additional Debug Options to review and select additional debug link options. PWB displays the Additional Debug Options dialog box.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 50 of 16 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

51

5. Choose OK when you are finished to return to the LINK Options dialog box. 6. Choose OK to close the LINK Options dialog box and use any new options you might have set. You are now ready to build your project with any new options you have selected. To build a modified project: From the Project menu, choose Rebuild All.

Changing Options for Individual Modules

Most of the modules in a program can generally be built using the same options. However, you may occasionally want to modify the options for a single module. The example that follows shows how to customize your project to change the assembler options for PAGER.ASM only. To do this, you manually edit the instructions in the project makefile for compiling PAGER.ASM. To open SHOW.MAK for editing: 1. If the SHOW project is open, choose Close Project from the Project menu. This step is important because you cannot edit a PWB makefile for a project that is currently open. 2. Choose the Open command from the File menu and open the SHOW.MAK file in the editor. To customize the assembly of PAGER.ASM: 1. Find the rule for compiling PAGER.ASM:

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 51 of 17 Printed: 10/09/00 02:44 PM

52

Environment and Tools

PAGER.obj : PAGER.ASM show.inc !IF $(DEBUG) $(ASM) /c $(AFLAGS_G) $(AFLAGS_D) /FoPAGER.obj PAGER.ASM !ELSE $(ASM) /c $(AFLAGS_G) $(AFLAGS_R) /FoPAGER.obj PAGER.ASM !ENDIF

This rule contains a conditional statement with two commands. The first command is for debug builds, and the second command is for release builds. You can edit either one of these commands, or both. They contain the following macros defined earlier in the makefile:
Macro ASM AFLAGS_G AFLAGS_D AFLAGS_R Definition The name of the MASM assembler Global options for assembly Debug options for assembly Release options for assembly

As an example, suppose that PAGER.ASM contained data structures which you want to pack on 32-bit boundaries for the release build only. The /Zp4 flag tells the ML program to pack data structures on 4-byte boundaries. 2. Edit the release build command as follows.
$(ASM) /c $(AFLAGS_G) $(AFLAGS_R) /Zp4 /FoSHOWUTIL.obj SHOWUTIL.ASM

Because it is hard to be sure what options the flags macros will invoke, the new option should be placed after them, so that it will supersede any instructions they may contain. Note that both the assembler options, such as /Zp, and NMAKE macros, such as AFLAGS_G, are case sensitive and must appear exactly as shown. Warning After this modification, PWB still recognizes this makefile as a PWB makefile. However, if you make changes beyond adding options to individual command lines, PWB may no longer recognize the file as a PWB makefile. If this happens, you can delete the makefile and re-create it, or you can use it as a non-PWB makefile. For more information on using non-PWB makefiles, see Using a Non-PWB Makefile on page 55. You could save your changes to the makefile by choosing Save from the File menu, then reopen the project and rebuild SHOW with the custom option you just installed. Because PAGER.ASM does not contain any data declarations, however, the new options have no real purpose or effect.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 52 of 18 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

53

The Program Build Process

This section explains the correspondence between projects and makefiles. Normally, the build process is automatic, but you may encounter situations that require customized build options. Read this section to learn how the utilities work with PWB. The following diagram illustrates the PWB build process.

Figure 3.2

The PWB Build Process

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 53 of 19 Printed: 10/09/00 02:44 PM

54

Environment and Tools

When you save your project by choosing the Save button in the Edit Project dialog box, PWB uses the list of files along with the rules in the selected project template to scan for dependencies and write the project makefile. When you choose the Build or Rebuild All command from the Project menu, PWB releases as much memory as possible and passes the makefile to NMAKE, which builds the project. NMAKE stops at the end of the first build step that produces an error (as opposed to a warning) or at the end of a successful build. In either case, NMAKE returns the results of the build to PWB along with a log of any errors and warnings. For more information about NMAKE, see Chapter 16, Managing Projects with NMAKE. PWB saves the output of the build for you to view in the Build Results window or to step through when you choose the Next Error (SHIFT+F3), Previous Error (SHIFT+F4), and Goto Error commands on the Project menu. You can run the program, set program arguments, and debug the program by choosing commands in the Run menu. If you have turned on the generation of browser information, PWB builds the browser database when you build the program. Once you have a browser database, you can use the commands in the Browse menu to navigate your programs source files and examine the structure of your program. For more information, see Using the Source Browser on page 88.

Extending a PWB Project

Makefiles that are not written by PWB often contain utility targets that are not used in the process of building the project itself. These targets are used to clean up intermediate files, perform backups, process documentation, or automate other tasks related to the project. You can extend a PWB makefile to perform these kinds of tasks by adding new rules. These additional rules must be placed in a special section of the project makefile. In the following example you will add a section that creates a file with information about the project. This file has the same base name as the project and the extension .LST. It lists the files in the project and the major options used for the build. This example section can be used with any assemblylanguage PWB project. Use the SHOW project to see how to add a custom section. If you have been following the tutorial, you have already made one custom edit to the SHOW.MAK file.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 54 of 20 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

55

To add a custom section to the PWB makefile: 1. If the project is open, choose Close Project from the Project menu. This step is crucial because PWB disables modification of the project makefile until the project is closed or a different project is opened. (This restriction does not apply to non-PWB project makefiles.) 2. From the File menu, choose the Open command and open the SHOW.MAK file in the editor. 3. Press CTRL+END to move the cursor to the end of the makefile. 4. Type the following new comment line exactly as shown:
# << User_supplied_information >>

You must put the number sign (#) in column one and type the contents of the line exactly as shown, including capitalization. Failing to type this line accurately will make the project unrecognizable to PWB or will cause PWB to change your custom build information in unexpected ways. You can copy this line from Help rather than typing it in, if you wish. Press ALT+A, type USI, press F1, and then copy the line. Move back to the make file, and paste the line in at the end. NMAKE requires space between rules. Therefore, you should separate this line from the lines above it by one blank line. Similarly, you should leave at least one line between the separator and your custom build rules. For more information about NMAKE and the syntax of makefiles, see Chapter 16, Managing Projects with NMAKE. This comment line is used by PWB as a separator. Anything above this comment is regarded as belonging to PWB, and you should not edit the information there. The exception is to add options to individual command lines, as described in Changing Options for Individual Modules on page 49. Anything in the makefile after the separator is your information, and PWB ignores it. NMAKE, however, processes the entire file. Now that you have a separator to show PWB where your custom information starts, you can add the custom information. The separator and custom section is included in the following text, and can also be found in the EXTRA.TXT file in the SAMPLES directory:

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 55 of 21 Printed: 10/09/00 02:44 PM

56

Environment and Tools

# << User_supplied_information >> # # # # # # # # # # Example 'user section' for PWB project makefiles, used in the PWB Tutorial. NOTE: This is not a standalone makefile. Append this file to makefiles created by PWB. This user section adds a new target to build a project listing that shows the build type, options, and a list of files in the project.

!IFNDEF PROJ !ERROR Not a standalone makefile. !ENDIF !IF $(DEBUG) BUILD_TYPE = debug !ELSE BUILD_TYPE = release !ENDIF # Project files and information-list target # $(PROJ).bld : $(PROJFILE) @echo <<$(PROJ).bld : Project Build Information Build Type: $(BUILD_TYPE) Program Arguments: $(RUNFLAGS) Project Files $(FILES: =^ ) Assembler Options Global: $(AFLAGS_G) Debug: $(AFLAGS_D) Release: $(AFLAGS_R) Link Options Global: $(LFLAGS_G) Debug: $(LFLAGS_D) Release: $(LFLAGS_R) <<KEEP

The custom section of a PWB makefile can use any of the information defined by PWB. This example takes advantage of many macros defined by PWB. For example, the PROJFILE macro, which contains the name of the project makefile, is used as the dependent of the listing file so that the listing is rebuilt whenever the project makefile changes. In addition, this custom section uses many features of NMAKE, including macros, macro substitution, preprocessing directives, and inline files. For more

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 56 of 22 Printed: 10/09/00 02:44 PM

Chapter 3 Managing Multimodule Programs

57

information about NMAKE and makefiles, see Chapter 16, Managing Projects with NMAKE. To rebuild using the custom options: 1. Choose Open Project from the Project menu and reopen the SHOW project. 2. From the Project menu, choose Build Target. 3. Type the name of the new target SHOW.BLD in the Target text box, and then choose OK. PWB informs you that the build options have changed and asks if you want to rebuild everything. 4. Choose Yes to confirm that you want to rebuild everything. The project information file that is created shows the project name, indicates whether the build is a debug or release build, lists the files in the project, and lists the assembler and linker options used for the build.

Using a Non-PWB Makefile

PWB makefiles are highly structured and stylized makefiles that are generated from the rules in the project template and a list of files that you supply. Many projects have existing makefiles that PWB cant read because they do not have this stylized structure. These makefiles are called non-PWB or foreign makefiles. You can still take advantage of many of PWBs project features with non-PWB makefiles. The features that cannot be used are shown as unavailable menu items. Note that a PWB makefile is not required to use the Source Browserall you need to have is a browser database. For information on building a browser database, see Building Databases for Non-PWB Projects on page 94. To use a non-PWB make file: 1. From the Project menu, choose Open Project. 2. Select the non-PWB make file to open. 3. Select the Use as a Non-PWB Makefile check box. The Open Project dialog box appears. 4. Choose OK. Note A PWB makefile cannot be edited or modified when it is the open project. However, PWB does not disable modification of non-PWB makefiles. You can edit a non-PWB makefile, even when it belongs to the currently open project.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 57 of 23 Printed: 10/09/00 02:44 PM

58

Environment and Tools

You can now use the Build, Rebuild All, and Build Target commands from the Project menu. The Build and Rebuild All commands work as they do with a PWB makefile by building the first target. However, the Language Options commands and the LINK Options command on the Options menu are unavailable. You set these kinds of options by editing the makefile. When you close a non-PWB project, PWB saves the environment, window layout, and file history just as it does for a PWB project.

Where to Go from Here

This concludes the PWB tutorial section of this manual. If you wish, you can leave PWB by choosing Exit from the File menu (or by pressing ALT+F4). Chapter 4, User Interface Details, explains how to start PWB, describes the elements of the user interface, and gives you an overview of the menus. Chapter 5, Advanced PWB Techniques, explains search techniques (including regular-expression searching), describes how to use the browser, and shows how to write PWB macros. Chapter 6, Customizing PWB, describes how to change the behavior of PWB to suit your needs. Chapter 7, PWB Reference, contains an alphabetical reference to PWB menus, keys, functions, predefined macros, and switches.

Filename: LMAETC03.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 64 Page: 58 of 24 Printed: 10/09/00 02:44 PM

57

C H A P T E R

User Interface Details

This chapter summarizes the PWB user interface. It contains:

u u u u u

General information on starting PWB. Instructions on how to use elements of the PWB screen. A description of the indicators on the status bar. A summary of every PWB menu command. Instructions on how to use menus and dialog boxes.

Starting PWB
You can start PWB in either of the following ways:
u u

From the the Windows operating system Program Manager From the operating-system command line

From the Command Line

To start PWB from the command line: At the operating-system prompt, type:
PWB [ [options ] ] [ [filename] ]

PWB starts with its default startup sequence. For a complete list of PWB options and their meanings, see PWB Command Line on page 131. Sometimes, you will want to modify the default startup sequence. The following procedures are examples of how you can start PWB to accommodate different circumstances.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 57 of 1 Printed: 10/09/00 02:48 PM

58

Environment and Tools

To start PWB with an existing PWB project: Type PWB /PP project.mak PWB opens the specified project and the files that you were working on with the project.

To start PWB with the project you used in your last session: Type PWB /PL As with the previous option, the /PL option opens a project and arranges your screen as it was when you left PWB.

To start PWB quickly for editing a file such as CONFIG.SYS: Type PWB /DAS /t CONFIG.SYS This command suppresses autoloading of extensions and status files (/DAS). It also tells PWB not to remember CONFIG.SYS for the next PWB session (/t CONFIG.SYS).

Using the Windows Operating System Program Manager

Microsoft Windows offers features that can enhance program development, particularly if you plan to develop Windows-based applications. You can edit and build your application in an MS-DOS session and then immediately run it under the Windows operating system. See Getting Started for a full description of how to set up Windows operating system icons for MASM in the Windows Program Manager. To start PWB with Windows, double-click the PWB icon. You can add a Program Item to the Program Manager for each project you are working on. Use the PIF editor to open PWB.PIF, and then choose Save As on the File menu to create a .PIF file with the same base name as your project. Next, use the Optional Parameters text box to specify the /PF or /PP options and the name of the project makefile. To run PWB in a window by default, you can change Display Usage in the PIF file to Windowed and (optionally) Execution to Background. Then, choose Project Templates on the Options menu. In the Build Rule edit field of the Customize Project Templates dialog box, type: macro WXFLAGS "/w" and select Set Build Rule. Choose OK.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 58 of 2 Printed: 10/09/00 02:48 PM

Chapter 4 User Interface Details

59

Using the Windows Operating System File Manager

When programming, you are often concentrating on which file or project you want to work on and would prefer that the computer provide the right tool for the job. With the Windows File Manager, you can associate certain types of files with the commands that operate on those files. Therefore, when you doubleclick the filename in the File Manager, the right tool starts with the correct command-line options. You can associate project makefiles (.MAK files) with the PWB .PIF file. Double-clicking a project makefile then starts PWB and opens that project, source files and all. To associate PWB with .MAK files: 1. Select any file in the File Manager with the extension .MAK. 2. From the File menu, choose Associate. 3. Type the command PWB.PIF in the dialog box. (Make sure that your PWB.PIF file specifies a question mark (?) in the Optional Parameters text box.) Now when you double-click a project makefile, the File Manager automatically starts PWB, and PWB opens that project. Note Be sure you have set your PATH, INIT, and TMP environment variables prior to starting the Windows operating system so PWB can find all its files.

The PWB Screen

Figure 4.1 shows the PWB display. The table which follows it describes each of the user interface elements.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 59 of 3 Printed: 10/09/00 02:48 PM

60

Environment and Tools

Figure 4.1 Name Menu bar Menu Desktop Icon Window Scroll bars Status bar

User Interface Elements Description Lists available menus. Lists PWB commands. Background area. Displays a window in compact form. Contains source code; displays Help, browser results, build results, or error messages. Change position in file or list. Shows command buttons for the mouse and shortcut keys; summarizes commands and file and keyboard status.

Figure 4.2 shows a PWB window. The table which follows it describes each of a windows elements.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 60 of 4 Printed: 10/09/00 02:48 PM

Chapter 4 User Interface Details

61

Figure 4.2 Name

Window Elements Description Moves window. Drag to move the window. Closes the window. Click to close the window. Identifies window. Press ALT+number to move to that window. Indicates window contents, a filename, or pseudofile title. Shrinks window to an icon. Click to minimize the window. Enlarges window to maximum size or restores window to its original size. Scrolls up by lines. Click to scroll up. Scrolls up by pages. Click to page up. Indicates relative position in the file. Drag to change position. Scrolls down by pages. Click to page down. Scrolls down by lines. Click to scroll down. Sizes window. Drag to size the window. Moves window. Drag to move the window.

Window border Close box Window number Window title Minimize box Maximize/Restore box Scroll up arrow Page up area Scroll box Page down area Scroll down arrow Size area Move bar

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 61 of 5 Printed: 10/09/00 02:48 PM

62

Environment and Tools

Figure 4.3 shows the PWB status bar. The table which follows it describes each of the status bars elements.

Figure 4.3 Name

Status Bar Elements Description Shows command buttons for the mouse and shortcut keys, and summarizes commands. Indicates current file, editor, and keyboard status, as described in the following table. Shows the location of the cursor in the file. Show common commands and shortcut keys. Click the button or press the key to execute the command. Indicates the line at the cursor. When scanning a file during a search or when loading a file, PWB displays the current line in the line indicator as specified by the Noise switch. Indicates the column at the cursor.

Message area Status Location Command buttons Line

Column

The status area of the status bar displays one of the following letters to indicate the corresponding status.
Letter T R L M P A X O C N Description File is temporary and is not recorded in the PWB status file. File is no-edit (read-only); modification is disabled. Line endings in the file are linefeed characters only. File is modified. File is a pseudofile. Meta prefix (F9) is active. Macro recording is turned on. Overtype mode is enabled. In insert mode, no indicator appears.
CAPS LOCK is on. NUM LOCK is on.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 62 of 6 Printed: 10/09/00 02:48 PM

Chapter 4 User Interface Details

63

Figure 4.4 shows the Window menu with the PWB Windows cascaded menu pulled down. The table which follows it describes each element of a menu.

Figure 4.4 Name Menu

PWB Menu Elements Description Displays a list of commands. Executes the command. When the command is dimmed, it is unavailable. Executes the command directly and bypasses the use of the menu. Press the key to execute the command. Lists a group of related commands. The command for a cascaded menu has a small right arrow after the command. To open a cascaded menu, click the command or move the selection cursor to the command and press the RIGHT ARROW key. To close an open cascaded menu, press the LEFT ARROW key. Executes the command. Press the highlighted letter key to execute the command. Indicates the selected command. Press the UP ARROW and DOWN ARROW keys to move the selection cursor. Press ENTER to execute the command.

Menu command Shortcut key Cascaded menu

Access key Selection cursor

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 63 of 7 Printed: 10/09/00 02:48 PM

64

Environment and Tools

PWB Menus
PWB commands are organized into menus; the menu names appear along the menu bar at the top of the screen. When a menu or command is selected, PWB displays a brief description of the selected menu on the status bar. To get more information about a menu or command, point the mouse cursor to the name and click the right mouse button, or highlight the name by using the arrow keys and then press F1.

File
The File menu provides commands to open, close, and save files. You can switch to any open PWB file or find a specific file on your disk. You can also print a selection, a file, or a list of files.
Command New Open Find Merge Next Save Save As Save All Close Print DOS Shell All Files Exit Description Start a new file Open an existing file Locate a file or list of files on disk Merge one or more files into the current file Open the next file in the list of files specified on the command line Save the current file Save the current file with a different name Save all modified files Close the current file Print a selection, the current file, or a list of files Temporarily exit to the operating system List all open files in PWB Leave PWB

Edit
The Edit menu provides commands to manipulate text, set the selection mode, and record macros.
Command Undo Redo Repeat Cut Description Reverse the effect of your recent edit Reverse the effect of the last Undo Repeat the last edit Delete selected text and copy it to the clipboard

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 64 of 8 Printed: 10/09/00 02:48 PM

Chapter 4 User Interface Details Command Copy Paste Delete Set Anchor Select To Anchor Stream Mode Box Mode Line Mode Read Only Set Record Record On Description Copy selected text to the clipboard Insert text from the clipboard Delete selected text without copying it to the clipboard Save the current cursor position Select text from the anchor to the cursor Set stream selection mode Set box selection mode Set line selection mode

65

Toggle the PWB no-edit state (to prevent accidental modification or to allow modification) Define a macro name and its shortcut key Record commands for a macro

Search
The Search menu provides commands to perform single-file and multifile text and regular-expression searches. You can do single-file and multifile find-andreplace operations. You can define and jump to marks or go to specific lines.
Command Find Replace Log Next Match Previous Match Goto Match Goto Mark Define Mark Set Mark File Description Search for an occurrence of a text string or pattern Search for a string or pattern and replace it with another Turn multifile searching on and off Move to the next match Move to the previous match Go to the match at the cursor in the Search Results window Move to a mark or line number Set a mark at the cursor Open or create a mark file

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 65 of 9 Printed: 10/09/00 02:48 PM

66

Environment and Tools

Project
The Project menu provides commands to open and create projects, build a project or selected targets in the project, and determine the location of build errors and messages.
Command Compile File Build Rebuild All Build Target New Project Open Project Edit Project Close Project Next Error Previous Error Goto Error Description Compile or assemble the current source file Build the project Build all files in the project (even those that have not been modified) Build specific targets in the project Create a new project Open an existing project Change the list of files in the project Remove the current project from memory without changing its contents Move to the next error Move to the previous error Move to the error at the cursor in the Build Results window

Run
The Run menu provides commands to set arguments for the projects program, run and debug the program, run operating-system commands, and add or run custom Run menu commands.
Command Execute Program Arguments Debug Run DOS Command Customize Run Menu Description Run the current program Specify commands passed to your program for Execute or Debug Run CodeView for the current program Perform any single DOS task without exiting PWB Add commands to the Run menu

The custom commands that you add to the Run menu appear after the Customize Run Menu command.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 66 of 10 Printed: 10/09/00 02:48 PM

Chapter 4 User Interface Details

67

Options
The Options menu provides commands to set environment variables for use within PWB, customize the look and behavior of PWB, and assign keys to commands. For projects, you can set the build type, customize the project template, and set assembler and utility options.
Command Environment Variables Key Assignments Editor Settings Colors Build Options Project Templates Language Options Description View and modify environment variables Assign keys that invoke functions and macros Change the setting of any PWB switch Change screen colors Specify whether the program is built as a debug or release version; specify a build directory Cascaded menu of commands for project templates Cascaded menu of compiler options commands

The Project Templates cascaded menu provides the following commands to manage project templates:
Command Set Project Template Customize Project Template Save Custom Project Template Remove Custom Project Template Description Changes the run-time support and project template Modify the current project template Save the current template as a new, custom template Delete custom project templates

The Language Options cascaded menu provides the following commands for setting assembler and compiler options for any other languages that may be installed:
Command MASM Options Description Set assembler options

Note Additional languages, such as Basic and FORTRAN, are listed when their PWB extensions are loaded. To load the Basic extension, rename PWBBASIC.XXT in the BIN subdirectory to PWBBASIC.MXT. For FORTRAN, do the same for PWBFORT.XXT.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 67 of 11 Printed: 10/09/00 02:48 PM

68

Environment and Tools

The following commands appear when the utilities extension (PWBUTILS) is loaded:
Command LINK Options NMAKE Options CodeView Options Description Set linker options for your project Set options for NMAKE when it builds the project Set options for CodeView when debugging the project

The following command appears when the browser extension (PWBROWSE) is loaded:
Command Browse Options Description Define the way the Source Browser database is built

Browse
The Browse menu provides the commands for the PWB Source Browser. You can select a browser database. You can jump to specific definitions or symbols in your project and view complex relationships among program symbols. You can also view your program as an outline, function-call tree, or, if you are using Microsoft C++, you can even view it as a class-inheritance tree.
Command Open Custom Goto Definition Goto Reference View Relationship List References Call Tree (Fwd/Rev) Function Hierarchy Module Outline Which Reference? Class Tree (Fwd/Rev) Class Hierarchy Next Previous Match Case Description Open a custom browser database, open the project database, or save the current database Locate the definition of any symbol in your source code Locate the references to any name in the browser database Query the browser database Display a list of functions that call each function and show the use of each variable, type, macro, or class View which functions call other functions Display a program outline Display an outline of program modules Display a list of possible references for the ambiguous reference at the cursor View the class-inheritance tree (for the C++ language) View the hierarchy of classes (for the C++ language) Find the next definition or reference Find the previous definition or reference Define whether or not browse queries are case sensitive

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 68 of 12 Printed: 10/09/00 02:48 PM

Chapter 4 User Interface Details

69

Window
The Window menu provides commands to manipulate and navigate windows in PWB.
Command New Close Close All Move Size Restore Minimize Maximize Cascade Tile Arrange PWB Windows PWB Window Build Results Search Results Print Results Record Clipboard Help Browser Output 1 window1 ... 5 window5 All Windows Description Duplicate the active window Close the active window Close all windows Start window-moving mode for the active window Start window-sizing mode for the active window Restore a minimized or maximized window to normal size Shrink the active window to an icon Enlarge windows to maximum size Arrange windows to show all their titles Arrange windows so that none overlap Organize windows in a useful configuration for viewing Help, source code, and Build Results Cascaded menu that lists the following special PWB windows: Description View the results of builds View the results of logged searches View the results of print operations View, edit, save recorded macros View the PWB clipboard Access the Help system View the results of browser queries Move to window n

View a list of all open windows

The All Windows command does not appear until the full list of open windows is too long to fit on the menu.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 69 of 13 Printed: 10/09/00 02:48 PM

70

Environment and Tools

Help
The Help menu contains commands to access the Microsoft Advisor Help system. You can see the index or table of contents for the system, get contextsensitive Help, and perform global plain-text searches in the Help.
Command Index Contents Topic Help on Help Next Global Search Search Results About Description Display a list of available indexes Display a table of contents for each component of the Help system Display Help about the item or keyword at the cursor Display information on how to use Help Display the next Help screen that has the same name as the topic you last viewed Search all open Help files for a string or regular expression View the results of the last global Help search Display the PWB copyright and version number

Executing Commands
PWB commands appear in menus and as buttons. You can execute these commands in two ways:
u

With a Microsoft Mouse or any fully compatible pointing device You perform mouse operations by clicking moving the mouse cursor to the specified item and briefly pressing the left mouse button. Double-click by pressing the left button twice, quickly. Always use the left mouse button unless specifically instructed otherwise. With the keyboard

Choosing Menu Commands

To choose a menu command with the mouse: 1. Click the menu name to open the menu. 2. Click the command. To choose a menu command from the keyboard: 1. Press the ALT key to activate the menu bar. 2. Press the highlighted character in the menu name (such as F for File). An alternative is:

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 70 of 14 Printed: 10/09/00 02:48 PM

Chapter 4 User Interface Details

71

1. Press the ALT key to activate the menu bar. 2. Use the RIGHT ARROW and LEFT ARROW keys to select a menu. 3. Press ENTER to open the menu. 4. Press the highlighted character in the command name (such as S for Save in the File menu), or use the UP ARROW and DOWN ARROW keys to select the command and then press ENTER. There are several ways to close an open menu without executing a command. To close a menu without executing a command: Do one of the following procedures: u Click outside of the menu. u Press ESC. u Press ALT twice. When a menu command is dimmed (rather than black), it is unavailable. For example, when no windows are open, the Close command on the File menu is unavailable. If a command you want to use is unavailable, you must perform some other action or complete a pending action before you can invoke that command.

Shortcut Keys
Some commands are followed by the names of keys or key combinations. Press the shortcut key to execute the command immediately. You dont have to go through the menu. For example, press SHIFT+F2 to execute the Save command, which saves the current file. All menu commands with shortcut keys and many other menu commands invoke predefined PWB macros to carry out their action. You can change the key or add new shortcut keys for these commands by assigning a key to the predefined macro. For a complete list of predefined macros and their corresponding menu commands, see Predefined PWB Macros on page 207. For more information on assigning keys, see Changing Key Assignments on page 109. Many PWB functions have been assigned to keys besides those listed on the menus. Choose the Key Assignments command on the Options menu to view a list of functions and macros and their assigned keys.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 71 of 15 Printed: 10/09/00 02:48 PM

72

Environment and Tools

Buttons
You can often execute commands by using buttons or boxes, which are areas of the screen that perform an action when you click them or select them from the keyboard. For example, the rectangle at the upper-left corner of a window is the close box. Clicking this box with the mouse closes the window. A command name surrounded by angle brackets (< >) appearing on the status bar or in a dialog box is a button. The following buttons are on the status bar when you first start PWB:
<General Help> <F1=Help> <Alt=Menu>

The General Help button brings up a screen that explains how to use the Help system. The other two buttons remind you of PWB functions: F1 summons Help, and ALT activates the menu bar. Clicking one of these buttons with the mouse performs the same function as pressing the key. When you have opened more than one window, PWB displays the following buttons:
<F1=Help> <Alt=Menu> <F6=Window>

Click the Window button or press

F6

to move to the next window.

When a menu is selected or a dialog box is displayed, an informative message appears on the status bar. While PWB displays this message, no buttons are available and clicking the status bar does nothing.

Dialog Boxes
When a menu command is followed by an ellipsis (...), PWB needs more information before executing the command. You enter this information in a dialog box that appears when you choose the command. Dialog boxes can contain any of the items in Figure 4.5.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 72 of 16 Printed: 10/09/00 02:48 PM

Chapter 4 User Interface Details

73

Figure 4.5

Dialog Box Elements

Option Button A button that you select from a list of mutually exclusive choices. Click the one you want, press its highlighted letter, or use the arrow keys to move among the choices. Text Box An area in which you can type text. You can move the cursor within the text box by clicking the location with the mouse or by pressing the LEFT ARROW and RIGHT ARROW keys. You can toggle between insert and overtype mode by pressing the INS key. To select text for deletion, click and drag the mouse over the text or press SHIFT plus an arrow key. Press DEL to delete the text, or type new text to replace the highlighted text. List Box A box displaying a list of information (such as the contents of the current disk directory). If the number of items exceeds the visible area, click the scroll bar to move through the list or press PGUP , PGDN, or the arrow keys. You can move to the next item in the list that starts with a particular letter by typing that letter.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 73 of 17 Printed: 10/09/00 02:48 PM

74

Environment and Tools

Combo Box The combination of a text box and a drop-down list box. You can type the name of an item in the text box or you can select it from the list. To open the list, click the highlighted arrow, or press ALT+DOWN ARROW or ALT+UP ARROW. You can then click the item or press the arrow keys to select the item you want. You can also press the first letter of an item to select it. When you have selected an item, click the highlighted arrow or press ALT+DOWN ARROW or ALT+UP ARROW to close the list. Command Button A button within angle brackets (< >) that invokes a command. Choose the OK button to accept the current options, or choose the Cancel button to exit the dialog box without changing the current options. Choose the Help button to see Help on the dialog box. If one of the command buttons in a dialog box is highlighted, press ENTER to execute that command. You can also click a command button to execute that command. If a button contains an ellipsis (...), it indicates that another dialog box will appear when you choose it. Check Box An on/off switch. If the box is empty, the option is turned off. If it contains the letter X, the option is turned on. Click the box with the mouse, or press the SPACEBAR or the UP ARROW and DOWN ARROW keys to toggle a check box on and off. Key Box A pair of braces ({ }) that allows you to enter a key by pressing the key. The key box is always followed by a text box where you can type the name of the key. When the cursor is in the key box (between the braces), most keys lose their usual meaning, including ESC, F1, and the dialog box access keys. The key you press is interpreted as the key to be specified. Only TAB, SHIFT+TAB, ENTER, and NUMENTER retain their usual meaning. To specify one of these keys, type the name in the text box.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 74 of 18 Printed: 10/09/00 02:48 PM

Chapter 4 User Interface Details

75

Figure 4.6

Key Box and Check Box

Clicking a dialog-box item either selects it (a text box, for example) or toggles its value (a check box or option button). You can also move among items with the TAB and SHIFT+TAB keys. Dialog boxes usually contain access keys, identified by highlighted letters. Pressing an access key is equivalent to clicking that item with the mouse or moving to it by pressing TAB or SHIFT+TAB, and then pressing ENTER. Although some access keys are uppercase and others lowercase, dialog boxes are not case sensitive. Therefore, you can type either an uppercase or a lowercase character. Note When the cursor is in a text box, access keys are interpreted as text. You must press ALT along with the highlighted letter. Pressing ALT is also required in list boxes because typing a letter by itself moves the cursor to the next item that starts with that letter.

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 75 of 19 Printed: 10/09/00 02:48 PM

76

Environment and Tools

Filename: LMAETC04.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 86 Page: 76 of 20 Printed: 10/09/00 02:48 PM

77

C H A P T E R

Advanced PWB Techniques

This chapter introduces you to some of the powerful features in the Programmers WorkBench. It is not an exhaustive discussion of all the ways to use PWB. However, it can provide a starting point for you to begin your own investigation of PWB using the information in the Microsoft Advisor and in Chapter 7, Programmers WorkBench Reference. This chapter contains:
u

u u u

Find and search-and-replace techniques, including marks and regular expressions. How to use the PWB Source Browser. How to execute PWB functions and macros. An overview of PWB macros, macro recording, and the macro language.

Searching with PWB

PWB offers the following ways to search your files for information:
u

Visually inspecting code, moving with the cursor or the PGUP and PGDN keys. This method is most effective either when you are familiarizing yourself with some old code or after you have switched from CodeView back to PWB and want to examine the local impact of a proposed change. Searching with text strings. When you have a specific string in mind (for example, FileName), you can find, in sequence, all the references to the name in your file. Searching with regular expressions. Regular expressions describe patterns of text. This is useful when you have a number of similarly named program symbols and youd like to see them all in succession. For example, Windows API (application programming interface) names are made up of multiple words; the start of each new word is shown as a capital

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 77 of 1 Printed: 10/09/00 02:38 PM

78

Environment and Tools

letter (for example, GetTextMetrics). With this in mind, you might search for a string optionally starting with spaces and the letters GetText followed by any uppercase letter. This is expressed with a regular expression such as *GetText[A-Z], which means zero or more spaces (using the * operator after a space), followed by GetText, followed by any uppercase letter (using a character class).
u

Searching multiple files with text strings or regular expressions. A multifile search is called a logged search. Instead of finding one match, PWB finds all matches in one operation. You can then browse the results of the search. Using the Source Browser. The Source Browser enables you to perform faster and more sophisticated searches than plain text searches because it maintains a complete database of relationships between program symbols. For example, to find all occurrences of FileName in your entire program (regardless of the number of files in the program), you can use the View References command from the Browse menu. The Source Browser has many more capabilities than just finding symbols. It can also produce call trees and perform sophisticated queries on the use-anddefinition relationships among functions, variables, and classes in your program.

These searching techniques are discussed in detail in the following sections.

Searching by Visual Inspection

If you think youre close to the text you want to see, dont try a fancy search use the PGUP or PGDN key. Its often faster. One trick you can use to speed up this method of searching is to leave a trail in the form of marks (names associated with file locations).

Using Marks
PWB lets you set named marks at any location in your file by using the Define Mark command from the Search menu or by using the Mark function. You can access these locations by name using the Goto Mark command or the Mark function. For example, if you are writing code and want to leave certain sections until later, or if you are revising an existing program and dont fully understand all the algorithms, you might leave a mark at each location in the code you want to come back to. That way, you can work on some sections of the program first, and then come back to the marked areas after further research. To save marks between PWB sessions, create a mark file using the Set Mark File command from the Search menu.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 78 of 2 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

79

Using the Find Command

The Find command on the Search menu allows you to search a file using text strings and regular expressions. Searching forward uses the Psearch function (assigned to the F3 key), while searching backwards uses the Msearch function (assigned to the F4 key). Find can help you locate any string of text in any file you specify. PWB usually searches the file you are currently editing. However, it can also search a list of files. This is particularly useful for finding all occurrences of a string in an entire project. The function used is called Mgrep. The results of a multifile search are logged, that is, put into the Search Results window. To see the logged results of a search, choose Search Results from the PWB Windows cascaded menu. There are two ways to use the information that PWB puts into Search Results:
u

You can look at the matches in sequence by choosing Next Match and Previous Match from the Search menu. You can go directly to a specific match by moving the cursor to the match listed in the Search Results window and choosing Goto Match from the Search menu. PWB then jumps to the location of the match.

The Match commands on the Search menu work with the Search Results window in exactly the same way that the Project menus Next Error, Previous Error, and Goto Error commands work with the Build Results window. These Project menu commands are described in Fixing Build Errors on page 23. To illustrate the logged-search technique, suppose you want to locate all instances of a software interrupt instruction in the SHOW projects source files. To search all the source files in this project: 1. From the Search menu, choose Find. PWB brings up the Find dialog box. 2. Turn on Log Search check box. 3. Type int in lowercase. 4. Select the Match Case check box to exclude uppercase or mixed-case occurrences of the word.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 79 of 3 Printed: 10/09/00 02:38 PM

80

Environment and Tools

5. Choose the Files button. PWB brings up the Search In Selected Files dialog box.

6. Type SHOW*.ASM in the File Name text box. This wildcard specifies all filenames beginning with SHOW and having the .ASM extension. 7. Choose the Add Pattern button to add the wildcard to the file list. 8. In the Drives / Dirs window, select the SAMPLES\SHOW subdirectory under the main MASM directory. 9. Return to the File Name text box by clicking the box or by pressing ALT+F. 10. Type $INCLUDE:dos.inc (with the environment variable, INCLUDE, all in caps). Preceding an environment variable name with a dollar sign causes the contents of that variable to be inserted into the search string. The INCLUDE variable normally contains the path to the directory where general-purpose include files are kept. 11. Press ENTER to add DOS.INC to the file list, or click Add / Delete. 12. Choose OK to start the search. When PWB finishes the search, it displays the Log Search Complete dialog box.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 80 of 4 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

81

From this dialog box you can:

u u

Choose View Results to open the Search Results window. Choose Cancel to close the dialog box.

Choose Cancel now (you will open the Search Results window later). To go to the first match: From the Search menu, choose Next Match. You can step sequentially through all occurrences of the string using the Next Match command. Choose Previous Match to move to the previous occurrence of the string. When you reach the end of Search Results, PWB displays the following message:
End of Search Results

Sometimes, you cannot focus the search narrowly enough to make a sequential scan of Search Results profitable. In this example, you wanted only instances of the software interrupt instruction, but PWB found many more occurrences of int. In these cases, you can examine the results of the search and skip the matches that arent relevant. To view the Search Results: To see all matches from the search, open the Search Results window. You can do this by choosing Search Results from the PWB Windows cascaded menu on the Window menu.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 81 of 5 Printed: 10/09/00 02:38 PM

82

Environment and Tools

In the Search Results window, PWB displays the file, line, and column where the string was located. It also shows as much of the matching line as will fit in the window.

For example, if the instruction you were looking for is the Interrupt 10h in PAGERR.ASM, .you can jump directly to that location. To jump directly to a match: 1. Put the cursor on the match. 2. From the Search menu, choose Goto Match. PWB opens the correct file if it is not already open and positions the cursor on the text you located. You can use multifile searching regardless of whether the files that you want to search are open in PWB.

Using Regular Expressions

The PWB searching capabilities that you have used so far are useful when you know the exact text you are looking for. Sometimes, however, you have only part of the information that you want to match (for example, the beginning or end of the string), or you want to find a wider range of information. In such cases, you can use regular expressions.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 82 of 6 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

83

Regular expressions are a notation for specifying patterns of text, as opposed to exact strings of characters. The notation uses literal characters and metacharacters. Every character that does not have special meaning in the regular-expression syntax is a literal character and matches an occurrence of that character. For example, letters and numbers are literal characters. A metacharacter is an operator or delimiter in the regular-expression syntax. For example, the backslash (\) and the asterisk (*) are metacharacters. PWB supports two syntaxes for regular expressions: UNIX and non-UNIX. Each syntax has its own set of metacharacters. The UNIX metacharacters are .\[]*+^$. The non-UNIX metacharacters are ?\[]*+^$@#(){}. Because it uses fewer metacharacters, the UNIX form is a little more verbose. However, it is more familiar to programmers who have experience with UNIX tools such as awk and grep. This book uses the UNIX syntax, but any expression that can be written with this syntax can also be written with the non-UNIX syntax. The regular-expression syntax used by PWB depends on the setting of the Unixre switch (this is a Boolean switch, and UNIX is the default). You can change the Unixre switch by using the Editor Settings dialog box on the Options Menu. Note PWB switches that take regular expressions always use UNIX syntax. They are independent from the Unixre switch.

Finding Text
In the multifile searching example, you learned how to locate every occurrence of int in the SHOW project. In a large project, finding every int would yield too many matches. To narrow the search, you can use a regular expression. For this example, lets say you want to match any int instruction. You can specify this with a regular expression. The expression below matches text that:
u u u

Begins with the keyword int Is followed by white space Is followed by one or more hex digits (characters between 0 and 9 or between A and F)

The syntax for this regular expression is shown in Figure 5.1.

Figure 5.1

Regular Expression Example

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 83 of 7 Printed: 10/09/00 02:38 PM

84

Environment and Tools

It illustrates the following important features of regular expressions: 1. Regular expressions can contain literal text. In this example, int is literal text and is matched exactly. 2. Regular expressions can contain predefined regular expressions. Here, \:b is shorthand for a pattern that matches one or more spaces or tabs (that is, white space). For a complete list of predefined regular expressions, see Appendix B. 3. You can use classes of characters in regular expressions. A class matches any one character in the class. For example, the class [0-9a-f] is the class of characters that contains the digits between 0 and 9 and the lowercase letters between A and F. The dash ( ) defines a range of characters in a class. 4. The plus sign (+) after the class instructs PWB to look for one or more occurrences of any of the characters in the class. This is the key to regular expressions. You dont have to know exactly what the interrupt number is; all you have to do is describe what kind of characters make it up. The pattern int\:b[0-9A-F] matches strings such as
int 21h int 3Ah ; Print 25 lines... ; DOS function interrupt

Figure 5.2 shows a more detailed way to write an expression that matches only an int 20h or an int 21h.

Figure 5.2

Complex Regular Expression Example

This expression is more precise than most searches require, but it is useful as an illustration of how to write a complex regular expression. You can interpret this expression as follows:

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 84 of 8 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

85

1. Start at beginning of the line, which is specified by a caret (^) at the beginning of the regular expression. Using an initial caret is particularly helpful in a situation like this if your file uses space characters rather than tabs. Otherwise, when you begin your search criteria with \:b, the search will return one match for every space character preceding the matching text. For example, if your instruction column is indented eight spaces, searching for \:bmov\:b will return eight copies of every mov instruction, one for each of the preceding space characters. Including the inital caret, however, will result in only one match per line. 2. Skip any label on the line, without matching a comment line. The [^; \t] indicates a class made up of any characters that are not a semicolon, a space or a tab character. Within brackets, a caret (^) at the beginning of the class indicates an inverse class, that is, one including all characters except the specified ones. Following the class is an asterisk, indicating that zero or more such characters may be present. In general, optional items are specified using the asterisk (*) operator, which indicates that zero or more of the preceding character should be matched. For example, the expression * means match zero or more spaces. 3. Skip white space. The predefined UNIX regular expression \:b is equivalent to [ \t]+, which requires that there be at least one space or tab. 4. Look for the int instruction as literal text. 5. Skip white space. The expression [ \t]+ is equivalent to \:b, and requires that there be one or more space or tab. 6. Skip optional 0 digits. 7. Look for a 2 digit as literal text. 8. Look for either a 0 digit or a 1 digit. 9. Look for an uppercase or lowercase h character. This expression is so exact that it may take longer to write than the time it saves. The key to using regular expressions effectively is determining the minimal characteristics that make the text qualify as a match. To find all int 20h and int 21h instructions: 1. From the Search menu, choose Find. 2. In the Find Text box, type ^\:bint\:b2[01]. 3. Select the Regular Expression check box. 4. Choose the Files button. 5. Add the pattern *.ASM and the file $INCLUDE:DOS.INC to the file list. 6. Choose OK to start the search.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 85 of 9 Printed: 10/09/00 02:38 PM

86

Environment and Tools

When the search is complete, choose View Results. You can see in the Search Results window that PWB matched only the int 20h and int 21h instructions.

Replacing Text
You can use regular expressions when changing text to achieve some extremely powerful results. A regular expression replacement can be a simple one-to-one replacement, or it can use tagged expressions. A tagged expression marks part of the matched text so that you can copy it into the replacement text. For example, you can manipulate lists of files easily using regular expressions. This exercise shows how to get a clean list of files that is stripped of the size and time-stamp information. To get a clean list of .ASM files in the current directory: 1. From the File menu, choose New. This gives you a new file for the directory listing. 2. Execute the function sequence Arg Arg !dir *.ASM Paste. The default key sequence for this command is to press type!dir *.asm, then press SHIFT+INS.
ALT+A twice,

Arg Arg introduces a text argument to the Paste function with an Arg count of two. The exclamation point (!) designates the text argument to be run as an operating-system command. Without the exclamation point, the text is the name of a file to be merged. If only one Arg is used, PWB inserts the text argument. PWB runs the DIR command and captures the output. When the DIR command is complete, PWB prompts you to press a key. When you press a key, PWB then inserts the results of the command at the cursor. For more information about this and other forms of the Paste function, see Paste in Chapter 7, Programmers WorkBench Reference. 3. From the Search menu, choose Replace. 4. In the Find Text box, type \:b\:z \:z-.*$ This pattern means:
u u u u u

White space followed by A number followed by Exactly one space followed by A number followed by A dash () followed by

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 86 of 10 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

u u

87

Any sequence of characters, then End of the line

This string must be tied to the end of the line to prevent the search from finding anything too close to the beginning of the line. 5. Make sure there are no characters in the Replace Text text box. 6. Choose Replace All. PWB prompts you to verify that you want to replace text with an empty string. 7. Choose OK to confirm that you want to perform the empty replacement. All the file-size, date, and time-stamp information is removed. Because you did not reuse any of the original text in the replacement, this is a simple regular expression replacement. Choose Close from the File menu to discard the text you created in the previous exercise. A more complicated task is backing up the .ASM files to a directory called LAST, which is assumed to be a subdirectory of the current directory. A batch file makes this easier. You can create such a batch file using regular expressions. To create a batch file that copies the .ASM files to a subdirectory: 1. Create a list of .ASM files in the current directory as described in the previous example, but do not remove the file sizes, dates, and times. 2. Delete the heading printed by the DIR command. 3. From the Search menu, choose Replace. 4. In the Find Text text box, type ^\([^ ]+\)[ ]+\([^ ]+\).* 5. This expression finds a string that starts at the beginning of the line (^). Placing parts of the expression inside the delimiters \( and \) is called tagging. The first tagged expression (\([^ ]+\)) matches one or more characters that are not spaces. A leading caret in a class means not. The pattern then matches one or more spaces ([ ]+), followed by the second tagged expression which matches one or more characters that are not spaces. The remainder of the line is matched by the wildcard (.), which matches any character, and the repeat operator (*). Matching the rest of the line is important because that is how this pattern removes everything after the filename. It discards these portions of the matched text.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 87 of 11 Printed: 10/09/00 02:38 PM

88

Environment and Tools

6. In the Replace Text text box, type COPY \1.\2 .\\LAST 7. Select Replace All and choose OK to begin the find-and-replace operation. PWB transforms each directory entry into a command to copy the file to the LAST subdirectory.

The word COPY is inserted literally. The text matched in the first tagged expression (the base name) replaces the expression \1. The period is inserted literally. The text matched by the second tagged expression (the filename extension) replaces the expression \2. The space is inserted literally. The text .\\LAST is inserted as .\LAST. Be sure to use two backslashes to indicate a literal backslash; otherwise, PWB expects a reference to a tagged expression such as \1 and displays an error message. Youll notice that the last two lines of the file are not useful in your batch file. They are the remnants of the summary statistics produced by the DIR command. Delete these two lines and you have a finished batch file.

Using the Source Browser

Another search technique is browsing. Browsing uses information generated by the compiler to help you find pieces of code quickly. This section introduces you to some of the capabilities of the Source Browser. The browser is a handy tool for moving about in projects, large and small.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 88 of 12 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

89

In addition to navigating through your program, you can use the browser to explore the relationships between parts of the project. The browser database contains full information about where each symbol is defined and used and about the relationships among modules, constants, macros, variables, functions, and classes. Note that the browser files can be very large.

Creating a Browser Database

Before you can use the PWB Source Browser, you must build a browser database. PWB helps you maintain this database automatically as a part of a normal project build. To build a browser database: 1. Open the SHOW project using the Open Project command from the Project menu (this project is located in the SAMPLES\SHOW subdirectory of your main MASM directory). 2. From the Options menu, choose Browse Options. PWB displays the Browse Options dialog box.

3. Select the Generate Browse Information check box. 4. Choose OK. The browser changes the project makefile to build the project. It adds compiler options for creating browser information (.SBR files). It includes a BSCMAKE command which combines the .SBR files and creates a browser database (a .BSC file). 5. From the Project menu, choose Rebuild All. Rebuilding the entire project ensures that the database contains up-to-date information for all files in your program.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 89 of 13 Printed: 10/09/00 02:38 PM

90

Environment and Tools

When the build completes, the following new files are on your disk:
u u u u

SHOW.BSC, the browser database SHOWUTIL.SBR, a zero-length placeholder for the SHOWUTIL module. PAGER.SBR, a placeholder for PAGER. SHOW.SBR, a placeholder for SHOW.

After adding each .SBR files contribution to the database, BSCMAKE truncates it and leaves the empty .SBR file on disk to provide an up-to-date target for later builds. Leaving these files on the disk ensures that a browser database is not rebuilt unless it is out of date with respect to its source files. A PWB project is not required to create a browser database (although it is convenient). For information on how to build a browser database for non-PWB projects, see Building Databases for Non-PWB Projects on page 94.

Finding Symbol Definitions

When you are working on a program, its easy to forget where a particular variable, constant, or function is defined. You can use the Find command to locate occurrences of a symbol, but that offers little information about which one is the definition. To make such searches easier, you can choose Goto Definition from the Browse menu to jump directly to the definition of any symbol in your program. The following procedure uses the SHOW project to demonstrate how powerful the browser can be. To investigate the GetNamePos procedure: 1. From the Window menu, choose Close All. 2. Open SHOW.ASM. 3. Go to line 174 (from the Search menu, choose Goto Mark, type 174, and press ENTER). 4. Move the cursor to the GetNamePos procedure. 5. From the Browse menu, choose Goto Definition. PWB displays the Goto Definition dialog box.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 90 of 14 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

91

Notice that GetNamePos is highlighted and the defining files name is displayed in the list box to the right. More than one defining file is listed if a name is defined in several scopes. 6. Choose OK. PWB opens SHOWUTIL.ASM and shows the definition of GetNamePos.

Showing the Call Tree

Often when analyzing an existing programs flow, or when looking for opportunities for optimization, its useful to refer to a call tree. A call tree is a view of your program that provides, for each function, a list of other functions called. To generate a call tree of SHOW: 1. From the Browse menu, choose Call Tree. PWB displays the Display Tree dialog box.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 91 of 15 Printed: 10/09/00 02:38 PM

92

Environment and Tools

2. Choose SHOW.ASM from the Modules list box. Notice that the Functions list box changes to show only the functions in SHOW.ASM. 3. Choose OK to see the call tree. Three kinds of annotations appear in the call tree: ? A symbol followed by a question mark is used by your program but not defined in any of the program files in the browse database. These are often library functions. [n] The number n between square brackets shows symbols that are used more than once. In the preceding example, GetNamePos is listed (under SHOW.ASM) as:
GetNamePos[3]

This means that there are three references to GetNamePos in SHOW. ... (ellipsis) The ellipsis means that the full information for the function appears elsewhere in the call tree.

Finding Unreferenced Symbols

As you write, rewrite and maintain a program, you will occasionally remove function calls or references to global variables, leaving unused code or data space in your program. Since the browser database contains information about where every function and variable is referenced, you can easily identify ones that are not used. This section shows how to use the Source Browser to find and remove the extra code and data.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 92 of 16 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

93

The system include files define many more functions than most programs use. Therefore, unreferenced functions in your program are easiest to find when using a browser database that does not contain the system include files. This example begins by building a browser database for SHOW that does not contain information defined by system include files. To build the SHOW browser database: 1. From the Options menu, choose Browse Options. PWB displays the Browse Options dialog box. 2. In the Browse Options dialog box, select the Generate Browse Information, the Exclude System Include Files, and the Include Unreferenced Symbols check boxes. 3. Choose OK. Now that the browse options are set, rebuild the project and browser database by choosing Rebuild All from the Project menu. With the updated browser database, you can obtain a list of references for functions and variables. To get a list of references for function and variables: 1. From the Browse menu, choose List References. PWB displays the List References dialog box.

2. Select the Functions, Variables and Macros options, and then choose OK. PWB opens the Browser Output window and creates the list of references. Each name is followed by a colon and a list of functions that refer to the name. To find an unreferenced symbol: Search for the regular expression :$ (colon, dollar sign). This pattern specifies a colon at the end of the line. It finds names that are followed by an empty list of references.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 93 of 17 Printed: 10/09/00 02:38 PM

94

Environment and Tools

In the list of references created above for SHOW, a search for this expression will find no matches, since there are no unreferenced symbols.To find all unreferenced items with one search, you can perform a logged search and add only <browse> (the Browser Output pseudofile) to the file list. This is especially useful for large projects. To go to the definition of an unreferenced symbol in the source: 1. Place the cursor on the symbol in question. From the Browse menu, choose Goto Definition. PWB automatically selects the definition of the symbol under the cursor. However, if the symbol begins with @ or ? or other punctuation characters, the nonalphabetic character is not automatically recognized as part of the symbol name. To include it, mark the entire name before choosing Goto Definition. 2. Choose OK. PWB jumps to the definition of the selected symbol in the appropriate source file, where you can remove the unused function, macro or variable.

Advanced Browser Database Information

In the previous sections, you learned the basics of building a browser database and some useful applications of the Source Browser. In this section, you will find information on what goes into a browser database and how to estimate the disk requirements to build one. You will also learn how to build a database for non-PWB projects and how to build a single database for related projects.

Estimating .SBR and .BSC File Size

When you build a browser database, you first create an .SBR file for each source file in the project. Each of these files contains the following information:
u u

u u u

The name of the source file and the files it includes. Every symbol defined in the source file and the files it includes. These symbols are the names of all functions, types (including the names of all classes, structures, and enumerations and their members), macros (including symbols in the expanded macro), and variables in the file. These symbols also include all parameters and local variables for the functions. The location of all symbol definitions in the files. The location of all references to every symbol in the files. Linkage information.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 94 of 18 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

95

This is a tremendous amount of information about your program and can therefore occupy a large quantity of disk space. The benefit is that the Source Browser provides fast, sophisticated access to this database of knowledge about your program. For assembler source files, the .SBR file may be between a quarter and a half the size of the preprocessed source file (that is, the source file with comments removed, all files included, and all macros expanded). You might assume that the resulting browser database (.BSC file) is approximately the sum of all the .SBR files. However, the browser database is the union of the information in the component .SBR files. This means that the .BSC file is usually not very large. Much of the information in the .SBR files is defined in include files, which are common to many modules in the project. The union of the .SBR files is relatively small because most of the include-file information is duplicated in each .SBR file. Even for C or C++ programs, which tend to create much larger .BSC files, a good-sized program will seldom require a .BSC file larger than 500K.

Building Databases for Non-PWB Projects

The simplest way to build a browser database for non-PWB projects is to build the browser database separately from the project. You can use a makefile or a batch file for this purpose. The process requires only two steps: 1. Create an .SBR file for each module. The simplest way to do this is to run the compiler with the options to produce an .SBR file and no other files. For example, the ML command line:
ML /Zs /W0 /Fr *.asm

specifies that the compiler processes all .ASM files in the current directory, checks syntax only (/Zs) and issues no warnings (/W0). Therefore, no object files are produced. However, browser information (.SBR files) are generated ( /Fr). 2. Combine the .SBR files into a browser database. The syntax for this command is: BSCMAKE options /o project.BSC *.sbr For complete information on BSCMAKE options and syntax, see Chapter 19. The process of creating a browser database changes little between projects. Therefore, you could use a batch file for many projects similar to the following example:

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 95 of 19 Printed: 10/09/00 02:38 PM

96

Environment and Tools

ECHO OFF REM Require at least one command-line option IF %1.==. GOTO USAGE REM Compile to generate only .SBR files ML /Zs /W0 /Fr *.asm REM Build the browser database BSCMAKE %2 %3 %4 %5 %6 %7 %8 /o%1.BSC *.sbr GOTO END :USAGE REM Print instructions ECHO -Usage: %0 project [option]... ECHO project Base name of browser database ECHO [option]... List of BSCMAKE options :END

This batch file assumes that all the project sources are in the current directory. It requires that you specify the name of the browser database and allows BSCMAKE options. You may want to change this file to specify different BSCMAKE or assembler options. If your projects sources are distributed across several directories, you must write a custom batch file or makefile to build the database. For more information on the BSCMAKE utility, see Chapter 19. To use a custom browser database in PWB: 1. From the Browse menu, choose Open Custom. 2. Choose the Use Custom Database button. 3. Select your custom browser database and choose OK. If you want to save this database name permanently, choose Save Current Database. 4. Choose OK. The PWB Source Browser opens your custom database. You can now browse your non-PWB project. If you are using a makefile to build your project, you can choose Open Project from the Project menu and open it as a non-PWB project makefile. If the project makefile has the same base name as the browser database and resides in the same directory, PWB automatically opens the database when you open the project. For more information on using a non-PWB makefile for a project in PWB, see Using a Non-PWB Makefile on page 55.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 96 of 20 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

97

Building Combined Databases

If you have two or more closely related projects, you can combine the browser databases for the projects. For example, if two large programs differ only in one or two modules so that most of the sources are shared between the two projects, it can be useful to browse both projects with a single browser database. To build a combined browser database: 1. Generate the .SBR files for both projects. 2. Pass all of the .SBR files to BSCMAKE to build the combined database. The resulting database is the inclusive-OR of the information in the two projects.

Executing Functions and Macros

The menus and dialog boxes in PWB provide access to almost everything you need to do to develop your projects. You can edit, search, and browse your source files. You can build, run, and debug your project, and you can view Help for the entire system. However, the visible display provides access to only part of the capabilities available in PWB. Behind the menu commands lie functions with many more options than you can access from the menus. Many functions and macros are not assigned to keys by default. The sophisticated PWB user learns how to use the functions and predefined macros to perform the precisely correct action. Each function has several forms that are invoked with the combinations of the Arg and Meta prefixes. These two functions are used to introduce arguments and modify the action of PWB functions. Arg (ALT+A) The fundamental function in PWB. You use Arg to begin selecting text, introduce text and numeric function arguments, or modify the action of functions by increasing the Arg count. To pass a text argument to a function, for example, press ALT+A, and then type the text. The text you type doesnt go into your file. The Text Argument dialog box appears when you type the first letter of the text.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 97 of 21 Printed: 10/09/00 02:38 PM

98

Environment and Tools

You can then edit the text. PWB displays the current argument count and Meta state in the dialog box. Notice that there is no OK button in this dialog box. Instead of choosing OK, press the key for the function you want to execute with this argument. Choose the Cancel button if you do not want to execute a function. Meta (F9) Modifies the action of a function in different ways from the various argument types. It generally toggles an aspect of the functions action. For example, the text-deletion functions usually move the deleted text to the clipboard. However, when modified with Meta, they clear the text without changing the clipboard. The combination of Arg and Meta greatly increases the number of variations available to each function. For example, the Psearch function can perform different search operations depending on how it is executed. Psearch can:
u u u u u

Repeat the previous search (Psearch). Search for text (Arg text Psearch). Perform a case-sensitive text search (Arg Meta text Psearch). Search for a regular expression (Arg Arg text Psearch). Search for a case-sensitive regular expression (Arg Arg Meta text Psearch).

Because you can reassign keys to your preference, the PWB documentation cannot assume that a specific key executes a given function or macro. Therefore, the PWB documentation gives a sequence of functions or macros by name, followed by the same sequence of actions by key name. In this book, the key is the default key. In PWB Help, the displayed key is the one currently assigned to that function. When no key is assigned, PWB displays unassigned. For example, to insert the definition of a macro at the cursor, you pass the name of the macro to the Tell function and modify Tells action with the Meta prefix. This sequence of actions is expressed as follows:
u

Execute the function sequence Arg Meta macroname Tell (ALT+A F9 macroname CTRL+T).

If the Tell function is assigned to a different key, Help displays that key in place of CTRL+T. Chapter 7, Programmers WorkBench Reference, contains complete descriptions of all forms of each function in PWB.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 98 of 22 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

99

Executing Functions and Macros by Name

The most frequently used functions and macros are assigned to certain keys by default. For example, the Paste function is assigned to SHIFT+ENTER, Linsert is assigned to CTRL+N, and so on. Sometimes, however, you want to use a function or macro that is not assigned to a key. You can always assign a key by using the Key Assignments command or by using the Assign function. However, that is a lot of trouble for something you need only once. PWB allows you to execute a function or macro by name, rather than by pressing a key. To execute a function or macro by name: Perform the function sequence Arg function Execute (ALT+A function F7). In other words, press ALT+A (execute the Arg function), type the name of the function or macro, and then press F7 (invoke the Execute function). The argument to Execute doesnt have to be a single function or macro name. It can be a list of functions and macros. The argument is really a temporary, nameless macro. This means that you can do anything in an argument to Execute that you can do in a macro. PWB follows the rules for macro syntax and execution. You can define labels, test function results, and loop. Warning When executed from a macro, PWB functions that display a yes-or-no prompt assume a Yes response. To restore the prompt, use the macro prompt directive (<). For more information, see Macro Prompt Directives in PWB Help.

Writing PWB Macros

The Programmers WorkBench, like other editors designed for programmers, provides a macro language so that you can customize and extend the editor or automate common tasks. You can create macros in one of the following ways:
u

By recording actions you perform. The recording mechanism allows you to perform a procedure once, while PWB is recording. After youve recorded it, you can execute the macro to repeat the recorded procedure. By manually writing macros. This technique is less automatic but does allow you to write more powerful macros.

These two techniques are not mutually exclusive. You can start by recording a macro that approaches the steps you want to perform, then edit it to expand its functionality or handle different situations.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 99 of 23 Printed: 10/09/00 02:38 PM

100

Environment and Tools

When Is a Macro Useful?

Macros are useful for automating procedures you perform frequently. You may also write macros that automate tedious one-time tasks. Of course, not every task is a good candidate for automation. It might take longer to write the macro than to do the task by hand. If you dont expect to perform a task often, dont automate it. Also, automated editing procedures introduce an element of risk. You might not foresee situations that your macro can encounter. Incorrect macros can sometimes be destructive. A little experience with macros and some careful testing will enable you to create a good set of macros for your own use.

Recording Macros
Recording actions you perform with the mouse or at the keyboard can be a powerful way to write a macro. You turn on recording and perform the actions that you want the macro to execute. You can concentrate on the task that you want to automate, instead of concentrating on the syntax of the macro language. For example, if you occasionally reverse characters when you type quickly, a macro to transpose them is useful. Before recording a macro to transpose characters, you should think about what you are going to do while recording the macro. To transpose characters, you will select the character at the cursor, cut it onto the clipboard, move over one character, and then paste the character you cut. To record a macro that transposes characters: 1. From the Edit menu, choose Set Record. PWB brings up the Set Macro Record dialog box.

2. In the Name text box, type Transpose. 3. Click the mouse in the key box (between the braces { }), or press the cursor is in the key box. 4. Press CTRL+SHIFT+T (for transpose).

TAB until

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 100 of 24 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

101

PWB automatically fills in the name of the key you pressed.

5. Press TAB to leave the key box, and then choose OK. PWB closes the Set Macro Record dialog box. When you turn on macro recording, PWB records a macro called Transpose and associates it with SHIFT+CTRL+T. Important The Set Macro Record command does not start the macro recorder. It only specifies the name and key association for the macro you are going to record. 6. From the Edit menu, choose Record On. When you choose Record On, the macro recorder starts. To indicate that the macro recorder is running, PWB displays the letter X on the status bar. Notice that the Project, Options, and Help menus are unavailable while PWB is recording a macro. 7. Select the character at the cursor by holding down the SHIFT key and pressing the RIGHT ARROW key. 8. Press SHIFT+DEL to cut the character onto the clipboard. 9. Press the RIGHT ARROW key to move the cursor to the new location for the character.

Filename: LMAET05A.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Harold S. Henry Last Saved By: Mike Eddy Revision #: 89 Page: 101 of 25 Printed: 10/09/00 02:38 PM

Chapter 5 Advanced PWB Techniques

101

10. Press SHIFT+INS to paste the character from the clipboard back into the text. 11. From the Edit menu, choose Record On to stop the macro recorder. Press SHIFT+CTRL+T to switch the character at the cursor with the character to the right. You can now use the new macro and key assignment for the rest of the PWB session. To edit the macro: From the Window menu, choose Record from the PWB Windows cascaded menu. PWB opens the Record window.

The Record window shows the definition of the Transpose macro that you just recorded. You can edit the definition to change the way the macro works. For example, you decide that the macro should reverse the character at the cursor with the character to the left, instead of the character to the right. To redefine the macro: 1. Change the macro to read as follows:
Transpose:=select left delete left paste

2. Move the cursor to the macro definition.

Filename: LMAET05B.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 6 Page: 101 of 1 Printed: 10/09/00 02:50 PM

102

Environment and Tools

3. Press ALT+=, the default key for the Assign function. Assigning the macro replaces the previous definition of Transpose with the new definition. 4. Return to the file you were originally viewing. Up to this point, the macro exists only in memory. To use your recorded macro for subsequent PWB sessions, you must save the definition of the macro to disk. To save the macro: 1. If the Record window is not open, choose Record from the PWB Windows cascaded menu. PWB opens the Record window. 2. From the File menu, choose Save. PWB inserts the macro definition and the key assignment into your TOOLS.INI file for future sessions. When you leave PWB, you are prompted to save TOOLS.INI. Your changes are not permanent until you actually save TOOLS.INI.

Flow Control Statements

Recorded macros have the inherent limitation of playing back one fixed sequence of commands. Often you need a macro to execute repeatedly until some condition is satisfied. This requires that you use flow control statements to govern the actions your macro takes. All editor functions return a true or false value. The macro flow control operators that use these values are:
Operator +>label >label =>label :>label Meaning Branch to label if last function yields TRUE Branch to label if last function yields FALSE Branch unconditionally to label Define label

These rudimentary operators are not as sophisticated as a high-level languages IF statement or FOR loop. They are more like an assembly languages conditional jump instruction. However, they provide the essential capabilities needed for writing loops and other conditional constructs.

Filename: LMAET05B.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 6 Page: 102 of 2 Printed: 10/09/00 02:50 PM

Chapter 5 Advanced PWB Techniques

103

Flow Control Example

If you frequently perform multiple-window editing, a macro that restores the display to a single window can be helpful. Such a macro requires the following logic: 1. Switch to the next window. 2. If the switch is not successful (meaning that only one window is present), end the macro. 3. If the switch is successful (another window is present), close that window and go back to step one. This macro will be called CloseWindows and assigned to SHIFT+CTRL+W. To create the CloseWindows macro: 1. From the File menu, choose All Files. PWB displays the All Files dialog box. Notice that your TOOLS.INI file is in the list of open files, even though you did not explicitly open it. PWB opens TOOLS.INI to load its configuration information (unless when you specify /DT on the PWB command line). 2. Select TOOLS.INI file in the list of open files. 3. Choose OK. PWB opens a window and displays your TOOLS.INI file. 4. Find the section of TOOLS.INI that begins with [pwb]. This is the section where PWB keeps its startup configuration information. 5. In the PWB section, type the following two new lines:
CloseWindows:= :>Loop Openfile -> Meta Window Window =>Loop CloseWindows: SHIFT+CTRL+W

If you want these definitions to take effect immediately, select both lines and press ALT+= to execute the Assign function. You can also assign the definitions one at a time. 6. Choose Save from the File menu to make this macro and key assignment part of your TOOLS.INI file. The next time you start PWB, the CloseWindows macro is defined and assigned to the SHIFT+CTRL+W key. The first line you typed uses the := operator to associate the macro definition with the name CloseWindows. After the operator is the list of functions and macro operators that specify what the macro is to do. The second line is a

Filename: LMAET05B.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 6 Page: 103 of 3 Printed: 10/09/00 02:50 PM

104

Environment and Tools

SHIFT+CTRL+W

separate statement that uses the : operator to assign the macro to the key.

The CloseWindows macro works as follows: 1. Loop defines a label called Loop. There cannot be a space between the :> operator and the label name. 2. Openfile switches to the window under the active window. 3. The -> operator examines the return value from the Openfile function. If the function returns false because there is no other window, the -> operator exits the macro. 4. The phrase Meta Window closes the active window. 5. Window returns to the window you started from. 6. Loop unconditionally transfers control back to the Loop label and starts the sequence again. When this macro is defined, you can press SHIFT+CTRL+W whenever you want to close all windows except the active window.

User Input Statements

PWB macros can prompt for input. This helps you write more general macros. For example, you might keep a history of the changes you make to a file at the top in a format similar to the following:
//** Revision History ** //15-Nov-1991:IAD:Add return value for DoPrint //31-Oct-1991:IAD:Implement printing primitives

To facilitate entering the revision history in reverse chronological order and to make it easy to keep track of where you were in the source file, you can write a macro to perform the following steps: 1. Set a mark at the cursor for future reference. 2. Insert a revision history header at the beginning of the file if one is not present. 3. Insert the current date. 4. Prompt for initials and insert them just below the header. 5. Prompt for comments and insert them after the initials. 6. Return to the saved position in the file. Note that while this macro is executing, you can choose the Cancel button in the dialog boxes that prompt for initials and comments. The macro must handle these cases and gracefully back out of the changes to the file.

Filename: LMAET05B.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 6 Page: 104 of 4 Printed: 10/09/00 02:50 PM

Chapter 5 Advanced PWB Techniques

105

To enter this macro in TOOLS.INI: 1. Open TOOLS.INI for editing. 2. Type the following macros and key assignment in the [pwb] section of TOOLS.INI:
LineComment:=// " RevHead:= "** Revision History **" RevComment:= \ Arg Arg "Start" Mark \ Begfile Arg RevHead Psearch +>Found \ Linsert LineComment RevHead \ :>Found \ Down Linsert Begline LineComment Curdate " (" \ Arg "Initials" Prompt ->Quit Paste Endline ") " \ Arg "Comment" Prompt ->Quit Paste =>End \ :>Quit Meta Ldelete \ :>End Arg "Start" Mark RevComment:Ctrl+H

There are at least two spaces before the backslash at the end of each line. The backslashes are line-continuation characters. They allow you to write a macro that is more than one line long. In this case, line continuations format the macro in a readable way. To further assist in readability, you can indent the parts of the macro which define the actual keystrokes, as in the preceding example. 3. Choose Save from the File menu to save your changes. 4. To reinitialize PWB, execute the Initialize function by pressing SHIFT+F8. PWB discards all of its current settings and rereads the PWB section of TOOLS.INI. The same effect can be achieved by quitting and restarting PWB. The following discussion analyzes the workings of the definitions you added to TOOLS.INI. It repeats one or two lines from the text you typed and describes how each line works. You may want to refer to the full definition as you follow along. The first two lines
LineComment:="//" RevHead:= "** Revision History **"

define two utility macros that are used by the main RevComment macro. They define strings that are used several times in RevComment. The third line

Filename: LMAET05B.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 6 Page: 105 of 5 Printed: 10/09/00 02:50 PM

106

Environment and Tools

RevComment:= \

declares the name of the macro. The succeeding lines define the action of the RevComment macro.

Filename: LMAET05B.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 6 Page: 106 of 6 Printed: 10/09/00 02:50 PM

Chapter 5 Advanced PWB Techniques

107

The first line of the definition

Arg Arg "Start" Mark \

sets a mark named Start at the cursor so that the macro can restore the cursor position after inserting the comments at the beginning of the file. The next line
Begfile Arg RevHead Psearch +>Found \

moves to the beginning of the file (Begfile), then searches forward for the revision-history header. If the header is found, PWB branches to the Found label; otherwise, it executes the next line.
Linsert LineComment RevHead \

If the macro is here, the header was not located in the file. The Linsert function creates a new line, and PWB types the revision-history header. The macro continues with the line:
:>Found \

This line defines the Found label. At this point in the macro, the cursor is on the line with the header. The next lines insert the new revision information, starting with the following line:
Down Linsert Begline LineComment Curdate " (" \

PWB moves the cursor down one line (Down ), inserts a new line (Linsert ), moves to the beginning of the line (Begline), and calls the LineComment macro to designate the line as a comment. PWB then types the current date (Curdate) and an open parenthesis. The macro prompts for initials:
Arg "Initials" Prompt ->Quit Paste Endline ") " \

The macro uses the Prompt function to get your initials. If you choose the Cancel button, the function returns false, so the macro branches to the label Quit. If you choose the OK button, the text you typed in the dialog box is passed to the Paste function, which inserts the text. The macro moves the cursor to the end of the line (Endline) and types a closing parenthesis. The code on this line explicitly handles the case when you cancel the prompt (the false condition). The phrase ->Quit causes PWB to skip to the label Quit when Prompt returns false. If you use the Prompt function and you do not handle the false condition, a null argument (a text string with zero length) is passed to the next function.

Filename: LMAET05B.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 6 Page: 107 of 7 Printed: 10/09/00 02:50 PM

108

Environment and Tools

Therefore, a phrase like Arg "Que?" Prompt Paste pastes either the input or nothing, depending on whether you choose the OK or Cancel button. Passing a null argument to Paste is harmless, but some functions require an argument. In these cases, you can use the -> operator to terminate the macro. The RevComment macro uses an explicit label so that it can end the macro without an error when you choose the Cancel button. The next line of the macro is almost the same as the previous line in the macro.
Arg "Comment" Prompt ->Quit Paste =>End \

On this line, if the paste is carried out, an unconditional branch is taken to the label End and passes over the Quit branch, which is defined on the next line.
:>Quit Meta Ldelete \

The Quit branch is taken when you cancel a prompt. The macro has to clean up the text already inserted by the macro. The Meta Ldelete function deletes the incomplete line that would have been the revision-history entry. The next line defines the last step of the macro.
:>End Arg "Start" Mark

The End label defines the entry point for the common cleanup code. This line restores the cursor to the initial position when you invoked the macro. Because this line does not end in a line-continuation character (\), it is the end of the RevComment macro. The last line that you typed is not part of the RevComment macro. It is a separate TOOLS.INI entry.
RevComment:Ctrl+H

This line assigns the CTRL+H key to the RevComment macro. You can polish this macro by adding Arg "Start" Meta Mark to the end of the macro. This phrase deletes the mark. A better alternative is to use the Savecur and Restcur functions instead of named marks. However, this example uses named marks to illustrate how to use them in a macro.

Filename: LMAET05B.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 6 Page: 108 of 8 Printed: 10/09/00 02:50 PM

Chapter 5 Advanced PWB Techniques

109

Filename: LMAET05B.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 6 Page: 109 of 9 Printed: 10/09/00 02:50 PM

109

C H A P T E R

Customizing PWB

PWB is a completely customizable development environment. You can modify PWB in the following ways:
u u

u u u

Changing mapping of keystrokes to actions. Changing default behavior of PWB (for example, how tabs are handled or if PWB automatically saves files). Changing the colors of parts of the PWB display. Adding new commands to the Run menu. Programming new editor actions (macros). Instructions on how to write macros are in Writing PWB Macros on page 98.

In addition to the customizations that you can make by using the commands in the Options menu, you can also customize PWB by editing the TOOLS.INI file. Note Another category of customization that is not covered in this book is how to write PWB extensions. An extension is a dynamically loaded module that can access PWBs internal functions. Extensions can do much more than macros. To learn more about writing PWB extensions, see the Microsoft Advisor Help system (choose PWB Extensions from the main Help table of contents).

Changing Key Assignments

PWB maps actions (functions and macros) to keys. You can assign any of these actions to keys other than the default keys. For example, Exit is a PWB function. Its default key assignment is user may prefer to use ALT+X to leave the editor.
F8.

A BRIEF

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 109 of 1 Printed: 10/09/00 02:42 PM

110

Environment and Tools

To make ALT+X execute the Exit function: 1. From the Options menu, choose Key Assignments. PWB displays the Key Assignments dialog box.

2. Select Exit in the Macro/Function List box, or type exit in the Macro/Function Name text box. 3. Move the cursor to the New Key box between the braces ({}) by clicking between the braces or by pressing ALT+K. 4. Press ALT+X. PWB types ALT+X in the text box after the braces and displays the name of the macro or function that ALT+X is currently assigned to. With the default settings, you can see that ALT+X is assigned to the Unassigned function. Pressing a key in the key box is a quick way to find out the name of the function assigned to the key. Note When the cursor is in the key box (between the braces), most keys lose their usual meaning, including ESC, F1, and the dialog box access keys. The key you press is interpreted as the key to be assigned. Only TAB, SHIFT+TAB, ENTER, and NUMENTER retain their usual meaning. To assign one of these keys, type the name of the key in the text box. 5. Press TAB to move the cursor out of the key box. 6. Choose Assign.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 110 of 2 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB

111

PWB assigns Exit to the ALT+X key. Note that Exit is still assigned to the F8 key. Functions can be assigned to many keys. 7. Choose OK. Important To change a key, you must choose the Assign button. The OK button dismisses only the dialog box. It does not perform any other action. This design allows you to assign many keys in one session with the dialog box. The change remains in effect for the duration of the session. To make a permanent key assignment: 1. From the Options menu, choose Key Assignments. 2. Choose Save. PWB displays the Save Key Assignments dialog box, which lists all of the unsaved assignments that you have made during the PWB session by using the Key Assignments dialog box. 3. Delete any settings that you do not want to save. 4. Choose OK. PWB writes your new settings into the [PWB] section of TOOLS.INI for subsequent sessions. When you exit PWB, you are prompted to save TOOLS.INI. Your changes are not permanent until you actually save the file to disk. If you already know the function name, you can make a quick assignment for the current session by using the Assign function instead of going through the Key Assignments dialog box. To assign a key using the Assign function: Execute the function sequence: Arg function:key Assign (ALT+A function:key ALT+=). For example, to assign Exit to ALT+X: 1. Press ALT+A to execute Arg. 2. Type exit:ALT+X 3. Press ALT+= to execute Assign. The assignment is in effect for the rest of the PWB session. The key assignments you make by using the Assign function are not listed in the Save Key Assignments dialog box.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 111 of 3 Printed: 10/09/00 02:42 PM

112

Environment and Tools

To discover the name of the function or macro that is currently assigned to a key, use the Key Assignments dialog box (as previously described) or use the Tell function. To find a current key assignment using Tell: 1. Press CTRL+T to execute Tell. PWB displays the prompt:

2. Press the key you want to find out about. If you press F10, PWB displays the function assigned to the F10 key (Openfile).

The Tell function has many other uses in addition to displaying key assignments. For more information on Tell, see page 202.

Changing Settings
When you first use PWB, you dont have to specify the tab stops, whether the editor starts in insert or overtype mode, and so on. These settings (called switches) are all covered by defaults. PWBs default behavior can be extensively customized by changing the values of PWB switches. Switches fall into three categories:
u

Boolean switches. True/false or on/off switches that can also be specified as yes/no or 0/1. An example of a Boolean switch is Autosave, which governs whether PWB saves a file when you switch to a different one. Numeric switches. An example of a numeric switch is Undocount, which determines the maximum number of editing actions you can undo. Text switches. Examples of a text switch are Markfile, the name of the file in which to store marks, Tabstops, a list of tab-stop intervals, and Readonly, the operating-system command for PWB to run when saving a read-only file.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 112 of 4 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB

113

To change the setting for Tabstops: 1. From the Options menu, choose Editor Settings. PWB displays the Editor Settings dialog box. 2. Tabstops is a text switch (not a numeric switch as you might expect), so select the Text option button. 3. Select Tabstops in the Switch List box. PWB shows the current setting for Tabstops in the Switch text box at the top of the dialog box. 4. Move to the Switch text box by clicking in the box or by pressing PWB selects only the switch value, instead of the entire text. 5. Type the new setting:
3 4 7 8

ALT+S.

This setting defines a tab stop at columns 4, 8, 15, and every eight columns thereafter. At this point, the Editor Settings dialog box should look like:

6. Choose the Set Switch button to change the setting of the Tabstops switch. 7. Choose OK.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 113 of 5 Printed: 10/09/00 02:42 PM

114

Environment and Tools

Important To change a setting you must choose the Set Switch button. The OK button only dismisses the dialog box. It does not perform any other action. This design allows you to set many switches in one session with the dialog box. The new tab stops you set are used for the current session. If you want to use this setting permanently, you must choose the Save button in the Editor Settings dialog box. This changes your TOOLS.INI file in the same way as for key assignments. You can make temporary switch assignments for the current session by using the Assign function. You do this in the same way as for a key assignment by typing Arg switch:value Assign (ALT+A switch:value ALT+=). You may be curious about the Switch Owner box that you did not use in this example. The Switch Owner is either PWB or a PWB extension such as PWBHELP (the extension that provides the Microsoft Advisor in PWB). Type or select a switch owner to set switches for that extension. Each extension has its own section in TOOLS.INI. Note When you choose Set Switch, most switch settings take effect immediately. However, changes to the Height switch do not take effect until you choose OK.

Customizing Colors
You can change the color of almost any item in the PWB interface. For a table showing the names and meanings of PWBs color settings, see page 252 in Chapter 7, the Programmers WorkBench Reference. Some displays show a brilliant green for the left and right triangular symbols surrounding buttons in Help. To change the light green to light cyan: 1. From the Options menu, choose Colors. PWB displays the Colors dialog box.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 114 of 6 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB

115

2. Select Helpitalic in the Color list box. 3. Select Cyan in the Foreground list box. 4. Choose Set Color. To verify your change, press F1. The green symbols in help are now light cyan blue. While you are viewing Help, you can find out what parts of PWB the rest of the color names determine. To leave Help, choose the Cancel button or press ESC. PWB returns you to the Colors dialog box. The Bright Fore and Bright Back check boxes determine if the given color is the usual version of the color or the bright version of the color. Bright black, for example, is usually a dark gray color. If you want to save your new colors for subsequent sessions, choose the Save button. PWB displays the Save Colors dialog box where you can delete modifications that you dont want to save. When you choose OK in the Save Colors dialog box, PWB modifies TOOLS.INI to record your changes.

Adding Commands to the Run Menu

You can add up to six commands to the Run menu to integrate your own utilities into PWB. A command is the name of any executable (.EXE or .COM) file, batch (.BAT) file, or built-in operating-system command such as DIR or COPY. Suppose you use an outline processor to keep project notes. You can start the outline processor from PWBs Run menu.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 115 of 7 Printed: 10/09/00 02:42 PM

116

Environment and Tools

To add a command to the Run menu: 1. From the Run menu, choose Customize Run Menu. 2. Choose the Add button. PWB displays the Add Custom Run Menu Item dialog box for you to describe your custom menu item:

3. Type Project ~Notes... in the Menu Text box. The tilde (~) before the letter N indicates the highlighted access letter for the menu command. The ellipsis (...) uses the standard convention to indicate that the command will require more information before it is completed. An ellipsis is commonly associated with a dialog box command but can be used in this context as well. 4. Specify the full path to the outlining program, OUTLINE.EXE, in the Path Name text box. (The program name OUTLINE.EXE is for example purposes only. Substitute the name of your own outliner or other program in its place.) 5. Specify the arguments you want to pass to the outliner in the Arguments text box: %|dpfF.log. This example illustrates a powerful feature of PWB: its ability to extract parts of the filename to form a new name for customized menu items. The specification %|dpfF extracts the drive (d), path (p), and base name (f) of the current file. Anything after F is added to the end of the name. For example, if the current file is C:\SOURCE\COUNT.ASM, the argument that PWB passes to the program is C:\SOURCE\COUNT.LOG.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 116 of 8 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB

117

6. In the Help Line text box, type the explanatory message that appears on the status bar when you browse this menu item:
Run the OUTLINE program

7. Choose OK to confirm your entries. PWB adds the command to your Run menu and modifies TOOLS.INI to save the new item. You can now access your outline processor directly from the Run menu.

Note You can add other text processing or word processing programs to the Run menu. If you change the current file using another program, PWB prompts you to update the file or to ignore the changes made by the other program.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 117 of 9 Printed: 10/09/00 02:42 PM

118

Environment and Tools

How PWB Handles Tabs

The following functions and switches control how PWB handles tabs:
Name Realtabs Entab Tabalign Filetab Tabdisp Tab Backtab Tabstops Type Switch Switch Switch Switch Switch Function Function Switch Description Determines if PWB preserves tabs on modified lines The white space translation method The alignment of the cursor within a tab field The width of a tab field The fill-character for displaying tab fields Moves the cursor to the next tab stop Moves the cursor to the previous tab stop Tab positions for Tab and Backtab

For detailed information on each function and switch, see Help or Chapter 7, Programmers WorkBench Reference. For instructions on how to set a switch see Changing Settings on page 112. For instructions on how to assign a function to a key, see Changing Key Assignments on page 109. To understand how PWB handles tabs, you need to know only a few facts:
u

u u u

The Tab (TAB) and Backtab (SHIFT+TAB) cursor-movement functions and the Tabstops switch have nothing to do with tab characters. They affect cursor movement, rather than the handling of tab characters, and are not discussed further here. For more information on these items, see Chapter 7, Programmers WorkBench Reference. PWB never changes any line in your file unless you explicitly modify it (lines longer than PWBs limit of 250 characters are the exception). Some text editors translate white space (that is, entab or detab) when they read and write the file. PWB does not translate white space when it reads or writes a file. This is to be compatible with source-code control systems that would detect the translated lines as changed lines. PWB translates white space according to the Entab switch only when you modify a line. Tabalign has an effect only when Realtabs is set to yes. A tab break occurs every Filetab columns. When PWB displays a tab in the file, it fills from the tab character to the next tab break with the Tabdisp character. Figure 6.1 illustrates how PWB displays tabs.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 118 of 10 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB

119

Figure 6.1
u

How PWB Displays Tabs

When translating white space, PWB preserves the exact spacing of text as it is displayed on screen.

To set the width of displayed tabs, change the setting of the Filetab switch. To tell PWB to translate white space on lines that you modify, set the Realtabs switch to no and the Entab switch to a nonzero value, according to the translation method that you want to use. The Entab switch takes one of the following values:
Entab
0 1 2

Translation Method Translate white space to space characters Translate white space outside of quotation-mark pairs to tabs Translate white space to tabs

To preserve white space exactly as you type it, set the Realtabs switch to yes and the Entab switch to 0. When Realtabs is yes, the Tabalign switch comes into effect. When Tabalign is set to yes, PWB automatically repositions the cursor onto the physical tab character in the file, similar to the way a word processor positions the cursor. When Tabalign is set to no, PWB allows the cursor to be anywhere in the tab field. If you want the TAB key to type a tab character, assign the TAB key to the Graphic function. Note that when a dialog box is displayed, the TAB key always moves to the next option. You can always use the following method to type a tab character, whether you are in a dialog box or an editing window. To type a literal tab character in your text or in a dialog box: 1. Execute the Quote function (press CTRL+P). 2. Press TAB.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 119 of 11 Printed: 10/09/00 02:42 PM

120

Environment and Tools

Examples
The following example sets up tabs so that they act the same as in other Microsoft editors, such as QuickC or Word:
realtabs:yes tabalign:yes graphic:tab trailspace:yes entab:0

The Trailspace switch is needed so that the TAB key will have an effect on otherwise blank lines. To save your file so that it does not include any actual tab characters (ASCII 9), use the following settings:
realtabs:no entab:0 tabstops:3

The Tabstops value determines the number of spaces inserted for each press of the tab key. Another example of a common tab configuration is one in which the TAB key inserts a tab in insert mode but moves over text to the next tab stop when the editor is in overtype mode. First, use the following tab settings:
realtabs:yes tabalign:yes

Then insert the following macro into the PWB section of your TOOLS.INI:
;Insert mode and overtype mode tabbing TabIO:= Insertmode +>over Insertmode "\t" => :>over Insertmode Tab TabIO:TAB \

For more information on PWB macros see Writing PWB Macros on page 98.

PWB Configuration
PWB keeps track of three kinds of information between sessions in these three files:
File TOOLS.INI Information Saved Configuration and customizations, such as key assignments, colors, and macro definitions

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 120 of 12 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB CURRENT.STS project .STS The editing environment used most recently The editing and building environment for a project

121

TOOLS.INI is described in the next section: The TOOLS.INI File. For more information about CURRENT.STS, see Current Status File CURRENT.STS on page 128, and for more information about the project.STS files, see Project Status Files on page 129. When you start PWB, it reads the TOOLS.INI file, loads PWB extensions, and reads the CURRENT.STS or project status file in the following order: 1. PWB reads the [PWB] section of TOOLS.INI (except when PWB is started using the /D or /DT command-line options). For more information on tagged sections, see TOOLS.INI Section Tags. If the [PWB] section contains Load switches, PWB loads the specified extension when each switch is encountered. When PWB loads an extension, it also reads the extensions tagged section of TOOLS.INI, if any. For example, when the Help extension is loaded, PWB reads the [PWBPWBHELP] section of TOOLS.INI. 2. PWB autoloads extensions (except when the /D or /DA option is used to start PWB). The automatic loading of PWB extensions is described in the next section, Autoloading Extensions. 3. PWB reads the TOOLS.INI operating-system tagged section (except when /D or /DT is used). 4. PWB reads the CURRENT.STS status file (except when /D or /DS is used to start PWB). 5. PWB reads the TOOLS.INI tagged section for the file extension of the current file (except when /D or /DT is used to start PWB). 6. PWB runs the Autostart macro if it is defined in TOOLS.INI (except when /D or /DT is used).

Autoloading Extensions
PWB automatically loads extensions if they follow a specific naming convention and reside in a certain directory. For extensions that follow the convention, it is not necessary to put load statements in TOOLS.INI. PWB searches the directory where the PWB executable file is located for filenames with the following pattern:
PWB*.MXT

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 121 of 13 Printed: 10/09/00 02:42 PM

122

Environment and Tools

PWB loads as many extensions with names of this form as it finds. When PWB loads an extension, it also loads the extensions tagged section of TOOLS.INI. To suppress extension autoloading, use the /DA option on the PWB command line.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 122 of 14 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB

123

Important Do not rename editor extensions. PWB and some extensions may assume the predefined filename.

The TOOLS.INI File

PWB, like other Microsoft tools, stores information in a file called TOOLS.INI. This file retains information about how you want PWB to work under various circumstances. PWB expects to find this file in the directory specified by your INIT environment variable. TOOLS.INI is a text file. You can edit it using PWB or any other text editor. PWB also can store information directly to TOOLS.INI when, for example, you choose the Save Colors button in the Colors dialog box. PWB modifies this file when you save a recorded macro, a changed switch, a new key assignment, a custom browser database, or a custom project template.

TOOLS.INI Section Tags

The TOOLS.INI file is divided into sections, separated by tags. These tags are specified in the form: [[tagname]] The tagname is the base name of an executable file, such as NMAKE, CVW, or PWB. The tag defines the start of a TOOLS.INI section that contains settings for the indicated tool. PWB extends this simple syntax to enable you to take different action depending on the operating system or the current files extension. The extended syntax is: [[PWB-modifier]] The modifier can be the base name of a PWB extension, an operating systems identifier, or a filename extension for files that you edit.

Operating-System Tags
The following table lists the operating-system tags for various operating environments. If you are running the Windows operating system, use the tag for the version of MS-DOS that you are running.
Tag [PWB-4.0] [PWB-5.0] Operating Environment MS-DOS versions 4.0 and 4.01 MS-DOS version 5.0

Be sure to use the correct version number for your operating system.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 123 of 15 Printed: 10/09/00 02:42 PM

124

Environment and Tools

Filename-Extension Tags
The operating-system tags are read only once at startup. PWB reads the filename-extension tagged sections each time you switch to a file with that extension. For example, suppose that you want the tab stops for MASM files to be every eight columns, and every five columns for text files. To set tab options based on filename extension: 1. Open your TOOLS.INI file in an editing window. 2. Create a MASM section by typing the tag:
[PWB-.ASM PWB-.INC ]

3. Create a text file section by typing the tag:

[PWB-.TXT]

4. Put the appropriate Tabstops, Entab, and Realtabs switches in each section. The lines that begin with a semicolon are comments.
[PWB-.ASM PWB-.INC ; Set the tab stops for MASM to 8 tabstops : 8 ; Translate white space to tabs entab : 1 realtabs : no [PWB-.TXT] ; Set the tab stops for text files to 5 tabstops : 5 ; Translate white space to spaces entab : 0 realtabs : no

Depending on whether the current file is a MASM (.ASM or .INC) file or a text (.TXT) file, the tab stops are set at 8 or 5 columns, respectively. PWB reads multiple sections and applies the appropriate settings. You can use this to your advantage by storing all your general settings in the [PWB] section and storing differences in separate tagged sections. Filename-extension tagged sections are useful for the kinds of files you edit most frequently. However, its impossible to define settings for every conceivable extension. To handle this case, PWB provides a special extension (..) that means all extensions not defined elsewhere in TOOLS.INI. For example, to set tab stops to 5 for all files except MASM files, modify the preceding example to use the [PWB-..] tag in place of [PWB-.TXT].

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 124 of 16 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB

125

Note When you choose the Save button in the Key Assignments, Editor Settings, and Colors dialog boxes, and when you save a recorded macro or custom Run menu command, PWB saves the setting in the main section. If the setting is for a PWB extension, it is saved in that extensions tagged section. PWB never modifies or writes settings in a filename-extension or operating-system section.

Named Tags
You can define tagged sections of TOOLS.INI that you load manually. Use manually loaded sections to make special key assignments, to load complex or rarely used macros, or to use a special PWB configuration under a particular circumstance. The syntax for a manually-loaded section tag is: [PWB-name] Where name is the name of the tagged section. A single section of TOOLS.INI can be given several tag names. These tags have the form: [PWB-name1 PWB-name2...] When you want to use the settings defined in one of these named sections, pass the name of the section to the Initialize function (SHIFT+F8). To read a tagged section of TOOLS.INI: Execute Arg name Initialize (ALT+A name SHIFT+F8) You can use this method to read any tagged section, including the automatically loaded sections. Note When you execute Initialize with no arguments, PWB clears all the current settings before reading the [PWB] section, including settings that you have made for specific PWB extensions. PWB does not reread the operatingsystem or other additional sections of TOOLS.INI. To reread the main section without clearing other settings that you want to remain in effect, label the main PWB section with the tag [PWB PWB-main]. You can then use Arg main Initialize to recover your startup settings, instead of using Initialize with no arguments.

TOOLS.INI Statement Syntax

Within each TOOLS.INI section you place a series of comments or statements. Each statement is a macro definition, key assignment, or switch setting, and

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 125 of 17 Printed: 10/09/00 02:42 PM

126

Environment and Tools

must be stated on a single logical line. Statements can be continued across lines by using line-continuations.

General Macro Syntax

The general syntax for a macro definition is: name := definition PWB does not reserve any names. Therefore, be careful not to redefine a PWB function. For more information about how to write macros, see Writing PWB Macros on page 98.

General Key Syntax

The general syntax for a key assignment is: name : key The name is the name of a function or macro, and the key is the name of a key. To see how to write a given key, use the Tell function as described in Changing Key Assignments on page 109. Note that certain keys have fixed meanings when the cursor is in a dialog box or in the Help window. You can assign one of these keys to a function or macro, but the fixed meaning is used in a dialog box or the Help window. The following keys have fixed meanings:
Key
ESC F1 TAB SHIFT+TAB SPACEBAR ENTER, SHIFT+ENTER, NUMENTER, SHIFT+NUMENTER

Dialog Box Choose Cancel See Help on the dialog box (choose Help) Move to the next option Move to the previous option Toggle the setting of the current option Choose the default action

Help Window Close the Help window See Help on the current item Move to the next hyperlink Move to the previous hyperlink Activate the current hyperlink Activate the current hyperlink

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 126 of 18 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB

127

Note The Windows operating system or a terminate-and-stay-resident (TSR) program may override PWBs use of specific keys. PWB has no knowledge of keys that are reserved by these external processes. PWB lists these keys as available keys in the Key Assignments dialog box and allows you to assign functions to these keys, but you may not be able to use them. See the documentation for your operating environment to see what keys are reserved by the system.

General Switch Syntax

The general syntax for a switch setting is: switch : value The exact syntax for the switch value depends on the switch. See Chapter 7, PWB Reference, for more information about each switch.

Line Continuation
All statements in TOOLS.INI must be stated on a single logical line. A logical line can be written on several physical lines by using the TOOLS.INI linecontinuation character, the backslash (\). The backslash must be preceded by a space to be treated as a line-continuation character. Precede the backslash by two spaces if you want the concatenated statement to contain a space at that location. If the backslash is preceded by a tab, PWB treats the tab as if it were two spaces. The backslash should be the last character on the line except for spaces or tabs. The backslash in the following statement is not a line continuation.
Qreplace:CTRL+\

However, the backslash at the end of the first line below is a line continuation.
findtag:=Arg Arg "^\\[^\\]+\\]" Psearch ->nf Arg Setwindow => :>nf Arg "no tag" Message \

In this example, the backslash is preceded by two spaces. The first space is included to separate ->nf from Arg in the concatenated macro definition. The second space identifies the backslash that follows it as the line-continuation character.

Comments
In the TOOLS.INI file, PWB treats the text that follows a semicolon (;) up to the end of the line as a comment. To specify the beginning of a comment, you must place the semicolon at the beginning of a line or following white space.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 127 of 19 Printed: 10/09/00 02:42 PM

128

Environment and Tools

For example, the first semicolon in the following statement is part of a command, and the second semicolon begins a comment.
Printcmd:lister -t4 %s -c; ;Print using lister program

In the following example, the first semicolon is a key name, and the second semicolon begins a comment.
Sinsert:CTRL+; ;Stream insertion: CTRL plus semicolon

Semicolons inside a quoted string do not begin a comment.

Environment Variables
The INIT environment variable tells PWB where to find the TOOLS.INI file and where to store the CURRENT.STS file. In general, the INIT, TMP, LIB, INCLUDE, HELPFILES, and PATH environment variables must all be properly set for your development environment to work smoothly. To set the INIT environment variable from the command line: u Type SET INIT=C:\INIT The operating-system SET command sets the environment variable to contain the string C:\INIT. This example presumes that you want to store your initialization files in C:\INIT. You could use any other directory. Make sure that the INIT environment variable lists a single directory. Multiple directories in INIT can cause inconsistent behavior. The following list outlines how the environment works:
u

The environment is always inherited from the parent process. The parent is the process that starts the current process. In MS-DOS, the parent is often COMMAND.COM or the Windows operating system. Inheritance of environment variables is a one-way process. A child inherits from its parent. You can make changes to the environment in a child (when you use the Environment Variables command in PWB, for example), but they are not passed back to the parent. This means that any changes to environment variables that you make while shelled out are lost when you return to PWB. Each MS-DOS session under the Windows operating system inherits its environment from the Windows operating system. Changes made to the environment in one session do not affect any other session.

The best way to make sure your environment is set properly is to explicitly set it in one of your startup files. These are:
u

CONFIG.SYS

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 128 of 20 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB

u

129

AUTOEXEC.BAT

PWB can save the complete table of environment variables for each project. You can then use the Environment Variables command from the Options menu to change environment variables for individual projects. If you prefer that PWB save the environment variables for all PWB sessions or use the current operating-system environment when it starts up, change the Envcursave and Envprojsave switches. For more information on these switches, see the Programmers WorkBench Reference on pages 259 and 260.

Current Status File CURRENT.STS

The first time you run PWB or CodeView, it creates a CURRENT.STS (current status) file in your INIT directory. If there is no INIT directory, PWB and CodeView create the file in the current directory. CURRENT.STS keeps track of the following items for PWB:
u

u u u u u

Open windows, including their size and position and the list of open files in each window Screen height Window style Find string Replace string The options used in a find or find-and-replace operation, such as the use of regular expressions Optionally, all environment variables

PWB and CodeView share the current location and filename for the active window. When you leave CodeView after a debugging session and return to PWB, PWB positions the cursor at the place where you stopped debugging. For more information on the items that CodeView saves in CURRENT.STS, see The CURRENT.STS State File on page 316. The next time you run PWB, it reads CURRENT.STS and restores the editing environment to what it was when you left PWB. For more information on how PWB uses environment variables, see Environment Variables on page 127. The status files are plain text files. You can load one into an editor and read it. However, you might corrupt the file if you try to modify it. There is no need to modify it because PWB keeps it updated for you. No harm occurs if you delete CURRENT.STS. However, you will have to manually reopen the files you were working on.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 129 of 21 Printed: 10/09/00 02:42 PM

130

Environment and Tools

Project Status Files

For each project, PWB creates a project status file. PWB stores this file in the project directory and gives it the name project.STS, where project is the base name of the project. Project status files contain the same kind of information that CURRENT.STS contains, except on a per-project basis. This scheme allows PWB to keep track of your screen layout, file history, and environment variables for each project. The project status files also contain the current project template, language and utility options, build directory, and the programs run-time arguments. The main difference between the two status files is that the CURRENT.STS file supplies default status information settings that PWB uses when you have not set a project. PWB uses the projects status file when you open that project. PWB can also save all environment variables, including PATH, INCLUDE, LIB, and HELPFILES, depending on how the envcursave and envprojsave switches are set. For more information, see Environment Variables on page 127. Important While it is harmless to delete CURRENT.STS, you should not delete project status files. They contain important information for building and updating your project. If you delete a project status file, you may need to delete the project makefile and start over.

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 130 of 22 Printed: 10/09/00 02:42 PM

Chapter 6 Customizing PWB

131

Filename: LMAETC06.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 100 Page: 131 of 23 Printed: 10/09/00 02:42 PM

131

C H A P T E R

Programmers WorkBench Reference

PWB Command Line

Syntax Options PWB [[options]] [[/t]] files Use the following case-insensitive options when starting PWB: /D[[S|T|A]]... Disables PWB loading the initialization files or PWB extensions as indicated by the following letters:
Letter S T A Meaning Disable reading the status file CURRENT.STS Disable reading TOOLS.INI Disable PWB extension autoload

The /D option alone disables loading all the PWB extension and initialization files. See: Autoload. Note If you start PWB with the /DT option, this means that PWB options you change during the session cannot be saved. /PP makefile Opens the specified PWB project. /PF makefile Opens the specified non-PWB project (foreign makefile). /PL Resets the last project. Use this option to start PWB in the same state you last left it. You can set this option as the default by setting the Lastproject switch to yes.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 131 of 1 Printed: 10/09/00 02:46 PM

132

Environment and Tools

/E command Executes the given command or sequence of commands as a macro upon startup. If command contains a space, command should be enclosed in double quotation marks ("). A single command need not be quoted. If command uses literal quotation marks, place a backslash (\) before each mark. To use a backslash, precede it with another backslash. /R PWB starts in no-edit mode. You cannot modify files in this mode. See: Noedit. /M {mark | line} PWB starts at the specified location. See: Mark. [[[[/T]] file]]... Tells PWB to load the given files on startup. If you specify a single file, PWB loads it. If you specify multiple files, PWB loads the first file; then when you use File Next or the Exit function, PWB loads the next file in the list. If a /T precedes a filename or wildcard, PWB loads each file as a temporary file. PWB does not include temporary files in the list of files saved between sessions. Note No other options can follow /T on the PWB command line. You must specify /T for each file you want to be temporary.

PWB Menus and Keys

Many PWB menu commands activate PWB functions or predefined macros. The menu commands that are attached to functions and macros are listed in the tables that follow. To assign a shortcut key for one of these menu commands, use the Key Assignments command on the Options menu and assign a key to the corresponding function or macro. For details on using the Key Assignments dialog box, see Changing Key Assignments on page 109. Names beginning with an underscore (_pwb...) are macros. Names without an underscore are functions.
Table 7.1 File Menu and Keys Menu Command New Close Macro or Function _pwbnewfile _pwbclosefile Default Keys Unassigned Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 132 of 2 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Next Save Save All Table 7.1 Menu Command DOS Shell n file Exit _pwbnextfile _pwbsavefile _pwbsaveall File Menu and Keys (continued) Macro or Function _pwbshell _pwbfilen _pwbquit Default Keys Unassigned Unassigned
ALT+F4

133

Unassigned
SHIFT+F2

Unassigned

Table 7.2 Edit Menu and Keys Menu Command Undo Redo Repeat Cut Copy Paste Delete Set Anchor Select To Anchor Stream Mode Box Mode Line Mode Record On Macro or Function _pwbundo _pwbredo _pwbrepeat Delete Copy Paste _pwbclear Savecur Selcur _pwbstreammode _pwbboxmode _pwblinemode _pwbrecord Default Keys Unassigned Unassigned Unassigned
SHIFT+DEL, SHIFT+NUMCTRL+INS, SHIFT+NUM* SHIFT+INS, SHIFT+NUM+ DEL

Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned

Table 7.3 Search Menu and Keys Menu Command Log Next Match (Logging on) Next Match (Logging off) Previous Match (Logging on) Previous Match (Logging off) Goto Match Macro or Function _pwblogsearch _pwbnextlogmatch _pwbnextmatch _pwbpreviouslogmatch _pwbpreviousmatch _pwbgotomatch Default Keys Unassigned
SHIFT+CTRL+F3

Unassigned
SHIFT+CTRL+F4

Unassigned Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 133 of 3 Printed: 10/09/00 02:46 PM

134

Environment and Tools Table 7.4 Project Menu and Keys Menu Command Compile File Build Rebuild All Close Next Error Previous Error Goto Error Macro or Function _pwbcompile _pwbbuild _pwbrebuild _pwbcloseproject _pwbnextmsg _pwbprevmsg _pwbsetmsg Default Keys Unassigned Unassigned Unassigned Unassigned
SHIFT+F3 SHIFT+F4

Unassigned

Table 7.5 Run Menu and Keys Menu Command command1 command2 command3 command4 command5 command6 command7 command8 command9 Macro or Function _pwbuser1 _pwbuser2 _pwbuser3 _pwbuser4 _pwbuser5 _pwbuser6 _pwbuser7 _pwbuser8 _pwbuser9 Default Keys [ALT+Fn] [ALT+Fn] [ALT+Fn] [ALT+Fn] [ALT+Fn] [ALT+Fn] [ALT+Fn] [ALT+Fn] [ALT+Fn]

Table 7.6 Browse Menu and Keys Menu Command Goto Definition Goto Reference View Relationship List References Call Tree (Fwd/Rev) Function Hierarchy Module Outline Which Reference Class Tree (Fwd/Rev) Class Hierarchy Macro or Function Pwbrowsegotodef Pwbrowsegotoref Pwbrowseviewrel Pwbrowselistref Pwbrowsecalltree Pwbrowsefuhier Pwbrowseoutline Pwbrowsewhref Pwbrowsecltree Pwbrowseclhier Default Keys Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 134 of 4 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Table 7.6 Browse Menu and Keys (continued) Menu Command Next Previous Macro or Function Pwbrowsenext Pwbrowseprev Default Keys
CTRL+NUM+ CTRL+NUM-

135

Table 7.7 Window Menu and Keys Menu Command New Close Close All Move Size Restore Minimize Maximize Cascade Tile Arrange n file Macro or Function _pwbnewwindow _pwbclose _pwbcloseall _pwbmove _pwbresize _pwbrestore _pwbminimize _pwbmaximize _pwbcascade _pwbtile _pwbarrange _pwbwindown Default Keys Unassigned
CTRL+F4

Unassigned
CTRL+F7 CTRL+F8 CTRL+F5 CTRL+F9 CTRL+F10 F5 SHIFT+F5 ALT+F5 ALT+n

Table 7.8 Help Menu and Keys Menu Command Index Contents Topic Help on Help Next Search Results Macro or Function _pwbhelp_index _pwbhelp_contents _pwbhelp_context _pwbhelp_general _pwbhelp_again _pwbhelp_searchres Default Keys Unassigned
SHIFT+F1 F1

Unassigned Unassigned Unassigned

PWB Default Key Assignments

PWBs default keys assignments are shown in table 7.9. In each position having the text Unassigned, you can assign a function or macro to that key without taking away a default keystroke. You cannot assign keys for positions that are

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 135 of 5 Printed: 10/09/00 02:46 PM

136

Environment and Tools

empty. These can usually be expressed in a different way. For example, CTRL+{ is expressed as SHIFT+CTRL+[.
Table 7.9 PWB Default Key Assignments Key
! # $ % & ( *

Plain Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic

SHIFT

ALT

CTRL

CTRL+SHIFT

Graphic Graphic Graphic Graphic

Unassigned Unassigned Unassigned Unassigned Unassigned _pwbwindow1 _pwbwindow2 _pwbwindow3 _pwbwindow4 _pwbwindow5 _pwbwindow6 _pwbwindow7 _pwbwindow8 _pwbwindow9 Unassigned Unassigned Unassigned Assign Unassigned Arg (Browse menu) Unassigned Unassigned

Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Mword Unassigned Ppage Right

Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned

+
, . / 0 1 2 3 4 5 6 7 8 9 : ; < = >

@ A
B C D

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 136 of 6 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Table 7.9 PWB Default Key Assignments (continued) Key
E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ { | } ~ F1 F2

137

Plain Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic _pwbhelp_context Setfile

SHIFT

ALT

CTRL

CTRL+SHIFT

Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic Graphic _pwbhelp_contents _pwbsavefile

(Edit menu) (File menu) Unassigned (Help menu) Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned (Options menu) (Project menu) Unassigned (Run menu) (Search menu) Unassigned Unassigned Unassigned (Window menu) Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned _pwbhelp_back Unassigned

Up Pword Cdelete Unassigned Unassigned Sinsert Unassigned Replace Mark Linsert Lasttext Quote Unassigned Mpage Left Tell Lastselect Insertmode Mlines Down Ldelete Plines Pbal Qreplace Setwindow Pwbhelpnext Unassigned

Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Record Sethelp Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 137 of 7 Printed: 10/09/00 02:46 PM

138

Environment and Tools

Table 7.9 PWB Default Key Assignments (continued) Key

F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 F16 LEFT RIGHT UP DOWN INS DEL HOME END ENTER BKSP ESC GOTO NUM* NUM+ NUMNUM/ NUMENTER

Plain Psearch Msearch _pwbcascade Selwindow Execute Exit Meta Openfile Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Left Right Up Down Insertmode _pwbclear Begline Endline Emacsnewl Emacscdel Cancel Home Graphic Graphic Graphic Graphic Emacsnewl

SHIFT

ALT

CTRL

CTRL+SHIFT

_pwbnextmsg _pwbprevmsg _pwbtile _pwbprevwindow Refresh Initialize Shell Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Select Select Select Select Paste Delete Select Select Newline Emacscdel Unassigned Unassigned Copy Paste Delete Newline

Unassigned _pwbquit _pwbarrange Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Undo Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned

Compile _pwbclose _pwbrestore Winstyle _pwbmove _pwbresize _pwbminimize _pwbmaximize Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Mword Pword Mlines Plines Copy Unassigned Begfile Endfile Unassigned Unassigned Unassigned Unassigned Unassigned Pwbrowsenext Pwbrowseprev Unassigned Unassigned

_pwbnextlogmatch _pwbpreviouslogmatch Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Select Select Unassigned Unassigned Unassigned Unassigned Select Select Unassigned Undo Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 138 of 8 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Table 7.9 PWB Default Key Assignments (continued) Key
PGUP PGDN TAB

139

Plain Mpage Ppage Tab

SHIFT

ALT

CTRL

CTRL+SHIFT

Select Select Backtab

Unassigned Unassigned Unassigned

Unassigned Unassigned Unassigned

Select Select Unassigned

Note on Available Keys

PWB allows you to assign functions and macros to almost any key combination. However, some keys have a fixed meaning in certain circumstances or operating environments. PWB lists these key as available keys in the Key Assignments dialog box, and PWB allows you to assign a command to the key. However, when the circumstance holds, or you are running PWB in a specific environment, certain keys have a fixed meaning that overrides any assignment that you make.

Help Window
In the Help window, the following keys have a fixed meaning:
Key
ESC TAB SHIFT+TAB ENTER NUMENTER SHIFT+ENTER SHIFT+NUMENTER SPACE

Meaning Close the Help window Move to next hyperlink Move to previous hyperlink Activate current hyperlink Activate current hyperlink Activate current hyperlink Activate current hyperlink Activate current hyperlink

Dialog Boxes
In dialog boxes, all keys have predetermined meanings. Your assignments have no effect when a dialog box is displayed. In particular, note the following keys:
Key
ESC ENTER F1 TAB SHIFT+TAB

Meaning Choose Cancel Choose the active command button Choose Help Move to the next option or command Move to the previous option or command

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 139 of 9 Printed: 10/09/00 02:46 PM

140

Environment and Tools Key

SPACE CTRL+P

Meaning Toggle active option When used in a text box, inserts the next key as a literal value. Use this key to type a literal tab character.
ESC (Cancel)

The Text Argument dialog box is an exception. All keys except F1 (Help) have their assigned meaning.

and

Microsoft Windows
When running PWB with the Windows operating system, some keys are reserved for use by Windows. You can override these reserved keys by setting options in a PIF file.
Key
ALT+ESC CTRL+ESC ALT+TAB ALT+SPACE ALT+ENTER

Default Meaning in the Windows operating system Switch to the next window in the Windows operating system Switch to the the Windows operating system Task Manager Switch to the next application Activate the current windows system menu Shift application between full screen and window

PWB Functions
PWB provides a rich variety of editing, searching, and project-management capabilites in the form of functions. Most of PWBs menus and dialogs call these functions (or macros that use these functions) to perform their actions. You can write your own macros that use these capabilities in ways that precisely suit your needs. You can also execute every function directly, either by pressing a key or by using the Execute function. Table 7.10 summarizes PWB functions. Most functions can be executed in different ways to perform related actions. Complete details are given in the A-toZ reference that follows the table.
Table 7.10 PWB Functions Function Arg Arrangewindow Assign Backtab Begfile Begline Description Begin a function argument Arrange windows or icons Define a macro or assign a key Move to previous tab stop Move to beginning of file Move to beginning of line Keys
ALT+A

Unassigned
ALT+= SHIFT+TAB CTRL+HOME HOME

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 140 of 10 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Table 7.10 Function Cancel Cancelsearch Cdelete Clearmsg Clearsearch Closefile Compile Copy Curdate Curday Curtime Delete Down Emacscdel Emacsnewl Endfile Endline Environment Execute Exit Graphic Home Information Initialize Insert Insertmode Lastselect Lasttext Ldelete Left Linsert Logsearch PWB Functions (continued) Description Cancel arguments or current operation Cancel background search Delete character Clear Build Results Clear Search Results Close current file Compile and build Copy selection to the clipboard Todays date (dd-Mmm-yyyy) Day of week (Tue) Current time (hour:minute:second) Delete selection Move down one line Delete character Start a new line Move to end of file Move to end of line Set or insert environment variable Execute macros and functions by name Advance to next file or leave PWB Type character Move to window corner (Obsolete) Reinitialize Insert spaces or lines Toggle insert/overtype mode Recover last selection Recover last text argument Delete lines Move left Insert lines or indent line Toggle search logging Keys
ESC

141

Unassigned
CTRL+G

Unassigned Unassigned Unassigned

CTRL+F3 CTRL+INS, SHIFT+NUM*

Unassigned Unassigned Unassigned

SHIFT+DEL, SHIFT+NUMCTRL+X, DOWN BKSP, SHIFT+BKSP ENTER, NUMENTER CTRL+END END

Unassigned
F7 F8

(many)
GOTO

SHIFT+F8

Unassigned
CTRL+V, INS CTRL+U CTRL+O CTRL+Y CTRL+S, LEFT CTRL+N

Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 141 of 11 Printed: 10/09/00 02:46 PM

142

Environment and Tools Table 7.10 Function Mark Maximize Menukey Message Meta Mgrep Minimize Mlines Movewindow Mpage Mpara Mreplace Mreplaceall Msearch Mword Newfile Newline Nextmsg Nextsearch Noedit Openfile Paste Pbal Plines Ppage Ppara Print Project Prompt Psearch Pwbhelp PWB Functions (continued) Description Set, clear, or go to a mark or line number Enlarge window to full size Activate menu Display a message or refresh the screen Modify the action of a function Search across files for text or pattern Shrink window to an icon Scroll down by lines Move window Move up one page Move up one paragraph Multifile replace with confirmation Multifile replace Search backward for pattern or text Move back one word Create a new pseudofile Move to the next line Go to build message location Go to search match location Toggle the no-edit restriction Open a new file Insert file or text from clipboard Balance paired characters Scroll up by lines Move down one page Move down one paragraph Print file or selection Set or clear project Request text argument Search forward for pattern or text Help topic lookup Keys
CTRL+M

Unassigned
ALT

Unassigned
F9

Unassigned Unassigned
CTRL+UP , CTRL+W

Unassigned
CTRL+R, PGUP

Unassigned Unassigned Unassigned

F4 CTRL+A, CTRL+LEFT

Unassigned
SHIFT+ENTER, SHIFT+NUMENTER

Unassigned Unassigned Unassigned

F10 SHIFT+INS, SHIFT+NUM+ CTRL+[ CTRL+DOWN, CTRL+Z CTRL+C, PGDN

Unassigned Unassigned Unassigned Unassigned

F3

Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 142 of 12 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Table 7.10 Function Pwbhelpnext Pwbhelpsearch Pwbrowse1stdef Pwbrowse1stref Pwbrowsecalltree Pwbrowseclhier Pwbrowsecltree Pwbrowsefuhier Pwbrowsegotodef Pwbrowsegotoref Pwbrowselistref Pwbrowsenext Pwbrowseoutline Pwbrowsepop Pwbrowseprev Pwbrowseviewrel Pwbrowsewhref Pwbwindow Pword Qreplace Quote Record Refresh Repeat Replace Resize Restcur Right Saveall Savecur Sdelete Searchall Selcur PWB Functions (continued) Description Relative help topic lookup Global full-text help search Go to first definition Go to first reference Browse Call Tree (Fwd/Rev) Browse Class Hierarchy Browse Class Tree (Fwd/Rev) Browse Function Hierarchy Browse Goto Definition Browse Goto Reference Browse List References Browse Next Browse Module Outline Go to previously browsed location Browse Previous Browse View Relationship Browse Which Reference? Open a PWB window Move forward one word Replace with confirmation Insert literal key Toggle macro recording Reread or discard file Repeat the last editing operation Replace pattern or text Resize window Restore saved position Move right Save all modified files Save cursor position Delete streams Highlight occurrences of pattern or text Select to saved position Keys
CTRL+F1

143

Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned
CTRL+NUM+

Unassigned Unassigned
CTRL+NUM-

Unassigned Unassigned Unassigned

CTRL+F, CTRL+RIGHT CTRL+\ CTRL+P SHIFT+CTRL+R SHIFT+F7

Unassigned
CTRL+L

Unassigned Unassigned
CTRL+D, RIGHT

Unassigned Unassigned Unassigned Unassigned Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 143 of 13 Printed: 10/09/00 02:46 PM

144

Environment and Tools Table 7.10 Function Select PWB Functions (continued) Description Select text Keys
SHIFT+PGUP , SHIFT+CTRL+PGUP , SHIFT+PGDN, SHIFT+CTRL+PGDN, SHIFT+END, SHIFT+CTRL+END, SHIFT+HOME, SHIFT+CTRL+HOME, SHIFT+LEFT, SHIFT+CTRL+LEFT, SHIFT+UP , SHIFT+RIGHT , SHIFT+CTRL+RIGHT , SHIFT+DOWN

Selmode Selwindow Setfile Sethelp Setwindow Shell Sinsert Tab Tell Unassigned Undo Up Usercmd Window Winstyle

Change selection mode: box Move to window Open or change files Opens, closes, and lists help files Adjust file in window Start a shell or run a system command Insert a stream of blanks or break line Move to the next tab stop Show key assignment or macro definition Remove a function assignment from a key Undo and redo editing operations Move up Execute a custom Run menu command Move to next or previous window Add or remove scroll bars

Unassigned
F6 F2 SHIFT+CTRL+S CTRL+] SHIFT+F9 CTRL+J TAB CTRL+T

(All unassigned keys)

ALT+BKSP, SHIFT+CTRL+BKSP CTRL+E, UP

Unassigned Unassigned
CTRL+F6

Cursor-Movement Commands
PWB provides the following commands to navigate through text. In addition to the commands in the PWB editor, the Source Browser provides powerful commands to navigate through the source of your programs.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 144 of 14 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Table 7.11 Cursor-Movement Commands Cursor Movement Up one line Down one line Left one column Right one column Upper-left corner of window Top of window Bottom of window Leftmost column in window Rightmost column in window Lower-right corner of window Up one window Down one window Column one One column past window width Back one word Forward one word Beginning of line End of line Next paragraph Previous paragraph End of paragraph End of previous paragraph Beginning of file End of file To specific line number Position before last scroll Saved position Named mark Scroll window down one line Scroll window up one line Scroll window so cursor at top Command Up Down Left Right Home Meta Up Meta Down Meta Left Meta Right Meta Home Mpage Ppage Meta Begline Meta Endline Mword Pword Begline Endline Ppara Mpara Meta Ppara Meta Mpara Begfile Endfile Arg number Mark Arg Mark Restcur Arg name Mark Mlines Plines Arg Plines Keys
UP DOWN LEFT RIGHT

145

HOME
F9 UP F9 DOWN F9 LEFT F9 RIGHT

HOME
PGUP PGDN F9 HOME F9 END CTRL+LEFT CTRL+RIGHT HOME END

Unassigned Unassigned
F9 Unassigned F9 Unassigned CTRL+HOME CTRL+END ALT+A number CTRL+M ALT+A CTRL+M

Unassigned
ALT+A name CTRL+M CTRL+UP CTRL+DOWN ALT+A CTRL+DOWN

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 145 of 15 Printed: 10/09/00 02:46 PM

146

Environment and Tools Table 7.11 Cursor-Movement Commands (continued) Cursor Movement Scroll window so cursor at bottom Scroll window so cursor at home Command Arg Mlines Arg Setwindow Keys
ALT+A CTRL+UP ALT+A CTRL+]

Arg
Key
ALT+A

Arg Begin an argument to a function or begin a selection. After you execute Arg, PWB displays Arg[1] on the status bar. Each time you execute Arg, PWB increments the Arg count. PWB functions perform variations of their action depending on the Arg count and the Meta state. You can use the Meta and Arg function prefixes in any order. See: Meta. To select text or create a function argument: 1. Execute Arg (ALT+A). 2. Execute a cursor-movement function. Or hold down the SHIFT key and click the left mouse button. PWB creates a stream, box, or line selection based on the current selection mode. A selection in each of these modes creates a function argument called streamarg, boxarg, or linearg, respectively. To create a text argument: 1. Execute Arg (ALT+A). 2. Type the text of the argument. When you type the first character of the argument, PWB displays the Text Argument dialog box where you can enter the textarg without modifying your file. The Text Argument dialog box does not have an OK button; instead, you execute the function to which you are passing the text argument. Choose Cancel to save the text and do nothing.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 146 of 16 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

147

To pick up text from a window: 1. Select the text that you want to use in the Text Argument dialog box. 2. Execute Lasttext (CTRL+O). PWB copies the selected text into the text argument dialog box.

Returns See

To cancel an argument or selection:

u

Execute Cancel (ESC).

The return value of Arg cannot be tested. Cancel, Lastselect, Lasttext, Meta, Prompt

Arrangewindow
Key Unassigned Arrangewindow Cascades all unminimized windows on the desktop. Does not affect minimized windows. See: _pwbcascade. Arg Arrangewindow (ALT+A Unassigned) Arranges all unminimized windows on the desktop. Does not affect minimized windows. See: _pwbarrange. Meta Arrangewindow (F9 Unassigned) Tiles up to 16 unminimized windows. Does not affect minimized windows. See: _pwbtile. Meta Arg Arrangewindow (F9 ALT+A Unassigned) Arranges all icons (minimized windows) on the desktop. Returns True False Windows or icons arranged. Nothing to arrange, or more than 16 windows open.

Assign
Key
ALT+=

The Assign function assigns a function to a keystroke, defines a macro, or sets a PWB switch. You can also assign keys and set switches by using the commands in the Options menu. To see the current assignment for a key or the

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 147 of 17 Printed: 10/09/00 02:46 PM

148

Environment and Tools

definition of a macro, use Options Keys Assignments or the Tell function (CTRL+T). See: Tell. Assign Performs the assignment using the text on the current line. If the line ends with a line continuation, PWB uses the next line, and so on for all continued lines. Arg Assign (ALT+A ALT+=) Same as Assign, except uses text starting from the cursor. Arg textarg Assign (ALT+A textarg ALT+=) Performs the assignment using the specified textarg. Arg mark Assign (ALT+A mark ALT+=) Performs the assignment using the text from the line at the cursor to the specified mark. The mark argument can be either a line number or a previously defined mark name. See: Mark. Arg boxarg | linearg | streamarg Assign (ALT+A boxarg | linearg | streamarg ALT+=) Performs the assignment using the selected text. Ignores blank and comment lines. Returns Example True False Assignment successful. Assignment invalid.

To set the Tabstops switch to 8: 1. Execute Arg (ALT+A). 2. Type the following switch assignment:
tabstops:8

3. Execute Assign (ALT+=). Update Assign Arg Assign With PWB 1.x, Assign and Arg Assign do not recognize line continuations. With PWB 2.00, they use all continued lines for the assignment. Arg streamarg Assign With PWB 1.x, a streamarg is not allowed. With PWB 2.00, Assign accepts a streamarg. Arg ? Assign With PWB 1.x, this form of the Assign function displays the current assignments for all functions, switches, and macros in the <ASSIGN>Current Assignments and Switch Settings pseudofile.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 148 of 18 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

149

With PWB 2.00, the <ASSIGN> pseudofile does not exist; therefore, this form of the Assign function is obsolete. If you use this command or execute a macro that executes this command, PWB issues the error:
Missing ':' in '?'

PWB is expecting an assignment or definition using the name ?, which is a legal macro name.

Backtab
Key
SHIFT+TAB

Backtab Moves the cursor to the previous tab stop on the line. Returns Update See True False Cursor moved. Cursor is at left margin.

PWB 2.0 supports variable tab stops. PWB 1.x supports only fixed-width tab stops. Tab, Tabstops

Begfile
Key
CTRL+HOME

Begfile Moves the cursor to the beginning of the file. Returns See True False Endfile Cursor moved. Cursor not moved; the cursor is already at the beginning of the file.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 149 of 19 Printed: 10/09/00 02:46 PM

150

Environment and Tools

Begline
Key
HOME

Begline Places the cursor on the first nonblank character in the line. Meta Begline (F9 HOME) Places the cursor in the first character position of the line (column one). Returns Example True False Cursor moved. Cursor not moved; the cursor is already at the destination.

The following macro moves the cursor to column one, then toggles between column one and the first nonblank character of the line.
toggle_begline := Left ->x Meta :>x Begline

The result of the Left function is tested to determine if the cursor is already in column one. If the cursor is in column one, PWB skips the Meta and executes Begline to move to the first nonblank character. If the cursor is not in column one, PWB executes Meta Begline to move there. Example This macro mimics the behavior of the BRIEF
bhome:= Meta Begline +> Home +> Begfile

HOME

key:

The result of Meta Begline (go to column 1 on the line) is tested to determine if the cursor moved. If the cursor moved, the test (+>) succeeds and the macro exits. If the cursor did not move, the cursor is already in column 1, so the macro advances to the home position with Home. If the cursor did not move going to the home position, the macro advances to the beginning of the file with Begfile. See Left, Meta

Cancel
Key
ESC

Cancel Cancels the current selection, argument, or operation. If a message appears on the status bar, the Cancel function restores the original contents of the status bar.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 150 of 20 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

151

If a dialog box or menu is open, Cancel closes the dialog box or menu and takes no further action. If Help on a dialog box, menu, or message box is being displayed, Cancel closes the Help dialog box. Returns See Cancel always returns true. Arg

Cancelsearch
Key Unassigned Cancelsearch Cancels a background search. The Search Results window contains the partial results of the aborted search and is not flushed. You can browse matches listed in the Search Results by using the Next Match, Previous Match, and Goto Match commands from the Search menu and by using the Nextsearch function (Unassigned). Cancelsearch applies only to multithreaded environments. Returns See True False Background search was canceled. No background search in progress.

Nextsearch, _pwbnextlogmatch, _pwbpreviouslogmatch, _pwbgotomatch

Cdelete
Key
CTRL+G

Cdelete Deletes the previous character, excluding line breaks. If the cursor is in column 1, Cdelete moves the cursor to the end of the previous line. In insert mode, Cdelete deletes the previous character, reducing the line length by 1. In overtype mode, Cdelete deletes the previous character and replaces it with a space character. If the cursor is beyond the end of the line, the cursor moves to the immediate right of the last character on the line.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 151 of 21 Printed: 10/09/00 02:46 PM

152

Environment and Tools

Emacscdel is similar to Cdelete. However, in insert mode, Emacscdel deletes line breaks; in overtype mode beyond the end of the line, it does not automatically move to the end of the line. Returns See True False Cursor moved. Cursor not moved.

Delete, Emacscdel, Ldelete, Sdelete

Clearmsg
Key Unassigned Clearmsg Clears the contents of the Build Results window. Arg Clearmsg (ALT+A Unassigned) Clears the current set of messages in the Build Results window. Returns See True False Cleared a message set or the contents of Build Results. The Build Results window is empty.

Nextmsg, _pwbnextmsg, _pwbprevmsg, _pwbsetmsg

Clearsearch
Key Unassigned Clearsearch Clears the contents of the Search Results window. Arg Clearsearch (ALT+A Unassigned) Clears the current set of matches in the Search Results window. Returns See True False Cleared a match set or the contents of Search Results. The Search Results window is empty.

Clearmsg, Logsearch, _pwbnextlogmatch, _pwbpreviouslogmatch, _pwbgotomatch

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 152 of 22 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

153

Closefile
Key Unassigned Closefile Closes the file in the active window. If no files remain in the windows file history, the window is also closed. Arg Closefile (ALT+A Unassigned) Closes the file named by the text at the cursor. Arg linearg | boxarg | streamarg Closefile (ALT+A linearg | boxarg | streamarg Unassigned) Closes the file named by the selected text. Arg textarg Closefile (ALT+A textarg Unassigned) Closes the specified file. Returns See True False The file was closed. No file was closed.

Refresh, _pwbclosefile

Compile
Key
CTRL+F3

The Compile function compiles and builds targets in the project or runs external commands, capturing the result of the operation in the Build Results window. Under multithreaded environments the commands run in the background. Arg Compile (ALT+A CTRL+F3) Compiles the current file. This is equivalent to Project Compile File. Arg Compile fails if no project is open. See: _pwbcompile. Arg textarg Compile (ALT+A textarg CTRL+F3) Builds the target specified by textarg. This is equivalent to Build Target command on the Project menu. Arg textarg Compile fails if no project is open. To build the current project, execute Arg all Compile. Arg Meta textarg Compile (ALT+A textarg F9 CTRL+F3) Rebuilds the specified target and its dependents. See: _pwbrebuild.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 153 of 23 Printed: 10/09/00 02:46 PM

154

Environment and Tools

This command is equivalent to specifying the NMAKE /a option. Note that you can also include NMAKE command-line macro definitions in the text you pass to the Compile function. Arg Meta Compile (ALT+A F9 CTRL+F3) Aborts the background compile after prompting for confirmation. Also clears the queue of pending background operations (if any). Arg Arg textarg Compile (ALT+A ALT+A textarg CTRL+F3) Runs the program or operating-system command specified by textarg. The output is displayed in the Compile Results window. Under multithreaded environments, the program runs in the background, and the Compile Results window is updated as the program executes. Several programs can be queued for background execution. Do not use this command to execute an interactive program. The program is able to change the display but may not receive input. To run an interactive program, use the Shell function (SHIFT+F9). Returns True False Operation successfully initiated. Operation not initiated.

Copy
Keys Menu
CTRL+INS, SHIFT+NUM*

Edit menu, Copy command Copy Copies the current line to the clipboard. Arg Copy (ALT+A CTRL+INS) Copies text from the cursor to the end of the line. The text is copied to the clipboard, but the line break is not included. Arg boxarg | linearg | streamarg Copy (ALT+A boxarg | linearg | streamarg CTRL+INS) Copies the selected text to the clipboard. Arg textarg Copy (ALT+A textarg CTRL+INS) Copies the specified textarg to the clipboard. Arg mark Copy (ALT+A mark CTRL+INS) Copies the text from the cursor to the mark. The text is copied to the clipboard. The mark argument can be either a line number or a previously defined mark. See: Mark.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 154 of 24 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

155

The text is copied as a boxarg or linearg depending on the relative positions of the cursor and the mark. If the cursor and the mark are in the same column, the text is copied as a linearg. If the cursor and the mark are in different columns, the text is copied as a boxarg. Arg number Copy (ALT+A number CTRL+INS) Copies the specified number of lines to the clipboard, starting with the current line. For example, Arg 5 Copy copies five lines to the clipboard. Returns See Copy always returns true. Delete, Ldelete, Sdelete, Paste

Curdate
Key Unassigned Curdate Types the current date at the cursor in the format day-month-year, for example: 17-Apr-1999. Returns See True False Date typed. Typing the date would make the line too long.

Curday, Curfile, Curfilenam, Curfileext, Curtime

Curday
Key Unassigned Curday Types the three-letter abbreviation for the current day of the week, as follows: Mon Tue Wed Thu Fri Sat Sun. Returns See True False Day typed. Typing the day would make the line too long.

Curdate, Curfile, Curfilenam, Curfileext, Curtime

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 155 of 25 Printed: 10/09/00 02:46 PM

156

Environment and Tools

Curtime
Key Unassigned Curtime Types the current time in the format hours:minutes:seconds, for example, 17:08:32. Returns See True False Time typed. Typing the time would make the line too long.

Curdate, Curday, Curfile, Curfilenam, Curfileext

Delete
Keys Menu
SHIFT+DEL, SHIFT+NUM

Edit menu, Cut command Delete Deletes the single character at the cursor, excluding line breaks. It does not copy the deleted character onto the clipboard. Note that the Delete function can delete more than one character, depending on the current selection mode. Arg Delete (ALT+A SHIFT+DEL) Deletes from the cursor to the end of the line. The deleted text is copied onto the clipboard. In stream selection mode, the deletion includes the line break and joins the current line to the next line. Arg boxarg | linearg | streamarg Delete (ALT+A boxarg | linearg | streamarg SHIFT+DEL) Deletes the selected text. The text is copied on to the clipboard. Meta ... Delete (F9 ... SHIFT+DEL) As above but discards the deleted text. The contents of the clipboard are not changed.

Returns

Delete always returns true.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 156 of 26 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

157

Down
Keys
DOWN, CTRL+X

Down Moves the cursor down one line. If a selection has been started, it is extended by one line. If this movement results in the cursor moving out of the window, the window is adjusted downward as specified by the Vscroll switch. Meta Down (F9 DOWN) Moves the cursor to the bottom of the window without changing the column position. Returns See True False Up Cursor moved. Cursor did not move; the cursor is at the destination.

Emacscdel
Keys
BKSP, SHIFT+BKSP

Emacscdel Deletes the previous character. If the cursor is in column 1, Emacscdel moves the cursor to the end of the previous line. In insert mode, Emacscdel deletes the previous character, reducing the length of the line by 1. If the cursor is in column one, Emacscdel deletes the line break, joining the current line to the previous line. In overtype mode, Emacscdel deletes the previous character and replaces it with a space character. If the cursor is in column 1, Emacscdel moves the cursor to the end of the previous line and does not delete the line break. Emacscdel is similar to Cdelete, but Cdelete never deletes line breaks; in overtype mode beyond the end of the line, Cdelete automatically moves to the end of the line. Returns See True False Cursor moved. Cursor not moved.

Cdelete, Delete, Ldelete, Sdelete

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 157 of 27 Printed: 10/09/00 02:46 PM

158

Environment and Tools

Emacsnewl
Keys
ENTER, NUMENTER

Emacsnewl In insert mode, starts a new line. In overtype mode, moves the cursor to the beginning of the next line. PWB automatically positions the cursor on the new line, depending on the setting of the Softcr switch. Returns Update Emacsnewl always returns True. In PWB 1.x, PWB performs special automatic indentation for C files. In PWB 2.00, language-specific automatic indentation is handled by language extensions if the feature is enabled. Otherwise, PWB uses its default indentation rules. Newline, Softcr, C_Softcr

See

Endfile
Key
CTRL+END

Endfile Places the cursor at the end of the file. Returns See True False Begfile Cursor moved. Cursor did not move; the cursor is at the end of the file.

Endline
Key
END

Endline Moves the cursor to the immediate right of the last character on the line. Meta Endline (F9 END) Moves the cursor to the column that is one column past the active window width.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 158 of 28 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

159

Returns See

True False

Cursor moved. Cursor did not move; the cursor is at the destination.

Begline, Traildisp, Trailspace

Environment
Key Unassigned Environment Executes the current line as an environment-variable setting. For example, if the current line contains the following text when you execute Environment:
PATH=C:\UTIL;C:\DOS

PWB adds this setting to the current environment table. The effect is the same as the operating-system SET command. PWB uses the new environment variable for the rest of the session (including shells). Depending on the settings of the Envcursave and Envprojsave switches, PWB saves the environment table for PWB sessions and/or projects. See: Envcursave, Envprojsave. Arg textarg Environment (ALT+A textarg Unassigned) Executes the argument as an environment-variable setting. Arg linearg | boxarg Environment (ALT+A linearg | boxarg Unassigned) Executes each selected line or line fragment as an environment-variable setting. Meta Environment (F9 Unassigned) Performs environment-variable substitutions for all variables on the current line, replacing each variable with its value. The syntax for an environment variable isINDEX: Environment variable, specfying in PWB $(ENV) | $ENV: where ENV is the uppercase name of the environment variable. Arg Meta Environment (ALT+A F9 Unassigned) Performs environment-variable substitutions (described above) for the text from the cursor to the end of the line. Arg boxarg | linearg | streamarg Meta Environment (ALT+A boxarg | linearg | streamarg F9 Unassigned) Performs environment-variable substitutions for the selected text.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 159 of 29 Printed: 10/09/00 02:46 PM

160

Environment and Tools

Returns Update

True False

Environment variable successfully set or substituted. Syntax error or line too long.

Because the <ENVIRONMENT> pseudofile no longer exists, this form of the Environment function is obsolete; it is replaced by the Environment command on the Options menu.

Execute
Key
F7

The Execute function executes PWB functions and macros by name. It allows you to execute commands that are not assigned to a key or execute a sequence of commands in one step. The Execute function executes the commands by the same rules as macros. Function prompts are suppressed, and you can use the macro flow-control and macro prompt directives. You do not need to define a macro to use these features. Arg Execute (ALT+A F7) Executes the text from the cursor to the end of the line as a PWB macro. Arg linearg | textarg Execute (ALT+A linearg | textarg F7) Executes the specified text as a PWB macro. Returns True False Last executed function returned true. Last executed function returned false.

Exit
Key
F8

Exit If you specified multiple files on the PWB command line, PWB advances to the next file. Otherwise, PWB quits and returns control to the operating system. If the Autosave switch is set to yes, the file is saved if it has been modified. If Autosave is no and the file is modified, PWB prompts for confirmation to save the file.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 160 of 30 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

161

Meta Exit (F9 F8) Performs like Exit with the Autosave switch set to no, independent of the current setting of Autosave. If you have changed any files, PWB asks for confirmation to save before exiting. Arg Exit (ALT+A F8) Like Exit, except PWB quits immediately without advancing to the next file (if any). Arg Meta Exit (ALT+A F9 F8) Like Meta Exit, except PWB quits immediately without advancing to the next file. Returns See No return value. _pwbquit

Graphic
Keys Assigned to most alphanumeric and punctuation keys. Graphic Types the character corresponding to the key that you pressed. Returns See True False The character is typed. Typing the character would make the line too long.

Assign, Quote

Home
Key
GOTO

(Numeric-keypad 5)

Home Places the cursor in the upper-left corner of the window. Meta Home (F9 GOTO) Places the cursor in the lower-right corner of the window. Returns See True False Cursor moved. Cursor not moved; it is already at the destination.

Begline, Endline, Left, Right

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 161 of 31 Printed: 10/09/00 02:46 PM

162

Environment and Tools

Initialize
Key
SHIFT+F8

Initialize Discards all current settings, including extension settings, then reads the statements from the [PWB] section of TOOLS.INI. Arg Initialize (ALT+A SHIFT+F8) Reads the statements from a tagged section of TOOLS.INI. The tag name is specified by the continuous string of nonblank characters starting at the cursor. Arg textarg Initialize (ALT+A textarg SHIFT+F8) Reads the statements from the TOOLS.INI tagged section specified by textarg. Example The section tagged with
[PWB-name]

is initialized by the command

Arg name Initialize

Example

To reload the main section of TOOLS.INI without clearing other settings that you want to remain in effect, label the main section of TOOLS.INI with the tag:
[PWB PWB-main]

then use Arg main Initialize to recover your main settings instead of using Initialize with no arguments. Returns True False Initialized tagged section in TOOLS.INI. Did not find tagged section in TOOLS.INI.

Information
Update (obsolete) The PWB 1.x Information function and its associated pseudofile <INFORMATION-FILE> are obsolete; they do not exist in PWB 2.00.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 162 of 32 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

163

Insert
Key Unassigned Insert Inserts a single-space character at the cursor, independent of the insert/overtype mode. Arg Insert (ALT+A Unassigned) Breaks the line at the cursor. Arg boxarg | linearg | streamarg Insert (ALT+A boxarg | linearg | streamarg Unassigned) Inserts space characters into the selected area. Returns Example True False Spaces or line break inserted. Insertion would make a line too long.

If paragraphs in your file consist of a sequence of lines beginning in the same column and are separated from other paragraphs by at least one blank line, the following macro indents a paragraph to the next tab stop:
para_indent:=_pwbboxmode Meta Mpara Down Begline Arg Meta Ppara Up Begline Tab Insert \

This macro starts with the predefined PWB macro _pwbboxmode to set box selection mode, then creates a box selection from the beginning of the paragraph to the end, one tab stop wide. The Insert function inserts spaces in the selection. See Sinsert , Linsert

Insertmode
Keys
INS, CTRL+V

Insertmode Toggles between insert mode and overtype mode. If overtype mode is on, the letter O appears on the status bar. The cursor can also change shape, depending on the Cursormode switch. See: Cursormode. In insert mode, each character you type is inserted at the cursor. This insertion shifts the remainder of the line one position to the right. In overtype mode, the character you type replaces the character at the cursor.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 163 of 33 Printed: 10/09/00 02:46 PM

164

Environment and Tools

Returns

True False

PWB is in insert mode. PWB is in overtype mode.

Lastselect
Key
CTRL+U

Lastselect Duplicates the last selection. The Arg count and Meta state that were previously in effect are not duplicatedonly the selection. The new Arg count is one, and the Meta state is the current Meta state. To use a higher Arg count, execute Arg (ALT+A). To toggle the Meta state, execute Meta (F9). The re-created selection uses the same pair of line:column coordinates as the previous selection. Thus, different text can be selected if you have made additions or deletions to the file since the last selection. See Arg, Lasttext, Meta

Lasttext
Key
CTRL+O

Lasttext Displays the last text argument in the Text Argument dialog box. You can edit the text and then execute any PWB function that accepts a text argument, or you can cancel the dialog box. If you edit the text and then cancel the dialog box, PWB retains the modified text. Thus, when you execute Lasttext again, the new text appears in the dialog box. Arg [[Arg]]... [[Meta]] Lasttext (ALT+A [[ALT+A]]... [[F9]] CTRL+O) Displays the last text argument in the Text Argument dialog box with the specified Arg count and Meta state. Arg [[Arg]]... linearg | boxarg | streamarg [[Meta]] Lasttext (ALT+A [[ALT+A]]... linearg | boxarg | streamarg [[F9]] CTRL+O) Displays the first line of the selection in the Text Argument dialog box with the specified Arg count and Meta state.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 164 of 34 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

165

Returns Example

The return value of Lasttext cannot be tested. The OpenInclude macro that follows opens an include file named in the next #include directive. The macro demonstrates a technique using the Lasttext function to pick up text from the file and modify it without modifying the file or the clipboard.
OpenInclude := \ Up Meta Begline Arg Arg "^[ \t]*#[ \t]*include" Psearch -> Arg Arg "[<>\"]" Psearch -> Right Savecur Psearch -> Selcur Lasttext Begline "$INCLUDE:" Openfile <n +> Lastselect Openfile < \ \ \

In the fourth line, Lasttext pulls the selected filename into the Text Argument dialog box. The text argument is modified to prepend $INCLUDE: before passing it to the Openfile function. Example In some macro-programming situations, you dont want to use the text immediately. Instead, you need to pick up some text, do some other processing, then use the text. In this situation, use the phrase: (make selection) Lasttext Cancel ... This picks up the text, then cancels the Text Argument dialog box. The selected text remains in the Lasttext buffer for later use. To reuse the text, call Lasttext again. See Arg, Lastselect, Meta, Prompt

Ldelete
Key
CTRL+Y

Ldelete Deletes the current line and copies it to the clipboard. Arg Ldelete (ALT+A CTRL+Y) Deletes text from the cursor to the end of the line and copies it to the clipboard. Arg mark Ldelete (ALT+A mark CTRL+Y) Deletes the text from the line at the cursor to the line specified by mark and copies it to the clipboard. The mark cannot be a line number.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 165 of 35 Printed: 10/09/00 02:46 PM

166

Environment and Tools

Arg number Ldelete (ALT+A number CTRL+Y) Deletes the specified number of lines starting from the line at the cursor and copies them to the clipboard.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 166 of 36 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

167

Arg boxarg | linearg Ldelete (ALT+A boxarg | linearg CTRL+Y) Deletes the specified text and copies it to the clipboard. The argument is a linearg or boxarg regardless of the current selection mode. The argument is a linearg if the starting and ending points are in the same column. Meta ... Ldelete (F9 ... CTRL+Y) As above but discards the deleted text. The clipboard is not changed. Returns See Ldelete always returns true. Cdelete, Delete, Emacscdel, Sdelete

Left
Keys
LEFT, CTRL+S

Left Moves the cursor one character to the left. If this movement results in the cursor moving out of the window, the window is adjusted to the left as specified by the Hscroll switch. Meta Left (F9 LEFT) Moves the cursor to the first column in the window. Returns See True False Cursor moved. Cursor not moved; the cursor is in column one.

Begline, Down , Endline, Home, Right, Up

Linsert
Key
CTRL+N

Linsert Inserts one blank line above the current line. Arg Linsert (ALT+A CTRL+N) Inserts or deletes blanks at the beginning of a line to move the first nonblank character to the cursor. Arg boxarg | linearg Linsert (ALT+A boxarg | linearg CTRL+N) Inserts blanks within the specified area.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 167 of 37 Printed: 10/09/00 02:46 PM

168

Environment and Tools

The argument is a linearg or boxarg regardless of the current selection mode. The argument is a linearg if the starting and ending points are in the same column. Arg mark Linsert (ALT+A mark CTRL+N) Like boxarg | linearg except the specified area is given by the cursor position and the position of the specified mark. The mark argument must be a named mark: it cannot be a line number. See: Mark. Returns See Linsert always returns true. Insert , Sinsert

Logsearch
Key Unassigned Logsearch Toggles the search-logging state. The default search-logging mode when PWB starts up is determined by the Enterlogmode switch. Returns True False Search logging turned on. Search logging turned off.

Mark
Key
CTRL+M

The Mark function moves the cursor to a mark or specific location, defines marks, and deletes marks. Note that you cannot set a mark at specific text in a PWB window such as Help; PWB marks only the window position. If you want to save marks between sessions, assign a filename to the Markfile switch or use the Set Mark File command on the Search menu. Mark (CTRL+M) Moves the cursor to the beginning of the file. Arg Mark (ALT+A CTRL+M) Restores the cursor to its location prior to the last window scroll. Use Arg Mark to return to your previous location after a search or other large jump.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 168 of 38 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

169

Arg number Mark (ALT+A number CTRL+M) Moves the cursor to the beginning of the line specified by number in the current file. Line numbering starts at 1. Arg textarg Mark (ALT+A textarg CTRL+M) Moves the cursor to the specified mark. Arg Arg textarg Mark (ALT+A ALT+A textarg CTRL+M) Defines a mark at the cursor position. The name of the mark is specified by textarg. Arg Arg textarg Meta Mark (ALT+A ALT+A textarg F9 CTRL+M) Deletes the specified mark. This form of the Mark function always returns true. Returns See True False Move, definition, or deletion successful. Invalid argument or mark not found.

Markfile, Restcur, Savecur, Selcur

Maximize
Key Unassigned Maximize Expands the window to its maximum size. If the window is already maximized, the window is restored. When the window is maximized and scroll bars are turned off by using the Winstyle function, PWB turns off the window borders. This is the clean screen look. Meta Maximize (F9 Unassigned) Restores the window to its original size. Returns See True False Window is maximized. Window is restored.

Minimize, Winstyle

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 169 of 39 Printed: 10/09/00 02:46 PM

170

Environment and Tools

Menukey
Key
ALT

Menukey Activates the menu bar. Unlike other PWB functions, Menukey can be assigned to only one key. It cannot be assigned to a combination of keys. Returns You cannot test the return value of Menukey.

Message
Key Unassigned Message Clears the status bar. Arg Message (ALT+A Unassigned) Displays the text from the cursor to the end of the line on the status bar. Arg textarg Message (ALT+A textarg Unassigned) Displays textarg on the status bar. Meta ... Message (F9 ... Unassigned) As above and also repaints the screen. Returns Example Message always returns true. The following macro is useful when writing new macros (the ! is the macro name):
! := Meta Message

With this definition you can place an exclamation point in your macros wherever you want a screen update. If you also want to display a status-bar message at the time of the update, use the phrase: ... Arg "text of message" ! ... See Prompt

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 170 of 40 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

171

Meta
Key
F9

Meta Modifies the action of the function it prefixes. When the Meta state is turned on, the letter A (for Alternate) appears in the status bar. You can use the Meta and Arg function prefixes in any order. Returns See True False Meta state turned on. Meta state turned off.

Arg, Lasttext, Lastselect

Mgrep
Key Unassigned The Mgrep function searches all the files listed in the Mgreplist macro. PWB places all matches in the Search Results window. Under multithreaded environments, PWB performs the search in the background. To browse the list of matches, use _pwbnextlogmatch (CTRL+SHIFT+F3), _pwbpreviouslogmatch (CTRL+SHIFT+F4), and the Nextsearch function (Unassigned). Mgrep (Unassigned) Searches for the previously searched string or pattern. Arg Mgrep (ALT+A Unassigned) Searches for the string specified by the characters from the cursor to the first blank character. Arg textarg Mgrep (ALT+A textarg Unassigned) Searches for textarg. Arg Arg Mgrep (ALT+A ALT+A Unassigned) Searches for the regular expression specified by the characters from the cursor to the first blank character. Arg Arg textarg Mgrep (ALT+A ALT+A textarg Unassigned) Searches for the regular expression specified by textarg. Meta ... Mgrep (F9 ... Unassigned) As above except that the value of the Case switch is reversed for the search.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 171 of 41 Printed: 10/09/00 02:46 PM

172

Environment and Tools

Returns

True With MS-DOS, indicates that a match was found. With multithreaded environments, indicates that a background search was successfully initiated. False No matches, no search pattern specified, search pattern invalid, or search terminated by CTRL+BREAK.

Update

In PWB 2.00, search and build results and their browsing functions are separate. A background build operation and a background search can be performed simultaneously. In PWB 1.x, search and build results appear in the same window, and are browsed with the same commands. A background build operation and a multifile search cannot be performed at the same time in PWB 1.x.

Minimize
Key Unassigned Minimize Shrinks the active window to an icon (a minimized window). If the window is already minimized, restores the window. Arg Minimize (ALT+A Unassigned) Minimizes all open windows. Meta Minimize (F9 Unassigned) Restores the window to its unminimized state. Returns See True False Maximize Window minimized: the window is an icon. Window restored: the window is not an icon.

Mlines
Keys
CTRL+UP , CTRL+W

Mlines Scrolls the window down as specified by the Vscroll switch.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 172 of 42 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

173

Arg Mlines (ALT+A CTRL+UP ) Scrolls the window so the line at the cursor moves to the bottom of the window. Arg number Mlines (ALT+A number CTRL+UP ) Scrolls the window down by number lines. Returns See True False Plines Window scrolled. Invalid argument.

Movewindow
Key Unassigned Movewindow Enters window-moving mode. In window-moving mode, only the following actions are available:
Action Move up one row Move down one row Move left one column Move right one column Accept the new position Cancel the move Key
UP DOWN LEFT RIGHT ENTER ESC

Arg number Movewindow (ALT+A number Unassigned) Moves the upper-left corner of the window to the screen row specified by number. Meta Arg number Movewindow (F9 ALT+A number Unassigned) Moves the upper-left corner of the window to the screen column specified by number. Returns True False Window moved. Window not moved.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 173 of 43 Printed: 10/09/00 02:46 PM

174

Environment and Tools

Mpage
Keys
PGUP , CTRL+R

Mpage Moves the cursor backward in the file by one window. Returns See True False Ppage Cursor moved. Cursor not moved.

Mpara
Key Unassigned Mpara Moves the cursor to the beginning of the first line of the current paragraph. If the cursor is already on the first line of the paragraph, it is moved to the begining of the first line of the preceding paragraph. Meta Mpara (F9 Unassigned) Moves the cursor to the first blank line preceding the current paragraph. Returns See True False Ppara Cursor moved. Cursor not moved; no more paragraphs in the file.

Mreplace
Key Unassigned Mreplace Performs a find-and-replace operation across multiple files, prompting for the find-and-replacement strings and for confirmation at each occurrence. Mreplace searches all the files listed in the special macro Mgreplist. Arg Arg Mreplace (ALT+A ALT+A Unassigned) Performs the same action as Mreplace but uses regular expressions.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 174 of 44 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

175

Meta ... Mreplace (F9 ... Unassigned) As above except reverses the sense of the Case switch for the operation. Returns See True False At least one replacement made. No replacements made or operation aborted.

Mgrep, Mreplaceall, Qreplace, Replace

Mreplaceall
Key Unassigned Mreplaceall Performs a find-and-replace operation across multiple files, prompting for the find-and-replacement strings. Mreplaceall searches all the files listed in the special macro Mgreplist. Arg Arg Mreplaceall (ALT+A ALT+A Unassigned) Performs the same action as Mreplaceall but uses regular expressions. Meta ... Mreplaceall (F9 ... Unassigned) As above except reverses the sense of the Case switch for the operation. Returns See True False At least one replacement made. No replacements made or operation aborted.

Mgrep, Mreplace, Qreplace, Replace

Msearch
Key
F4

Msearch Searches backward for the previously searched string or pattern. Arg Msearch (ALT+A F4) Searches backward for the string specified by the text from the cursor to the first blank character. Arg textarg Msearch (ALT+A textarg F4) Searches backward for the specified text.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 175 of 45 Printed: 10/09/00 02:46 PM

176

Environment and Tools

Arg Arg Msearch (ALT+A ALT+A F4) Searches backward for the regular expression specified by the text from the cursor to the first blank character. Arg Arg textarg Msearch (ALT+A ALT+A textarg F4) Searches backward for the regular expression defined by textarg. Meta ... Msearch (F9 ... F4) As above except reverses the sense of the Case switch for the search. Returns See True False String found. Invalid argument, or string not found.

Mgrep, Psearch

Mword
Keys
CTRL+LEFT, CTRL+A

Mword Moves the cursor to the beginning of the current word, or if the cursor is not in a word or at the beginning of the word, moves the cursor to the beginning of the previous word. A word is defined by the Word switch. Meta Pword (F9 CTRL+RIGHT ) Moves the cursor to the immediate right of the previous word. Returns See True False Pword Cursor moved. Cursor not moved; there are no more words in the file.

Newfile
Key Unassigned The Newfile function creates a new pseudofile. If the Newwindow switch is set to yes, it opens a new window for the file. Newfile (Unassigned) Creates a new untitled pseudofile. The new pseudofile is given a unique name of the form: <Untitled.nnn>Untitled.nnn

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 176 of 46 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

177

where nnn is a three-digit number starting with 001 at the beginning of each PWB session. The window title shows Untitled.001. Use the pseudofile name <Untitled.001> to refer to the file in a text argument or dialog box. Arg Newfile (ALT+A Unassigned) Creates a new pseudofile with the name specified by the text from the cursor to the end of the line. The resulting full pseudofile name is:
"<Text on the line>Text on the line"

Arg textarg Newfile (ALT+A textarg Unassigned) Creates a new pseudofile with the name specified by textarg. The resulting full pseudofile name is:
"<textarg>textarg"

If you want to use a different short name and window title, use the full name as an argument to the Setfile or Openfile functions. For example, Arg "<temp>Temporary File" Openfile opens a pseudofile in a new window that has the title Temporary File. Returns True False Successfully created the pseudofile. Unable to create the pseudofile.

Newline
Keys
SHIFT+ENTER, SHIFT+NUMENTER

Newline Moves the cursor to a new line. If the Softcr switch is set to yes, PWB automatically indents to an appropriate position based on the type of file you are editing. Meta Newline (F9 SHIFT+ENTER) Moves the cursor to column 1 of the next line. Returns Update Newline always returns true. In PWB 1.x, PWB performs special automatic indentation for C files. In PWB 2.00, language-specific automatic indentation is handled by language extensions if the feature is enabled. Otherwise, PWB uses its default indentation rules. Emacsnewl

See

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 177 of 47 Printed: 10/09/00 02:46 PM

178

Environment and Tools

Nextmsg
Key Unassigned Nextmsg Advances to next message in the Build Results window. Arg number Nextmsg (ALT+A number Unassigned) Moves to the nth message in the current set of messages, where n is specified by number. To move relative to the current message, use a signed number. For example, when number is +1, PWB moves to the next message, and when it is 1, PWB moves to the previous message. Arg Nextmsg (ALT+A Unassigned) Moves to the next message in the current set of messages that does not refer to the current file. Meta Nextmsg (F9 Unassigned) Advances to the next set of messages. Arg Arg Nextmsg (ALT+A ALT+A Unassigned) Sets the message at the cursor as the current message. This works only when the cursor is on a message in the Build Results window. Returns Update True False Message found. No more messages found.

In PWB 1.x, Nextmsg also browses the results of searches. In PWB 2.00, search results are browsed with the Nextsearch function. Meta Nextmsg In PWB 1.x, deletes the current set of messages and advances to the next set. In PWB 2.00, Meta Nextmsg does not delete the set. To delete sets of messages in PWB 2.00, use the Clearmsg function. Meta Arg Arg Nextmsg In PWB 1.x, closes the Compile Results window. In PWB 2.00, it behaves like Arg Arg Nextmsg.

See

Clearmsg

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 178 of 48 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

179

Nextsearch
Key Unassigned Nextsearch Advances to the next match in the Search Results window. Arg number Nextsearch (ALT+A number Unassigned) Moves to the nth match in the current set of matches, where n is specified by number. To move relative to the current match, use a signed number. For example, when number is +1, PWB moves to the next match, and when it is 1, PWB moves to the previous match. Arg Nextsearch (ALT+A Unassigned) Moves to the next match in the current set of matches that does not refer to the current file. Meta Nextsearch (F9 Unassigned) Advances to the next set of matches. Arg Arg Nextsearch (ALT+A ALT+A Unassigned) Sets the match at the cursor as the current match. This works only when the cursor is on a match in the Search Results window. Update See In PWB 1.x, the results of searches are browsed using the Nextmsg function. Clearsearch

Noedit
Key Unassigned The Noedit function toggles the no-edit state of PWB or the current file. When the no-edit state is turned on, PWB displays the letter R on the status bar and disallows modification of the file. Noedit Toggles the no-edit state. If you started PWB with the /R (read-only) option, Noedit removes the no-edit limitation. Meta Noedit (F9 Unassigned) Toggles the no-edit state for the current file. This form of the Noedit command works only for disk files and has no effect on pseudofiles.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 179 of 49 Printed: 10/09/00 02:46 PM

180

Environment and Tools

If you have the Editreadonly switch set to no, PWB turns on the no-edit state for files that are marked read-only on disk. This function toggles the noedit state for the file so that you can modify it. Returns True False File or PWB in no-edit state; modification disallowed. File or PWB not in no-edit state; modification allowed.

Openfile
Key
F10

The Openfile function opens a file in a new window, ignoring the Newwindow switch. Arg Openfile (ALT+A F10) Opens the file at the cursor in a new window. The name of the file is specified by the text from the cursor to the first blank character. Arg textarg Openfile (ALT+A textarg F10) Opens the specified file in a new window. If the argument is a wildcard, PWB creates a pseudofile containing a list of files that match the pattern. To open a file from this list, position the cursor at the beginning of the name and use Arg Openfile or Arg Setfile. Returns See True False File and window successfully opened. No argument specified, or file did not exist and you did not create it.

Newfile, Setfile

Paste
Keys Menu
SHIFT+INS, SHIFT+NUM+

Edit menu, Paste command Paste (SHIFT+INS) Copies the contents of the clipboard to the file at the cursor. The text is always inserted independent of the insert/overtype mode. If the clipboard contents were copied to the clipboard as a linearg, PWB inserts the contents of the clipboard above the current line. Otherwise, the contents of the clipboard are inserted at the cursor.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 180 of 50 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

181

Arg boxarg | linearg | streamarg Paste (ALT+A boxarg | linearg | streamarg SHIFT+INS) Replaces the selected text with the contents of the clipboard. Arg Paste (ALT+A SHIFT+INS) Copies the text from the cursor to the end of the line. The text is copied to the clipboard and inserted at the cursor. Arg textarg Paste (ALT+A textarg SHIFT+INS) Copies textarg to the clipboard and inserts it at the cursor. Arg Arg filename Paste (ALT+A ALT+A filename SHIFT+INS) Copies the contents of the file specified by textarg to the current file above the current line. Arg Arg !textarg Paste (ALT+A ALT+A !filename SHIFT+INS) Runs textarg as an operating-system command, capturing the commands output to standard output. The output is copied to the clipboard and inserted above the current line. You must enter the exclamation mark as shown. Returns True False text Paste always returns true except for the following cases. Tried Arg Arg filename Paste and file did not exist, or the pasted would make a line too long. Example The following command copies a sorted copy of the file SAMPLE.TXT to the current file: Arg Arg !SORT <SAMPLE.TXT Paste (ALT+A ALT+A !SORT <SAMPLE.TXT SHIFT+INS).

Pbal
Key
CTRL+[

Pbal Scans backward through the file, balancing parentheses (( )) and brackets ([ ]). The first unmatched parenthesis or bracket is highlighted when found. If an unbalanced parenthesis or bracket is found, it is highlighted and the corresponding character is inserted at the cursor. If no unbalanced characters are found, PWB displays a message box. The search does not include the cursor position and looks for more opening brackets or parentheses than closing ones.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 181 of 51 Printed: 10/09/00 02:46 PM

182

Environment and Tools

Arg Pbal (ALT+A CTRL+[) Like Pbal except that it scans forward through the file and searches for right brackets or parentheses lacking opening partners. Meta Pbal (F9 CTRL+[) Like Pbal but does not insert the unbalanced character. If no unbalanced characters are found, moves to the matching character. Arg Meta Pbal (ALT+A F9 CTRL+[) Like Arg Pbal but does not insert the character. If no unbalanced characters are found, moves to the matching character. Update Returns See In PWB 1.x, the messages appear on the status bar. In PWB 2.00, they appear in a message box. True False Balance successful. Invalid argument, or no unbalanced characters found.

Infodialog

Plines
Keys
CTRL+DOWN, CTRL+Z

Plines Scrolls the text up as specified by the Vscroll switch. Arg Plines (ALT+A CTRL+DOWN) Scrolls the text such that the line at the cursor is moved to the top of the window. Arg number Plines (ALT+A number CTRL+DOWN) Scrolls the text up by number lines. Returns See True False Mlines Text scrolled. Invalid argument.

Ppage
Keys
PGDN, CTRL+C

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 182 of 52 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

183

Ppage Moves the cursor forward in the file by one window. Returns See True False Mpage Cursor moved. Cursor not moved.

Ppara
Key Unassigned Ppara Moves the cursor to the beginning of the first line of the next paragraph. Meta Ppara (F9 Unassigned) Moves cursor to the beginning of the first blank line after the current paragraph. If the cursor is not on a paragraph, moves the cursor to the first blank line after the next paragraph. Returns See True False Mpara Cursor moved. Cursor not moved; no more paragraphs in the file.

Print
Key Unassigned The Print function prints files or selections. If the Printcmd switch is set, PWB uses the command line given in the switch. Otherwise, PWB copies the file or selection to PRN. Under multithreaded environments, PWB runs the print command in the background. Print (Unassigned) Prints the current file. Arg textarg Print (ALT+A textarg Unassigned) Prints all the files listed in textarg. Use a space to separate each name from the preceding name. You can use environment variables to specify paths for the files.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 183 of 53 Printed: 10/09/00 02:46 PM

184

Environment and Tools

Arg boxarg | linearg | streamarg Print (ALT+A boxarg | linearg | streamarg Unassigned) Prints the selected text. Arg Meta Print (ALT+A F9 Unassigned) Cancels the current background print. Returns Update True False Print successfully submitted. Could not start print job.

In PWB 1.x there is no way to cancel a background print.

Project
Key Unassigned Project Open the last project. Arg Project (ALT+A Unassigned) Open the project makefile at the cursor as a PWB project. The name of the project is specified by the text from the cursor to the first blank character. Arg textarg Project (ALT+A textarg Unassigned) Open the project makefile specified by textarg as a PWB project. Arg Arg Project (ALT+A ALT+A Unassigned) Close the current project. Arg Meta Project (ALT+A F9 Unassigned) Open the project makefile at the cursor as a non-PWB project (foreign makefile). Arg textarg Meta Project (ALT+A textarg F9 Unassigned) Open the project makefile specified by textarg as a non-PWB project. Returns See True False A project is open. A project is not open.

Lastproject

Prompt
Key Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 184 of 54 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

185

The Prompt function displays the Text Argument dialog box where you can enter a text argument. You can use this function interactively, but because it is mainly useful in macros, it is not assigned to a key by default. You usually use Lasttext or Arg to directly enter a text argument. Prompt Displays the Text Argument dialog box without a title. See: Lasttext Arg Prompt (ALT+A Unassigned) Uses the text of the current line from the cursor to the end of the line as the title. Arg textarg Prompt (ALT+A textarg Unassigned) Uses textarg as the title. Arg boxarg | linearg | streamarg Prompt (ALT+A boxarg | linearg | streamarg Unassigned) Uses the selected text as the title. If the selection spans more than one line, the title is the first line of the selected text. Returns Example True False Textarg entered; the user chose the OK button. The dialog box was canceled.

With the following macro, PWB prompts for a Help topic:

QueryHelp := Arg "Help Topic to Find:" Prompt -> Pwbhelp QueryHelp : Ctrl+Q

When you press

CTRL+Q, PWB displays a dialog box with the string Help Topic to Find: as the title and waits for a response. PWB passes your

response to the Pwbhelp function as if the command Arg textarg Pwbhelp had been executed. If you cancel the dialog box, Prompt returns false and the macro conditional -> terminates the macro without executing Pwbhelp. See Assign

Psearch
Key
F3

Psearch Searches forward for the previously searched string or pattern. Arg Psearch (ALT+A F3) Searches forward in the file for the string specified by the text from the cursor to the first blank character.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 185 of 55 Printed: 10/09/00 02:46 PM

186

Environment and Tools

Arg textarg Psearch (ALT+A textarg F3) Searches forward for the specified text. Arg Arg Psearch (ALT+A ALT+A F3) Searches forward in the file for the regular expression specified by the text from the cursor to the first blank character. Arg Arg textarg Psearch (ALT+A ALT+A textarg F3) Searches forward for the regular expression defined by textarg. Meta ... Psearch (F9 ... F3) As above but reverses the value of the Case switch for one search. Returns True False String found. Invalid argument, or string not found.

Pwbhelp
Key Unassigned Pwbhelp Displays the default Help topic. Arg Pwbhelp (ALT+A Unassigned) Displays Help on the topic at the cursor. Equivalent to the macro _pwbhelp_context (F1). Arg textarg Pwbhelp (ALT+A textarg Unassigned) Displays Help on the specified text argument. Arg streamarg Pwbhelp (ALT+A streamarg Unassigned) Displays Help on the selected text. The selection cannot include more than one line. Meta Pwbhelp (F9 Unassigned) Prompts for a key, then displays Help on the function or macro assigned to the key you press. If you press a key that is not assigned to a function or macro, PWB displays help on the Unassigned function. If you press a key that PWB does not recognize, the prompt remains displayed until you press a key that PWB recognizes. Returns True False Help topic found. Help topic not found.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 186 of 56 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

187

Pwbhelpnext
Key
CTRL+F1

Pwbhelpnext Displays the next physical topic in the current Help database. Meta Pwbhelpnext (F9 CTRL+F1) Displays the previous Help topic on the backtrace list. This is the Help topic that you previously viewed. Up to 20 Help topics are retained in the backtrace list. Equivalent to the Back button on the Help screens and the macro _pwbhelp_back (ALT+F1). Arg Pwbhelpnext (ALT+A CTRL+F1) Displays the next occurrence of the current Help topic within the Help system. Equivalent to the macro _pwbhelp_again (Unassigned). Use this command when the Help topic appears several times in the set of open Help databases. Returns True False Help topic found. Help topic not found.

Pwbhelpsearch
Key Unassigned The Pwbhelpsearch function performs a global search of the Help system. The search is case insensitive unless you use the Meta form of Pwbhelpsearch, which uses the setting of the Case switch to determine case sensitivity. Pwbhelpsearch (Unassigned) Displays the results of the last global Help search. Equivalent to the predefined macro _pwbhelp_searchres (Unassigned). Arg Pwbhelpsearch (ALT+A Unassigned) Searches Help for the word at the cursor. Arg textarg Pwbhelpsearch (ALT+A textarg Unassigned) Searches Help for the selected text. Arg Arg Pwbhelpsearch (ALT+A ALT+A Unassigned) Searches Help using the regular expression at the cursor.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 187 of 57 Printed: 10/09/00 02:46 PM

188

Environment and Tools

Arg Arg textarg Pwbhelpsearch (ALT+A ALT+A textarg Unassigned) Searches Help for the selected regular expression. Meta ... Pwbhelpsearch (F9 ... Unassigned) As above except the search is case sensitive if the Case switch is set to yes. Returns True False At least one match found. No matches found, or search canceled.

Pwbrowse Functions
Most of the Pwbrowse... functions provided by the PWBROWSE Source Browser extension display one of the Source Browsers dialog boxes. The Source Browser functions attached to Browse menu commands are listed in the following table.
Function Pwbrowsecalltree Pwbrowseclhier Pwbrowsecltree Pwbrowsefuhier Pwbrowsegotodef Pwbrowsegotoref Pwbrowselistref Pwbrowsenext Pwbrowseoutline Pwbrowseprev Pwbrowseviewrel Pwbrowsewhref Browse Menu Command Call Tree (Fwd/Rev) Class Hierarchy Class Tree (Fwd/Rev) Function Hierarchy Goto Definition Goto Reference List References Next Module Outline Previous View Relationship Which Reference Key Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned
CTRL+NUM+

Unassigned
CTRL+NUM-

Unassigned Unassigned

The browser functions in the following table do not correspond to a Browse menu command.
Function Pwbrowse1stdef Pwbrowse1stref Pwbrowsepop Description Go to 1st definition Go to 1st reference Go to previously browsed location Key Unassigned Unassigned Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 188 of 58 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

189

Pwbwindow
Key Unassigned The Pwbwindow function opens PWB windows. If the specified window is already open, PWB switches to that window. Arg Pwbwindow (ALT+A Unassigned) Opens the PWB window with the name at the cursor. The name is specified by the text from the cursor to the first blank character. Arg textarg Pwbwindow (ALT+A textarg Unassigned) Opens the specified PWB window. Arg Meta Pwbwindow (ALT+A F9 Unassigned) Closes the PWB window specified by the name at the cursor. Arg textarg Meta Pwbwindow (ALT+A textarg F9 Unassigned) Closes the specified PWB window. Returns True False The specified window was opened. The window could not be opened.

Pword
Keys
CTRL+RIGHT , CTRL+F

Pword Moves the cursor to the beginning of the next word. A word is defined by the Word switch. Meta Pword (F9 CTRL+RIGHT ) Moves the cursor to the immediate right of the current word, or if the cursor is not in a word, moves it to the right of the next word. Returns See True False Mword Cursor moved. Cursor not moved; there are no more words in the file.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 189 of 59 Printed: 10/09/00 02:46 PM

190

Environment and Tools

Qreplace
Key
CTRL+\

The Qreplace function performs a find-and-replace operation on the current file, prompting for find-and-replacement strings and confirmation at each occurrence. Qreplace (CTRL+\) Performs the replacement from the cursor to the end of the file, wrapping around the end of the file if the Searchwrap switch is set to yes. Arg boxarg | linearg | streamarg Qreplace (ALT+A boxarg | linearg | streamarg CTRL+\) Performs the replacement over the selected area. Note that PWB does not adjust the selection at each replacement for changes in the length of the text. For boxarg and streamarg, PWB may replace text that was not included in the original selection or miss text included in the original selection. Arg mark Qreplace (ALT+A mark CTRL+\) Performs the replacement on text from the cursor to the specified mark. Replaces over text as if it were selected, according to the current selection mode. The mark argument cannot be a line number. See: Mark. Arg number Qreplace (ALT+A number CTRL+\) Performs the replacement for the specified number of lines, starting with the line at the cursor. Arg Arg ... Qreplace (ALT+A ALT+A ... CTRL+\) As above except using regular expressions. Meta ... Qreplace (F9 ... CTRL+\) As above except the sense of the Case switch is reversed for the operation. Returns See True False At least one replacement was performed. String not found, or invalid pattern.

Mreplace, Replace, Searchwrap

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 190 of 60 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

191

Quote
Key
CTRL+P

Quote Reads one key from the keyboard and types it into the file or dialog box. In a dialog box, the key is always CTRL+P, no matter what function or macro you may have assigned to CTRL+P for the editor. This is useful for typing a character (such as keystroke is assigned to a PWB function. Returns True False
TAB

or CTRL+L) whose

Quote always returns true except in the following case. Character would make line too long.

Record
Key
SHIFT+CTRL+R

The Record function toggles macro recording. While a macro is being recorded, PWB displays the letter X on the status bar, and a bullet appears next to the Record On command from the Edit menu. If a menu command cannot be recorded, it is disabled while recording. When macro recording is stopped, PWB assigns the recorded commands to the default macro name Playback. During the recording, PWB writes the name of each command to the definition of Playback in the Record window, which can be viewed as it is updated. Macro recording in PWB does not record changes in cursor position accomplished by clicking the mouse. Use the keyboard if you want to include cursor movements in a macro. Record (SHIFT+CTRL+R) Toggles macro recording on and off. Arg textarg Record (ALT+A textarg SHIFT+CTRL+R) Turns on recording if it is off and assigns the name specified in the text argument to the recorded macro. Turns off recording if it is turned on. Meta Record (F9 SHIFT+CTRL+R) Toggles macro recording. While recording, no editing commands are executed until recording is turned off. Use this form of the function to record a macro without modifying your file.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 191 of 61 Printed: 10/09/00 02:46 PM

192

Environment and Tools

Arg Record (ALT+A SHIFT+CTRL+R) Arg Arg textarg Record (ALT+A ALT+A textarg SHIFT+CTRL+R) Arg Arg Meta Record (ALT+A ALT+A F9 SHIFT+CTRL+R) As above but if the target macro already exists, the commands are appended to the end of the macro. Returns Update True False Recording turned on. Recording turned off.

In PWB 2.00, more menu commands can be recorded than with PWB 1.x.

Refresh
Key
SHIFT+F7

Refresh Prompts for confirmation and then rereads the file from disk, discarding its Undo history and all modifications to the file since the file was last saved.
Returns True False Condition File reread. Prompt canceled

Arg Refresh (ALT+A SHIFT+F7) Prompts for confirmation and then removes the file from the active window and the windows file history. If the active window is the last window that has the file in its history, the file is discarded from memory without saving changes, and the file is closed.
Returns True False Condition File removed from the window. Prompt canceled, or bad argument. The file is not removed from the window.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 192 of 62 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

193

Repeat
Key Unassigned Repeat Repeats the last editing action relative to the current cursor position. The Repeat function considers the following types of operations to be editing actions:
u

Typing a contiguous stream of characters without entering a command or moving the cursor Deleting text Pasting from the clipboard

u u

Repeat does not repeat macros or cursor movements. Arg number Repeat (ALT+A number Unassigned) Performs the last action the number of times specified by number. Returns True False Action repeated and returned true. Action repeated and returned false, or no action to repeat.

Replace
Key
CTRL+L

The Replace function performs a find-and-replace operation on the current file, prompting for find and replacement strings. Replace substitutes all matches of the search pattern without prompting for confirmation. Replace (CTRL+L) Performs the replacement from the cursor to the end of the file, wrapping around the end of the file if the Searchwrap switch is on. Arg boxarg | linearg | streamarg Replace (ALT+A boxarg | linearg | streamarg CTRL+L) Performs the replacement over the selected area. Note that PWB does not adjust the selection at each replacement for changes in the length of the text. For boxarg and streamarg, PWB may replace text that was not included in the original selection or miss text included in the original selection.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 193 of 63 Printed: 10/09/00 02:46 PM

194

Environment and Tools

Arg mark Replace (ALT+A mark CTRL+L) Performs the replacement on text from the cursor to the specified mark. It searches the range of text as if it were selected, according to the current selection mode. The mark argument cannot be a line number. Arg number Replace (ALT+A number CTRL+L) Performs the replacement over the specified number of lines, starting with the current line. Arg Arg ... Replace (ALT+A ALT+A ... CTRL+L) As above except using regular expressions. Meta ... Replace (F9 ... CTRL+L) As above except the sense of the Case switch is reversed for the operation. Returns See Example True False At least one replacement was performed. String not found, or invalid pattern.

Qreplace, Searchwrap To use the replace function in a macro, use the phrase:
...Replace "pattern" Newline "replacement" Newline +>found...

Enter the replies to the prompts as you would when executing Replace interactively. This example also shows where to place the conditional to test the result of Replace. You can specify special characters in the find-and-replacement strings by using escape sequences similar to those in the C language. Note that backslashes in the macro string must be doubled. To restore the usual prompts, use the phrase:
...Replace <

To use an empty replacement text (replace with nothing), use the following phrase:
...Replace "pattern" Newline " " Cdelete Newline...

If you find that you write many macros with empty replacements, the common phrase can be placed in a macro, as follows:
nothing := " " Cdelete Newline

In addition, macro definitions can be more readable with the following definition:
with := Newline

With these definitions, you can write:

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 194 of 64 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

... Replace "pattern" with nothing ...

195

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 195 of 65 Printed: 10/09/00 02:46 PM

196

Environment and Tools

Resize
Key Unassigned Resize Enters window-resizing mode. When in window-resizing mode, only the following actions are available:
Action Shrink one row Expand one row Shrink one column Expand one column Accept the new size Cancel the resize Key
UP DOWN LEFT RIGHT ENTER ESC

Arg number Resize (ALT+A number Unassigned) Resizes the window to number rows high. Arg number Meta Resize (ALT+A number F9 Unassigned) Resizes the window to number columns wide. See Movewindow

Restcur
Key Unassigned Restcur Moves the cursor to the last position saved with the Savecur function (Unassigned, Set To Anchor command, Edit menu). Restcur always clears the saved position. Returns See True False Selcur Position restored. No saved position to restore.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 196 of 66 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

197

Right
Keys
RIGHT , CTRL+D

Right Moves the cursor one character to the right. If this action causes the cursor to move out of the window, PWB adjusts the window to the right according to the Hscroll switch. Meta Right (F9 RIGHT ) Moves the cursor to the rightmost position in the window. Returns Example True False Cursor on text in the line. Cursor past text on the line.

In a macro, the return value of the Right function can be used to test if the cursor is on text in the line or past the end of the line. The following macro tests the return value to simulate the Endline function:
MyEndline := Begline :>loop Right +>loop

See

Begline, Endfile, Endline, Home, Left

Saveall
Key Unassigned Saveall Saves all modified disk files. Pseudofiles are not saved. Returns Saveall always returns true.

Savecur
Key Menu Unassigned Edit menu, Set Anchor command Savecur Saves the cursor position (sets an anchor).

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 197 of 67 Printed: 10/09/00 02:46 PM

198

Environment and Tools

To restore the cursor to the saved position, use the Restcur function (Unassigned). To select text from the current position to the saved position, use the Select To Anchor command from the Edit menu or the Selcur function (Unassigned). Returns Savecur always returns true.

Sdelete
Key Unassigned Sdelete Deletes the character at the cursor. Does not copy the character to the clipboard. Arg Sdelete (ALT+A Unassigned) Deletes text from the cursor to the end of the line, including the line break. The deleted text is copied to the clipboard. Arg streamarg | boxarg | linearg Sdelete (ALT+A streamarg | boxarg | linearg Unassigned) Deletes the selected stream of text from the starting point of the selection to the cursor and copies it to the clipboard. Always deletes a stream, regardless of the current selection mode. Meta ... Sdelete (F9 ... Unassigned) As above but discards the deleted text. The contents of the clipboard are unchanged. Returns Sdelete always returns true.

Searchall
Key Unassigned Searchall Highlights all occurrences of the previously searched string or pattern. Moves the cursor to the first occurrence in the file. Arg Searchall (ALT+A Unassigned) Highlights all occurrences of the string specified by the text from the cursor to the first blank character.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 198 of 68 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

199

Arg textarg Searchall (ALT+A textarg Unassigned) Highlights all occurrences of textarg. Arg Arg Searchall (ALT+A ALT+A Unassigned) Highlights all occurrences of the regular expression defined by the characters from the cursor to the first blank character. Arg streamarg Searchall (ALT+A streamarg Unassigned) Highlights all occurrences of streamarg. Arg Arg textarg Searchall (ALT+A ALT+A textarg Unassigned) Highlights all occurrences of a regular expression defined by textarg. Meta ... Searchall (F9 ... Unassigned) As above but reverses the value of the Case switch for one search. Returns True False String or pattern found. No matches found.

Selcur
Key Menu Unassigned Edit menu, Select To Anchor command Selcur Selects text from the cursor to the position saved using the Set Anchor command from the Edit menu or the Savecur function (Unassigned). If no position has been saved, Selcur selects text from the cursor to the beginning of the file. Returns Selcur always returns true.

Select
Keys
SHIFT+PGUP , SHIFT+CTRL+PGUP , SHIFT+PGDN, SHIFT+CTRL+PGDN, SHIFT+END, SHIFT+CTRL+END, SHIFT+HOME, SHIFT+CTRL+HOME, SHIFT+LEFT, SHIFT+CTRL+LEFT, SHIFT+UP , SHIFT+RIGHT , SHIFT+CTRL+RIGHT , SHIFT+DOWN

Select Causes a shifted key to take on the cursor-movement function associated with the unshifted key and begins or extends a selection.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 199 of 69 Printed: 10/09/00 02:46 PM

200

Environment and Tools

To see the key combinations currently assigned to this function, use the Key Assignments command from the Options menu.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 200 of 70 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

201

Selmode
Key Unassigned Selmode Advances the selection mode between stream, line, and box modes, starting with the current mode. Returns See True False New mode is stream mode. New mode is box mode or line mode.

_pwbstreammode, _pwbboxmode, _pwblinemode

Selwindow
Key
F6

Selwindow Moves the focus to the next window. Arg Selwindow (ALT+A F6) Moves the focus to the next unminimized window. Minimized windows (icons) are skipped. Arg number Selwindow (ALT+A number F6) Moves the focus to the specified window. Meta Selwindow (F9 F6) Moves the focus to the previous window. Arg Meta Selwindow (ALT+A F9 F6) Moves the focus to the previous unminimized window. Returns True False Focus moved to another window. No other windows are open.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 201 of 71 Printed: 10/09/00 02:46 PM

202

Environment and Tools

Setfile
Key
F2

Setfile Switches to the first file in the active windows file history. If there are no files in the file history, PWB displays the message No alternate file. When the Autosave switch is set to yes, PWB saves the current file if it has been modified. Setfile does not honor the Newwindow switch. To open a new window when you open a file, use Openfile. Arg Setfile (ALT+A F2) Switches to the filename that begins at the cursor and ends with the first blank character. Arg textarg Setfile (ALT+A textarg F2) Switches to the file specified by textarg. If the file is not already open, PWB opens it. You can use environment-variable specifiers in the argument. If the argument is a drive or directory name, PWB changes the current drive or directory to the specified one and displays a message to confirm the change. See: Infodialog. Arg !number Setfile (ALT+A !number F2) If the argument has the form !number, PWB switches to the file with that number in the file history. The number can be from 1 to 9, inclusive. See: _pwbfilen. Arg wildcard Setfile (ALT+A wildcard F2) If the argument is a wildcard, PWB creates a pseudofile containing a list of files that match the pattern. To open a file from this list, position the cursor at the beginning of the name and execute Arg Openfile (ALT+A F10) or Arg Setfile (ALT+A F2). Meta ... Setfile (F9 ... F2) As above but does not save the changes to the current file. Arg Arg Setfile (ALT+A ALT+A F2) Saves the current file. Arg Arg textarg Setfile (ALT+A ALT+A textarg F2) Saves the current file under the name specified by textarg. Returns True False wish saved. File opened successfully. No alternate file, the specified file does not exist, and you did not to create it; or the current file needs to be saved and cannot be

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 202 of 72 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

203

See

Newfile

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 203 of 73 Printed: 10/09/00 02:46 PM

204

Environment and Tools

Sethelp
Key
SHIFT+CTRL+S

The Sethelp function opens and closes single Help files. The Sethelp function can also display the current list of open Help files. Sethelp affects only the current PWB session. Arg Sethelp (ALT+A SHIFT+CTRL+S) Opens the Help file specified by the filename at the cursor. Arg streamarg | textarg Sethelp (ALT+A streamarg | textarg SHIFT+CTRL+S) Opens the Help file specified by the selected filename. Meta ... Sethelp (F9 ALT+A SHIFT+CTRL+S) As above except the specified Help file is closed. Arg ? Sethelp (ALT+A ? SHIFT+CTRL+S) Lists all currently open Help files. Returns True False Helpfiles Help file opened or closed, or list of Help files displayed. The specified file could not be opened or closed, or the list of files could not be displayed.

See

Setwindow
Key
CTRL+]

Setwindow Redisplays the contents of the active window. Meta Setwindow (F9 CTRL+]) Redisplays the current line. Arg Setwindow (ALT+A CTRL+]) Adjusts the window so that the cursor position becomes the home position (upper-left corner). Returns Setwindow always returns true.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 204 of 74 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

205

Shell
Key
SHIFT+F9

Shell Runs an operating-system command shell. To return to PWB, type exit at the operating-system prompt. Warning Do not start terminate-and-stay-resident (TSR) programs in a shell. This causes unpredictable results. Arg Shell (ALT+A SHIFT+F9) Runs the text from the cursor to the end of the line as a command to the shell, and returns to PWB. Arg boxarg | linearg Shell (ALT+A boxarg | linearg SHIFT+F9) Runs each selected line as a separate command to the shell, and returns to PWB. Arg textarg Shell (ALT+A textarg SHIFT+F9) Runs textarg as a command to the shell, and returns to PWB. Meta ... Shell (F9 ... SHIFT+F9) Runs a shell, ignoring the Autosave switch. Modified files are not saved to disk, but they are retained in PWBs virtual memory. Returns True False Shell ran successfully. Invalid argument, or error starting the operating-system command processor.

See

Askrtn, Restart , Savescreen

Sinsert
Key
CTRL+J

Sinsert Inserts a space at the cursor. Arg Sinsert (ALT+A CTRL+J) Inserts a line break at the cursor, splitting the line.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 205 of 75 Printed: 10/09/00 02:46 PM

206

Environment and Tools

Arg streamarg | linearg | boxarg Sinsert (ALT+A streamarg | linearg | boxarg CTRL+J) Inserts a stream of blanks between the starting point of the selection and the cursor. The insertion is always a stream, regardless of the current selection mode. Returns Example True False Spaces or line break inserted. Insertion would make a line too long.

The following macro inserts a stream of spaces up to the next tab stop, regardless of the current selection mode:
InsertTab := Arg Tab Sinsert

See

Insert , Linsert

Tab
Key
TAB

Tab Moves the cursor to the next tab stop. If there are no tab stops to the right of the cursor, the cursor does not move. Tab stops are defined by the Tabstops switch. Returns Update See True False Cursor moved. Cursor not moved.

In PWB 1.x, tab stops appear at fixed intervals. In PWB 2.00, tab stops can be at variable or fixed intervals. Backtab

Tell
Key
CTRL+T

Tell Displays the message Press a key to tell about and waits for a keystroke. After you press a key or combination of keys, Tell brings up the Tell dialog box showing the name of the key and its assigned function in TOOLS.INI key-assignment format.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 206 of 76 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

207

The key-assignment format is: function:key If the key is not assigned a function, Tell displays unassigned for the function name. See: Unassigned. If you press a combination of keys, but Tell still shows the Press a key prompt (when you press SCROLL LOCK, for example), PWB is unable to recognize that combination of keys and you cannot use it as a key assignment. Arg Tell (ALT+A CTRL+T) Prompts for a key, then displays the name of the function or macro assigned to the key in one of these formats: function:key macroname:=definition Arg textarg Tell (ALT+A textarg CTRL+T) Displays the definition of the macro named by textarg. If you specify a PWB function, Tell displays: function:function Meta ... Tell (F9 ... CTRL+T) As above except Tell types the result into the current file rather than displaying it in a dialog box. This is how to discover the definition of any macro, including PWB macros. Returns Update Remarks True False Assignment displayed or typed. No assignment for the key or the specified name.

In PWB 1.x, the prompt and results appear on the status bar; in PWB 2.00, the prompt and results appear in dialog boxes. Meta Tell is a convenient and reliable way of writing a key assignment when you are configuring PWB. For example, if you want to execute the Curdate function (type todays date) when you press the CTRL, SHIFT, and D keys simultaneously, perform the following steps: 1. Go to an empty line in the [PWB] section of TOOLS.INI. 2. Execute Meta Tell (F9 CTRL+T). Tell displays the message: Press a key to tell about. 3. Press the D, SHIFT, and CTRL keys simultaneously. If you have not already assigned a function to this combination, Tell types:
unassigned:Shift+Ctrl+D

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 207 of 77 Printed: 10/09/00 02:46 PM

208

Environment and Tools

4. Select the word unassigned and type curdate. 5. If you want the assignment to take effect immediately, move the cursor to the line youve just entered and execute the Assign function (ALT+=). You can use Meta Arg textarg Tell to recover the definition of a predefined PWB macro or a macro that you have not saved or entered into a file. See _pwbusern, Assign, Record

Unassigned
Keys Assigned to all available keys. Unassigned Displays a message for keys that do not have a function assignment. All unassigned keys are actually assigned the Unassigned function. Thus, to remove a function assignment for a key, assign the Unassigned function to the key. The Unassigned function is not useful in macros. Returns See The Unassigned function always returns false. Assign, Tell

Undo
Keys
ALT+BKSP, SHIFT+CTRL+BKSP

Undo Reverses the last editing operation. The maximum number of times this can be performed for each file is set by the Undocount switch. Meta Undo (F9 ALT+BKSP) Performs the operation previously reversed with Undo . This action is often called redo. Returns See True False Operation undone or redone. Nothing to undo or redo.

_pwbundo , _pwbredo , Repeat

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 208 of 78 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

209

Up
Keys
UP, CTRL+E

Up Moves the cursor up one line. If a selection has been started, it is extended by one line. If this movement results in the cursor moving out of the window, the window is adjusted upward as specified by the Vscroll switch. Meta Up (F9 UP) Moves the cursor to the top of the window without changing the column position. Returns See True False Down Cursor moved. Cursor not moved; the cursor is already at the destination.

Usercmd
Key Unassigned The Usercmd function executes a custom command added to the Run menu by using Customize command from the Run menu or setting the User switch. Arg number Usercmd (ALT+A number Unassigned) Executes the given custom Run menu command. The number can be in the range 19. Returns See True False Command exists. Command does not exist, or invalid argument.

_pwbusern, Assign, Record

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 209 of 79 Printed: 10/09/00 02:46 PM

210

Environment and Tools

Window
Key Unassigned Window Switch to the next window.
Returns True False Condition Switched to next window. No next window to switch to: zero or one window open.

Arg [[Arg]] Window (ALT+A [[ALT+A]] Unassigned) Open a new window.

Returns True False Condition Opened a new window. Window not opened.

Meta Window (F9 Unassigned) Close the active window.

Returns True False Condition Window closed. No open window to close.

Meta Arg Window (ALT+A F9 Unassigned) Switch to the previous window.

Returns True False Condition Switched to previous window. No previous window to switch to: zero or one window open.

Update See

In PWB 1.x, Arg Window and Arg Arg Window split the window at the cursor. In PWB 2.00, these forms of Window open a new window. Selwindow, Setwindow

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 210 of 80 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

211

Winstyle
Key
CTRL+F6

Winstyle Advances through the following series of window styles, starting from the current style:
Horizontal Scroll Bar No No Yes Yes Vertical Scroll Bar No Yes No Yes

When the horizontal scroll bar is not shown, a maximized window does not show its bottom border. Similarly, when the vertical scroll bar is not shown, a maximized window does not show its left and right borders. PWB always displays the title bar. To get the clean-screen look, maximize the window and advance the window style until the borders disappear. Default Returns Update Set the default window style with the Defwinstyle switch. True False Changed window style. No windows open.

The no-border state in PWB 1.x is not available in PWB 2.00. In PWB 2.00, when a window is maximized and no scroll bars are present, PWB displays the window without borders. Maximize

See

Predefined PWB Macros

PWB predefines a number of macros, most of which correspond to a command in the PWB menus. You can define a shortcut key for a menu command by assigning the key to the corresponding macro. Note that some menu commands such as the Open command from the File menu do not correspond to a macro, and some macros do not correspond to a menu command.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 211 of 81 Printed: 10/09/00 02:46 PM

212

Environment and Tools Table 7.12 PWB Macros Macro Curfile Curfileext Curfilenam _pwbarrange _pwbboxmode _pwbbuild _pwbcancelbuild _pwbcancelprint _pwbcancelsearch _pwbcascade _pwbclear _pwbclose _pwbcloseall _pwbclosefile _pwbcloseproject _pwbcompile _pwbfilen _pwbgotomatch _pwbhelp_again _pwbhelp_back _pwbhelp_contents _pwbhelp_context _pwbhelp_general _pwbhelp_index _pwbhelpnl Description Current files full path Current files extension Current files name Arrange command, Window menu Box Mode command, Edit menu Build command, Project menu Cancel Build command, Project menu Cancel Print command, File menu Cancel Search command, Search menu Cascade command, Window menu Delete command, Edit menu Close command, Window menu Close All command, Window menu Close command, File menu Close command, Project menu Compile command, Project menu n file, File menu Goto Match command, Search menu Next command, Help menu Previous Help topic Contents command, Help menu Topic command, Help menu Help on Help command, Help menu Index command, Help menu Display the message:
Online Help Not Loaded

Key Unassigned Unassigned Unassigned

ALT+F5

Unassigned Unassigned Unassigned Unassigned Unassigned

F5 DEL CTRL+F4

Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned Unassigned

ALT+F1 SHIFT+F1 F1

Unassigned Unassigned
F1 when Help

extension not loaded Unassigned Unassigned Unassigned

CTRL+F10 CTRL+F9 CTRL+F7

_pwbhelp_searchres _pwblinemode _pwblogsearch _pwbmaximize _pwbminimize _pwbmove _pwbnewfile

Search Results command, Help menu Line Mode command, Edit menu Log command, Search menu Maximize command, Window menu Minimize command, Window menu Move command, Window menu New command, File menu

Unassigned

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 212 of 82 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Table 7.12 Macro _pwbnewwindow _pwbnextfile _pwbnextlogmatch _pwbnextmatch _pwbnextmsg _pwbpreviouslogmatch _pwbpreviousmatch _pwbprevmsg _pwbprevwindow _pwbquit _pwbrebuild _pwbrecord _pwbredo _pwbrepeat _pwbresize _pwbrestore _pwbsaveall _pwbsavefile _pwbsetmsg _pwbshell _pwbstreammode _pwbtile _pwbundo _pwbusern _pwbviewbuildresults _pwbviewsearchresults _pwbwindown PWB Macros (continued) Description New command, Window menu Next command, File menu Next Match command, Search menu Next Match command, Search menu Next Error command, Project menu Previous Match command, Search menu Previous Match command, Search menu Previous Error command, Project menu Move to previous window Exit command, File menu Rebuild All command, Project menu Record command, Edit menu Redo command, Edit menu Repeat command, Edit menu Resize command, Window menu Restore command, Window menu Save All command, File menu Save command, File menu Goto Error command, Project menu DOS Shell command, File menu Stream Mode command, Edit menu Tile command, Window menu Undo command, Edit menu command n, Run menu View build results button View search results button n file, Window menu Key Unassigned Unassigned

213

SHIFT+CTRL+F3

Unassigned
SHIFT+F3 SHIFT+CTRL+F4

Unassigned
SHIFT+F4 SHIFT+F6 ALT+F4

Unassigned Unassigned Unassigned Unassigned

CTRL+F8 CTRL+F5

Unassigned
SHIFT+F2

Unassigned Unassigned Unassigned

SHIFT+F5

Unassigned
ALT+Fn

Unassigned Unassigned
ALT+n

PWB continually redefines the following macros to reflect the current files name:
Macro Curfile Curfileext Curfilenam Description Full path File extension File base name

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 213 of 83 Printed: 10/09/00 02:46 PM

214

Environment and Tools

PWB uses the following special-purpose macros:

Macro Autostart Mgreplist Playback Restart Description Executed on startup while reading TOOLS.INI List of files for logged searches, multifile replace, Mgrep, and Mreplace Default name of recorded macros (Obsolete)

By default, these macros are undefined.

Autostart
Key Unassigned The special PWB macro Autostart is executed after PWB finishes all initialization at startup. If used, it must be defined in the [PWB] section of TOOLS.INI. Definition By default, Autostart is not defined.

Curfile
Key Unassigned The Curfile macro types the full path of the current file. This macro is redefined each time you switch to a new file. Definition Example curfile := "pathname" The following macro copies the full path of the current file to the clipboard for later use:
Path2clip := Arg Curfile Copy

See

Arg, Copy, Curdate, Curday, Curfilenam, Curfileext, Curtime

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 214 of 84 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

215

Curfileext
Key Unassigned The Curfileext macro types the filename extension of the current file. This macro is redefined each time you switch to a new file. Definition Example curfileext := "extension" The following macro copies the base name plus the extension of the current file to the clipboard for later use:
Filename2clip := Arg Curfilenam Curfileext Copy

See

Arg, Copy, Curdate, Curday, Curfile, Curfilenam, Curtime

Curfilenam
Key Unassigned The Curfilenam macro types the base name of the current file. This macro is redefined each time you switch to a new file. Definition Example curfilenam := "basename" The following macro copies the base name of the current file to the clipboard for later use:
Name2clip := Arg Curfilenam Copy

See

Arg, Copy, Curdate, Curday, Curfile, Curfileext, Curtime

Mgreplist
Key Unassigned The special PWB macro Mgreplist is used by the Find and Replace commands on the Search menu, Mgrep, Mreplace, and Mreplaceall to specify the list of files to search.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 215 of 85 Printed: 10/09/00 02:46 PM

216

Environment and Tools

When you create a list of files to search using the Files button in either the Find or Replace dialog box, PWB redefines the Mgreplist macro with the specified list of files. To see the current list of files, choose the Files button in the Replace dialog box. You can change the list in this dialog box, and either choose OK to perform the find-and-replace operation, or choose Cancel to cancel the replace and accept the changes to Mgreplist. You can also insert the definition of Mgreplist into the current file by using the phrase: Arg Meta Mgreplist Tell (ALT+A F9 Mgreplist CTRL+T). You can edit the macro, then redefine it by using the Assign function (ALT+=). Definition Mgreplist:= "list" list Space-separated list of filenames The filenames can use the operating-system wildcards (* and ?), and can use environment-variable specifiers. Note that backslashes (\) must be doubled in the macro string. See Assign, Tell, Mgrep, Mreplace, Mreplaceall

Restart
Key Update Unassigned In PWB 1.x, the special PWB macro Restart is executed whenever PWB returns from a shell, build, or other external operation. In PWB 2.00, the Restart macro is never executed automatically and has no special meaning; it is an ordinary macro.

_pwbarrange
Key Menu
ALT+F5

Window menu, Arrange command

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 216 of 86 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

217

The _pwbarrange macro arranges all unminimized windows on the desktop. The following illustration shows a typical desktop after execution of _pwbarrange:

Figure 7.1

Arranged Windows

Definition

_pwbarrange:=cancel arg arrangewindow < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Arrangewindow Arranges all unminimized windows on the desktop. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running.

See

Arrangewindow

_pwbboxmode
Key Menu Definition Unassigned Edit menu, Box Mode command The _pwbboxmode macro sets the selection mode to box selection mode. _pwbboxmode := :>more selmode ->more selmode

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 217 of 87 Printed: 10/09/00 02:46 PM

218

Environment and Tools

:>more Defines the label more. Selmode Advances to the next selection mode. ->more Branches to the label more if Selmode returns false. The Selmode function advances the selection mode from box, to stream, to line. Selmode returns true when the mode is stream mode. The macro executes the Selmode function until it returns true (sets stream mode), then advances the selection mode once to set box selection mode. See Enterselmode, Selmode

_pwbbuild
Key Menu Unassigned Project menu, Build command The _pwbbuild macro builds the all target of the current PWB project. The all pseudotarget in a PWB project lists all the targets in the project. For non-PWB projects, _pwbbuild builds the targets that were last specified by using the Build Target command from the Project menu. PWB redefines _pwbbuild each time you use Build Target. If no target has been specified, NMAKE builds the first target listed in the project makefile. Definition _pwbbuild := cancel arg "all" compile < Cancel Establishes a uniform ground state by cancelling any selection or argument. Arg all Compile Builds the all pseudotarget in the current project. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Arg, Cancel, Compile

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 218 of 88 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

219

_pwbcancelbuild
Key Menu Unassigned Project menu, Cancel Build command The _pwbcancelbuild macro terminates the current background build or compile and flushes any queued build operations. Definition _pwbcancelbuild := cancel arg meta compile Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Meta Compile Terminates the background build process. See Arg, Cancel, Compile, Meta

_pwbcancelprint
Key Definition Unassigned The _pwbcancelprint macro terminates all background print operations. _pwbcancelprint := cancel arg meta print Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Meta Print Terminate background print operations. See Arg, Cancel, Meta, Print

_pwbcancelsearch
Key Menu Unassigned Search menu, Cancel Search command

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 219 of 89 Printed: 10/09/00 02:46 PM

220

Environment and Tools

The _pwbcancelsearch macro cancels the current background search. PWB performs logged searches in the background under multithreaded environments. Definition _pwbcancelsearch := cancel cancelsearch < Cancel Establishes a uniform ground state by canceling any selection or argument. Cancelsearch Cancels the current background search. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Cancelsearch, Logsearch

_pwbcascade
Key Menu
F5

Window menu, Cascade command The _pwbcascade macro arranges all unminimized windows in cascaded fashion so that all of their titles are visible. Up to 16 unminimized windows can be cascaded.

Definition

_pwbcascade := cancel arrangewindow < Cancel Establishes a uniform ground state by canceling any selection or argument. Arrangewindow Cascades all unminimized windows. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running.

See

Arrangewindow, Cancel

_pwbclear
Key
DEL

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 220 of 90 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

221

Menu

Edit menu, Delete command The _pwbclear macro removes the selected text from the file. If there is no selection, PWB removes the current line. The selection or line is not copied to the clipboard. It can be recovered only by using the Undo command from the Edit menu or Undo (ALT+BKSP).

Definition

_pwbclear := meta delete Meta Delete Removes the selection or the current line from the file without modifying the clipboard.

See

Delete, Meta

_pwbcloseall
Key Menu Definition Unassigned Window menu, Close All command The _pwbcloseall macro closes all open windows. _pwbcloseall := cancel arg arg meta window < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Arg Meta Window Closes all windows. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Arg, Cancel, Meta, Window

_pwbclosefile
Key Menu Unassigned File menu, Close command

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 221 of 91 Printed: 10/09/00 02:46 PM

222

Environment and Tools

The _pwbclosefile macro closes the current file. If no files remain in the windows file history, the window is closed. Definition _pwbclosefile := cancel closefile < Cancel Establishes a uniform ground state by canceling any selection or argument. Closefile Closes the current file. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Closefile

_pwbcloseproject
Key Menu Definition Unassigned Project menu, Close Project command The _pwbcloseproject macro closes the current project. _pwbcloseproject := cancel arg arg project < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Arg Project Closes the current project. < Restores the functions prompt (if any). By default, function prompts are suppressed within a macro. See Arg, Cancel, Project

_pwbcompile
Key Menu Unassigned Project menu, Compile File command

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 222 of 92 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

223

The _pwbcompile macro compiles the current file. Definition _pwbcompile := cancel arg compile < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Compile Compiles the current file. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Arg, Cancel, Compile

_pwbgotomatch
Key Menu Unassigned Search menu, Goto Match command The _pwbgotomatch macro sets the match listed at the current location in the Search Results pseudofile as the current match and moves the cursor to the location specified by that match. Definition _pwbgotomatch := cancel arg arg nextsearch < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Arg Nextsearch Goes to the current match. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Arg, Cancel, Nextsearch

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 223 of 93 Printed: 10/09/00 02:46 PM

224

Environment and Tools

_pwbhelpnl
The _pwbhelpnl macro displays a message indicating the Help extension is not loaded. The Help keys are assigned this macro until the Help extension is loaded. Definition _pwbhelpnl := cancel arg "OnLine Help Not Loaded" message Cancel Establishes a uniform ground state by canceling any selection or argument. Arg OnLine Help Not Loaded Message Displays the message on the status bar. See Arg, Cancel, Load, Message

_pwbhelp_again
Key Menu Unassigned Help menu, Next command The _pwbhelp_again displays the next occurrence of the last topic for which you requested Help. If no other occurrences of the topic are defined in the open files, PWB redisplays the current topic. The topic that PWB looks up when you use this command is displayed after the Next command on the Help menu, as follows: Next: topic key topic key Definition Topic string used for the command. Current key assignment for _pwbhelp_again (if any).

_pwbhelp_again:=cancel arg pwbhelp.pwbhelpnext < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Sets the Arg prefix for the Pwbhelpnext function. Pwbhelp. Specifies that the function is the PWBHELP extension function.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 224 of 94 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

225

Pwbhelpnext Displays the next occurrence of the previously requested topic. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Pwbhelpnext

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 225 of 95 Printed: 10/09/00 02:46 PM

226

Environment and Tools

_pwbhelp_back
Key
ALT+F1

The _pwbhelp_back macro displays the previously viewed Help topic. Up to 20 topics are kept in the Help backtrace list. Definition _pwbhelp_back:=cancel meta pwbhelp.pwbhelpnext < Cancel Establishes a uniform ground state by canceling any selection or argument. Meta Sets the meta prefix for the function. Pwbhelp. Specifies that the function is the PWBHELP extension function. Pwbhelpnext Displays the previously viewed Help topic. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Pwbhelpnext

_pwbhelp_contents
Key Menu
SHIFT+F1

Help menu, Contents command The _pwbhelp_contents macro opens the Help window and displays the toplevel contents of the Help system. Within the Help system, most Help topics have a Contents button at the top of the window. This button also takes you to the top-level contents.

Definition

_pwbhelp_contents:=cancel arg "advisor.hlp!h.contents" pwbhelp.pwbhelp < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg "advisor.hlp!h.contents" Defines a text argument with the topic name for the general table of contents.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 226 of 96 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

227

Pwbhelp. Specifies that the function is the PWBHELP extension function. Pwbhelp Looks up the topic h.contents in the ADVISOR.HLP Help file. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Pwbhelp

_pwbhelp_context
Key Menu
F1

Help menu, Topic command The _pwbhelp_context macro looks up Help on the topic at the cursor, the current selection, or the specified text argument.

Definition

_pwbhelp_context:=arg pwbhelp.pwbhelp < Arg Sets the Arg prefix for the Pwbhelp function. Pwbhelp. Specifies that the function is the PWBHELP extension function. Pwbhelp Displays Help on the topic at the cursor. When text is selected, displays Help on the selected text. When you have entered an argument in the Text Argument dialog box, displays Help on the topic specified by the text argument. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running.

See

Pwbhelp

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 227 of 97 Printed: 10/09/00 02:46 PM

228

Environment and Tools

_pwbhelp_general
Key Menu Unassigned Help menu, Help on Help command The _pwbhelp_general macro opens the Help window and displays information about using the Help system. Definition _pwbhelp_general:=cancel arg "advisor.hlp!h.default" pwbhelp.pwbhelp < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg "advisor.hlp!h.default" Defines a text argument with the topic name for default Help. Pwbhelp. Specifies that the function is the PWBHELP extension function. Pwbhelp Looks up the topic h.default in the ADVISOR.HLP Help file. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Pwbhelp

_pwbhelp_index
Key Menu Unassigned Help menu, Index command The _pwbhelp_index macro opens the Help window and displays the top-level table of indexes in the Help system. Within the Help system, most Help topics have an Index button at the top of the window. This button also takes you to the top-level table of indexes. Definition _pwbhelp_index:=cancel arg "advisor.hlp!h.index" pwbhelp.pwbhelp < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg "advisor.hlp!h.index" Defines a text argument with the topic name for the Help index.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 228 of 98 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

229

Pwbhelp. Specifies that the function is the PWBHELP extension function. Pwbhelp Looks up the topic h.index in the ADVISOR.HLP Help file. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Pwbhelp

_pwbhelp_searchres
Key Menu Unassigned Help menu, Search Results command The _pwbhelp_searchres macro opens the Help window and displays the list of matches found during the last global Help search. Definition _pwbhelp_searchres:=cancel pwbhelp.pwbhelpsearch < Cancel Establishes a uniform ground state by canceling any selection or argument. Pwbhelp. Specifies that the function is the PWBHELP extension function. Pwbhelpsearch Opens the Help window and displays the results of the last global Help search. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Pwbhelpsearch

_pwblinemode
Key Menu Unassigned Edit menu, Line Mode command

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 229 of 99 Printed: 10/09/00 02:46 PM

230

Environment and Tools

The _pwblinemode macro sets the selection mode to line selection mode. Definition _pwblinemode := :>more selmode ->more selmode selmode :>more Defines the label more. Selmode Advances to the next selection mode. ->more Branches to the label more if Selmode returns false. The Selmode function advances the selection mode from box, to stream, to line. Selmode returns true when the mode is stream mode. The macro executes the Selmode function until it returns true (sets stream mode), then advances the selection mode twice to set line selection mode. See Enterselmode, Selmode

_pwblogsearch
Key Menu Unassigned Search menu, Log command The _pwblogsearch macro toggles search logging on and off. When search logging is turned on, PWB displays a bullet next to the Log command on the Search menu. The Next Match command executes the _pwbnextlogmatch macro, and the Previous Match command executes the _pwbpreviouslogmatch macro. When search logging is turned off, no bullet appears and the Next Match and Previous Match commands execute _pwbnextmatch and _pwbpreviousmatch. Definition _pwblogsearch := cancel logsearch < Cancel Establishes a uniform ground state by canceling any selection or argument. Logsearch Toggles the logging of search results on and off. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Logsearch

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 230 of 100 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

231

_pwbmaximize
Key Menu
CTRL+F10

Window menu, Maximize command The _pwbmaximize macro enlarges the active window to its largest possible size, showing only the window, the menu bar, and the status bar on the PWB screen.

Definition

_pwbmaximize := cancel maximize < Cancel Establishes a uniform ground state by canceling any selection or argument. Maximize Enlarges the active window to full size. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running.

See

Cancel, Minimize

_pwbminimize
Key Menu
CTRL+F9

Window menu, Minimize command The _pwbminimize macro minimizes the active window, reducing the window to an icon. To restore a window to its original size, double-click in the box or use the Restore command (CTRL+F5) on the Window menu.

Definition

_pwbminimize := cancel minimize < Cancel Establishes a uniform ground state by canceling any selection or argument. Minimize Shrinks the window to an icon. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running.

See

Cancel, Maximize, Minimize

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 231 of 101 Printed: 10/09/00 02:46 PM

232

Environment and Tools

_pwbmove
Key Menu
CTRL+F7

Window menu, Move command The _pwbmove macro starts window-moving mode for the active window. In window-moving mode, you can only do the following:
Action Move up one row Move down one row Move left one column Move right one column Accept the new position Cancel the move Key
UP DOWN LEFT RIGHT ENTER ESC

To move the window in larger increments, you can use a numeric argument with the Movewindow function. Definition _pwbmove := cancel movewindow < Cancel Establishes a uniform ground state by canceling any selection or argument. Movewindow Starts window-moving mode. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Arrangewindow, Cancel, Maximize, Minimize, Resize

_pwbnewfile
Key Menu Unassigned File menu, New command The _pwbnewfile macro creates a new pseudofile.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 232 of 102 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

233

New pseudofiles are given a unique name of the form: <Untitled.nnn>Untitled.nnn where <nnn> is a three-digit number starting with 001 at the beginning of each PWB session. The window title shows Untitled.nnn. The file may be referred to by the name <Untitled.nnn>. When the Newwindow switch is set to yes, or the active window is a PWB window, a new window is opened for the file. Otherwise, the file is opened in the active window, and the previous file is placed in the windows file history. Definition _pwbnewfile := cancel newfile < Cancel Establishes a uniform ground state by canceling any selection or argument. Newfile Creates a new untitled pseudofile. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Setfile

_pwbnewwindow
Key Menu Unassigned Window menu, New command The _pwbnewwindow macro opens a new window, which shows the current file. The new window has the complete file history as the original window. Definition _pwbnewwindow := cancel arg window Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Window Opens a new window on the current file See Arg, Cancel, Window

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 233 of 103 Printed: 10/09/00 02:46 PM

234

Environment and Tools

_pwbnextfile
Key Menu Unassigned File menu, Next command The _pwbnextfile macro moves to the next file in the list of files specified on the PWB command line. If no more files remain in the list, this macro ends the PWB session. When the Newwindow switch is set to yes, or the active window is a PWB window, a new window is opened for the file. Otherwise, the file is opened in the active window, and the previous file is placed in the windows file history. Definition _pwbnextfile := cancel exit < Cancel Establishes a uniform ground state by canceling any selection or argument. Exit Moves to the next file specified on the command line. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Exit, Askexit, Cancel, PWB Command Line

_pwbnextlogmatch
Key Menu
SHIFT+CTRL+F3

Search menu, Next Match command The _pwbnextlogmatch macro advances the cursor to the next match listed in the Search Results pseudofile. The Next Match command on the Search menu executes this macro when search logging is turned on. When search logging is turned off, Next Match executes the _pwbnextmatch macro.

Definition

_pwbnextlogmatch := cancel nextsearch < Cancel Establishes a uniform ground state by canceling any selection or argument.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 234 of 104 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

235

Nextsearch Advances to the next match in Search Results. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Nextsearch

_pwbnextmatch
Key Menu Unassigned Search menu, Next Match command The _pwbnextmatch macro searches forward in the file using the last search pattern and options. The search options are Match Case, Wrap Around, and Regular Expression. The Next Match command on the Search menu executes this macro when search logging is turned off. When search logging is turned on, Next Match executes the _pwbnextlogmatch macro. Definition _pwbnextmatch := cancel psearch < Cancel Establishes a uniform ground state by canceling any selection or argument. Psearch Searches forward in the file for the next occurrence of the last search string or pattern. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Psearch

_pwbnextmsg
Key Menu
SHIFT+F3

Project menu, Next Error command

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 235 of 105 Printed: 10/09/00 02:46 PM

236

Environment and Tools

The _pwbnextmsg macro moves the cursor to the next message in Build Results. Definition _pwbnextmsg := cancel nextmsg < Cancel Establishes a uniform ground state by canceling any selection or argument. Nextmsg Goes to the next message in Build Results. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Nextmsg

_pwbpreviouslogmatch
Key Menu
SHIFT+CTRL+F4

Search menu, Previous Match command The _pwbpreviouslogmatch macro moves the cursor to the previous match listed in the Search Results pseudofile. The Previous Match command on the Search menu executes this macro when search logging is turned on. When search logging is turned off, Previous Match executes the _pwbpreviousmatch macro.

Definition

_pwbpreviouslogmatch := cancel arg "-1" nextsearch < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg "-1" Nextsearch Moves to the previous match listed in Search Results. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running.

See

Arg, Cancel, Nextsearch

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 236 of 106 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

237

_pwbpreviousmatch
Key Menu Unassigned Search menu, Previous Match command The _pwbpreviousmatch macro searches backward in the file, using the last search pattern and options. The search options are Match Case, Wrap Around, and Regular Expression. The Previous Match command on the Search menu executes this macro when search logging is turned off. When search logging is turned on, Previous Match executes the _pwbpreviouslogmatch macro. Definition _pwbpreviousmatch := cancel msearch < Cancel Establishes a uniform ground state by canceling any selection or argument. Msearch Searches backward in the file for the last search string or pattern. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Msearch

_pwbprevmsg
Key Menu
SHIFT+F4

Project menu, Previous Error command The _pwbprevmsg macro moves the cursor to the previous message in the Build Results pseudofile.

Definition

_pwbprevmsg := cancel arg "-1" nextmsg < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg "-1" Nextmsg Goes to the previous message in Build Results.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 237 of 107 Printed: 10/09/00 02:46 PM

238

Environment and Tools

< Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Arg, Cancel, Nextmsg

_pwbprevwindow
Key
SHIFT+F6

The _pwbprevwindow macro moves the focus to the previous window. That is, PWB sets the previously active window as the active window. This action moves among the open windows in the reverse order of Selwindow (F6). Definition _pwbprevwindow:=cancel meta selwindow < Cancel Establishes a uniform ground state by canceling any selection or argument. Meta Selwindow Moves the focus to the previous window. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Meta, Selwindow

_pwbquit
Key Menu
ALT+F4

File menu, Exit command The _pwbquit macro leaves PWB immediately. Any specified files on the PWB command line that have not been opened are ignored.

Definition

_pwbquit := cancel arg exit < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Exit Leaves PWB.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 238 of 108 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

239

< Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Arg, Askexit, Cancel, Exit, Savescreen

_pwbrebuild
Key Menu Unassigned Project menu, Rebuild All command The _pwbrebuild macro forces a rebuild of everything in the current project. For non-PWB projects, _pwbrebuild rebuilds the targets that were last specified by using the Build Target command on the Project menu. PWB redefines _pwbrebuild each time you use Build Target. If no target has been specified, NMAKE rebuilds the first target listed in the project makefile. Definition _pwbrebuild := cancel arg meta "all" compile < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Meta "all" Compile Rebuilds the all pseudotarget. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Arg, Cancel, Compile, Meta

_pwbrecord
Key Menu Unassigned Edit menu, Record On command The _pwbrecord macro toggles macro recording on and off. If you have not set the recorded macro name and key, PWB displays the Set Macro Record dialog box so you can set them. Execute _pwbrecord again to start recording. Definition _pwbrecord := cancel record <

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 239 of 109 Printed: 10/09/00 02:46 PM

240

Environment and Tools

Cancel Establishes a uniform ground state by canceling any selection or argument. Record Toggles macro recording on and off. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Record

_pwbredo
Key Menu Unassigned Edit menu, Redo command The _pwbredo macro restores the last modification that was reversed using Edit Undo or Undo (ALT+BKSP). Definition _pwbredo := cancel meta undo < Cancel Establishes a uniform ground state by canceling any selection or argument. Meta Undo Restores the last undone modification. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Meta, Undo

_pwbrepeat
Key Menu Definition Unassigned Edit menu, Repeat command The _pwbrepeat macro repeats the last editing operation once. _pwbrepeat := cancel repeat <

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 240 of 110 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

241

Cancel Establishes a uniform ground state by canceling any selection or argument. Repeat Repeats the last operation one time. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Repeat

_pwbresize
Key Menu
CTRL+F8

Window menu, Size command The _pwbresize macro starts window-sizing mode for the active window. When in window-resizing mode, only the following actions are available:
Action Shrink one row Expand one row Shrink one column Expand one column Accept the new size Cancel the resize Key
UP DOWN LEFT RIGHT ENTER ESC

To size the window in larger increments, you can use the numeric forms of the Resize function. Definition _pwbresize := cancel resize < Cancel Establishes a uniform ground state by canceling any selection or argument. Resize Starts window-sizing mode.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 241 of 111 Printed: 10/09/00 02:46 PM

242

Environment and Tools

< Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Arrangewindow, Cancel, Maximize, Minimize, Movewindow

_pwbrestore
Key Menu
CTRL+F5

Window menu, Restore command The _pwbrestore macro restores the active window to its size before it was maximized or minimized.

Definition

_pwbrestore := cancel meta maximize Cancel Establishes a uniform ground state by canceling any selection or argument. Meta Maximize Restores the window to its previous size.

See

Cancel, Maximize, Meta, Minimize

_pwbsaveall
Key Menu Unassigned File menu, Save All command The _pwbsaveall macro saves all modified disk files. Modified pseudofiles are not saved. Definition _pwbsaveall := cancel saveall < Cancel Establishes a uniform ground state by canceling any selection or argument. Saveall Writes all modified files to disk.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 242 of 112 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

243

< Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, Saveall

_pwbsavefile
Key Menu
SHIFT+F2

File menu, Save command The _pwbsavefile macro saves the current file to disk. If the current file is a pseudofile (an untitled file), PWB displays the Save As dialog box so you can give the file a more meaningful name.

Definition

_pwbsavefile := cancel arg arg setfile < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Arg Setfile Writes the current file to disk. < Restores the functions prompt (if any). By default, function prompts are suppressed when a macro is running.

See

Arg, Cancel, Setfile

_pwbsetmsg
Key Menu Unassigned Project menu, Goto Error command The _pwbsetmsg macro sets the message listed at the current location in the Build Results pseudofile as the current message and moves the cursor to the location specified by that message. See Definition Nextmsg _pwbsetmsg := cancel arg arg nextmsg <

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 243 of 113 Printed: 10/09/00 02:46 PM

244

Environment and Tools

Cancel Establishes a uniform ground state by canceling any selection or argument. Arg Arg Nextmsg Goes to the current message. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Arg, Cancel, Nextmsg

_pwbshell
Key Menu Unassigned File menu, DOS Shell command The _pwbshell macro temporarily leaves PWB, starting a new operating-system shell. To return to PWB, type exit at the operating-system prompt. Definition _pwbshell := cancel shell < Cancel Establishes a uniform ground state by canceling any selection or argument. Shell Starts an operating-system shell. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Askrtn, Cancel, Savescreen, Shell

_pwbstreammode
Key Menu Definition Unassigned Edit menu, Stream Mode command The _pwbstreammode macro sets the selection mode to stream selection mode. _pwbstreammode := :>more selmode ->more

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 244 of 114 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

245

:>more Defines the label more. Selmode Advances to the next selection mode. ->more Branches to the label more if Selmode returns false. The Selmode function advances the selection mode from box, to stream, to line. Selmode returns true when the mode is stream mode. The macro executes Selmode until it returns true (sets stream selection mode). See Enterselmode, Selmode

_pwbtile
Key Menu
SHIFT+F5

Window menu, Tile command The _pwbtile macro tiles all unminimized windows on the desktop so that no windows overlap and the desktop is completely covered. Up to 16 unminimized windows can be tiled.

Definition

_pwbtile := cancel meta arrangewindow < Cancel Establishes a uniform ground state by canceling any selection or argument. Meta Arrangewindow Tiles all unminimized windows. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running.

See

Arrangewindow, Cancel, Meta

_pwbundo
Key Menu Unassigned Edit menu, Undo command

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 245 of 115 Printed: 10/09/00 02:46 PM

246

Environment and Tools

The _pwbundo macro reverses the last modification made to the current file. The maximum number of modifications that can be undone for each file is determined by the Undocount switch. Definition _pwbundo := cancel undo < Cancel Establishes a uniform ground state by canceling any selection or argument. Undo Reverses the last modification. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. See Cancel, _pwbredo

_pwbusern
Macro _pwbuser1 _pwbuser2 _pwbuser3 _pwbuser4 _pwbuser5 _pwbuser6 _pwbuser7 _pwbuser8 _pwbuser9 Description Run custom Run menu command 1 . . . . . . . Run custom Run menu command 9 Key [ [ALT+Fn] ] [ [ALT+Fn] ] [ [ALT+Fn] ] [ [ALT+Fn] ] [ [ALT+Fn] ] [ [ALT+Fn] ] [ [ALT+Fn] ] [ [ALT+Fn] ] [ [ALT+Fn] ]

Menu

Run command command Title of custom Run menu item.

The _pwbusern macros execute custom commands in the Run menu. To add a new command to the Run menu, use the Customize Run Menu command or assign a value to the User switch. Definition _pwbusern := cancel arg "n" usercmd <

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 246 of 116 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

247

Cancel Establishes a uniform ground state canceling any selection or argument. Arg "n" Usercmd Executes custom run menu item number n. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. Example See _pwbuser1 := cancel arg 1 usercmd < This macro executes custom Run menu command number 1. Arg, Cancel, Usercmd

_pwbviewbuildresults
Key Button Unassigned The View Results button in the Build Operation Complete dialog box. The _pwbviewbuildresults macro opens the Build Results window. PWB executes this macro when you choose the View Results button in the Build Operation Complete dialog box. You can redefine this macro to change the behavior of the View Results button. For example, if you want to move to the first message in the log and arrange windows, add _pwbnextmsg _pwbarrangewindow to the end of the macro definition. Definition _pwbviewbuildresults:=cancel arg "<COMPILE>" pwbwindow Cancel Establishes a uniform ground state by canceling any selection or argument. Arg "<COMPILE>" Pwbwindow Opens the Build Results window. See Pwbwindow

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 247 of 117 Printed: 10/09/00 02:46 PM

248

Environment and Tools

_pwbviewsearchresults
Key Button Unassigned The View Results button in the Search Operation Complete dialog box. The _pwbviewSearchresults macro opens the Search Results window. PWB executes this macro when you choose the View Results button in the Search Operation Complete dialog box. You can redefine this macro to change the behavior of the View Results button. For example, if you want to move to the first location in the log and arrange windows, add _pwbnextsearch _pwbarrangewindow to the end of the macro definition. Definition _pwbviewsearchresults:=cancel arg <SEARCH> pwbwindow Cancel Establishes a uniform ground state by canceling any selection or argument. Arg "<SEARCH>" Pwbwindow Opens the Search Results window. See Pwbwindow

_pwbwindown
Macro _pwbwindow1 _pwbwindow2 _pwbwindow3 _pwbwindow4 _pwbwindow5 _pwbwindow6 _pwbwindow7 _pwbwindow8 _pwbwindow9 Description Switch to window 1 . . . . . . . Switch to window 9 Key
ALT+1 ALT+2 ALT+3 ALT+4 ALT+5 ALT+6 ALT+7 ALT+8 ALT+9

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 248 of 118 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

249

Menu

Window n file n file Window number Current file in the window

The _pwbwindown macros each set a specific numbered window as the active window. Definition _pwbwindown := cancel arg "n" selwindow < Cancel Establishes a uniform ground state by canceling any selection or argument. Arg "n" Selwindow Moves to window number n. < Restores the functions prompt (if any). By default, function prompts are suppressed while a macro is running. Example See _pwbwindow1 := cancel arg "1" selwindow < This macro sets window number 1 as the active window. Arg, Cancel, Selwindow

PWB Switches
PWB provides the following switches to customize its behavior. You set switches by adding entries to the TOOLS.INI file or by using the Editor Settings, Key Assignments, and Colors commands on the Options menu.
Switch Askexit Askrtn Autoload Autosave Backup Beep Build Case Description Prompt before leaving PWB Prompt before returning from a shell Load PWB extensions automatically Save files when switching File backup mode Issue audible or visible alerts Rules and definitions for the build process Make letter case significant in searches

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 249 of 119 Printed: 10/09/00 02:46 PM

250

Environment and Tools Color Color of interface elements

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 250 of 120 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Switch Cursormode Dblclick Deflang Defwinstyle Editreadonly Enablealtgr Entab Enterinsmode Enterlogmode Enterselmode Envcursave Envprojsave Factor Fastfunc Filetab Friction Height Hike Hscroll Infodialog Keepmem Lastproject Load Markfile Mousemode Msgdialog Msgflush Newwindow Noise Printcmd Readonly Realtabs Restorelayout Rmargin Savescreen Description Block or underline cursor state Double-click threshold Default language Default window style Allow editing of files marked read-only on disk Enable the ALTGR key on non-US keyboards Tab translation mode while editing Enter PWB in insert mode Enter PWB with search logging turned on Enter PWB in specified selection mode Save environment variables for PWB sessions Save environment variables for projects Auto-repeat factor Functions for fast auto-repeat Width of tab characters in the file Delay between repetitions of fast functions Height of the display Window adjustment factor Horizontal scrolling factor Set of information dialogs displayed XMS/EMS memory kept during shell, build, and compile Set the last project on startup PWB extension to load Name of the current mark file Mouse configuration; disabled or swapped buttons Display a dialog box for build results Keep only one set of build results Create a new window when opening a file Line counting interval Command for printing files Command for saving disk read-only files Preserve tab characters in the file Restore the window layout when a project is set Right margin for word wrap Preserve the operating-system screen

251

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 251 of 121 Printed: 10/09/00 02:46 PM

252

Environment and Tools Switch Searchdialog Searchflush Searchwrap Shortnames Softcr Tabalign Tabdisp Tabstops Tilemode Timersave Tmpsav Traildisp Traillines Traillinesdisp Trailspace Undelcount Undocount Unixre User Vscroll Width Word Wordwrap Description Display a dialog box for search results Keep only one set of search results Make searches wrap around the end of the file Allow access to loaded files by base name Perform automatic indenting Align the cursor in tab fields Character for displaying tab characters Variable tab stops Window tiling style Timer interval for saving files Number of files kept in file history Character for displaying trailing spaces Preserve trailing lines Character for displaying trailing lines Preserve trailing spaces Maximum number of file backups Maximum number of edits per file to undo Use UNIX regular-expression syntax Custom Run menu item Vertical scrolling factor Width of the display Definition of a word Wrap words as they are entered

Extension Switches
The standard PWB extensions define additional switches to control their behavior. You set these switches in tagged sections of TOOLS.INI specific to that extension.
PWB Extension PWBROWSE.MXT PWBMASM.MXT PWBHELP.MXT Description Source Browser Assembly Language Microsoft Advisor Help TOOLS.INI Section Tag [PWB-PWBROWSE] [PWB-PWBMASM] [PWB-PWBHELP]

The PWBROWSE switches are described in Browser Switches on page 286. The PWBHELP switches are described in Help Switches on page 287.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 252 of 122 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

253

Filename-Parts Syntax
The filename-parts syntax is used by PWB to pass the name of the current file to external programs or operating-system commands. You use this syntax in the Printcmd, Readonly, and User switches. Syntax Syntax %% A literal percent sign (%). %s The fully qualified path of the current file. If the current file is a pseudofile, %s specifies the name of a temporary disk file created for the external command to operate on. The temporary file is destroyed before returning to PWB and is never accessible to the editor. %| [[d]][[p]][[f]][[e]]F Parts of the current filename. The parts of the name are drive, path, filename, and extension. If the current file is a disk file named:
C:\SCRATCH\TEST.TXT

Syntax

or the pseudofile:
"<COMPILE>Build Results"

the given syntax yields:

Syntax %|F %|dF %|pF %|fF %|eF %|pfF %s %% Disk File C:\SCRATCH\TEST.TXT C: \SCRATCH TEST .TXT \SCRATCH\TEST C:\SCRATCH\TEST.TXT % <COMPILE> C:\TMP\PWB00031.R00 % <COMPILE> Pseudofile <COMPILE>

The title of a pseudofile cannot be specified with the filename-parts syntax, but it is accessible to macros by using the Curfile predefined macro. Warning The %|F syntax always specifies the name of the current file in the active window. For some commands, such as the command specified in the Readonly switch, this may not be the desired file. Use %s for the Readonly switch.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 253 of 123 Printed: 10/09/00 02:46 PM

254

Environment and Tools

See

Printcmd, Readonly, User

Boolean Switch Syntax

You can use either one of the following syntaxes to set Boolean switches in PWB: Syntax 1 switch : [[ yes | no | on | off | 1 | 0 ]] switch The name of a PWB switch. yes, on, 1 Enable the feature controlled by switch. no, off, 0 Disable the feature controlled by switch. Syntax 2 [[no ]]switch : switch Enable the feature controlled by switch. no switch Disable the feature controlled by switch.

Askexit
Type Boolean The Askexit switch determines if PWB prompts for confirmation before returning to the operating system. Syntax Askexit:{ yes | no } yes no Default See Prompt for confirmation before leaving PWB. Do not prompt before leaving PWB.

Askexit:no Exit

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 254 of 124 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

255

Askrtn
Type Boolean The Askrtn switch determines if PWB prompts before returning to PWB after running a shell or external command. Syntax Askrtn:{ yes | no } yes Prompt for confirmation before returning to PWB. This setting allows you to review the contents of the operating-system screen before returning to the editor. no Do not prompt before returning to PWB. Default See Askrtn:yes Shell

Autoload
Type Boolean The Autoload switch determines if PWB automatically loads its extensions on startup. When the Autoload switch is yes, PWB automatically loads extensions whose names begin with PWB and are found in the same directory as PWB.EXE. PWB always loads extensions named in a Load switch. If you disable automatic extension loading, you can load extensions as you need them by assigning a value to the Load switch as follows: Arg load: pwbextension Assign (ALT+A load:pwbextension ALT+=). The pwbextension is the path of the extensions executable file. PWB automatically assumes the filename extension .MXT. You can specify an environment-variable path by using an environment-variable specifier. Syntax Autoload:{ yes | no } yes Automatically load PWB extensions on startup.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 255 of 125 Printed: 10/09/00 02:46 PM

256

Environment and Tools

no Do not automatically load PWB extensions on startup. Load only those extensions named in Load switches in TOOLS.INI. Default Update Autoload:yes PWB 1.x extensions are not compatible with PWB 2.0. They are refused when you request that they be loaded. Old extensions must be recompiled with the new extension-support libraries and header files. In some cases, old extensions must also be modified for use with PWB 2.00. Updated Microsoft PWB 1.x extensions not included with this product are available by contacting Microsoft Product Support Services in the United States or your local Microsoft subsidiary.

Autosave
Type Boolean The Autosave switch determines if PWB automatically saves the current file without prompting whenever you move to another file, exit PWB, or execute an external operation such as a shell, build, or compile. When the Autosave switch is set to no, PWB maintains the contents of files in memory for internal operations, and prompts to save modified files on exit or for external operations such as a build. With this setting, PWB never saves a file unless you explicitly save it. Syntax Autosave:{ yes | no } yes no Default Update See Automatically save files. Do not automatically save files.

Autosave:no In PWB 1.x, the default value of Autosave is yes. Shell, Timersave

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 256 of 126 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

257

Backup
Type Text The Backup switch determines what happens to the old copy of a file before the new version is saved to disk. Syntax Backup:[[ undel | bak ]] (none) No backup: PWB overtypes the file. undel PWB moves the old file to a hidden directory so you can retrieve it with the UNDEL utility. The number of copies saved is specified by the Undelcount switch. bak The extension of the previous version of the file is changed to .BAK. Default Backup:bak

Beep
Type Boolean The Beep switch determines PWBs alerting method. When set to yes, PWB issues an audible sound. When no, PWB flashes the menu bara visual beep. Syntax Beep:{ yes | no } yes no Default Generate an audible beep. Flash the menu bar.

Beep:yes

Case
Type Boolean The Case switch determines if letter case is distinguished in searches.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 257 of 127 Printed: 10/09/00 02:46 PM

258

Environment and Tools

The search functions that use the Case switch have meta forms that temporarily reverse the sense of the Case switch. The Unixre and Case switches have no effect on the syntax of regular expressions used by the Build or Word switches. These switches always use case-sensitive UNIX regular expressions. Syntax Case:{ yes | no } yes Case is significant in searches. Uppercase letters in search patterns do not match lowercase letters in text. no Case is not significant in searches. Uppercase letters match lowercase letters. Default See Case:no Meta, Mgrep, Mreplace, Msearch, Psearch, Replace.

Color
Type Syntax Text The Color switch specifies color of various parts of the PWB display. Color:name value name Identifies the part of PWB affected by the color value. value Two hexadecimal digits specifying the foreground and background color of the indicated item.

Color Names
PWB uses the following color names and default color values for the various parts of the PWB display:
Table 7.13 PWB Color Names Name Alert Background Border Default Value 70 07 07 Description Message box (Not visible) Window borders

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 258 of 128 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Table 7.13 PWB Color Names (continued) Name Builderr Buttondown Desktop Dialogaccel Dialogaccelbor Dialogbox Disabled Elevator Enabled Greyed Helpbold* Helpitalic* Helpnorm* Helpunderline* Helpwarning* Highlight Hilitectrl Info Itemhilitesel Listbox Location Menu Menubox Menuhilite Menuhilitesel Menuselected Message Pushbutton Pwbwindowborder Pwbwindowtext Scratch Scrollbar Selection Shadow Default Value 40 07 80 7F 7F 70 78 07 70 78 8F 8A 87 8C 70 1F 07 3F 0F 70 70 70 70 7F 0F 07 70 70 07 87 07 70 71 08 Description Build message line in active window Button while it is down Desktop Dialog box accelerator Dialog box accelerator border Dialog box Disabled items in menus and dialogs Scroll box Available items in menus and dialogs (Not visible) Bold Help text Italic Help text and the characters Plain Help text Emphasized Help text Current hyperlink Highlighted text; text found by searches Highlighted control item Special information Highlighted character in selected item List box within a dialog box Location indicator in status bar Menu bar Menu Highlighted character in menu Highlighted character in selected menu Selected menu Message area of status bar Button that is not pressed PWB window borders PWB window text (Not visible) Gray area and arrows in scroll bar Current selection Shadows

259

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 259 of 129 Printed: 10/09/00 02:46 PM

260

Environment and Tools Table 7.13 PWB Color Names (continued) Name Status Text Default Value 7F 17 Description Indicator area of status bar Text in a window

* Defined by the Help extension. Define these settings in the [PWB-PWBHELP] section of TOOLS.INI.

Color Values
Color values for the Color switch are two hexadecimal digits that specify the color of the item. The first digit specifies the background color and the second digit specifies the foreground color, according to the following table:
Table 7.14 PWB Color Values Color Black Blue Green Cyan Red Magenta Brown White Digit 0 1 2 3 4 5 6 7 Color Dark Gray Bright Blue Bright Green Bright Cyan Bright Red Bright Magenta Yellow Bright White Digit 8 9 A B C D E F

For example, a setting of 3E displays a cyan background (3) and a yellow foreground (E). Note that only color displays support all the colors listed. If you have a monochrome adapter or monochrome monitor, the only available colors are black (0), white (7), and bright white (F). All other colors are displayed as white.

Cursormode
Type Numeric The Cursormode switch determines the shape of the cursor when PWB is in insert and overtype mode, according to the following table:

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 260 of 130 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Cursormode Value 0 1 2 3 Insert Mode Cursor Underscore Block Block Underscore Overtype Mode Cursor Underscore Block Underscore Block

261

Default See

Cursormode:2 Status Bar

Dblclick
Type Numeric The Dblclick switch sets the double-click threshold for the mouse (the maximum time between successive clicks of the mouse button). The units for the Dblclick switch are 1/18 of a second. Default See Dblclick:10 Mousemode

Deflang
Type Text The Deflang switch determines the default file extension for file lists in PWB dialog boxes. Syntax Deflang:language language One of the following settings:
Setting NONE Asm Basic C Extension .* .ASM .BAS .C

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 261 of 131 Printed: 10/09/00 02:46 PM

262

Environment and Tools Setting C++ CXX COBOL FORTRAN LISP Pascal Extension .CPP .CXX .CBL .FOR .LSP .PAS

Default

Deflang:NONE

Defwinstyle
Type Numeric The Defwinstyle switch sets the default window style. The possible values for Defwinstyle are:
Value 1 3 5 7 Style No scroll bars Vertical scroll bar Horizontal scroll bar Both scroll bars

You can change the active window style by using the Winstyle function (CTRL+F6). Default See Defwinstyle:7 Maximize

Editreadonly
Type Boolean The Editreadonly switch determines if PWB allows you to edit a file marked read-only on disk.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 262 of 132 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

263

Syntax

Editreadonly:{ yes | no } yes Allow modification of files that are marked read-only on disk. When PWB attempts to save the modified file, PWB informs you that the file is marked read-only. It also prompts you to confirm that the command specified by the Readonly switch is to be run. If you decline to run the command, PWB gives you the opportunity to save the file with a different name. no Disallow modification of read-only files. For files that cannot be modified, PWB displays the letter R on the status bar. You can reenable modification of a read-only file by using the Read Only command on the Edit menu or the Noedit function.

Default

Editreadonly:yes

Enablealtgr
Type Boolean The Enablealtgr switch determines if PWB recognizes the ALTGR key (the right ALT key) on international keyboards as ALTGR (Graphic Alt) or ALT. When ALTGR is enabled, pressing ALTGR+key produces the corresponding graphic character. ALTGR is never recognized as a key name for use in PWB key assignments. Syntax Enablealtgr:{ yes | no } yes no Default Recognize the right Recognize the right
ALT ALT

key as key as

ALTGR. ALT.

Enablealtgr:no

Entab
Type Numeric The Entab switch controls how PWB converts white space on modified lines. PWB converts white space only on the lines that you modify.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 263 of 133 Printed: 10/09/00 02:46 PM

264

Environment and Tools

When the Realtabs switch is set to yes, tab characters are converted. When set to no, tab characters are not converted. The Entab switch can have the following values:
Value 0 1 Meaning Convert all white space to space (ASCII 32) characters. Convert white space outside quoted strings to tabs. A quoted string is any span of characters enclosed by a pair of single quotation marks or a pair of double quotation marks. PWB does not recognize escape sequences because they are language-specific. For well-behaved conversions with this setting, make sure that you use a numeric escape sequence to encode quotation marks in strings or character literals. 2 Convert white space to tabs.

With settings 1 and 2, if the white space being considered for conversion to a tab character occupies an entire tab field or ends at the boundary of a tab field, it is converted to a tab (ASCII 9) character. The width of a tab field is specified by the Filetab switch. In all conversions, PWB maintains the text alignment as it is displayed on screen. Default See Entab:1 Filetab, Realtabs, Tabalign

Enterinsmode
Type Boolean The Enterinsmode switch determines if PWB is to start in insert mode or overtype mode. You can toggle the current mode by using the Insertmode function (INS). When the current mode is overtype mode, the letter O appears on the status bar. Depending on the setting of the Cursormode switch, the shape of the cursor reflects the current mode. Syntax Enterinsmode:{ yes | no } yes no Start PWB in insert mode. Start PWB in overtype mode.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 264 of 134 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

265

Default

Enterinsmode:yes

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 265 of 135 Printed: 10/09/00 02:46 PM

266

Environment and Tools

Enterlogmode
Type Boolean The Enterlogmode switch determines if search logging is turned on or off when PWB starts up. The current search-logging mode can be changed at any time using the Log command on the Search menu or the Logsearch function (Unassigned). Syntax Enterlogmode:{ yes | no } yes no Default Start PWB with search logging on. Start PWB with search logging off.

Enterlogmode:no

Enterselmode
Type Syntax Text The Enterselmode switch determines the selection mode when PWB starts up. Enterselmode:{ stream | box | line } stream Starts PWB in stream selection mode. box Starts PWB in box selection mode. line Starts PWB in line selection mode. Default See Enterselmode:stream Selmode

Envcursave
Type Boolean

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 266 of 136 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

267

The Envcursave switch determines if PWB saves and restores the current environment table for PWB sessions. You can change environment variables by using the Environment command on the Options menu or the Environment function (Unassigned). If you always want to use the operating-system environment, set both Envcursave and Envprojsave to no. Syntax Envcursave:{ yes | no } yes Save and restore environment variables for PWB sessions. Use this setting if you want to use an environment that is specific to PWB. The PWB environment overrides the operating-system environment. no Do not save environment variables between PWB sessions. Default Update Envcursave:no In PWB 1.x, the INCLUDE, LIB, and HELPFILES environment variables were always saved for PWB sessions and projects.

Envprojsave
Type Boolean The Envprojsave switch determines if PWB saves and restores the environment table for each project. A projects environment overrides both the PWB environment and the external (operating-system) environment. If you always want to use the operating-system environment table, set both Envcursave and Envprojsave to no. You can change environment variables by using the Environment command on the Options menu or the Environment function (Unassigned). Syntax Envprojsave:{ yes | no } yes Save environment variables for the project. Use this setting if you want to set project-specific environments. no Do not save environment variables for the project. Default Envprojsave:yes

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 267 of 137 Printed: 10/09/00 02:46 PM

268

Environment and Tools

Update

In PWB 1.x, the INCLUDE, LIB, and HELPFILES environment variables were always saved for PWB sessions and projects.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 268 of 138 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

269

Factor
Type Text The Factor switch, together with the Friction switch, controls how quickly PWB executes a fast function. A fast function is a PWB function whose action repeats as rapidly as possible while you hold down the associated keystroke. Syntax Factor:{ %percent | -constant } [[count]] percent Percentage between 0 and 100 to reduce friction. constant Constant value between 0 and 65,535 to reduce friction. count Interval between reductions of friction. PWB reduces friction by percent percent or constant every count repetition of a keystroke, until friction is zero. Default Example Factor:%50 10 If you hold down the RIGHT ARROW key with the settings:
Right :RIGHT Fastfunc:Right Friction:1000 Factor :%75 7

PWB moves the cursor at the current speed until it has moved seven characters to the right. Then PWB changes the friction to 250 (75 percent reduction of the initial friction of 1000). When the cursor has moved 14 characters, the friction changes to 188 (75 percent reduction of the friction of 250). The cursor moves faster the longer you hold down the RIGHT ARROW key. See Fastfunc

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 269 of 139 Printed: 10/09/00 02:46 PM

270

Environment and Tools

Fastfunc
Type Text The Fastfunc switch specifies functions whose action is rapidly repeated by PWB as you hold down the associated key combination. The Friction and Factor switches control the repeat speed and acceleration of fast functions. Syntax Fastfunc:function {on | off} function on off Default PWB function to repeat.

Enable fast repeat for function. Disable fast repeat for function.

Fastfunc:Down on Fastfunc:Left on Fastfunc:Mlines on Fastfunc:Mpage on Fastfunc:Mpara on Fastfunc:Mword on Fastfunc:Plines on Fastfunc:Ppage on Fastfunc:Ppara on Fastfunc:Pword on Fastfunc:Right on Fastfunc:Up on

Filetab
Type Numeric The Filetab switch determines the width of a tab field for displaying tab (ASCII 9) characters in the file. The width of a tab field determines how white space is translated when the Realtabs switch is set to no. The Filetab switch does not affect the cursor-movement functions Tab (TAB) and Backtab (SHIFT+TAB). Default See Filetab:8 Entab, Realtabs, Tabdisp

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 270 of 140 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

271

Friction
Type Numeric The Friction switch, together with the Factor switch, controls how quickly PWB executes a fast function. A fast function is a PWB function whose action repeats rapidly when you hold down the associated key. The value of the Friction switch is a decimal number between 0 and 65,535 and specifies the delay between repetitions of a fast function. As the function is repeated, the delay is reduced according to the setting of the Factor switch. Default See Friction:40 Factor, Fastfunc

Height
Type Numeric The Height switch determines the number of lines on the PWB screen. The Height switch can have one of these values: 25, 43, 50, or 60. The last setting of this switch is saved and restored across PWB sessions and for each project. Default Height: first screen height When you start PWB for the first time, PWB uses the current screen height. Thereafter, PWB restores the previous setting until you explicitly assign a new value to the Height switch. Note that when you change the setting for Height in the Editor Settings dialog box, the change does not take effect until you choose OK. Other switches takes effect immediately when you choose Set Switch. See Assign

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 271 of 141 Printed: 10/09/00 02:46 PM

272

Environment and Tools

Hike
Type Numeric The Hike switch determines the number of lines from the cursor to the top of the window after you move the cursor out of the window by more than the number of lines specified by the Vscroll switch. The minimum value is 1. When the window occupies less than the full screen, the value is reduced in proportion to the window size. Default See Hike:4 Hscroll

Hscroll
Type Numeric The Hscroll switch controls the number of columns that PWB scrolls the text left or right when you move the cursor out of the window. When the window does not occupy the full screen, the amount scrolled is in proportion to the window size. Text is never scrolled in increments greater than the size of the window. Default See Hscroll:10 Vscroll

Infodialog
Type Numeric The Infodialog switch determines which information dialog boxes are displayed.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 272 of 142 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

273

Syntax

Infodialog:hh hh Two hexadecimal digits specifying a set of flags to indicate which information dialog boxes should be displayed. When a bit is on (1), the corresponding dialog box is displayed. When a bit is off (0), the corresponding dialog box is not displayed. To set the value of Infodialog, add up the hexadecimal numbers listed in the table below for the dialog boxes you want to display.
Value 01 02 04 08 10 Information Dialog n occurrences found n occurrences replaced End of Build Results End of Search Results
'pattern' not found

No unbalanced characters found Changed directory to directory Changed drive to drive

Default

Infodialog:0F The default value of Infodialog tells PWB to display all information dialog boxes except for the Changed... dialog boxes.

Keepmem
Type Numeric The Keepmem switch specifies the amount of extended (XMS) memory or expanded (EMS) memory kept by PWB during a shell, compile, build, or other external command. Specify the value in units of kilobytes (1024 bytes). A larger number means that shelling is faster and leaves less memory for tools that use extended or expanded memory. A smaller number means that shelling is slower and leaves more memory for tools. If the number you specify is not large enough, PWB uses no extended or expanded memory. Default Keepmem:2048

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 273 of 143 Printed: 10/09/00 02:46 PM

274

Environment and Tools

Lastproject
Type Boolean The Lastproject switch determines if PWB automatically opens the last project on startup. The /PN, /PP, /PL, and /PF command-line options override the setting of the Lastproject switch. Syntax Lastproject:{ yes | no } yes no Default See On startup, open the last project that was open. Do not open the last project on startup.

Lastproject:no Project

Load
Type Text The Load switch specifies the filename of a PWB extension to load. When this switch is assigned a value, PWB loads the specified extension. The initialization specified in the extension is performed, and the functions and switches defined by the extension become available in PWB. The extension can be loaded during initialization of a TOOLS.INI section. You can also interactively load an extension by using the Editor Settings command on the Options menu or by using the Assign function to assign a value to the Load switch. Syntax Load:[[path]]basename[[ .ext]] path Can be a path or an environment-variable specifier. basename Base name of the extension executable file. ext Normally you do not specify a filename extension. See Autoload

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 274 of 144 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

275

Markfile
Type Text The Markfile switch specifies the name of the file PWB uses to save marks. When no mark file is open, marks are kept in memory, and they are lost when you exit PWB. When you open a mark file, marks in memory are saved in the mark file, unless a mark file is already open. When a mark file is already open, the marks in memory are saved in the open file. To open a mark file, use the Set Mark File command on the Search menu or assign a value to the Markfile switch by using the Editor Settings command on the Options menu or the Assign function. To close a mark file without opening a new one, assign an empty value to the Markfile switch. That is, use the setting:
Markfile:

To set a permanent mark file that is used for every PWB session, place a Markfile definition in the [PWB] section of TOOLS.INI. Syntax Default See Markfile: filename filename Markfile: The Markfile switch has no default value and is initially undefined. Assign, Mark The name of the file containing mark definitions.

Mark File Format

A mark file is a text file containing mark definitions of the form: markname filename line column The mark markname is defined as the location given by line and column in the file filename. The markname cannot contain spaces and cannot be a number. Update With PWB 1.x, when you open a mark file and no mark file is currently open, the marks in memory are lost. With PWB 2.00, the marks are saved in the new mark file.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 275 of 145 Printed: 10/09/00 02:46 PM

276

Environment and Tools

Mousemode
Type Numeric The Mousemode switch enables or disables the mouse and sets the actions of the left and right mouse buttons.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 276 of 146 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference Value 0 1 2 Description The mouse is disabled and the mouse pointer is not visible. Normal mouse control. Exchanges the actions of the left and right mouse buttons.

277

Default See

Mousemode:1 Dblclick

Msgdialog
Type Boolean The Msgdialog switch determines if PWB brings up a dialog box summarizing build results or only beeps when a build is complete. Syntax Msgdialog:{ yes | no } yes no Default See Display a dialog box summarizing build results when a build is complete. Beep when a build is complete.

Msgdialog:yes Beep, Compile, Searchdialog

Msgflush
Type Boolean The Msgflush switch determines if previous build results are retained in the Build Results window or flushed when a new build is started. Syntax Msgflush:{ yes | no } yes no Default See Flush previous build results when a new build is started. Save previous build results.

Msgflush:yes Nextmsg, Searchflush

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 277 of 147 Printed: 10/09/00 02:46 PM

278

Environment and Tools

Newwindow
Type Boolean The Newwindow switch determines if certain PWB functions open a file in a new window or in the active window. The Newwindow switch provides the default state of the New Window check box in the Open File dialog box. This check box does not change the value of the Newwindow switch. When Newwindow is set to yes, PWB behaves like a Multiple Document Interface (MDI) application. That is, when you open a new file, PWB opens a new window for the file, except in certain situations as noted below. When Newwindow is set to no, PWB behaves like PWB 1.x. In this case, PWB opens files into the active window, creating a file history for that window. This mode is useful when working with large numbers of files. Some functions use the Newwindow switch to determine if a new window is created when opening a file. The following functions ignore the Newwindow switch, and either create a new window or open the file into the active window:
Function Mreplace Openfile Setfile Nextmsg Nextsearch Creates a New Window No Yes No No No

When the active window is a PWB window, PWB always creates a new window. You cannot open a file into a PWB window. Syntax Newwindow:{ yes | no } yes Open a new window when a new file is opened. This setting makes PWB behave like other MDI applications such as Microsoft Word 5.5 and Microsoft Works. no Open files into the active window, adding the previous file to the windows file history. This setting makes PWB behave like PWB 1.x. Default See Newwindow:yes Exit, Mark, Mreplace, Newfile, Nextmsg, Nextsearch, Openfile, Setfile

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 278 of 148 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

279

Noise
Type Numeric The Noise switch specifies the number of lines counted at a time as PWB traverses a file while reading, writing, or searching. PWB displays the line counter on the right side of the status bar, in the area which usually shows the current line. Set Noise to 0 to turn off the display of scanned lines. Default Noise:50

Printcmd
Type Text The Printcmd switch specifies a program or operating system command that PWB starts when you choose the Print command from the File menu or execute the Print function (Unassigned). Syntax Printcmd: command_line command_line An operating-system command line.

To pass the filename of the current file, specify %s in the command line. Specify %% to pass a literal percent sign. You can extract parts of the full filename using a special PWB syntax. See Filename-Parts Syntax on page 247. Default See Printcmd:COPY %s PRN Print

Readonly
Type Text The Readonly switch specifies the operating-system command invoked when PWB attempts to write to a read-only file.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 279 of 149 Printed: 10/09/00 02:46 PM

280

Environment and Tools

When PWB attempts to overtype a file that is marked read-only on disk, PWB informs you that the file is read-only. It also prompts you to confirm that the command specified in the Readonly switch is to be run. If you decline to run the Readonly command, PWB gives you the opportunity to save the file with a different name. Syntax Readonly:[[command]] command Operating-system command line.

If no command is specified, PWB prompts you to enter a new filename to save the file. To pass the filename of the current file to the command, specify %s in the command line. Specify %% to pass a literal percent sign. You can extract parts of the full path using a special PWB syntax. See Filename-Parts Syntax on page 247. Note that only %s is guaranteed to give the name of the read-only file. The %|F syntax gives the current filename (the file displayed in the active window), even when PWB is saving a different file. Default Readonly: The default value specifies that PWB should run no command and should prompt for a different filename. Example The Readonly switch setting
Readonly:Attrib -r %s

removes the read-only attribute from the file on disk so PWB can overtype it. See Editreadonly, Noedit

Realtabs
Type Boolean The Realtabs switch determines if PWB preserves tab (ASCII 9) characters or translates white space according to the Entab switch when a line is modified. Realtabs also determines if the Tabalign switch is in effect. Syntax Realtabs:{ yes | no } yes Preserve tab characters when editing a line.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 280 of 150 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

281

no Default See

Translate tab characters when editing a line.

Realtabs:yes Entab, Filetab, Tabalign

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 281 of 151 Printed: 10/09/00 02:46 PM

282

Environment and Tools

Restorelayout
Type Boolean The Restorelayout switch determines if PWB restores the saved window layout and file history from the project status file when you open a project or retains the active window layout and file history. This switch provides the default state of the Restore Window Layout check box in the Open Project dialog box. Syntax Restorelayout:{ yes | no } yes Restore a projects saved window layout and file history when the project is opened. no Do not restore the projects windows and file history. Default See Restorelayout:yes Project

Rmargin
Type Numeric The Rmargin switch sets the right margin for word wrapping. It has an effect only when word wrapping is turned on. Default Update Rmargin:78 In PWB 1.x, Rmargin sets the beginning of a six-character probation zone where typing a space wraps the line. After the zone, typing any character wraps the current word. This behavior is similar to that of a typewriter. PWB 2.00 uses a word-processors style of wrapping. To maintain the same margins as PWB 1.x, increase your Rmargin settings by 6. See Softcr, Wordwrap

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 282 of 152 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

283

Savescreen
Type Boolean The Savescreen switch determines if PWB preserves the operating-system screen image and video mode. Syntax Savescreen:{ yes | no } yes Save the operating-system screen when starting PWB, and restore it when leaving PWB. no Do not preserve the operating-system screen. When you leave PWB, the operating-system screen is blank, and the video mode is left in PWBs last video mode. Default Savescreen:yes

Searchdialog
Type Boolean The Searchdialog switch determines if PWB brings up a dialog box that summarizes logged search results or only beeps when a logged search is complete. The Searchdialog switch has an effect only while logging search results. Syntax Searchdialog:{ yes | no } yes Display a dialog box summarizing search results when a logged search is complete. no Beep when a logged search is complete. Default See Searchdialog:yes Beep, Enterlogmode, Logsearch, Msgdialog

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 283 of 153 Printed: 10/09/00 02:46 PM

284

Environment and Tools

Searchflush
Type Boolean The Searchflush switch determines if previous logged search results are flushed or retained when you start a new logged search. This switch has an effect only when PWB performs a logged search. Syntax Searchflush:{ yes | no } yes Flush the previous search results from the Search Results window when a new search is begun. no Preserve previous search results in the Search Results window. Default See Searchflush:yes Logsearch, Mgrep

Searchwrap
Type Boolean The Searchwrap switch determines if search commands and replace commands wrap around the ends of a file. Syntax Searchwrap:{ yes | no } yes no Default See Searches wrap around the beginning and end of the file. Searches stop at the beginning and end of the file.

Searchwrap:no Msearch, Psearch, Replace.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 284 of 154 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

285

Shortnames
Type Boolean The Shortnames switch determines if currently loaded files can be accessed by their short names (base name only). Syntax Shortnames:{ yes | no } yes You can switch to a file currently loaded into PWB by specifying only the base name to the Setfile (F2) or Openfile (F10) functions. no You must specify the extension as well as the base name to switch to a file. Default See Shortnames:yes Openfile, Setfile

Softcr
Type Boolean The Softcr switch controls indentation of new lines based on the format of surrounding text when you execute the Emacsnewl (ENTER) and Newline (SHIFT+ENTER) functions. Syntax Softcr:{ yes | no } yes Indent new lines. no Do not indent new lines. After executing Emacsnewl or Newline, the cursor is placed in column 1. Default Softcr:yes

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 285 of 155 Printed: 10/09/00 02:46 PM

286

Environment and Tools

Tabalign
Type Boolean The Tabalign switch determines the positioning of the cursor when it enters a tab field. A tab field is the area of the screen representing a tab character (ASCII 9) in the file. The width of a tab field is specified by the Filetab switch. The Tabalign switch takes effect only when the Realtabs switch is set to yes. Syntax Tabalign:{ yes | no } yes PWB aligns the cursor to the beginning of the tab field when the cursor enters the tab field. The cursor is placed on the actual tab character in the file. no PWB does not align the cursor within the tab field. You can place the cursor on any column in the tab field. When you type a character at this position, PWB inserts enough leading blanks to ensure that the character appears in the same column. Default Tabalign:no

Tabdisp
Type Numeric The Tabdisp switch specifies the decimal ASCII code of the character used to display tab (ASCII 9) characters in your file. If you specify 0 or 255, PWB uses the space (ASCII 32) character. It is sometimes useful to set Tabdisp to the code for a graphic character so that tabs can be distinguished from spaces. Default See Tabdisp:32 The default value 32 specifies the ASCII space character. Filetab, Realtabs, Traildisp, Traillinesdisp

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 286 of 156 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

287

Tabstops
Type Text The Tabstops switch specifies variable tab stops used by the Tab and Backtab functions. Tab moves the cursor to the next tab stop; Backtab moves the cursor to the previous tab stop. Note that the Tabstops switch has no effect on the handling of tab (ASCII 9) characters in a file. Syntax Tabstops: [[tabwidth]]... repeat tabwidth The width of a tab stop. You can repeat tabwidth for as many tab stops as will fit on a PWB line (250 characters). repeat The width of every tab stop after the explicitly listed tab stops.A value of 0 for repeat specifies that there are no tab stops after the list of tabwidth settings. When the cursor is past the last tab stop, the Tab function does nothing. Default Update Tabstops:4 In PWB 1.x, Tabstops is a numeric switch specifying a single value, equivalent to the repeat value in PWB 2.0. The default PWB 2.00 Tabstops setting mimics the default behavior of PWB 1.x. The Tabstops switch setting
Tabstops:4

Example

sets a tab stop every four columns. Example The setting

Tabstops:3 4 7 8

sets a tab stop at columns 4, 8, 15, and every eight columns thereafter. Example The setting
Tabstops:3 4 7 25 25 0

sets a tab stop at columns 4, 8, 15, 40, and 65. When the cursor is past column 65, the Tab function does nothing. See Backtab, Entab, Filetab, Realtabs, Tab

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 287 of 157 Printed: 10/09/00 02:46 PM

288

Environment and Tools

Tilemode
Type Numeric The Tilemode switch specifies the window tiling style. It can take one of the values below:
Value 0 1 Tiling Style The first three windows are stacked one above the other. The top two windows are tiled side-by-side.

When four or more windows are open, the tiling is the same in the two styles. In stacked style (Tilemode:0), the top windows are placed one above the other, as shown in gray.

Figure 7.2

Vertical Tiling

In side-by-side style (Tilemode:1), the top two windows are tiled next to each other, as shown in Figure 7.3. This arrangement is good for comparing two files.

Figure 7.3

Horizontal Tiling

Default See

Tilemode:0 Arrangewindow

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 288 of 158 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

289

Timersave
Type Numeric The Timersave switch sets the interval in seconds between automatic file saves. The value must be in the range 0-65,535. Set Timersave to 0 to turn off time-triggered autosave. Default See Timersave:0 Autosave

Tmpsav
Type Numeric The Tmpsav switch determines the maximum number of files kept in the file history between sessions. When Tmpsav is 0, PWB lets the file history grow without limit; all files loaded into PWB appear in this list until you delete the CURRENT.STS file or change the value of the Tmpsav switch. Default Tmpsav:20

Traildisp
Type Numeric The Traildisp switch specifies the decimal ASCII code for the character used to display trailing spaces on a line. If you specify 0 or 255, PWB uses the space (ASCII 32) character. Default See Traildisp:0 Traillines, Trailspace, Traillinesdisp

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 289 of 159 Printed: 10/09/00 02:46 PM

290

Environment and Tools

Traillines
Type Boolean The Traillines switch determines if PWB preserves or removes empty trailing lines in a file when the file is written to disk. You can make trailing lines visible by setting the Traillinesdisp switch to a value other than 0 or 32. Syntax Traillines:{ yes | no } yes no Default See Preserve trailing blank lines in the file. Remove trailing blank lines from the file.

Traillines:no Traildisp, Trailspace

Traillinesdisp
Type Numeric The Traillinesdisp switch specifies the decimal ASCII code for the character displayed in the first column of blank lines at the end of the file. If you specify 0 or 255, PWB uses the space (ASCII 32) character. Default See Traillinesdisp:32 Traillines, Traildisp, Trailspace

Trailspace
Type Boolean The Trailspace switch determines if PWB preserves or removes trailing spaces from modified lines. You can make trailing spaces visible by setting the Traildisp switch to a value other than 0 or 32.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 290 of 160 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

291

Syntax

Trailspace:{ yes | no } yes no Preserve trailing spaces on lines as they are changed. Remove trailing spaces from lines as they are changed.

Default See

Trailspace:no Traillines, Traillinesdisp

Undelcount
Type Numeric The Undelcount switch determines the maximum number of backup copies of a given file saved by PWB. This switch is used only when the Backup switch is set to undel. Default Undelcount:32767

Undocount
Type Numeric The Undocount switch sets the maximum number of edits per file that you can reverse with Undo (ALT+BKSP). Default Undocount:30

Unixre
Type Boolean The Unixre switch determines if PWB uses UNIX regular-expression syntax or PWBs non-UNIX regular-expression syntax for search-and-replace commands. The Unixre and Case switches have no effect on the syntax of regular expressions used by the Build and Word switches. These switches always use case-sensitive UNIX regular-expression syntax.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 291 of 161 Printed: 10/09/00 02:46 PM

292

Environment and Tools

Syntax

Unixre :{ yes | no } yes no Use UNIX regular-expression syntax when searching. Use non-UNIX regular-expression syntax when searching.

Default

Unixre:yes

User
Type Syntax Text The User switch adds a custom menu item to the PWB Run menu. User: title, path, [[arg]], [[out]], [[dir]], [[help]], [[prompt]], [[ask]], [[back]], [[key]] If any argument to the User switch contains spaces, it must be enclosed in double quotation marks. title Menu title for the program to be added. No other command can have the same title. Prefix the character to be highlighted as the access key with a tilde (~) or ampersand (&). If you do not specify an access key, the first letter of the title is used. path Full path of the program. If the program is on the PATH environment variable, you can specify just the filename of the program. arg Command-line arguments for the program. To pass the name of the current file to the program, specify %s in the command line. Default: no arguments. out Name of a file to store program output. If no file is specified and the program is run in the foreground, the current file in PWB receives the output. Default: no output file. dir Current directory for the program. Default: PWBs current directory. help Text that appears on the status bar when the menu item is selected. Default: no help text. prompt Determines if PWB prompts for command-line arguments. The value of arg is the default response. Specify Y to prompt or any other character to run the program without prompting for arguments. Default: no prompt.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 292 of 162 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

293

ask Determines if PWB is to prompt for a keystroke before returning to PWB. Specify Y to prompt or any other character to return to PWB immediately after running the program. Default: return without prompting. back Determines if the program is run in the background under a multithreaded environment. Specify Y to run the program in the background or any other character to run it in the foreground. If you run the program in the background, you must also specify output. Default: run the program in the foreground. key A single digit from 1 to 9, specifying a key from ALT+F1 to ALT+F9 as the shortcut key for the command. Default: no shortcut key. Default Example By default, no custom menu commands are defined. The User switch setting
User : "~Print", XPRINT, "/2 %s", LPT1, , \ "Print the current file with XPRINT", y, n, n, 8

specifies the following custom Run menu command:

Option title path arg out dir help prompt ask back key Description The menu title is Print with the accelerator P. The XPRINT program is expected to be on the PATH. The default command line specifies the /2 option and the current filename. The program output is redirected to the LPT1 device. The XPRINT program is run in the current directory. The Help line is Print the current file with XPRINT. PWB prompts for additional arguments. PWB doesnt prompt before returning from XPRINT. The XPRINT program is to run in the foreground.
ALT+F8 runs the XPRINT program after prompting.

The backslash at the end of the first line of the definition is a TOOLS.INI line continuation. See Printcmd, _pwbusern, Usercmd

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 293 of 163 Printed: 10/09/00 02:46 PM

294

Environment and Tools

Vscroll
Type Numeric The Vscroll switch controls the number of lines scrolled up or down when you move the cursor out of the window. When the window is smaller than the full screen, the amount scrolled is in proportion to the window size. The minimum value for Vscroll is 1. Text is never scrolled in increments greater than the size of the window. The Mlines and Plines functions also scroll according to the value of the Vscroll switch. Default See Vscroll:1 Hscroll

Width
Type Numeric The Width switch controls the width of the display. Only an 80-column display is supported. Default See Width:80 Height

Word
Type Syntax Text Word: "regular_expression" "regular_expression" A macro string specifying a UNIX-syntax regular expression that matches a word. The Word switch specifies a case-sensitive UNIX regular expression that matches a word. The Unixre and Case switches are ignored.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 294 of 164 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

295

The Word switch accepts a TOOLS.INI macro string. The string can use escape sequences to represent nonprintable ASCII characters. Note that backslashes (\) must be doubled within a macro string. The Word switch is used by functions that operate on words: Mword , Pword , Pwbhelp, right-clicking the mouse for Help, and double-clicking the mouse to select a word. Default Examples Word:"[a-zA-Z0-9_$]+" The default value mimics the behavior of PWB 1.x. The Word switch can be used to change the definition of a word. The following examples show some useful word definitions. The following setting works the same way as the default setting, except that Pword and Mword stop at the end of a line:
Word:"\\{[a-zA-Z0-9_$]+\\!$\\}"

The default setting of the Word switch matches Microsoft C/C++ identifiers and unsigned integers. To restrict the definition of a word to match the ANSI C standard for identifiers, you would use the setting:
Word:"[a-zA-Z_][a-zA-Z0-9_]*"

Another useful setting is to define a word as a contiguous stream of nonspace characters:

Word:"[^ \t]+"

The following Word setting defines a word as an identifier or unsigned integer, a stream of white space, a stream of other characters, or the beginning or end of the line. This causes the word-movement functions to stop at each boundary, and allows a double-click to select white space.
Word:"\\{[a-zA-Z0-9_$]+\\![ ]+\\![^a-zA-Z0-9_$]+\\!$\\!^\\}"

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 295 of 165 Printed: 10/09/00 02:46 PM

296

Environment and Tools

Wordwrap
Type Boolean The Wordwrap switch determines if PWB performs automatic word wrap as you enter text. When word wrapping is turned on and you type a nonspace character past the column specified by Rmargin, PWB brings the current word down to a new line. A word is defined by the Word switch. Syntax Wordwrap:{ yes | no } yes no Default Update Wrap words as you enter text. Do not wrap.

Wordwrap:no See Rmargin

Browser Switches
The PWBBROWSE extension provides the following switches to control the behavior of the Source Browser in PWB.

Browcase
Type Numeric The Browcase switch determines the initial case sensitivity of the browser when a database is opened. The browser consults this switch only when it opens the database. This switch must appear in the [PWB-PWBROWSE] tagged section of TOOLS.INI. A dot appears next to the Match Case command on the Browse menu when the browser matches case. Choose Match Case to turn case-sensitive browsing on and off. Changing the current state does not affect the value of the Browcase switch.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 296 of 166 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

297

Syntax

Browcase:{ 0 | 1 | 2 } 0 Use the case sensitivity stored in the database by BSCMAKE. The default case sensitivity matches the case sensitivity of the source language. 1 Match case for browse queries. 2 Ignore case for browse queries.

Default

Browcase:0

Browdbase
Type Text The Browdbase switch specifies the browser database to use. When this switch is not set, or the setting is empty, the browser uses the database for the current project (if any). You set this switch by using the Save Current Database command in the Custom Database Management dialog box. This switch must appear in the [PWB-PWBROWSE] tagged section of TOOLS.INI. Syntax Browdbase: database database The full filename of the browser database (.BSC file) to use. When database is not specified, the browser uses the database for the open project.
indows operating systemWindows operating systemWindows operating systemthe Windows operating systemWindows operating system

Help Switches
The PWBHELP extension provides the following switches to control the behavior of the Help system in PWB.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 297 of 167 Printed: 10/09/00 02:46 PM

298

Environment and Tools

Color (Help Colors)

The PWBHELP extension defines the following Color switches to set the colors for items displayed in the Help window. These switches must appear in the [PWB-PWBHELP] tagged section of TOOLS.INI. When you choose OK in the Save Colors dialog box, PWB automatically writes the new settings to the correctly tagged section of TOOLS.INI.
Name Color: Helpnorm Color: Helpbold Color: Helpitalic Color: Helpunderline Color: Helpwarning Default Value 87 8F 8A 8C 70 Description Plain Help text Bold Help text Italic Help text and the characters Emphasized Help text Current hyperlink

For a complete description of the Color switch, see Color.

Helpautosize
Type Boolean The Helpautosize switch determines if PWB displays the Help window according to the size of the current topic or displays Help with its previous size and position. This switch must appear in the [PWB-PWBHELP] tagged section of TOOLS.INI. Syntax Helpautosize: { yes | no } yes When displaying a new topic, automatically resize the Help window to the size of the topic. no Do not automatically resize the Help window. The Help window is displayed with its previous size and position. Default Update Helpautosize:no In PWB 1.x, the Help window is always automatically resized. In PWB 2.00, the Help window is not resized by default.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 298 of 168 Printed: 10/09/00 02:46 PM

Chapter 7 Programmers WorkBench Reference

299

Helpfiles
Type Text The Helpfiles switch lists Help files or directories containing Help files that PWB should open in addition to the Help files listed in the HELPFILES environment variable. This switch must appear in the [PWB-PWBHELP] tagged section of TOOLS.INI. Syntax Helpfiles: [[file]][[;file]]... file The filename of a Help file to open or the name of a directory. If a directory name is used, all Help files in the directory are opened. Each file can contain wildcards or environment-variable specifiers. Default Helpfiles: By default, PWB uses only the Help files in the current directory and those listed in the HELPFILES environment variable.

Helplist
Type Boolean The Helplist switch determines if PWB searches every Help file when you request Help or displays the first occurrence of the topic that it finds. This switch must appear in the [PWB-PWBHELP] tagged section of TOOLS.INI. Syntax Helplist: { yes | no } yes Displays a list of Help files that contain the topic you requested Help on when the topic is defined more than once. no Does not display a list of topics. PWB displays the first Help associated with the requested topic. To see the other Help screens that define the topic, use the Next command on the Help menu. Default Helplist: yes

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 299 of 169 Printed: 10/09/00 02:46 PM

300

Environment and Tools

Helpwindow
(obsolete) The PWB 1.x Helpwindow switch is obsolete and does not exist in PWB 2.00. PWB 2.00 always displays Help in the Help window.

Filename: LMAETC07.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 5 Page: 300 of 170 Printed: 10/09/00 02:46 PM

P A R T

The CodeView Debugger

Chapter 8 Getting Started with CodeView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Chapter 9 The CodeView Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 Chapter 10 Special Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 Chapter 11 .................................................... Using Expressions in CodeView 375 Chapter 12 CodeView Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

Filename: LMAETP02.DOC Project: Part opening 2 Template: MSGRIDA1.DOT Author: Terri Sharkey Last Saved By: Mike Eddy Revision #: 13 Page: 291 of 1 Printed: 10/09/00 02:56 PM

Filename: LMAETP02.DOC Project: Part opening 2 Template: MSGRIDA1.DOT Author: Terri Sharkey Last Saved By: Mike Eddy Revision #: 13 Page: 292 of 2 Printed: 10/09/00 02:56 PM

293

C H A P T E R

Getting Started with CodeView

Microsoft CodeView is a window-oriented debugging tool that helps you find and correct errors in MASM and Microsoft C/C++ programs. With CodeView, you can examine source-level code and the corresponding compiled code at the same time. You can execute your code in increments and view and modify data in memory as your program runs. Your MASM 6.10 package includes CodeView for MS-DOS (CV.EXE) and CodeView for Windows (CVW.EXE). The names CodeView, CodeView debugger, and the debugger refer to both versions unless the discussion indicates otherwise. This chapter shows you how to:
u u u

u u u u u

Write programs to make debugging easier. Formulate a debugging strategy. Compile and link your programs to include Microsoft Symbolic Debugging Information. Set up the files CodeView needs. Configure CodeView with TOOLS.INI. Start CodeView and load a program. Use the CodeView command-line options. Use or disable the CURRENT.STS state file.

Preparing Programs for Debugging

You can use CodeView to debug any MS-DOS or Windows-based executable file produced from MASM or Microsoft C/C++ source code. Compiling means producing object code from source files. All references to compiling also apply to assembling unless stated otherwise.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 293 of 1 Printed: 10/09/00 02:42 PM

294

Environment and Tools

General Programming Considerations

This section describes programming practices that make debugging with CodeView easier and more efficient.

Multiple Statements on a Line

CodeView treats each source-code line as a unit. For this reason, you cannot trace and set a breakpoint on more than one statement per line. You can change from Source display mode to Mixed or Assembly display mode (see The Source Windows on page 324) and then set breakpoints at individual assembly instructions. If a single statement is broken across multiple lines, you may be able to set breakpoints on only the starting or ending line of the statement.

Macros and Inline Code

Microsoft C, C++, and MASM support macro expansion. Microsoft C and C++ also support inline code generation. These features pose a debugging problem because a macro or an inlined function is expanded where it is used, and CodeView has no information about the source code. This means that you cannot trace or set breakpoints in a macro or inlined function when debugging at the source level. To work around this condition, you can:
u u u

Manually expand the macro to its corresponding source code. Rewrite the macro as a function. Suppress inline code generation with the /Ob0 compiler option.

You can often rewrite macros as inline functions, then selectively disable inlining with a compiler option or pragma so that you can step and trace the routine. Rewriting macros as inlined functions can have additional benefits such as argument type checking. However, in some cases the best solution for debugging macros or inline code is to use Assembly or Mixed display mode.

Segment Ordering and Naming

For assembly-language programs, you must declare your segments according to the standard Microsoft high-level language format. MASM versions 5.10 and later provide directives to specify the standard segment order and naming.

Programs that Alter the Environment

Programs that run under CodeView can read the environment table, but they cannot permanently change it. When you exit CodeView, changes to the environment are lost.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 294 of 2 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

295

Programs that Access the Program Segment Prefix

CodeView processes the command line in the program segment prefix (PSP) the same way as the C/C++ run-time library does. Quotation marks are removed, and exactly one space is left between command-line arguments. As a result, a program that accesses the PSP directly cannot expect the command line to appear exactly as typed.

Compiling and Linking

After you compile and link your program into a running executable file, you can begin debugging with CodeView. To take full advantage of CodeView, however, you must compile and link with the options that generate CodeView Symbolic Debugging Information. This book refers to this information as CodeView information, debugging information, or symbolic information. The CodeView information tells CodeView about:
u u u u u

All program symbols, including locals, globals, and publics Data types Line numbers Segments Modules

Without this information, you cannot refer to any source-level names, and you can view the program only in Assembly display mode. When CodeView loads a module that does not contain symbolic information, CodeView starts in Assembly mode and displays the message:
CV0101 Warning: No symbolic information for PROGRAM.EXE

You get this message if you try to debug an executable file that you did not compile and link with CodeView options, if you use a compiler that does not generate CodeView information, or if you link your program with an old version of the linker. If you retain an old linker version and it is first in your path, the proper information may not be generated for CodeView. You can specify CodeView compiler and linker options from the command line, in a makefile, or from within the Microsoft Programmers Workbench (PWB). To compile and link your program with CodeView options from PWB, choose Build Options from the Options menu, and turn on Use Debug Options. By default, all project templates enable the generation of CodeView information for debug builds.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 295 of 3 Printed: 10/09/00 02:42 PM

296

Environment and Tools

Assembler/Compiler Options
You can specify CodeView options when you assemble a source file of a program you want to debug. Specify the /Zi option on the command line or in a makefile to instruct the assembler to include line-number and complete symbolic information in the object file. Symbolic information takes up a large amount of space in the executable file and in memory while debugging. If you do not need full symbolic information in some modules, compile those modules with the /Zd option. The /Zd option specifies that only line numbers and public symbols are included in the object file. In such modules you can view the source file and examine and modify global variables, but type information and names with local scope are not available. For modules that are assembled or compiled with the /Zd option, all names in that module are displayed and can only be referred to using their decorated name. The decorated name is the form of the name in the object code produced by the compiler. With full debugging information, CodeView can translate between the source form of the name and the decorated name. Name decoration encodes additional information into a symbols name by adding prefixes and suffixes. For example, the C compiler prefixes the names of functions that use the C calling convention with an underscore. You often see decorated names for library routines in disassembly or output from the Examine Symbols (X) command. For more information on decorated names, see Symbol Formats on page 385. All Microsoft high-level language compilers are optimizing compilers that may rearrange and remove source code. As a result, optimizations destroy the correspondence between source lines and generated machine code, which can make debugging especially difficult. While you are debugging, you should disable optimizations with the /Od compiler option. When you finish debugging, you can compile a final version of your program with full optimizations. Note The /Od option does not pertain to MASM.

Linker Options
When you are using Microsoft C/C++ or the Microsoft Assembler, you must use the Microsoft Segmented Executable Linker (LINK) version 5.30 or later to generate an executable file with CodeView information. If you include debugging options when you compile, the compiler automatically invokes the linker with the appropriate options. In turn, LINK runs the CVPACK utility, which compresses the symbolic information.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 296 of 4 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

297

When compiling, you can specify the compile-only (/c) option to disable running LINK. To include debugging information when you link the object modules separately, specify the LINK /CO option. LINK automatically runs CVPACK when you specify /CO. If you link with the /EXEPACK option, you must execute the programs startup code before setting breakpoints in the program. If you set breakpoints in a packed executable file before the startup code has executed, CodeView behavior is unpredictable. An executable file that includes debugging information can be executed from the command line like any other program. However, to minimize the size of the final version of the program, compile and link without the CodeView options. Examples The following command sequence assembles and links two files:
ML /C /Zi MOD1.ASM ML /C /Zd MOD2.ASM LINK /CO MOD1 MOD2

This example produces the object file MOD1.OBJ, which contains line-number and complete symbolic information, and the object file MOD2.OBJ, containing only line-number and public-symbol information. The object files are then linked to produce a smaller file than the file that is produced when both modules are assembled with the /Zi option. The following commands produce a mixed-language executable file:
CL /Zi PROG.CPP CL /Zi /Od /c /AL SUB1.C ML /C /Zi /MX SUB2.ASM LINK /CO PROG SUB1 SUB2

You can use CodeView to trace through C, C++, and MASM source files in the same session.

Debugging Strategies
The process of debugging a program varies from programmer to programmer and program to program. This section offers some guidelines for detecting bugs. If you are familiar with symbolic, source-level debuggers, you can skip this section.

Identifying the Bug

If your program crashes or yields incorrect output, it has a bug. There are times, however, when a program runs correctly with some input but produces incorrect

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 297 of 5 Printed: 10/09/00 02:42 PM

298

Environment and Tools

output or crashes with different input. You can assume a bug exists, but finding it may be difficult.

Locating the Bug

You may not need to use CodeView to find bugs in simple programs. For more complex programs, however, using CodeView can save you debugging time and effort.

Setting Breakpoints
When you debug with CodeView, you usually cycle between two activities:
u u

Running a small part of the program Stopping the program to check its status

You use breakpoints to switch between these tasks. CodeView runs your program until it reaches a breakpoint. At that time, CodeView gives you control. You can then enter CodeView commands in the Command window or use the menus and shortcut keys to proceed. To find an error, try the following:
u

Set breakpoints around the place you think the bug might be. Execute the program with the Go command so that it runs at full speed until it reaches the area that you suspect harbors the bug. You can then execute the program step by step with the Program Step and Trace commands to see if there is a program execution error. Set breakpoints when certain conditions become true. You can, for example, set a breakpoint to check a range of memory starting at DS:00, the base of your programs data. If your program writes to memory using a null pointer, the breakpoint is taken, and you can see what statement or variables within the statement are in error.

Setting Watch Expressions

Watch expressions constantly display the values of variables in the Watch window. By setting a Watch expression, you can see how a variable or an expression changes as your program executes. Try using watch expressions as follows:
u

Set a Watch expression on an important variable. Then step through a part of the program where you suspect there is a bug. When you see a variable in the Watch window take on an unexpected value, you know that there is probably a bug in the line you just executed.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 298 of 6 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

u

299

Explore Watch expressions. A bug can appear when your program builds complex data structures. Both the Watch window and the Quick Watch dialog box allow you to explore the data structure by expanding arrays and pointers. Use this feature to make sure the program creates the data structure correctly. As soon as you execute code that destroys the structure, you have probably found a bug.

Arranging Your Display

Your display can be more effective if you arrange your windows so that they display the information you need. You will need at least one Source window. You can open a second Source window to see each assembly-language instruction. You may also need one or more Memory windows to examine ranges of memory in various formats. You may want to change values in memory. For example, a program that does its own dynamic-memory allocation may need an initialized block of memory. You can edit memory directly in the Memory window or fill the block with zeros using the Memory Fill command. If a certain value is required for a mathematical function, you can type over values displayed in the Memory window or assign the value in the Command window. If you expect a value to appear at a certain location and it does not, you can use the Memory Search command to find it. Use the Register window to see the CPU registers and the Local and Watch windows to keep track of changing variable values. Open the Calls menu to examine your programs stack to see what routines have been called. You can set up CodeViews windows to display the information you want to see by using keyboard commands or the commands in the Window menu. For example, when you press SHIFT+F5 or choose Tile from the Windows menu, CodeView arranges all open windows to fill the entire window area. When the windows are tiled, you can press ALT+F5 or choose Arrange from the Windows menu. This allows you to move your open windows with a mouse so that you can view several or all of them at once.

Setting up CodeView
The MASM SETUP program installs all the necessary CodeView files. Make sure that all of the CodeView executable files (.EXE and .DLL files) are in a directory listed in the PATH environment variable. In addition, SETUP creates TOOLS.PRE in the INIT directory that you specify when you run SETUP. If you do not already have a TOOLS.INI file, rename TOOLS.PRE as TOOLS.INI.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 299 of 7 Printed: 10/09/00 02:42 PM

300

Environment and Tools

This file contains the recommended settings to run CodeView for MS-DOS and CodeView for Windows. For more information on the entries in TOOLS.INI, see Configuring CodeView with TOOLS.INI on page 301. CodeView version 4.0 introduces a new, flexible architecture for the debugger. CodeView is made up of a main executable program: CV.EXE (CodeView for MS-DOS) or CVW.EXE (CodeView for Windows) and a collection of dynamiclink libraries (DLLs). Each DLL implements an aspect of the debugging process. The following table summarizes CodeViews component DLLs:
TOOLS.INI Entry Eval Model Native Symbolhandler Transport Component Expression evaluator Additional nonnative execution model Native execution model Symbol handler Transport layer Required Required Optional Required Required Required Example C or C++ P-code MS-DOS or Windows MS-DOS or Windows Local or remote

This architecture allows for the implementation of such improbable debugging configurations as a Windows operating system-hosted debugger that debugs interpreted Macintosh programs across a network. The existing CVW.EXE could be used with new transport, symbol handling, and execution model DLLs. Instead of creating completely different programs for each combination of host and target, all that is needed is the appropriate set of DLLs.

CodeView Files
CodeView for Windows and CodeView for MS-DOS use several additional files. One of these is the executable program file that you are debugging. CodeView requires one executable (.EXE) file to load for debugging. program.EXE An .EXE-format program to debug. CodeView assumes the .EXE extension when you specify the program to load for debugging. source.ext A program source file. Your program may consist of more than one source file. When CodeView needs to load a source file for a module at startup or when you step into a new module, it searches directories in the following order: 1. The compiled directory. This is the source-file path specified when you invoke the compiler. 2. The directory where the program is located.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 300 of 8 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

301

If CodeView cannot find the source file in one of these directories, it prompts you for a directory. You can enter a new directory or press ENTER to indicate that you do not want a source file to be loaded for the module. If you do not specify a source file, you can debug only in Assembly mode. CV.HLP ADVISOR.HLP Help files for CodeView and the Microsoft Advisor. These two files are the minimum set of files required to use Help during a CodeView session. They must be in a directory listed in the HELPFILES environment variable or in the Helpfiles entry of TOOLS.INI. Depending on what programming environment you work in, you may also want to use the various programming language and p-code help files. TOOLS.INI Specifies paths for CodeView .DLL files and other files that CodeView uses. The MASM SETUP program creates the file TOOLS.PRE in the directory specified in your INIT environment variable. If CodeView cannot find the modules it needs in its own directory, it looks for entries in TOOLS.INI that specify paths for the modules it needs. You can include other settings for CodeView in TOOLS.INI. TOOLHELP.DLL System support .DLL for CVW. Remote debugging requires additional files and a different configuration. The files and configuration required for remote debugging are described in Chapter 10, Special Topics.

Configuring CodeView with TOOLS.INI

You can configure CodeView and other Microsoft tools including the Microsoft Programmers WorkBench (PWB) and NMAKE by specifying entries in the TOOLS.INI file. You must have separate sections in TOOLS.INI for each tool. TOOLS.INI sections begin with a taga line containing the base name of the executable file enclosed in brackets ([ ]). The tag must appear in column one. The CV and CVW section tags look like this:
[CV] ; . . . [CVW] ; . . . MS-DOS CodeView entries

Windows operating system CodeView entries

In the TOOLS.INI file, a line beginning with a semicolon (;) is a comment.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 301 of 9 Printed: 10/09/00 02:42 PM

302

Environment and Tools

CodeView looks for certain entries following the tag. Each entry may be preceded by any number of spaces, but the entire entry must fit on one line. You may want to indent each entry for readability.

CodeView TOOLS.INI Entries

You may want to specify or change entries in TOOLS.INI to customize CodeView. Table 8.1 summarizes the TOOLS.INI entries.
Table 8.1 Entry Autostart Color Cvdllpath Eval Helpbuffer Helpfiles Model Native Printfile Statefileread Symbolhandler Transport CodeView TOOLS.INI Entries Description Commands to execute on startup Screen colors Path to CodeView .DLL files Expression evaluator Size of help buffer List of help files Additional execution model (such as p-code) Native execution model Default name for print command or file Read or ignore CURRENT.STS state file Symbol handler Transport layer

Autostart
The Autostart entry specifies a list of Command-window commands that CodeView executes on startup. Syntax Autostart :command[[;command]]... command A command for CodeView to execute at startup. Separate multiple commands with a semicolon (;). The following entry automatically executes the programs run-time startup code. It specifies that CodeView always starts with the Screen Swap option off and the Trace Speed option set to fast.

Example

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 302 of 10 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

Autostart:OF-;TF;Gmain

303

Color
The Color entry is retained only for compatibility with previous versions of CodeView. You should set screen colors with the Colors command on the Options menu.

Cvdllpath
The Cvdllpath entry specifies the default path for CodeViews dynamic-link libraries (DLLs). CodeView searches this path when it cannot find its DLLs in CodeViews directory or along the PATH environment variable. This entry is recommended. Syntax Cvdllpath:path path The path to the CodeView .DLL files.

Eval
The Eval entry specifies an expression evaluator. The expression evaluator looks up symbols, parses, and evaluates expressions that you enter as arguments to CodeView commands. If there is no Eval entry in TOOLS.INI, CodeView loads the C++ expression evaluator by default. CodeView uses the specified expression evaluator when you are debugging modules with source files ending in the specified extensions. Syntax Eval:[[path\]]EEhost evaluator.DLL extension... path The path to the specified expression evaluator. host The host environment.
Specifier D1 W0 Operating Environment MS-DOS Windows

evaluator The source language expression evaluator.

Specifier CAN CXX Source Language C or MASM C, C++, or MASM

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 303 of 11 Printed: 10/09/00 02:42 PM

304

Environment and Tools

extension A source-file extension. CodeView uses the specified expression evaluator when it loads a source file with the given extension. You can list any number of extensions.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 304 of 12 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

305

Example

The following example loads both the C and C++ expression evaluators for the MS-DOS CodeView:
Eval:C:\C700\DLL\EED1CAN.DLL .C .ABC .ASM .H Eval:C:\C700\DLL\EED1CXX.DLL .CPP .CXX .XYZ .HXX

With the entries in this example, when you trace into a module whose source file has the extension .C, .ABC, or .ASM, CodeView uses the C expression evaluator. When you trace into a source file with a .CXX, .CPP, or .XYZ extension, CodeView switches to the C++ expression evaluator. Note The C++ expression evaluator is the only expression evaluator provided with MASM 6.10. For most MASM, C, and C++ programs the C++ expression evaluator is sufficient. You can load expression evaluators after CodeView has started by using the Load command from the Run menu. You can override CodeViews automatic choice of expression evaluator by using the Language command on the Options menu or the USE command in the Command window. For more information about choosing an appropriate expression evaluator and how to use expressions in CodeView, see Chapter 11, Using Expressions in CodeView.

Helpbuffer
The Helpbuffer entry specifies the size of the buffer CodeView uses to decompress help files. You can set Helpbuffer to 0 to disable Help and maximize the amount of memory available for debugging. Otherwise, specify a value between 1 and 256. Syntax Helpbuffer:size size The number of kilobytes (K) of memory to use for decompressing help files. The default help buffer size is 24K. Specify 0 to disable help. The following table shows values you can specify and the actual size of the buffer that is allocated:
Value Specified 124 25128 129256 Help Buffer Size 24K 128K 256K

The smallest buffer size is 24K, and the largest is 256K.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 305 of 13 Printed: 10/09/00 02:42 PM

306

Environment and Tools

Helpfiles
The Helpfiles entry lists help files for CodeView to load. These files are loaded before any files listed in the HELPFILES environment variable. Syntax Helpfiles:file[[;file]]... file A directory or help file. If you list a directory, CodeView loads all files with the .HLP extension in that directory. Separate multiple files or directories with a semicolon (;).

Model
The Model entry specifies an additional execution model that CodeView uses when you are debugging nonnative code such as p-code. The execution model handles tasks specific to the type of executable code that you are debugging. Syntax Model:[[path\]]NMhost model.DLL path The path to the specified file. host The host environment must be one of the following:
Specifier D1 W0 Operating Environment MS-DOS Windows

model A nonnative execution model. The p-code execution model (PCD) is required if you plan to debug p-code. Example
Model:NMD1PCD.DLL

Native
The Native entry specifies the native execution model. This DLL handles tasks that are specific to the machine and operating system on which you are running (the host) and specific to the native code (the target). Syntax Native:[[path\]]EMhost target.DLL path The path to the specified native execution model.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 306 of 14 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

307

host The host environment must be one of the following:

Specifier D1 W0 Operating Environment MS-DOS Windows

target The target environment must be one of the following:

Specifier D1 W0 Operating Environment MS-DOS Windows

Printfile
The Printfile entry lists the default device name or filename used by the Print command on the File menu. This can be a printer port (for example, LPT1 or COM2) or an output file. If Printfile is omitted, CodeView prints to a file named CODEVIEW.LST in the current directory. This entry is ignored by CVW, which does not have the Print command. Syntax Printfile:path path The path to the specified output file or the name of a device.

Statefileread
The Statefileread entry tells CodeView to read or ignore the CodeView state file (CURRENT.STS) on startup. You can toggle this setting from the command line using the /TSF (Toggle State File) option. These options have no effect on writing CURRENT.STS. CodeView always saves its state on exit. Syntax Statefileread:[[y | n]] y (yes) CodeView reads CURRENT.STS on startup. n (no) CodeView ignores CURRENT.STS on startup.

Symbolhandler
The Symbolhandler entry specifies a symbol handler. The symbol handler manages the CodeView symbol and type information.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 307 of 15 Printed: 10/09/00 02:42 PM

308

Environment and Tools

Syntax

Symbolhandler:[[path\]]SHhost.DLL path The path to the symbol handler. host The host environment must be one of the following:
Specifier D1 W0 Operating Environment MS-DOS Windows

Transport
The Transport entry specifies a transport layer. A transport layer provides the data link for communication between the host and target during debugging. Syntax Transport :path\TLhost transport.DLL [[COM{1|2}:[[rate]]]] path The path to the specified transport layer. host The host environment must be one of the following:
Specifier D1 W0 Operating Environment MS-DOS Windows

transport Specifies a transport layer.

Specifier LOC COM Transport Layer Local transport layer Serial remote transport layer

The optional [[COM{1|2}:[[rate]]]] specifies a communications port and baud rate for remote debugging. No space is allowed between COM and the port number (1 or 2). The default port is COM1. The <rate> can be any number from 50 through 9600. The default rate is 9600. You specify the local transport layer (LOC) when the debugger and the program you are debugging are running on the same machine. With the appropriate transport layer, CodeView can support remote debugging across serial lines or networks. For more information on remote debugging, see Chapter 10.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 308 of 16 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

309

The following example specifies the transport layer for debugging a program that is running on the same machine. Example
Transport:C:\C700\DLL\TLW0LOC.DLL

Memory Management and CodeView

CodeView for MS-DOS (CV) requires at least 2 megabytes of memory. The memory must be managed by a Virtual Control Program Interface (VCPI) server, DOS Protected-Mode Interface (DPMI) server, or extended memory (XMS) manager. These drivers manage memory at addresses above 1 megabyte on an 80286, 80386, or 80486 machine. CodeView loads itself and the debugging information for the program into high memory. In this way, CodeView uses only approximately 17K of conventional MS-DOS memory. CodeView can use the following memory managers:
u

A VCPI server such as EMM386.EXE or EMM386.SYS. With a VCPI server, your program is also able to use EMS memory. To use this memory manager you must have a command in your CONFIG.SYS file such as:
DEVICE=C:\DOS\EMM386.EXE ram

u u

A DPMI server such as 386max. An Extended Memory Standard (XMS) driver such as HIMEM.SYS. To use this memory manager you must have a command in your CONFIG.SYS file such as:
DEVICE=C:\DOS\HIMEM.SYS

For more information about using memory managers, see your memory managers documentation. When you make new entries in your CONFIG.SYS file, remember to reboot your system so that your changes take effect.

The CodeView Command Line

You can specify CV or CVW options when you start them from the command line. You can also specify commands from within the CodeView environment to modify these startup arguments. Syntax CV[[W]] [[options]] [[program [[arguments]] ]] CV[[W]] @file [[program [[arguments]] ]] W Indicates the Windows operating system version of CodeView.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 309 of 17 Printed: 10/09/00 02:42 PM

310

Environment and Tools

options One or more options. The CodeView options are described in the Command-Line Options section on page 310. program Program to be debugged. Specifies the name of an executable file to be loaded by the debugger. If you specify program as a filename with no extension, CodeView searches for a file with the extension .EXE. If you do not specify a program, CodeView starts up and displays the Load dialog box where you can specify a program and its command-line arguments. arguments The programs command-line arguments. All remaining text on the CodeView command line is passed to the program you are debugging as its command line. If the program you are debugging does not accept commandline arguments, you do not need to specify any. Once youve started debugging, you can change the programs command-line arguments. @file File of command-line arguments. You can also specify arguments in a text file. The file contains a list of arguments, one per line. An argument file lets you specify a large number of arguments without exceeding the operatingsystem limit on the length of a command line. This is especially useful when starting a session that uses many DLLs. After CodeView loads its DLLs, processes the debugging information, and loads the source file, the CodeView display appears. If you do not specify a program to debug or CodeView cannot find all of its required DLLs, CodeView prompts for the necessary files. After starting up, CodeView is at the beginning of the program startup code, and you are ready to start debugging. At this point, you can enter an execution command (such as Trace or Program Step) to execute through the startup code to the beginning of your program.

Leaving CodeView
To exit CodeView at any time, choose the Exit command from the File menu. You can also press ALT+F4, or type Q (for Quit) in the Command window. At this point, you may want to skip ahead to the next chapter, The CodeView Environment for information on CodeViews menus and windows. The rest of this chapter describes each command-line option in detail, then continues with a description of how PWB and CodeView use the CURRENT.STS file.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 310 of 18 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

311

Command-Line Options
CV and CVW accept some of the same options for debugging. Table 8.2 summarizes the CodeView command-line options.
Table 8.2 CodeView Command-Line Options Option /2 /8 /25, /43, /50 /B /Ccommands /F /G /I[0 | 1] /Ldll /M /N[0 | 1] /S /TSF /X /Y CV Yes No Yes Yes Yes Yes Yes Yes No Yes Yes Yes Yes No No CVW Yes Yes Yes Yes Yes No Yes Yes Yes Yes Yes No Yes Yes Yex Description Use two displays Use 8514 and VGA displays Set 25-line, 43-line, or 50-line mode Use black-and-white display Execute commands Flip video pages Control snow on CGA displays Trap NMIs and 8259 interrupts Load DLL or application symbols Disable mouse Trap nonmaskable interrupts Swap video buffers Read or ignore state file Set starting X coordinate (pixels) Set starting Y coordinate (pixels)

The remainder of this section describes each option in detail.

Use Two Displays (CV, CVW)

Option /2 The /2 option permits the use of two monitors. The program display appears on the default monitor, while CodeView displays on the secondary monitor. You must have two monitors and two adapters to use the /2 option. The secondary display must be a monochrome adapter. If you are debugging a Windows-based application and have an IBM PS/2 with an 8514 primary display and a Video Graphics Adapter (VGA) secondary display, use the /8 option.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 311 of 19 Printed: 10/09/00 02:42 PM

312

Environment and Tools

Use 8514 and VGA Displays (CVW)

Option /8 If your system is an IBM PS/2, you can configure it with an 8514 as the primary display and a VGA as the secondary display. To use this configuration, specify the /8 (8514) option on the CVW command line. If your VGA monitor is monochrome, it is recommended to use the /B (blackand-white) option. The 8514 serves as the Windows operating system screen and the VGA as the debugging screen. By default, the debugging screen operates in 50-line mode in this configuration. If you specify the /8 option, you can specify /25 or /43 for 25-line or 43-line mode on the debugging screen. Warning Results are unpredictable if you attempt to run non-Windows-based applications or the MS-DOS shell while you are running CVW with the /8 option.

Set Line-Display Mode (CV, CVW)

Options /25 /43 /50 If you have the appropriate display adapter and monitor, you can display 25, 43, or 50 lines when you are running CV, and 25 or 50 lines when you are running CVW. The mode you specify is saved in the CURRENT.STS file so that it is still in effect the next time you run CodeView. CVW.EXE supports 25, 43 and 50 lines on VGA monitors. It does not support 50-line mode on EGA monitors. If you specify a mode that is not supported by your adapter and your monitor, CodeView displays 25 lines. To display 43 or 50 lines on a screen, you must use the OEM fonts supplied with CodeView. There are two OEM files: OEM08.FON for 50-line mode, and OEM10.FON for 43-line mode. To use these fonts, change the OEMFONTS.FON entry in your SYSTEM.INI file. For example, to use 50-line mode, change:
OEMFONTS.FON=VGAOEM.FON

to:
OEMFONTS.FON=C:\MASM\BIN\OEM08.FON

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 312 of 20 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

313

Use Black-and-White Display (CV, CVW)

Option /B When you start CodeView, it checks the kind of display adapter that is installed in your computer. If the debugger detects a monochrome adapter, it displays in black and white; if it finds a color adapter, it displays in color. The /B option tells CodeView to display in black and white even if it detects a color adapter. If you use a monochrome display or laptop computer that simulates a color display, you many want to disable color. These displays may be difficult to read with CodeViews color display. You can also customize CodeViews colors by choosing the Colors command from the Options menu. For more information, see Colors on page 345.

Execute Commands (CV, CVW)

Option /Ccommands You type commands in the CodeView Command window. You can also specify Command-window commands when you start CodeView. The /C option allows you to specify one or more CodeView Command-window commands to be executed upon startup. If you specify more than one command, you must separate each one with a semicolon (;). If the commands contain spaces or redirection symbols (< or >), enclose the entire option in double quotation marks ("). Otherwise, the debugger interprets each argument as a separate CodeView command-line argument rather than as a Command-window command. For complete information on CodeView Command-window commands, see Chapter 12, CodeView Reference. Examples The following example loads CV with CALCPR as the executable file and /p TST.DAT as the programs command line:
CV /CGmain CALCPR /p TST.DAT

Upon startup, CV executes the high-level language startup code with the command Gmain. Since no space is required between the command (G) and its argument (main), there is no need to enclose the option in double quotation marks. The next example loads CV with CALCPR as the executable file and /p TST.DAT as the programs command line. It starts CodeView with a long list of startup commands.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 313 of 21 Printed: 10/09/00 02:42 PM

314

Environment and Tools

CV "/C VS &;G signal_lpd;MDA print_buffer L 20" CALCPR /p TST.DAT

CodeView starts with the Source window displaying in Mixed mode (VS &). Then it executes up to the function signal_lpd with the command G signal_lpd. Next, it dumps 20 characters starting at the address of print_buffer with the command MDA print_buffer L 20. Since some of the commands use spaces, the entire /C option is enclosed in quotation marks. In this example, the command directs CV to take Command-window input from the file SCRIPT.TXT rather than from the keyboard:
CV "/C<SCRIPT.TXT" CALCPR TST.DAT

Although the option does not include any spaces, you must enclose it in quotation marks so that the less-than symbol (<) is read by CodeView rather than by the operating-system command processor.

Set Screen-Exchange Method (CV)

Options /F /S CodeView allows you to move between the output screen, which contains your program display output, and the CodeView screen, which contains the debugging display. In MS-DOS, CodeView can perform this screen exchange in two ways: screen flipping or screen swapping. The /F (flipping) and /S (swapping) options allow you to choose the method from the command line. These two methods are: Flipping Flipping is the default for a computer with a graphics adapter. CodeView uses the graphic adapters video-display pages to store each screen of text. Flipping is faster than swapping and uses less memory, but it cannot be used with a monochrome adapter or to debug programs that use graphic video modes or the video-display pages. CodeView ignores the /F option if you have a monochrome adapter. Swapping Swapping is the default for computers with monochrome adapters. It has none of the limitations of flipping, but it is slower than flipping and requires more memory. To swap screens, CodeView creates a buffer in memory and uses it to store the screen that is not displayed. When you request the other screen, CodeView swaps the screen in the display buffer for the one in the storage buffer. When you use screen swapping, the buffer is 16K bytes for all adapters. The amount of memory CodeView uses is increased by the size of the buffer.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 314 of 22 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

315

Suppress Snow (CV, CVW)

Option /G The /G option suppresses snow that can appear on some CGA displays. Use this option if your CodeView display is unreadable because of snow.

Specify Interrupt Trapping (CV, CVW)

Options /I[[0 | 1]] /N[[0 | 1]] The /I option tells CV whether to handle nonmaskable-interrupt (NMI) and 8259-interrupt trapping. The /N option controls only CodeViews handling of NMIs and does not affect handling of interrupts generated by the 8259 chip. The following table summarizes the options and their effects:
Option /I0 /I1, /I /N0 /N1, /N Effect Trap NMIs and 8259 interrupts Do not trap NMIs or 8259 interrupts Trap NMIs Do not trap NMIs

You may need to force CodeView to trap interrupts with /I0 on computers that CodeView does not recognize as IBM compatible. Using /I0 enables the CTRL+C and CTRL+BREAK interrupts on such computers.

Load Other Files (CVW)

Option /Ldll /Lexe To load symbolic information from a dynamic-link library (DLL) or from another application, use the /L option when you start CodeView. Specify /L for each DLL or application that you want to debug. When you place a module in a DLL, neither code nor debugging information for that module is stored in an application executable (.EXE) file. Instead, the code and symbols are stored in the library and are not linked to the main program until run time. The same is true for symbols in another application running within Windows. Thus, CVW needs to search the DLL or other application for symbolic information. Because the debugger does not automatically know which libraries to look for, use the /L option to preload the symbolic information.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 315 of 23 Printed: 10/09/00 02:42 PM

316

Environment and Tools

Example

The following command starts CodeView for Windows:

CVW /LPRIORITY.DLL /LCAPPARSE.DLL PRINTSYS

CVW is used to debug the program PRINTSYS.EXE. CVW loads symbolic information for the dynamic-link libraries PRIORITY.DLL and CAPPARSE.DLL, as well as the file PRINTSYS.EXE.

Disable Mouse (CV, CVW)

Option /M If you have a mouse installed on your system, you can tell CodeView to ignore it by using the /M option. You may need to use this option if you are debugging a program that uses the mouse and there is a usage conflict between the program and CodeView.

Nonmaskable-Interrupt Trapping (CV, CVW)

Option /N For information on the /N option, see Specify Interrupt Trapping on page 314.

Set Screen Swapping (CV)

Option /S The /S option sets the CodeView screen-exchange method to swapping. For complete information on CodeView screen-exchange methods, see Set ScreenExchange Method on page 313.

Toggle State-File Reading

Option /TSF The Toggle State File (/TSF) option either reads or ignores CodeViews state file and color files, depending on the Statefileread entry in the CodeView sections of TOOLS.INI. The /TSF option reverses the effect of the Statefileread entry. The Statefileread entry is set to yes by default. These options have no effect on writing the files. CodeView always saves its state on exit.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 316 of 24 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

317

The effect of different combinations of Statefileread and /TSF are summarized in the following table:
/TSF Specified Specified Not specified Not specified Statefileread
y (or omitted) n y (or omitted) n

CodeView Result Do not read files Read files Read files Do not read files

The state file is CURRENT.STS. The color files are CLRFILE.CV4 for CV and CLRFILE.CVW for CVW.

Set Startup X and Y Coordinates

Options /X, /Y The window CodeView uses within Windows cannot be moved or sized while Windows is running. You can specify the position of the CodeView window with the /X and /Y options. In the Command Line field of the Program Item Properties dialog box, enter
C:\MASM\BIN\CVW.EXE /X:X /Y:Y

where X and Y are the pixel coordinates for the upper lefthand corner of the CodeView session window. (The location for your CVW.EXE file may be different.) Note that this still does not allow the CodeView window to be moved to another location on the Program Manager workspace. For more information on specifying command-line options with Windows operating system applications, see your Windows Users Guide.

The CURRENT.STS State File

CodeView and PWB save settings and state information in the CURRENT.STS file. The file contains information about the current state of the two environments. When you restart CodeView or PWB, they read CURRENT.STS and restore their previous state. CodeView uses additional files to save your most recent color settings. These files are CLRFILE.CV4 for CV and CLRFILE.CVW for CVW. CodeView and PWB search for these files in the directory that the INIT environment variable specifies. If no INIT environment variable exists, CodeView and PWB search the current directory. If no state file is found, new CURRENT.STS and CLRFILE.CV4 or CLRFILE.CVW files are created in the INIT directory or the current directory if no INIT variable is set.

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 317 of 25 Printed: 10/09/00 02:42 PM

318

Environment and Tools

Information about CodeView stored in CURRENT.STS includes:

u u u u u

Window layout Breakpoints Watch expressions Source, Local, and Memory display options Global CodeView options such as case sensitivity, screen exchange method, radix, and expression evaluator

You can set CodeView options in TOOLS.INI or on the command line and then modify them during a session. They are saved in CURRENT.STS when you exit CodeView. During each CodeView session, these features are set in the following order: 1. 2. 3. 4. From TOOLS.INI From the CodeView command line From CURRENT.STS During the debugging session

The following items are not saved between sessions:

u u

The current location (CS:IP). The expansion state of watch expressions. All watch expressions and their format specifiers are restored, but they appear in their contracted state. Absolute-address breakpoints. Breakpoints set at an absolute segment:offset address are not saved. CodeView saves breakpoints only at specific line numbers or symbols. Memory window addresses. Each memory window is restored with its display type and options, but CodeView does not save the starting address. Instead, Memory windows show the start of the data segment (address DS:00).

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 318 of 26 Printed: 10/09/00 02:42 PM

Chapter 8 Getting Started with CodeView

319

Filename: LMAETC08.DOC Project: Environment and Tools Template: MSGRIDA1.DOT Author: Cris Morris Last Saved By: Mike Eddy Revision #: 97 Page: 319 of 27 Printed: 10/09/00 02:42 PM

319

C H A P T E R

The CodeView Environment

CodeView provides a powerful environment in which to debug programs and dynamic-link libraries (DLLs). Its rich set of commands helps you track program execution and changing data values. In CodeView you can point-and-click your source code to start and stop execution or modify bytes in memory. You can also use more traditional keyboard commands. You can use function keys to execute common commands, such as tracing and stepping through a program. When you quit CodeView, it remembers your breakpoints, window arrangement, watch expressions, and option settings. This chapter describes the CodeView display, shows you how to use the menu commands, and how to interact with the different types of windows.

The CodeView Display

The CodeView screen is divided into three parts:
u u u

The menu bar across the top of the screen The window area between the menu bar and status bar The removable status bar across the bottom of the screen

Figure 9.1 shows a typical CodeView screen with several open windows. The figure shows selected elements of the display, which are described in the sections that follow.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 319 of 1 Printed: 10/09/00 02:41 PM

320

Environment and Tools

Figure 9.1

CodeView Display

The Menu Bar

The menu bar displays the names of the CodeView menus. To open a menu, use one of the following methods:
u u u

Click a menu title with the mouse. Press ALT plus the menu titles highlighted letter. Press and release ALT, use the arrow keys to select a menu, and then press DOWN ARROW or ENTER to open it.

Each command in a menu has a highlighted letter. To choose that command, press the highlighted letter. Many commands also list a shortcut key that you can press at any time instead of opening a menu and choosing a command. A command that does not apply to a particular situation is dimmed on the menu. When you press the corresponding shortcut key, no action is performed.

The Window Area

Most of your debugging takes place in the window area, where you can open, close, move, size, and overlap the various types of CodeView windows.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 320 of 2 Printed: 10/09/00 02:41 PM

Chapter 9 The CodeView Environment

321

Although each window serves a different function for debugging, the windows have a number of common features. The Close, Maximize, Restore, and Minimize boxes work in the same way as they do in PWB. The scroll bars also work the same as in PWB. For information on the window border controls, see Chapter 4, User Interface Details. Only one window can be active at a time. You always use the currently active window, which appears with a highlighted border and a shadow on the screen. The text cursor always appears in the active window.

The Status Bar

The status bar contains information about the active window. It usually includes a row of buttons you can click to execute commands. You can also use the shortcut keys shown on the buttons. To remove the status bar and gain an extra line for the window area, choose Status Bar from the Options menu, or type the OA- command in the Command window. To restore the status bar, choose Status Bar from the Options menu, or type the OA+ command in the Command window. For more information on this command, see the Options command on page 422.

CodeView Windows
CodeView windows organize and display information about your program. This section describes each CodeView window, the information you can display, and how you can change information and enter commands in the Command window. It also explains how to move among the windows and manipulate them.

How to Use CodeView Windows

Each CodeView window has a different function and operates independently of the others. Only one window can be active at a time. Commands you choose from the menus or by using shortcut keys affect the active window. The following list briefly describes each windows function: Source Displays the source or assembly code for the program you are debugging. You can open a second Source window to view an include file or any ASCII text file.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 321 of 3 Printed: 10/09/00 02:41 PM

322

Environment and Tools

Command Accepts debugging commands from the keyboard. CodeView displays the results, including error messages, in the Command window. When you enter a command in a dialog box, CodeView displays any resulting errors in a popup window. Watch Displays the values of variables and expressions you select. You can modify the value of watched variables, browse the contents of structures and arrays, and follow pointers through memory. Local Lists the values of all variables local to the current scope. You can set Local window options to show other scopes. You can modify the values of variables displayed in the Local window. Memory Displays the contents of memory. You can open a second Memory window to view a different section of memory. You can set Memory window options to select the format and address of displayed memory. You can directly change the displayed memory by typing in the Memory window. Register Displays the contents of the machines registers and flags. You can directly edit the values in the registers, and you can toggle flags with a single keystroke or mouse click. 8087 Displays the registers of the hardware math coprocessor or the software emulator. Help Displays the Microsoft Advisor Help system. The first time you run CodeView, it displays three windows. The Local window is at the top, the Source window fills the middle of the screen, and the Command window is at the bottom. The Local window is empty until you trace into the main part of the program. You can open or close any CodeView window. However, at least one Source window must remain open. When you exit CodeView, it records which windows are open and how they are positioned, along with their display options. These settings become the default the next time you run CodeView. To open a window, choose a window from the Windows menu. Some operations, such as setting a watch expression or requesting help, open the appropriate window automatically. You can change how CodeView displays information in the Source, Memory, and Local windows. Choose the appropriate window options command from the

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 322 of 4 Printed: 10/09/00 02:41 PM

Chapter 9 The CodeView Environment

323

Options menu. When the cursor is in one of these windows, you can press CTRL+O to display that windows options dialog box. CodeView automatically updates the windows as you debug your program. To interact with a particular window (such as entering a command or modifying a variable), you must select it. The selected window is the active window. The active window is marked in the following ways:
u u u u

The windows frame is highlighted. The window casts a shadow over other windows. The cursor appears in the window. The horizontal and vertical scroll bars move to the window.

To make a window active, click anywhere in the window or in the window frame. You can also press F6 or SHIFT+F6 to cycle through the open windows, making each one active in turn. You can also choose a window from the Windows menu or press ALT plus a window number. In addition, some CodeView commands make a certain window active.

Moving Around in CodeView Windows

To move the cursor to a specific window location, click that location. You can also use the keyboard to move the cursor as shown in Table 9.1.
Table 9.1 Moving Around with the Keyboard Action Move cursor up, down, left, and right Move cursor left and right by words Move cursor to beginning of line Move cursor to end of line Page up and down Page left and right Move cursor to beginning of window Move cursor to end of window Move to next window Move to previous window Restore window Move window Size window Minimize window Keyboard
UP ARROW, DOWN ARROW, LEFT ARROW, RIGHT ARROW CTRL+LEFT, CTRL+RIGHT HOME END PAGE UP , PAGE DOWN CTRL+PAGE UP , CTRL+PAGE DOWN CTRL+HOME CTRL+END F6 SHIFT+F6 CTRL+F5 CTRL+F7 CTRL+F8 CTRL+F9

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 323 of 5 Printed: 10/09/00 02:41 PM

324

Environment and Tools Maximize window Close window Tile windows Arrange windows
CTRL+F10 CTRL+F4 SHIFT+F5 ALT+F5

The Source Windows

The Source windows display the source code. You can open a second Source window to view other source files, header files, the same source file at a different location, or any ASCII text file. To open a Source window, use one of the following methods:
u u u u

From the Windows menu, choose Source 1 or Source 2. In the Command window, type the View Source (VS) command. Press ALT+3 to open Source window 1. Press ALT+4 to open Source window 2.

You cannot edit source code in CodeView, but you can temporarily modify the machine code in memory using the Assemble (A) command. For more information on the Assemble command, see page 400. Source windows can display three different views of your program code in three different modes:
u u u

Source mode shows your source file with numbered lines. Assembly mode shows a disassembly of your programs machine code. Mixed mode shows each numbered source line followed by a disassembly of the machine code for each line.

Note When you are debugging p-code while Native mode is off, CodeView displays p-code instructions rather than disassembled machine instructions. See the Options command on page 422. For more information on p-code, see Debugging P-code on page 363. CodeView automatically switches to Assembly mode when you trace into routines for which no source is available, such as library or system code. The debugger switches back to the original display mode when you continue tracing into code for which source code is available. For more information on setting display modes, see the View Source command on page 433. For detailed information about the Source window display options, see page 343.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 324 of 6 Printed: 10/09/00 02:41 PM

Chapter 9 The CodeView Environment

325

The Watch Window

The Watch window displays the value of program variables or the value of expressions you specify in a high-level language. For each expression or variable, you can change the format of the data that is displayed. You can expand aggregate variables, such as structures and arrays, to show all the elements of an aggregate and contract them to save space in the Watch window. You can follow chains of pointers to display and help debug more complex structures, such as linked lists or binary trees. To open a Watch window, use one of the following methods:
u u

From the Windows menu, choose Watch. In the Command window, type the Add Watch (W?) command followed by the variable or expression name. Press ALT+2.

To add expressions to the Watch window, use the Add Watch command from the Data menu or the Quick Watch dialog box (SHIFT+F9). You can also add watch expressions using the Add Watch (W?) and Quick Watch (??) commands. Note Do not edit a string in the Watch window. To change the value of any variable displayed in the Watch window, move the cursor to the value, delete the old value, and type the new value. To change the format in which a variable is displayed or to specify a new format, move the cursor to the end of the variable name and type a new format specifier. To toggle between insert and overtype modes, press the INS key.

Using the Watch Window to View Multi-Level Arrays

You can use the watch window to view the changing values of a structure or array as you step or trace through your program: 1. Open the Watch Window. 2. Add the structure whose elements you want to track to the Watch window with the Add Watch command from the Data menu, or by using the Quick Watch dialog box (SHIFT+F9). The structure name will be added to the Watch Window. 3. Using the mouse, double-click anywhere on the structure name in the Watch Window to expand it one level. Double-click again on any subsequent levels until the structure is open to the level you want to watch.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 325 of 7 Printed: 10/09/00 02:41 PM

326

Environment and Tools

4. Step or Trace through the code using will update with each step.

F8

or F10 keys. The structure elements

For information on expanding and contracting aggregate types and following pointers, see the Quick Watch command on page 453. For detailed information on specifying and using watch expressions, see the Codeview Expression Reference on page 393 and Chapter 11, Using Expressions in CodeView.

The Command Window

You type CodeView commands in the Command window to execute code, set breakpoints, and perform other debugging tasks. You can use the menus, mouse, and keyboard for many debugging tasks, but you can use some CodeView commands only in the Command window. When you first start the debugger, the Command window is active, and the cursor is at the CodeView prompt (>). To return to the Command window after you make another window active, click the command window, or press ALT+9. Using the Command window is similar to using an operating-system prompt, except that you can scroll back to view previous results and edit or reuse previous commands or parts of commands.

How to Enter Commands and Arguments

You enter commands in the Command window at the CodeView prompt when the Command window is active. Type the command followed by any arguments and press ENTER. Some commands, such as the Assemble (A) command, prompt for an indefinite series of arguments until you enter an empty response. CodeView may display errors, warnings, or other messages in response to commands you enter in the Command window. If a Source window is active and the Command window is open, you can still type Command-window commands. When you begin typing, the cursor moves to the Command window and remains there until you press ENTER. The cursor returns to the Source window, and CodeView executes the command. If you have begun typing but do not want to execute a command, press ESC to clear the text and place the cursor at the prompt. After you press ESC, the Command window becomes active.

Command Format
The format for CodeView commands is as follows:

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 326 of 8 Printed: 10/09/00 02:41 PM

Chapter 9 The CodeView Environment

327

command [[arguments]] [[;command2]] The command is the command name, and arguments are control options or expressions that represent values or addresses to be used by the command. The first argument can usually be placed immediately after command with no intervening spaces. Arguments may be separated by spaces or commas, depending on the command. For more information, see Chapter 12, CodeView Reference. To specify additional commands on the same line, separate each command with a semicolon (;). Commands are always one, two, or three characters long. They are not case sensitive, so you can use any combination of uppercase and lowercase letters. Arguments to commands may be case sensitive, depending on the command. Example The following example shows three commands separated by semicolons:
MDB 100 L 10 ; G .178 ; MDB 100 L 10

The first command (MDB 100 L 10) dumps 10 bytes of memory starting at address 100. The second command (G .178) executes the program up to line 178 in the current module. The third command is the same as the first and is used to see if the executed code changed memory. Example This example demonstrates the Comment (*) command:
U extract_velocity ;* Unassemble at this routine

The first command is the Unassemble (U) command, given the argument extract_velocity. The next command is the Comment command. Comment commands are used throughout the CodeView examples in this book.

How to Copy Text for Use with Commands

Copy and paste text instead of retyping. Text that appears in any CodeView window can be copied and used in a command. For example, an address that is displayed in a Memory window or the Register window can be copied and used in a breakpoint command. To copy and use text: 1. Select the text with the mouse or the keyboard. To select text with the mouse, move the mouse pointer to the beginning of the desired text, hold down the left mouse button, and drag the mouse. When you have selected the desired text, release the button.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 327 of 9 Printed: 10/09/00 02:41 PM

328

Environment and Tools

To select text with the keyboard, move the cursor to the desired text, hold down the SHIFT key, and move the cursor with the ARROW keys. 2. Choose the Copy command from the Edit menu or press
CTRL+INS.

3. Move the cursor to the location where you want to use the text and choose the Paste command from the Edit menu, or press SHIFT+INS. 4. Edit the command if desired, and press
ENTER

to execute the command.

Because all input to CodeView windows is line oriented, you cannot copy more than a single line. If you select more than a single line, the Copy command in the Edit menu is unavailable, and CTRL+INS has no effect. However, you can still select more than one line for use with the Print command on the File menu. For more information about the Print command, see Print on page 333. When editing a command, you can toggle between insert and overtype modes by pressing the INS key.

How to Use the Command Buffer

CodeView keeps the last several screens of commands and output in the Command window. You can scroll the Command window to view the commands you entered earlier in the session. This is particularly useful for viewing the output from commands, such as Memory Dump (MD) or Examine Symbols (X), whose output exceeds the size of the window. The TAB key provides a convenient way to move among the previously entered commands. Press TAB to move the cursor to the beginning of the next command, and press SHIFT+TAB to move to the beginning of the previous command. If the cursor is at the beginning or the end of the command buffer, the cursor wraps around to the other end. To return to the current command prompt, you can press CTRL+END or press TAB repeatedly. You can also reuse any command that appears in the Command window without copying and pasting. Move the cursor to the command or press TAB, edit the command if desired, and press ENTER to execute it. When you press ENTER, CodeView restores the original command, copies the new command to the current prompt, and executes the command. If you make a mistake while editing a command, press ESC to restore the line.

The Local Window

The Local window shows all local variables in the current scope. The Local window is similar to the Watch window, except that the variables that are displayed change as the local scope changes. A variable in the Local window is always shown in its default type format. When you edit in the Local window, you can toggle between insert and overtype modes by pressing the INS key.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 328 of 10 Printed: 10/09/00 02:41 PM

Chapter 9 The CodeView Environment

329

You can expand and contract pointers, structures, and arrays the same way you do in the Watch window. You can also change the values of the variables as in the Watch window. The keyboard shortcut to open or switch to the Local window is
ALT+1.

You can see the local variables of each active routine in the stack by selecting the routine from the Calls menu. For more information on this feature, see The Calls Menu on page 346. By default, the Local window shows the addresses of the local variables on the left side of the window. You can turn this address display on or off using the Options (O) command. For more information on the Options command, see page 422.

The Register Window

The Register window displays the names and current values of the native CPU registers and flags. When you are debugging p-code, it displays names and values of the p-code registers and flags. You can change the value of any register or flag directly in the Register window. To open the Register window, choose Register from the Windows menu, press ALT+7, or F2. You can also view and modify registers by using the Register (R) command. For more information about the Register command, see page 426. When a register value changes after a program step or trace, CodeView highlights the new value so you can see how your program uses the CPU registers. Depending on the current instruction, the Register window also displays the effective address at the bottom of the window. This display shows the location of an operand in physical memory and its value. If you are debugging on an 80386 or 80486 machine, you can view and modify the 32-bit registers. To turn on the 32-bit Registers option, choose the 386 command from the Options menu or use the O3+ command. The 32-bit registers are available if you are debugging on an 80386 or 80486 machine. When you are debugging p-code, CodeView displays the p-code registers: DS, SS, CS, IP, SP, BP, PQ, TH, and TL. If your program has taken an unexpected turn, you may be able to compensate for the problem and continue debugging if you change the value of a register or a flag. You can change a flag value before a dump or looping instruction to test a different branch of code, for example. You can change the instruction pointer (CS:IP) to jump to any code in your program or to execute code you have assembled elsewhere in memory.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 329 of 11 Printed: 10/09/00 02:41 PM

330

Environment and Tools

To change the value of any register, move the cursor to the register value you want to change and overtype the old value with the new value. The cursor automatically moves to the next register. Although you cannot change the value of the flag register numerically in the Register window, you can conveniently toggle the values of each flag using either the mouse or the keyboard:
u u

To toggle a flag with the mouse, double-click the flag. To toggle a flag using the keyboard, move the cursor to the flag and press any key except ENTER, TAB, or ESC. After toggling a flag, CodeView moves the cursor to the next flag.

To restore the value of the last flag or register that you changed, choose Undo from the Edit menu or press ALT+BACKSPACE. If you happen to lose the cursor somewhere in the register window, press TAB. The TAB key moves the cursor to the next register or flag that can be changed.

The 8087 Window

The 8087 window displays the current status of the math coprocessors registers and flags. If you are debugging a program that uses the software-emulated coprocessor, the emulated registers are displayed. To open the 8087 window, choose 8087 from the Windows menu or press ALT+8. The display in the 8087 window is the same as the display produced by the 8087 (7) command, except that the window is continually updated to show the current status of the math coprocessor. For more information about the display, see the 8087 command on page 448. If your program uses floating-point libraries provided by several Microsoft languages, or if your program does not use floating-point arithmetic, the 8087 window and 8087 command display the message:
Floating point not loaded

CodeView displays this message until at least one floating-point instruction has been executed.

The Memory Windows

Memory windows display memory in a number of formats. CodeView allows two Memory windows to be open at the same time. You can open a Memory window in several ways:
u

From the Windows menu, choose Memory 1 or Memory 2.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 330 of 12 Printed: 10/09/00 02:41 PM

Chapter 9 The CodeView Environment

u

331

From the Options menu, choose Memory1 Window when no Memory windows are open. In the Command window, enter the View Memory (VM) command. At the keyboard, press
ALT+5

u u

or ALT+6.

By default, memory is displayed as bytes or as the last type specified by a Memory Enter (ME), Memory Dump (MD), or View Memory (VM) command. The byte display shows hexadecimal byte values followed by an ASCII representation of those byte values. For values that are outside the range of printable ASCII characters (decimal 32 to 127), CodeView displays a period (.).

How to Change Memory Display Format

It is not always most convenient to view memory as byte values. If an area of memory contains character strings or floating-point values, you might prefer to view them in a directly readable form. To change the display format of a Memory window, choose Memory1 Window or Memory2 Window from the Options menu. CodeView displays a dialog box where you can choose from a variety of display options. When the cursor is in a Memory window, you can presss CTRL+O to display the corresponding Memory Window Options dialog box. You can also set memory display options using the View Memory (VM) command. For detailed information about the display options, see View Memory on page 431. To cycle through the display formats, click the <Sh+F3=Mem1Fmt> or <Sh+F3=Mem2 Fmt> buttons on the status bar, or press SHIFT+F3. Pressing CTRL+SHIFT+F3 displays the cycle in reverse order. When you first open the Memory window, it displays memory starting at address DS:00. To change the starting address, use one of the commands to set Memory window options. You can specify the starting address or enter an expression to use as the starting address. You can also type over the segment:offset addresses shown in the left column of the Memory window to change the displayed addresses. Move the cursor to an address in the window, or repeatedly press TAB until the cursor is on an address, and type a new address.

How to Change Memory Directly

To change the values in memory, overtype the value you want to change. To move quickly from field to field in the Memory window, press TAB. You can change memory by entering new values for the format that is displayed or by typing over the raw bytes in the window. CodeView ignores the input if you

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 331 of 13 Printed: 10/09/00 02:41 PM

332

Environment and Tools

press a key that does not make sense for the current format (for example, if you type the letter X in anything but ASCII format). To undo a change to memory, choose Undo from the Edit menu, or press ALT+BACKSPACE.

How to View Memory at a Dynamic Address

Live expressions make it easy for you to watch a dynamic view of an array or pointer in the Memory window. Live means that the starting address of memory in the window changes to reflect the current value of an address expression. To create a live expression, choose the Memory1 Window or Memory2 Window command from the Options menu. In the Memory Window Options dialog box, type in an address expression, then turn on the Re-evaluate Expression Always (Live) option. It is usually more convenient to view an item in the Watch window than in the Memory window. However, some items are more easily viewed using live expressions. For example, you can examine what is currently on top of the stack by entering SS:SP as the live expression.

The Help Window

In CodeView, you can request Help:
u u

u u u

From the Help menu. By pressing F1 when the cursor is on the keyword, menu, or dialog box for which you want Help. By clicking the right mouse button on a Help keyword. Using the Help (H) command. By choosing Help from the Windows menu. You can also press ALT+0 for Help on CodeView windows.

The Microsoft Advisor Help window is displayed whenever you request Help for CodeView. For information about getting the most out of the Microsoft Advisor Help system, see Chapter 21.

CodeView Menus
Many commands that you are likely to use frequently are in the CodeView menus. This section describes the menus and the commands or options in each menu. Not all commands are available in both versions of the CodeView debugger. When applicable, the menu descriptions discuss command availability.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 332 of 14 Printed: 10/09/00 02:41 PM

Chapter 9 The CodeView Environment

333

The File Menu

The File menu contains commands to load source files and other ASCII text files into the Source window, print from the active window, start an operatingsystem shell, and end the debugging session. The following table summarizes the commands on the File menu. Commands marked with an asterisk are not shown in the CVW File menu:

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 333 of 15 Printed: 10/09/00 02:41 PM

334

Environment and Tools Command Open Source Open Module Print* DOS Shell* Exit Purpose Opens a source, include, or other text file Opens a source file for a module in the program Prints all or part of the active window Goes to the operating-system prompt temporarily Exits CodeView

Open Source
The Open Source command displays the Open Source File dialog box. You can select the name of the source file, include file, or other text file to display in the active Source window.

Open Module
The Open Module command displays the Open Module dialog box. This dialog box provides an easy way to load the source file for any module in your program. The dialog box lists the source files that make up the modules in the program you are debugging. Only those modules that include line-number or full symbolic information are listed. CodeView displays the source file you choose in the active Source window.

Print
In CodeView for MS-DOS only, the Print command displays the Print dialog box, which offers several options to write information in the active window to a device or a file. You can print text in the active window in the following ways:
u u

Window view, which prints text that currently appears in the active window Complete window contents, which prints the contents of the active window, including what has scrolled out of the window

To print to a file, specify a filename in the dialog box. To append the printed text to the end of the file, select Append. To overwrite a file that already exists, select Overwrite. If you specify a device instead of a file, you can choose either Append or Overwrite. To print directly to a printer, specify the name of the printer port such as LPT1 or COM2. You must specify a filename or a device name. CodeView reports an error if you omit the name.

DOS Shell
In MS-DOS only, you can use the DOS Shell command to leave CodeView temporarily and go to the operating-system prompt.

Filename: LMAETC09.DOC Project: MASM Environment and Tools Template: MSGRIDA1.DOT Author: Mike Eddy Last Saved By: Mike Eddy Revision #: 44 Page: 334 of 16 Printed: 10/09/00 02:41 PM

Chapter 9 The CodeView Environment

335

When you choose the Shell command, CodeView starts a second copy of the command processor specified by the COMSPEC environment variable. If there is not enough memory to open a new shell, a message appears. Even if you do have enough memory to start a command shell, you may not have enough memory to execute large programs from the shell. While in the shell, do not start any terminate-and-stay-resident (TSR) programs, such as MSHERC.COM, and do not delete