 Microsoft  C - Installing and Using the Professional Development System








 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  Microsoft (R) C - Installing and Using the Professional Development System

                        FOR MS (R) OS/2 AND MS-DOS (R)
                              OPERATING SYSTEMS
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


                            MICROSOFT CORPORATION








 Information in this document is subject to change without notice and does
 not represent a commitment on the part of Microsoft Corporation. The
 software described in this document is furnished under a license agreement
 or nondisclosure agreement. The software may be used or copied only in
 accordance with the terms of the agreement. It is against the law to copy
 the software on any medium except as specifically allowed in the license or
 nondisclosure agreement. No part of this manual may be reproduced or
 transmitted in any form or by any means, electronic or mechanical, including
 photocopying and recording, for any purpose without the express written
 permission of Microsoft.
 (C) Copyright Microsoft Corporation, 1990. All rights reserved.


 Printed and bound in the United States of America.


 Microsoft, MS, MS-DOS, and CodeView are registered trademarks
 and Windows is a trademark of Microsoft Corporation.

 386-Max is a trademark of Qualitas, Inc.

 BRIEF is a registered trademark of UnderWare, Inc.

 IBM is a registered trademark of International Business
 Machines Corporation.

 UNIX is a registered trademark of American Telephone
 and Telegraph Company.



 Document No.  LN06516-1189 OEMO711-6Z

 10
  9
  8
  7
  6
  5
  4
  3
  2
  1









 Chapter 1  The Microsoft(R) C Professional Development System

      Before You Proceed
             System Requirements
             Package Contents
      Features New to Version 6.0
      Why Microsoft Programmer's WorkBench?

 Chapter 2  Installing Microsoft C

      Running SETUP
             Supplying SETUP Information
             Correcting Mistakes
             First Screen: Installing Libraries
             Second Screen: Installing Additional Files
             Third Screen: Specifying Directories
             Checking Available Disk Space
             SETUP Options
             Configuring Your System
             Choosing a Target Operating Environment
      Configuring Extended Memory for CodeView
      Customizing Microsoft C

 Chapter 3  Using the Programmer's WorkBench

      Starting PWB
             Specifying a Source File
             Command-Line Options
      Using Windows and Menus
             Windows
             Menus
             Dialog Boxes
             Getting Help
      Using the Editor
             Moving Around in a Source File
             Customizing the Editor
      Compiling and Linking
             Building Programs in PWB
             Compiling and Linking from the Command Line
      Debugging Programs
             Using the Browser
             Debugging with CodeView
             Running IO.C
             Debugging IO.C
      Getting More Details

 Chapter 4  Using the On-Line Reference

      Structure of the Microsoft Advisor
      Navigating Through the Microsoft Advisor
             Using the Help Menu
             Using the F1 Key
             Using Hyperlinks
             Using Help Windows and Dialog Boxes
             Accessing Different Types of Information
             Specifying Temporary Help Files
      Using QuickHelp
             Using the /HELP Switch
             Using the QH Command



 Chapter 1  The Microsoft(R) C Professional Development System
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 The Microsoft C Professional Development System is a collection of tools
 designed to increase DOS and OS/2 programming efficiency. The system offers



   þ   A customizable editor that is capable of being extended

   þ   An optimizing and incremental compiler

   þ   An intelligent linker

   þ   A project-oriented Make utility

   þ   A source-level browser

   þ   A complete on-line reference system

   þ   A source-level, window-oriented debugger


 The Programmer's WorkBench (PWB) integrates these tools, creating an
 environment in which you can edit, compile, link, and debug your programs.

 This book is a general introduction to the Microsoft C Professional
 Development System. This chapter introduces some of the features of the
 Professional Development System. Chapter 2 describes how to install the
 Professional Development System. Chapter 3 introduces the Programmer's
 WorkBench. Chapter 4 shows how to use the on-line reference systemÄa
 complete reference to the Professional Development System and the C
 language, which is available both within PWB and at the OS/2 and DOS command
 lines.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 Microsoft documentation uses the term "OS/2" to refer to the OS/2 systemsÄ
 Microsoft Operating System/2 (MS(R) OS/2) and IBM(R)  OS/2. Similarly, the
 term "DOS" refers to both the MS-DOS(R) and IBM Personal Computer DOS
 operating systems. The name of a specific operating system is used when it
 is necessary to note features that are unique to the system.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 If you'd like further information about a topic as you read through this
 book, you can consult


   þ   Advanced Programming Techniques

   þ   The C Reference guide

   þ   The on-line reference system (as discussed in Chapter 4)


 All of these sources are included in the Microsoft C package; they present
 detailed information about the various components of the Professional
 Development System.


 Before You Proceed

 Before installing Microsoft C, take a few minutes to make sure your computer
 meets minimum system requirements and that your package is complete.


 System Requirements

 Microsoft C requires the following configuration:


   þ   An IBM Personal Computer or 100% compatible running DOS version 3.0 or
       later or OS/2 version 1.1 or later.

   þ   An 8088 processor (a minimum of an 8 megahertz, 80286 processor is
       recommended).

   þ   512K (kilobytes) of available memory (RAM) for operating under DOS (1
       megabyte of RAM is recommended).

   þ   3 megabytes of RAM for operating under OS/2 (4 megabytes of RAM are
       recommended).

   þ   At least 384K of extended memory if you want to debug large DOS
       programs.

   þ   One hard-disk drive with a minimum of 8 megabytes of free space.
       (Depending on the options you want, you may need up to 20 megabytes of
       disk space.)

   þ   One 1.2 megabyte, 5.25-inch floppy disk drive or one 720K, 3.5-inch
       floppy disk drive.


 Programs compiled with Microsoft C version 6.0 support DOS versions 2.1 and
 later.


 Package Contents

 Check your Microsoft C package to see if everything is there. If any pieces
 are missing, contact the retailer from whom you purchased Microsoft C.

 In the package, you should find the following items:


   þ   Registration card. There are many advantages to being a registered
       owner of Microsoft C version 6.0, including notification of future
       software releases and easy access to customer assistance. Please take
       the time to fill out and mail the registration card now. (If you are
       already a registered owner of an earlier version of Microsoft C, a
       registration card is not included with the update.)

   þ   Disks. The distribution disk labeled "Setup/Compiler" contains a file
       named PACKING.LST that lists the location and description of all disk
       files in the Microsoft C package. Files on the disks are compacted and
       are uncompressed with the Setup program as they are installed.
       Microsoft C is distributed on 5.25-inch high density disks or 3.5-inch
       disks. If you need 360K disks to install the compiler, please send in
       the 3.5-inch media order card contained in the C 6.0 package or call
       Microsoft Customer Service (1-800-426-9400).

   þ   Installing and Using Microsoft C. It explains how to install and use
       Microsoft C.

   þ   Advanced Programming Techniques. This book discusses advanced topics
       concerning Microsoft C. Part 1, "Improving Program Performance,"
       examines options and methods for producing more efficient code. Part
       2, "Improving Programmer Productivity," describes tools and techniques
       the Professional Development System offers to help you work more
       efficiently. Part 3, "Special Environments," discusses graphics,
       mixed-language programming, and portability. Part 4, "OS/2 Support,"
       discusses developing OS/2 applications with the Professional
       Development System.

   þ   C Reference. This book includes a summary of compiler, linker, editor,
       the Microsoft CodeView(R) debugger, and other tool commands; a brief
       language reference; and a complete list of library functions.

   þ   Product Assistance Request. If you need to contact Microsoft Product
       Support, be sure to fill out this questionnaire before calling.

   þ   Documentation Feedback Card. To help Microsoft improve its
       documentation, a postage-paid survey mailer is included. Please take
       the time to fill out the card with any comments or suggestions.



 Features New to Version 6.0

 If you've used an earlier version of Microsoft C, you'll find many new
 capabilities in version 6.0, and you'll discover that you can perform
 familiar operations more quickly:


   þ   Speed up development with the integrated PWB environment, including a
       fast-turnaround incremental compiler and linker.

   þ   Increase program efficiency with global optimization and smaller
       run-time libraries.

   þ   Build programs more easily with the new Make facility (NMAKE) and
       PWB's powerful project capabilities.

   þ   Insert assembly code directly into your C source code with the
       integrated in-line assembler.

   þ   Track down program bugs and logic errors more quickly with the new
       Microsoft CodeView debugger version 3.0. With an 80286 or 80386
       processor and 1 megabyte or more of RAM, you can debug a program of
       any size in real mode.

   þ   Access all C run-time, language, compiler, linker, and utility
       documentation with the Microsoft Advisor and QuickHelp on-line
       reference systems.

   þ   Cross-reference program functions and variables with the PWB Source
       Browser.

   þ   Create OS/2 applications with increased support for dynamic-link
       libraries (DLLs), multiple threads, and improved debugging options.

   þ   Use based pointers to control placement of data in segments and
       generate better code for far-pointer manipulation.

   þ   Pass function parameters more efficiently with the _fastcall calling
       convention.

   þ   Edit source code with PWB's mouse- and window-oriented editor, which
       has all the functionality of the Microsoft Editor.



 Why Microsoft Programmer's WorkBench?

 The Programmer's WorkBench offers a wide array of features that can cut
 development time and increase your productivity.

 One feature that sets PWB apart from other development systems is its fully
 integrated, mouse- and window-based development environment. Most operations
 can be performed with menu selections or single keyboard commands. You never
 need to leave PWB to edit, build, debug, and run a program.

 PWB is built around the Microsoft Editor. The editor is completely
 extensible and can easily be configured to meet your personal needs. The
 editor combines advanced features such as macros and regular-expression
 search capabilities with the simplicity of a window-based application (see
 Figure 1.1).

 (This figure may be found in the printed book).

 As you develop your program, you can find information in the Microsoft
 Advisor on-line reference system instead of paging through manuals. A menu
 command provides complete information on the C language and run-time
 libraries. The Microsoft Advisor also supplies details on PWB, the compiler,
 linker, CodeView, and even the reference system itself. Figure 1.2 shows
 summary information on printf.

 (This figure may be found in the printed book).

 When you're ready to compile the program, you don't need to remember the
 full range of command-line compiler options. All of the options are
 conveniently available in a PWB dialog box and can be clicked on or off (see
 Figure 1.3). Setting options is simply a matter of using the mouse or
 keyboard to select compiler, linker, NMAKE, and CodeView switches.

 PWB uses the powerful NMAKE tool to speed up development. NMAKE examines
 each module of a program to determine whether changes have been made that
 require the module to be recompiled. NMAKE then automatically compiles the
 modules as necessary and links them. When you're ready to build your
 program, you just select a single menu command to start the process. PWB
 invokes NMAKE and builds an application, using the options you set.

 If any errors are encountered, PWB displays an error window with a full
 listing of the compile and link errors (see Figure 1.4). The editor
 indicates the source line containing the error, and you can use the on-line
 reference system to provide comprehensive information about each error.

 (This figure may be found in the printed book).

 (This figure may be found in the printed book).

 Once a program has been successfully built, you can run it from within PWB
 to test it. If you need to make modifications, you can interrupt the program
 and return directly to PWB to make the changes.

 Another useful PWB feature is the Source Browser. With the Browser you can
 examine your code and display information about function and variable
 relationships (see Figure 1.5). This option is helpful in tracking program
 flow and isolating bugs.

 (This figure may be found in the printed book).

 For bugs that are more difficult to locate and understand, use PWB's Debug
 Build option, and invoke the CodeView debugger directly from PWB. Then you
 can step and trace through your code at the source level and examine
 variables, registers, and memory (see Figure 1.6).

 Once you locate the bug you can exit CodeView and return directly to PWB,
 where you can fix the problem. When the code is completely debugged, a final
 release program can be built by using PWB's Release Build option.

 (This figure may be found in the printed book).






 Chapter 2  Installing Microsoft C
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 This chapter describes how to install Microsoft C on your system, configure
 extended memory for use with CodeView, and customize components of
 Microsoft C.

 Files on the disks are compressed; SETUP.EXE is provided for installing
 Microsoft C under DOS and OS/2 operating environments. SETUP uncompresses
 and copies a variety of filesÄthe compiler, the linker, the Programmer's
 WorkBench (PWB), the library manager, libraries, the help system, and
 othersÄfrom the distribution disks to your hard disk. SETUP also can build
 combined libraries from component libraries such as math libraries,
 memory-model-specific base libraries, and graphics libraries; and can build
 additional libraries as needed.

 Before you run the SETUP utility, back up the distribution disks and make
 sure you have enough disk space (between 5 and 10 megabytes, depending on
 which options you select) to install the Professional Development System.
 Then read the first part of the README.DOC file to see whether it has any
 information concerning the installation process.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 If you are installing Microsoft C from 3.5-inch disks, SETUP.EXE is found on
 the disk labeled "Setup." If you are using 5.25-inch disks, SETUP is on the
 disk labeled "Setup and Compiler."

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Running SETUP

 Insert the disk containing the SETUP program in drive A, make that drive the
 current drive, then run SETUP.EXE. The program first displays a screen
 reminding you to read the documentation before installing Microsoft C (see
 Figure 2.1). This initial screen also points out that the default answers to
 SETUP's questions are usually good when you first install Microsoft C. Press
 ENTER to proceed.

 (This figure may be found in the printed book).


 Supplying SETUP Information

 Before SETUP can install Microsoft C, it needs information about your system
 and the type of programming you intend to do. This first stage of SETUP is a
 series of questions divided among three screens. Default answers to the
 questions appear in brackets; you can press ENTER to accept the defaults, or
 you can type in your own answers to override the defaults. Detailed
 information on the questions appears at the bottom of each screen. Each
 screen concludes by asking if you want to change any of your choices. Press
 N and then ENTER to move to the next screen.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 The questions that are displayed on your screen may differ slightly from the
 questions that are shown in this chapter. For example, if DOS is specified
 as the host operating mode, later questions will refer to DOS.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Correcting Mistakes

 If you want to change any of your choices, press Y. The questions will be
 repeated, but the choices you previously made become the default answers.

 To exit the SETUP program at any time without saving default answers, press
 CTRL+C.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 The SETUP program doesn't erase any files from the distribution disks. If
 you make a mistake during the setup process, just run SETUP again.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 First Screen: Installing Libraries

 On the first SETUP screen (see Figure 2.2), you supply information SETUP
 uses to build run-time library files on your hard disk.

 (This figure may be found in the printed book).


 Selecting the Operating Mode

 Microsoft C can run under both OS/2 and DOS, and it can create executable
 files for either environment. Select the host operating mode under which
 your computer will usually run. Applications intended for OS/2 and DOS use
 different libraries. Specify the target operating mode for which you will
 most frequently be developing executable files. Both modes may optionally be
 selected.


 Building Combined Libraries

 SETUP can create combined libraries for the memory model, math options, and
 operating modes you specify. Combined libraries reduce the amount of time
 required for linking.

 The component libraries can be left on your hard disk after combined
 libraries are built. However, you should delete them to free disk space
 unless you plan to build additional combined libraries in the near future.

 You have the option of including the graphics libraries GRAPHICS.LIB and
 PGCHART.LIB in your combined libraries. GRAPHICS.LIB contains numerous
 functions for drawing lines, rectangles, circles, and other shapes.
 PGCHART.LIB contains functions for creating presentation-quality,
 high-resolution graphs. (Under OS/2 protected mode, you also have the option
 of including another library, GRTEXTP.LIB, in your combined library. This
 library provides support for OS/2 text-mode functions.) If you choose not to
 include these libraries in the combined libraries, they will be copied onto
 your disk as separate libraries. If you then use routines from these
 libraries, you will need to explicitly specify the libraries when you link.


 The first time you install Microsoft C, you should create only one or two
 combined libraries. If you need other memory models, math packages, or
 operating modes, rerun the SETUP program with the /L option.


 Choosing Math Options

 The math options you choose determine which math component libraries are
 included in your combined libraries. The default provided by SETUP depends
 on whether it detects a math coprocessor.

 Programs that use the 8087 library run only on a machine equipped with a
 math coprocessor. The 80x87 option generates applications that perform fast
 floating-point math.

 Programs linked with the emulator library will run on any computer, whether
 or not it has a coprocessor. If the computer has a coprocessor, the emulator
 library uses the coprocessor to perform all floating-point math operations.
 Otherwise, the library emulates a coprocessor.

 The alternate math library uses an alternate number representation; when a
 coprocessor is not present, programs using this library run faster than
 programs using the emulator. (Even if a coprocessor is installed, the
 alternate math library routines will not use it.) Selecting the alternate
 math library sacrifices some accuracy for increased execution speed and
 decreased program size.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 You may include all math libraries in your libraries, but doing so triples
 the number of combined libraries SETUP builds, thus tripling installation
 time and increasing storage requirements. If you intend to install all
 possible library configurations, you'll need approximately 6 megabytes of
 free space on your hard disk just for libraries. If you install just one
 library, you'll need about 3.3 megabytes.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 For more information on math options, see Chapter 4, "Controlling
 Floating-Point Math Operations," in Advanced Programming Techniques.


 Choosing Memory Models

 Microsoft C supports six standard memory models. Table 2.1 illustrates the
 relationship between the available memory models and the limits placed on
 their code and data segments.

 Table 2.1  Memory Models

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Memory Model  Code Segment Limit  Data Segment Limit
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Tiny          64K                 64K (CODE + DATA)

 Small         64K                 64K

 Medium        None                64K

 Memory Model  Code Segment Limit  Data Segment Limit
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Compact       64K                 None

 Large         None                None

 Huge          None                None

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 For more information on memory models, see Chapter 2, "Managing Memory," in
 Advanced Programming Techniques.


 Specifying Default Library Names

 SETUP normally gives each combined library a name of the form mLIBCfs.LIB,
 where m is S, M ,C, or L (memory model); f is A, E, or 7 (math library); and
 s is R or P (operating mode).

 This question will vary according to the target operating system you
 selected. If you chose OS/2, you will be asked whether to use the default
 OS/2 library names. If you selected both operating modes, you will be asked
 whether to use the default libraries for OS/2 and DOS.

 If you selected only one operating mode, or if you selected both but plan to
 program in one mode predominantly, you should have SETUP give default names
 to all libraries built for that mode.


 Second Screen: Installing Additional Files

 Your answers to questions on this screen determine whether PWB is installed
 (see Figure 2.3).

 (This figure may be found in the printed book).


 Installing PWB

 You may choose not to install PWB if you plan to use only the command-line
 version of the compiler and linker. If you install PWB, you can choose to
 configure the PWB editor so that it is similar to the BRIEF(R) editor.


 Installing the Microsoft Mouse

 If you have chosen OS/2 real mode and DOS as the host operating mode, you
 are asked whether you want to install the most recent version of the
 Microsoft Mouse device driver.


 Copying Patch Files

 If you have chosen OS/2 real mode and DOS as the host operating mode, you
 have the option of installing a patch for dealing with floating-point
 exceptions found under PC-DOS version 3.20.


 Third Screen: Specifying Directories

 On this screen, you specify the directories into which SETUP copies library,
 header, and other files (see Figure 2.4). You can choose to override the
 default options for directory names. Be sure to enter complete path names
 for your own directories. If the specified directories don't exist, SETUP
 asks whether you want to create them.

 (This figure may be found in the printed book).

 The questions about protected-mode executable files and dynamic link
 libraries appear only if OS/2 protected mode has been selected as the target
 operating mode.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 The questions about executable files concern the location of development
 tools, not the executable files you create with Microsoft C.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Checking Available Disk Space

 Before moving to stage two, SETUP checks your hard disk to see how much free
 space is available. If you don't have enough room to install Microsoft C, an
 error message informs you how much space is required for the files you've
 requested.

 If you don't have enough room on your hard disk, you can either delete
 existing hard-disk files or reduce the number of requested libraries.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 If you feel that SETUP has incorrectly sized your disk for some reason, you
 can disable space checking by using the /NOFREE option.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 SETUP Options

 SETUP has several options: /?, /COPY, /HELP, /LIB, /NOFREE, and /NOHELP.
 With the exception of /? and /HELP, you should not use any of the options
 the first time you run SETUP. The /? and /HELP options (see Figure 2.5)
 present information about the options.

 (This figure may be found in the printed book).

 The /COPY option uncompresses and copies individual files from the
 distribution disks. The /LIB option builds additional combined libraries
 after you have already installed Microsoft C, without going through the
 entire setup process. /NOFREE instructs SETUP not to check for available
 free disk space before uncompressing and copying files. The /NOHELP option
 suppresses the SETUP help information displayed at the bottom of the screen.



 Configuring Your System

 When SETUP has finished creating the combined libraries and placing them in
 the directories you specified, it creates files that are used for
 configuring your system.

 If you selected OS/2 real mode or DOS as the host environment, SETUP creates
 three files: NEW-VARS.BAT, NEW-CONF.SYS, and TOOLS.PRE. The files
 NEW-VARS.BAT and NEW-CONF.SYS are placed in the directory C:\C600\BIN; the
 file TOOLS.PRE is placed in the directory C:\C600\INIT. (These are the
 default directory names. If you have overridden them with your own choices,
 SETUP places these files in the directories you specified.)

 If you selected OS/2 protected mode as the host environment, SETUP creates
 two files: NEW-VARS.CMD and TOOLS.PRE. The file NEW-VARS.CMD is placed in
 the directory C:\C600\BINP; the file TOOLS.PRE is placed in the directory
 C:\C600\INIT. (These are the default directory names. If you have overridden
 them with your own choices, SETUP places these files in the directories you
 specified.)

 To permanently configure your system for Microsoft C, you must add the
 respective file contents to your AUTOEXEC.BAT (or STARTUP.CMD), CONFIG.SYS,
 and TOOLS.INI files, and reboot your system. You can, however, run
 NEW-VARS.BAT or NEW-VARS.CMD to set environment variables before you use
 Microsoft C.


 Changing AUTOEXEC.BAT or STARTUP.CMD

 The NEW-VARS.BAT and NEW-VARS.CMD files contain batch file commands that set
 environment variables. Insert these commands into the AUTOEXEC.BAT or
 STARTUP.CMD file. Table 2.2 describes the meaning of each variable.

 Table 2.2  Environment Variables

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Variable                          Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 PATH                              Path to search for applications

 LIB                               Location of run-time libraries

 INCLUDE                           Location of include (.H) files

 HELPFILES                         Location of help (.HLP) files

 INIT                              Location of initialization files

 Variable                          Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 TEMP                              Location of PWB/LINK temporary files

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Modifying CONFIG.SYS

 If the host operating mode is OS/2 real mode or DOS, be sure the  files  and
  buffer  values in CONFIG.SYS are large enough for Microsoft C. The values
 in NEW-CONF.SYS are minimums. The values in CONFIG.SYS should be greater
 than or equal to these amounts. Additionally, with OS/2, make sure the
 LIBPATH=  line of the CONFIG.SYS file specifies the location of the file
 MSHELP.DLL. OS/2 users who want to use the CodeView debugger must also
 include the statement  IOPL=YES.

 To use the extended memory features of CodeView under DOS, set
 DEVICE=HIMEM.SYS  (with HIMEM's fully qualified path name). See the section
 in this chapter titled "Configuring Extended Memory for CodeView" for
 additional information on running CodeView with extended memory in a DOS
 environment.


 Modifying TOOLS.INI

 SETUP creates a file called TOOLS.PRE. This file contains various PWB
 settings, such as those that specify libraries. You should add the contents
 of the TOOLS.PRE file to your existing TOOLS.INI file; if TOOLS.INI does not
 exist, you should rename TOOLS.PRE to TOOLS.INI.

 The TOOLS.INI file contains many configuration options, which help you
 customize the following utilities in Microsoft C:


   þ   PWB

   þ   The CodeView debugger

   þ   The Microsoft Advisor help system

   þ   The NMAKE utility


 You can use the PWB editor or a word processor to change the settings in the
 TOOLS.INI file. These are some of the options you can change:


   þ   The colors and the number of lines displayed by CodeView and PWB

   þ   Macros for PWB

   þ   Key assignments for PWB

   þ   Default key settings for PWB

   þ   The location of help files used by the Microsoft Advisor

   þ   Options for NMAKE


 A complete table of TOOLS.INI settings is available in on-line help and the
 C Reference.


 Choosing a Target Operating Environment

 In many cases you will program primarily for either the OS/2 protected mode
 or the DOS 3.x - OS/2 real mode and use one combined library. Allowing SETUP
 to make either DOS or OS/2 the default environment is the easiest method,
 but you can also manually choose a target environment.


 Choosing Defaults for a Single Mode

 Start by deciding which operating mode will be the default environment. Then
 give the combined library for that mode the default combined-library name.
 The composition of library names is explained in the section "Specifying
 Default Library Names."

 For example, the following steps will create a protected-mode executable
 file using the small memory model and the emulation floating-point library:



   1.  Use SETUP to create SLIBCEP.LIB, the combined library for the small
       memory model, floating-point emulation, and protected mode.

   2.  Rename SLIBCEP.LIB as SLIBCE.LIB (the same name without P), the
       default combined library name for the small memory model and
       floating-point emulation library.


 At this point you can use PWB or invoke the command-line compiler, CL,
 without specifying the target operating environment for your application.
 (In this example, you still need to supply the appropriate PWB or CL options
 to select a memory model and floating point options.) If you don't specify a
 memory-model option or floating-point option on the command line, the linker
 links SLIBCE.LIB, creating an executable file that runs in OS/2 protected
 mode.

 The same general procedure works for real mode, other memory models, and
 floating-point libraries: Create the appropriate operating mode and combined
 library, and give it the appropriate default combined-library name.


 Selecting a Mode at Compile Time

 If you need the flexibility of programming for both operating modes, you
 should use SETUP to create the combined libraries that you need for each
 model. Once you have created the combined libraries, you can select a model
 either by using the PWB options found in the C Compiler Options dialog box
 or the CL options listed in Table 2.3.

 Table 2.3  Operating Environment Options

ÖÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Option  Environment                                         Library Selected
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 /Lp     OS/2 protected mode                                 mLIBCfP.LIB

 /Lr     DOS 3.x - OS/2 real mode                            mLIBCfR.LIB

 Option  Environment                                         Library Selected
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 /Lc     DOS 3.x (synonym for /Lr)                           mLIBCfR.LIB

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Using these options causes CL to substitute one of these library names for
 the default combined-library name in the object module's library-search
 record.

 These options automatically set the /NODEFAULTLIBRARYSEARCH linker option,
 which overrides the default library (the syntax is /NOD:libraryname). For
 example, if you are programming for the OS/2 protected mode with the small
 memory model and floating-point emulation, and you supply the /Lp option for
 CL, the compiler passes the following option to the linker:

   /NOD:slibce slibcep


 Configuring Extended Memory for CodeView

 Extended memory refers to memory at physical addresses above 1 megabyte that
 can be accessed by an 80x86 CPU in protected mode.

 As previously mentioned, in order to use the extended memory features of
 CodeView under a DOS environment, you must set  DEVICE=HIMEM.SYS  (with
 HIMEM's fully qualified path name) in the CONFIG.SYS file. A sample entry of
 how to implement HIMEM is found in the NEW-CONF.SYS file that SETUP creates.


 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 HIMEM.SYS is an implementation of the XMS 2.x standard. The complete XMS
 source and specification are available from the Microsoft Information
 Center; call 1-800-426-9400.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 In addition, there are several factors to consider when using CodeView under
 DOS with extended memory:


   þ   At least 384K of extended memory should be set aside for use with
       HIMEM.SYS.

   þ   Other memory managers such as 386-Max(tm) or QEMM may not work in
       conjunction with HIMEM.SYS. You should use only one memory manager.

   þ   Older versions of HIMEM.SYS may present problems. Use the most recent
       version included on the distribution disks.

   þ   Many RAM disk (VDISK) and disk cache programs are incompatible with
       HIMEM.SYS. The HIMEM.SYS compatible RAMDRIVE RAM disk and SMARTDRV
       disk cache programs are provided on the distribution disks. If you are
       operating under Microsoft Windows(tm) , the SMARTDRV application
       shipped with the Professional Development System is incompatible with
       Windows 2.11, and is compatible only with Windows 3.0.

   þ   Check the documentation of installed terminate-and-stay-resident (TSR)
       programs to see if they are compatible with HIMEM/XMS 2.x. You can
       incrementally install each TSR until you find a potential offender.


 If you choose to install the HIMEM, RAMDRIVE, and SMARTDRV files, SETUP
 places them in the C:\C600\BIN directory.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 Extended memory should not be confused with expanded memory. Expanded memory
 refers to bank-switched memory that overcomes the 640K RAM limitation found
 in the 8088 processor.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Customizing Microsoft C

 In addition to modifying the TOOLS.INI file, Microsoft C can be customized
 in other ways. For example, a variety of editor functions and options can be
 set within PWB by using the Editor Settings command on the Options menu.

 For more information about customizing PWB, refer to Chapter 3 or see
 Chapter 8, "Customizing the Microsoft Programmer's WorkBench," in Advanced
 Programming Techniques. More information about customizing NMAKE and other
 utilities can also be found in Advanced Programming Techniques.






 Chapter 3  Using the Programmer's WorkBench
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 This chapter introduces the Programmer's WorkBench (PWB)Äa powerful
 integrated tool designed to make writing and debugging programs easier. PWB
 is a window-oriented programming environment that incorporates a text
 editor, a compiler, a linker, a debugger, a Make utility, a source-code
 browser, and an on-line help database. PWB provides an alternative to
 switching between command-linebased programs: You can edit, compile, link
 and debug from within an integrated environment. To demonstrate various
 features of PWB, this chapter provides a sample program for you to compile,
 link, and debug.

 This chapter explains how to start PWB and then introduces the following
 elements of PWB:


   þ   Windows and menus. You can quickly find the command you need with the
       menu system. The section "Using Windows and Menus" explains how to
       open and close windows and how to navigate through the menus.

   þ   Programmer's editor. Features such as "bookmarks," macros, customized
       key commands, and enhanced search capabilities decrease the amount of
       time you spend writing code.

   þ   Integrated compiler and linker. You can compile, link, and run a
       program without ever leaving the editor. PWB's integrated environment
       and project-management facilities save you hours of development time.

   þ   Integrated browser and debugger. With the Source Browser, you can
       quickly find a data declaration or function definition within your
       source code, and find references to all functions and variables in a
       multi-module program. With the CodeView debugger, you can set
       breakpoints, examine variables and machine registers, and step through
       execution of your program one line at a time.



 Starting PWB

 To run PWB for the first time, type

   PWB

 at the command line. (If errors occur, PWB displays error messages. See the
 README.DOC file for further information.)

 You can immediately begin writing source code in the new, untitled window
 that appears. PWB maintains a history of the files you have opened. The next
 time you run PWB, it opens the last file you worked on.


 Specifying a Source File

 You can open an existing source file by entering its name on the command
 line after the PWB command. If PWB can't find the specified file in the
 current directory, it asks if you want to create a new file. You can also
 open an existing source file with the Open command in the File menu.


 Command-Line Options

 PWB has several command-line options that you can issue when you start the
 program.

 Option                            Action
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 /e string                         The string represents a series of PWB
                                   commands that will be executed at
                                   start-up.

 /t file                           Indicates the specified file is
                                   temporary, and should not be kept in the
                                   file history. You must precede the name
                                   of each temporary file with a /t.

 /D                                Prevents all PWB initialization and
                                   status files from being read at
                                   start-up.

 /DS                               Prevents the CURRENT.STS file from being
                                   read.

 /DT                               Prevents the TOOLS.INI file from being
                                   read at
                                   start-up.

 /r                                Turns on the global "no-edit mode,"
                                   which gives all files opened with PWB
                                   Read Only status.

 /m bookmark                       Positions the cursor at the file
                                   location designated by bookmark.

 /?                                Lists the command-line options for
                                   starting up PWB.


 Using Windows and Menus

 This section introduces the PWB environment and describes how to control
 windows and choose commands from the menus. Terms used to describe elements
 of the PWB environment are also presented.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 You can enter commands in PWB with the keyboard or a Microsoft (or fully
 compatible) Mouse. Unless the Right mouse button is specifically mentioned,
 "clicking" means that you press and release the Left mouse button once.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Windows

 Figure 3.1 shows parts of a typical PWB screen. Some of the elements provide
 information only. For example, if CAPS LOCK is on, the letter  C  appears in
 the lower right corner of the screen; the letter  C  is informational. Other
 parts perform actions triggered by a specific keystroke or mouse action. For
 example, if you click the button in the upper left corner of a window, the
 window closes. The button is active rather than informational.

 (This figure may be found in the printed book).

 The parts of a PWB screen and their use are listed in Table 3.1 below.

 Table 3.1  Parts of a PWB Screen

ÖÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
 Name                  Use
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Menu bar              Lists names of available menus.

 Close button          Closes window (appears only if more than one window
                       is displayed).

 Name                  Use
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Title bar             Shows name of file currently being edited.

 Windows               Contain source code or display information
                       associated with on-line help.

 Maximize button       Enlarges or restores window to its original size.

 Screen number         Indicates number of help screen in the on-line help
                       database.

 Scroll bars           Indicate cursor position in the current file and
                       allow cursor movement.

 Reference bar         Lists shortcut keystrokes (keyboard users) and
                       directs PWB commands (mouse users); summar izes menu
                       contents and displays other information.

 File-type indicator   Indicates type of file. C: C source. text: any other
 Name                  Use
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
File-type indicator   Indicates type of file. C: C source. text: any other
                       user-created file. pseudo: file-like means of
                       displaying data.

 Line and column       Shows current line and column of text cursor.
 indicators

 Status indicators     A: Meta condition is on.
                       B: Background compile in OS/2.
                       C: CAPS LOCK is on.
                       L: A CR isn't used to terminate a line.
                       M: File has been modified.
                       N: NUM LOCK is on.
                       O: Overtype is on.
                       R: The file is set to Read Only status.
                       T: File is temporary.
                       X: A macro is recording.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Name                  Use
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 Menus

 The menu bar contains seven or more menus which can be accessed at any time.
 A brief description of the selected menu command is displayed in the
 reference bar. To get further information about what a menu does, invoke the
 on-line help system by using the ALT and ARROW keys to highlight a menu
 title or menu command, then press F1; or point the mouse cursor at the menu
 command and click the Right mouse button.

 PWB has the following menus:

 (Please refer to the printed      The File menu allows you to clear the
 book)                             Source window, load an existing source
                                   file, merge a file with the file in
                                   memory, display the next file in the
                                   file list specified at start-up, save
                                   the current file, save the current file
                                   under a different name, print the
                                   selection or current file contents,
                                   temporarily exit to DOS or OS/2, or
                                   permanently exit PWB. Additionally, a
                                   list of recently opened source files is
                                   displayed at the bottom of the menu.

 (Please refer to the printed      The Edit menu allows you to delete, cut,
 book)                             copy, and paste text. Anchors can be set
                                   in the text as reference points for
                                   selection. Box, stream, and line mode
                                   determine how text will be selected with
                                   the cursor. Read Only status protects
                                   source files. Commands to record, play,
                                   and edit recorded macros are also
                                   available in this menu. These items are
                                   discussed further in the section "Using
                                   the Editor."

 (Please refer to the printed      The View menu controls the active
 book)                             window. A window can be closed, sized,
                                   and split vertically or horizontally
                                   with the menu commands.

 (Please refer to the printed      The Search menu invokes commands that
 book)                             find or change text in source files.
                                   Commands to search the source file for
                                   compilation errors are also available.
                                   Commonly accessed text can be identified
                                   with "bookmarks." Once a bookmark is
                                   associated with a certain position in
                                   the source file, the Go To Mark command
                                   moves the cursor to that location.

 (Please refer to the printed      The Make menu is used for compiling or
 book)                             building (to "build" means to compile
                                   and link) programs. From this menu, you
                                   also create or edit program lists, which
                                   name the components of multi-module
                                   programs.

 (Please refer to the printed      The Run menu is used to execute your
 book)                             compiled program. Compiled programs can
                                   be debugged with CodeView using the
                                   Debug command. The Run menu also has
                                   options for issuing DOS or OS/2 commands
                                   and adding applications as PWB menu
                                   items (for example, the Customize Menu
                                   command).

 (Please refer to the printed      The items in the Options menu control
 book)                             the integrated environment. The
                                   Environment command temporarily changes
                                   path names for libraries, include files,
                                   and help files. Both Key Assignments and
                                   Editor Settings customize the operation
                                   of the PWB editor. The Build Options
                                   command saves current build options,
                                   determines what type of program will be
                                   built (OS/2, DOS) with the Initial Build
                                   option, and specifies whether the
                                   program is built as a debug or release
                                   version. The Browse, C Compiler,
                                   CodeView, LINK, and NMAKE commands
                                   configure their respective applications.

 (Please refer to the printed      The commands in the optional Browse menu
 book)                             are used to scan through data
                                   declarations and functions once a
                                   program has been compiled. Program call
                                   trees, references to variables, and
                                   symbol relationships can be shown in the
                                   Browser window. Menu items are disabled
                                   unless you have compiled your program
                                   with options that generate a Browser
                                   database.

 (Please refer to the printed      The optional Help menu accesses the
 book)                             on-line reference system. For more
                                   information, see Chapter 4, "Using the
                                   On-Line Reference."


 Choosing Menu Commands

 Choose a command from a menu by "pulling down" or "opening" the menu.

 To choose a 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),
       or use the right and left ARROW keys to select a menu. The left and
       right ARROW keys only select the menu; they do not open it.

   3.  Press the highlighted character in the command name (such as S for
       Save in the File menu), or use the up and down ARROW keys to highlight
       the command and then press ENTER.


 To choose a command with the mouse:


   1.  Open the menu by clicking the menu name.

   2.  Click the command.



 Closing Menus

 If you open a menu and then decide you don't want to issue a command, you
 can close the menu in any of these ways:


   þ   Press the ESC key

   þ   Click the mouse somewhere outside of the menu

   þ   Press ALT twice



 Using Shortcut Keys

 Certain menu items are followed by the names of keys or key combinations.
 These are "shortcut keys" for commonly used commands. Instead of issuing a
 command by opening a menu, press the shortcut key to issue the command.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 The reference bar at the bottom of the screen displays common shortcut keys.
 You can click any of these buttons to execute the indicated command.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Shaded Commands

 When a command within a menu is in grayed type, it is "disabled," or
 unavailable for use; some condition prevents the command from being used.
 For example, when PWB is first run, and no programs have been compiled or
 linked, the Next Error and Previous Error commands in the Search menu are
 both disabled.


 Ellipses

 If a command is followed by three periods (an ellipsis), it means more
 information must be provided before the command is executed. You provide
 this information in a dialog box that appears when you issue the command. If
 a command is not followed by an ellipsis, it is executed immediately.


 Dialog Boxes

 Some menu commands cause dialog boxes to appear. For example, Figure 3.2
 shows the dialog box opened by the Search menu's Find command.

 (This figure may be found in the printed book).

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 Dialog boxes usually offer shortcut keys. Shortcut keys are identified by
 highlighted letters, and can be activated by pressing the corresponding key.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Dialog boxes can contain one or more of the items in the following list.
 Press ALT and the item's highlighted letter or press the TAB or SHIFT+TAB
 keys to move among items in a dialog box. Dialog items can be set either
 with keyboard commands or with the mouse.

 Item                              Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Option buttons ()                 Offer a list of choices; only one option
                                   can be chosen. Use the ARROW keys to
                                   move between the choices. In Figure 3.2,
                                   three option buttons set the direction
                                   of the search (Forward, Backward, Find
                                   All).

 Check box [X]                     A yes/no switch. If the box is empty,
                                   the option is turned off. If it contains
                                   the letter X, the feature is on. Press
                                   the SPACEBAR or use the up and down
                                   ARROW keys to turn a check box on or
                                   off.

 Text box [. . . . .]              Accepts text that you enter. In Figure
                                   3.2, Find Text requires you to type in
                                   the text to search for.

 Command buttons                   Pass commands to the dialog box
 < OK >                            (enclosed in angle brackets). The OK
                                   button means to use the current
                                   settings. The Cancel button exits the
                                   dialog box and does not change the
                                   current settings. If one of the command
                                   buttons is highlighted, press ENTER to
                                   execute that command. Clicking a command
                                   button also executes it. If a button
                                   contains an ellipsis, it indicates that
                                   another dialog box will appear when the
                                   command is carried out.

 List boxes                        Display lists of information, such as
                                   the contents of the current disk
                                   directory, inside a list box. If the
                                   number of items exceeds the list box
                                   space, press the ARROW keys and
                                   PGUP/PGDN or click the scroll bar to
                                   move around the list.


 Getting Help

 PWB uses the Microsoft Advisor on-line help system to provide information
 about PWB, the compiler, the linker, the CodeView debugger, other utilities,
 and topics relating to the C language. Information can be displayed at any
 time and at any point you're using PWB or CodeView. For a complete
 discussion of the on-line reference, see Chapter 4.


 Menu Help

 To get information about a PWB menu command, choose the command with the
 ARROW key, then press F1; or point the mouse cursor at the menu command and
 click with the Right mouse button. A help window then appears with
 information about the command.


 Dialog-Box Help

 Many dialog boxes have a help button that provides additional information
 about the dialog box and its contents. To display the information, click the
 Help button with the mouse or press F1.


 The Help Menu

 You can also use the commands listed in the Help menu to display an index of
 all help topics, a table of contents, and information about using the
 on-line reference system itself.

 Choose the Contents command to display a global contents screen for the
 entire help system. The main contents lists information divided by topic,
 such as PWB, CodeView, or the C language. From the main contents, you can
 navigate to a selected topic's table of contents by clicking that topic.

 Choose the Index command to display a main index where you can move to other
 indexes for different components of the Microsoft C help database.


 Using the Editor

 The program editor is an important part of the PWB environment. This section
 provides a brief overview of its major functions, and assumes you are using
 the default key assignments.


 Moving Around in a Source File

 Many of the keys within the editor work as you would expect them to. For
 example:


   þ   The PGDN and PGUP keys advance forward or back within the file.

   þ   The HOME key moves the cursor to the beginning of the current line.

   þ   The END key moves the cursor to the end of the current line.

   þ   The ARROW keys move the cursor one character or one line at a time.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 For a complete list of editor commands, refer to the on-line help system's
 PWB Function Quick Reference section on the PWB global contents screen.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ




 If you click in the shaded area on either side of the scroll box (position
 marker) in the scroll bar, you move the cursor one full window at a time in
 that direction. If you click on the scroll-bar arrows, you move the cursor
 one row or column in the corresponding direction. If you click and drag the
 scroll box, you move the cursor to the corresponding position within the
 file.


 Defining a Block

 To define a block with the PWB editor using the keyboard:


   1.  Move the cursor to the beginning of the block.

   2.  Hold down the SHIFT key and move the cursor to the end of the block.

   3.  Use the other cursor keys (HOME, END, CTRL+RIGHT, and so on) while
       you're holding down SHIFT to extend the block.


 To define a block with the PWB editor using the mouse:


   1.  Move the cursor to the beginning of the block.

   2.  While holding down the left button, move to the end of the block.


 Once a block has been defined, it can be erased (press DEL), or placed into
 the Clipboard, a temporary buffer, by cutting (press SHIFT+DEL) or by
 copying (press CTRL+INS). Once in the Clipboard, the block can be inserted
 at a cursor location (press SHIFT+INS). While a block is defined, anything
 you type will delete the highlighted block and then insert the typed
 characters.

 Three text-selection modes are available in the Edit menu:


   1.  Box mode selects text in a rectangular area whose opposite corners are
       the starting and ending cursor positions.

   2.  Line mode selects entire lines of text from the starting cursor
       position to the ending cursor position.

   3.  Stream mode selects all text from the starting cursor position to the
       ending cursor location.


 Selecting a mode from the Edit menu changes the menu item to a new mode. The
 mode displayed in the menu is the next available text-selection mode.

 You can also toggle through the selection modes during text selection by
 clicking the Right mouse button while you hold down the Left mouse button.


 Setting Bookmarks

 You can set bookmarks anywhere in your source code with the Define Mark
 command in the Search menu. Move the cursor to the location you want to
 mark, then choose Define Mark.

 In the dialog box that appears, type the name you want to give the bookmark.
 The source file name and the row and column are already entered. Press ENTER
 to save the bookmark for the current session. To permanently save a
 bookmark, you must use the Add To Mark File option. Permanent bookmarks can
 be loaded with the Set Mark File command in the Search menu.

 To move the cursor to a bookmark, choose the Go To Mark command from the
 Search menu. A list of all bookmarks is displayed. Select the bookmark from
 the list using the ARROW keys or click the selected bookmark with the Left
 mouse button. Press ENTER to go to the bookmark.


 Setting Anchors

 An anchor is a temporary marker that identifies a cursor position somewhere
 in the text. Use anchors to select large blocks of text.

 To set an anchor, move the cursor to the desired location and use the Set
 Anchor command in the Edit menu. Use the Select To Anchor command in the
 Edit menu to select all text between the current cursor position and the
 anchor. Only one anchor may be set at a time.


 Searching for and Changing Text

 You can search for a string of text by using the Find command in the Search
 menu. Type the string you want to look for, then use the check boxes to set
 options such as wraparound search and case sensitivity. The Files button
 allows you to specify a list of files to be searched for the designated
 string.

 Once a string has been located, use the Repeat Last Find command in the
 Search menu (or press the shortcut key, F3) to move to the next occurrence
 of the string. If you specified several files to search, press SHIFT+F3 to
 move to the next occurrence of the string.

 To modify several instances of a string in the source file, use the Change
 command in the Search menu. Enter the target string, the replacement string,
 and the search options.

 PWB also supports the search and replace of text patterns using regular
 expressions. Both UNIX(R) and non-UNIX regular expression syntaxes are
 supported. For further information, see the on-line reference system.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 Multi-file searches run a built-in GREP facility, and text that is found may
 be scanned with the Next Error and Previous Error commands.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Creating Macros

 Editing tasks that you perform frequently can be saved as macros. A macro is
 the record of a sequence of commands and/or literal text. Each macro has a
 key combination that is used to "play back" the recorded actions.

 For example, suppose several programmers are working on a file and need to
 keep track of who made what changes. A macro can be used to insert a comment
 with the programmer's name.

 To create such a macro, choose the Set Record command in the Edit menu and
 enter a macro name and associated key combination. For this example, call
 the macro  modname  and let the key combination be CTRL+J. (Any key
 combination can be used for a macro.) After you've named the macro, choose
 the Record On command from the Edit menu. A bullet will appear to the left
 of the menu command and an X in the status line, indicating all keystrokes
 and menu commands are being recorded. Then type the following:

   /* j. courtney coded this */

 To stop the recording, choose Record On once again, which causes the bullet
 to disappear. This action associates all the recorded actions with the
 previously selected macro. Now, each time you press the CTRL+J key
 combination for the macro, the comment you typed is instantly inserted at
 the cursor position.

 You save macros to the TOOLS.INI file when you save the <record> pseudofile
 which can be reached by the Edit Macro command in the Edit menu. They may be
 changed or deleted by modifying the file. See the section "Customizing PWB"
 in on-line help for additional information about macros.


 Customizing the Editor

 You can customize the PWB editor to meet your needs. Editor settings can be
 modified, keyboard commands can be assigned, and command sets from other
 editors can be emulated. In addition, customized extensions to the editor
 can be written in C. See the on-line reference system and Chapter 8,
 "Customizing PWB," in Advanced Programming Techniques, for complete details.



 Changing Editor Settings

 The PWB editor has a variety of settings you can customize, such as word
 wrap, color, and width of tab stops.

 View or modify the settings by choosing the Editor Settings command from the
 Options menu. A pseudofile named <assign> appears. (The title bar says
 "Current Assignments and Settings," but the name <assign> appears in the
 File menu's list of files.) This file displays numerous editor settings in
 the format setting:value, where setting is the name of the setting, and
 value is a Boolean, numeric, or text value. You can learn about a setting by
 positioning the cursor on it and pressing F1.

 To change the value of a setting, enter a new value. The change does not
 take effect until you move the cursor to a different line. To save the
 changed assignments, press SHIFT+F2 (if the default keyboard assignments are
 in effect) or choose the Save command in the File menu. If you do not save,
 the assignments will be temporary and will last only for the duration of the
 PWB session.

 To return to your source file, press F2.


 Modifying Keyboard Assignments

 You can easily change all PWB keyboard assignments. Functions such as
 delete, home, and copy can be reassigned by choosing the Key Assignments
 command from the Options menu.

 A pseudofile named <assign> appears. (The title bar says "Current
 Assignments and Settings," but the name <assign> appears in the File menu's
 list of files.) This file lists PWB functions and the keys to which they are
 assigned. These appear in the format function:keyname. You can learn about a
 PWB function by positioning the cursor on the function name and pressing F1.
 A list of unused keys follows the assignment list.

 To assign a new key to a function, replace keyname with the name of the new
 key. The change does not take effect until you move the cursor to a
 different line.

 When you move the cursor to a different line, the line with the new
 assignment is highlighted. To make the assignment permanent, save the file
 by pressing SHIFT+F2 or by choosing the Save command in the File menu. This
 updates the TOOLS.INI file, where changes to key assignments are stored.

 To remove a key from a given function, assign the unassigned function to the
 key.


 Using Advanced Editor Features

 Most of the standard editing features in PWB are intuitive and easy to use.
 However, there are also many advanced editing options that allow you to
 customize and control the editor beyond simple menu commands.

 The PWB editor incorporates all of the powerful features found in the
 Microsoft Editor. A variety of functions and switches can be set to further
 customize the PWB editor and enhance its performance. A complete list of
 editor functions and settings is available in the on-line reference system.


 New or altered functions and settings can be added to the TOOLS.INI file so
 they are immediately loaded when PWB starts up. Or, they can be
 interactively entered while you are working in the PWB environment.

 For example, to interactively assign a key command to the editor's curdate
 function, which enters the current date at the cursor, first press ALT+A,
 then type the following into the argument dialog box:

   Curdate:SHIFT+CTRL+T

 Press ALT+= to assign the key to the function.

 Now, whenever you press SHIFT+CTRL+T, the current date will instantly be
 inserted at the editor's cursor position.

 For detailed information about advanced PWB editor features, refer to the
 Microsoft C Reference and the on-line reference system.


 Reconfiguring the Editor

 If you wish to use another set of editing commands, PWB comes with an
 additional .INI file containing key assignments for the BRIEF editor. You
 can add the contents of the file to TOOLS.INI, or you can simulate other
 editors' command sets by using the customization techniques previously
 described.


 Using Another Editor

 If you prefer to use another word processor or text editor, choose the Run
 menu's Customize Menu command. This command is used to add other programs
 (including word processors) to the Run menu so that you can run them from
 within the PWB environment. Through the dialog box you can specify directory
 paths and arguments to pass, and assign a key-command equivalent to run the
 editor. When you exit the program, you return to PWB.


 Compiling and Linking

 PWB uses a project-oriented approach to compiling and linking programs.
 After a source file has been created and a program list associated with it,
 PWB produces a makefile. A "program list" is a list of all of the source
 files that make up the program; the "makefile" contains information about
 the source files that compose the project. Whenever a multi-module program
 is compiled or linked, the NMAKE utility examines the makefile and
 determines which part of the project will be affected.

 The process of creating an executable file by compiling and linking is known
 as "building." When you build an application, the source code is first
 compiled on a module-by-module basis into .OBJ files, and then linked with
 the appropriate libraries.

 Makefiles are especially useful with multi-module programs, because only
 those source files that have changed are recompiled. This results in faster
 build times, since existing source files that haven't been changed are not
 recompiled. After you set a program list, building is a one-step process in
 PWB.


 Building Programs in PWB

 This section illustrates how to build programs under the PWB environment. To
 start, type in this sample program:

   /* IO.C: String input and output */

   #include <stdio.h>

   main()
   {
      char date[30];

      printf( "Enter today's date: \n" );
      gets( date );
      printf( "Sample program run on %s\n", date );
   }

 This simple program uses the  printf  and  gets  library functions to prompt
 for, and then print, today's date.


 Saving the Program

 To save the source file, pull down the File menu and choose either Save or
 Save As. If the file is new or you choose Save As, a dialog box prompts you
 for a file name (see Figure 3.3). If you choose Save with an existing file,
 PWB automatically saves the file under the name listed in the title bar of
 the source window. To save a copy of a file under a different name, choose
 Save As.

 (This figure may be found in the printed book).

 Type in the new name of the source file, IO.C.


 Setting and Clearing the Program List

 The Set Program List command in the Make menu tells PWB which makefile to
 use in building a program. It clears the current makefile setting, instructs
 PWB to use the makefile you have specified, and specifies which Browser
 (.BSC) file is associated with the current project.

 After you have saved the source file IO.C, choose the Set Program List
 command in the Make menu. In the dialog box that appears, type the base file
 name (IO), then press ENTER (see Figure 3.4). PWB automatically provides a
 .MAK extension.

 (This figure may be found in the printed book).

 If the makefile does not exist, PWB asks if you want to create a new
 makefile; answer yes to this dialog box. Another dialog box titled Edit
 Program List appears, listing all files in the current directory. From the
 list, select the files you want to include in the project (in this example,
 just IO.C).

 Press TAB until the cursor is within the list box containing the directory
 of files (another box lists the directory names). Use the ARROW keys to move
 to the IO.C file. Press ENTER and the file name appears in the program list
 below. Once the file is selected, press TAB until the Save List command
 button is highlighted, and then press ENTER.

 If you have a mouse, click IO.C once and then click the Add/Delete button
 (or just double-click IO.C). Once the file appears in the program list,
 click the Save List command button to save the makefile.

 PWB automatically determines the contents of the makefile based on the files
 you selected. You can edit the .MAK text file to change or add additional
 commands.

 If you want to create a new program or instruct PWB to "forget" about the
 current program, use the Clear Program List command in the Make menu. This
 action clears the current program list setting. You can then specify a new
 program to build with Set Program List.


 Setting Build Options

 Before compiling the program, you must specify the type of program you will
 be building. This is done with the Build Options command in the Options
 menu. Build Options calls a dialog box, whose Set Initial Build Options
 button presents a series of predefined compiler settings for creating
 programs (such as bound EXE, DOS EXE, DOS COM) and OS/2 .DLL libraries. Once
 an initial build option has been chosen, its settings can be changed with
 the C Compiler Options command in the Options menu.

 To specify an existing build option:


   1.  Choose the Build Options command from the Options menu

   2.  Select the Set Initial Build Options button

   3.  Use the mouse or the ARROW keys to select a build option from the list
       and press ENTER


 To save your own group of build option settings:


   1.  Select the appropriate settings in the C Compiler Options dialog box

   2.  Choose the Build Options command from the Options menu

   3.  Select the Save Current Build Options button

   4.  Type a description of the options and press ENTER


 The settings are now available through the Set Initial Build Options dialog
 box.


 Compiling and Linking the Program

 You can set a variety of compiler directives in the Options menu. The C
 Compiler Options command provides options for memory model, processor type,
 and other global settings that affect overall compilation (see Figure 3.5).


 (This figure may be found in the printed book).

 From within the C Compiler Options dialog box, you can use the Set Debug
 Options and Set Release Options buttons to easily create debug and release
 versions of your program.

 When you select the Set Debug Options button, a dialog box appears in which
 you can set parameters such as stack checking, optimization, and debug
 information. These settings also apply to programs built with the Debug
 Build option, which you select from the dialog box displayed by the Build
 Options command. Use debug settings when you are in the development phase
 and actively debugging your program. When the Release Build option is
 checked in the Build Options dialog box, the parameters specified in the Set
 Release Options dialog box apply.

 Similar debug and release options are also available for the linker with the
 LINK Options command in the Options menu (see Figure 3.6). You can display
 the options in both the C Compiler Options and LINK Options dialog boxes
 with the Show Debug Options and Show Release Options buttons.

 (This figure may be found in the printed book).

 The Set Release Options button in the C Compiler Options dialog box offers
 the same choices as Set Debug Options, but Set Release applies them to a
 final version of the program. Use these settings when your program is
 completely debugged and ready for release.

 For this example, use the default settings in the C Compiler Options dialog
 box.

 Before building the sample program, make sure that its name appears after
 the Compile File and Build commands in the Make menu. If the name does not
 appear after the Build command, choose the Set Program List command in the
 Make menu to set the makefile as the current project.

 To build the program, choose the Build command in the Make menu. If a
 compile or link error occurs, the build terminates, and the error appears in
 the Compile Results window. Use the on-line reference system to explain
 unknown errors by selecting the error and pressing F1. If you are using OS/2
 and errors occur, you will be informed and asked if you want to see the
 compile log.


 Running the Program

 After the program has been built, the name of your executable file is
 appended to the Execute command in the Run menu. Choose Execute to run the
 program. When the program is finished running, press any key to return to
 PWB.


 Building from Multiple Source Files

 You can build most applications from more than one source file. This section
 demonstrates how to create a multi-module program.

 First, edit the IO.C program:

   /* IO.C: Illustrates external functions */

   #include <stdio.h>

   void outsider(void); /* Add this function. */
   void sample(void);   /* Add this function. */

   main()
   {
      char date[30];

      sample();   /* Call new function. */
      outsider(); /* Call new function. */
      printf( "Enter today's date: \n" );
      gets( date );
      printf( "Sample program run on %s\n", date );
   }

   /* Implement the new sample function. */
   void sample(void)
   {
      printf( "A sample function.\n" );
   }

 The  main  function calls two new functions defined within the program:
 sample  and  outsider.

 Save the changed file and then choose New from the File menu. Type in a
 second source file:

   /* IOB.C: Second module for IO.C */

   #include <stdio.h>

   void outsider(void);

   void outsider(void)
   {
      printf( "This line is from the file IOB.C.\n" );
   }

 Save it as IOB.C. The two source files are combined to produce a
 multi-module program.


 Multiple Modules and the Program List

 Since the example program now uses two source files, the makefile must be
 changed to tell PWB which files should be compiled. Choose the Edit Program
 List command from the Make menu, add the IOB.C file to the list, and save
 it. When you create multimodule programs, the order of the file names added
 is inconsequential.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 A program list can include source files (with the .C extension), assembler
 files (.ASM), object files (.OBJ), library files (.LIB), definition files
 (.DEF), and resource files (.RC). For example, if you didn't include the
 graphics libraries in the combined library when you ran the SETUP program,
 you can place GRAPHICS.LIB in the program list to gain access to graphics
 functions under DOS.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 At this point you can compile and link the program.

 When you choose the Rebuild All command from the Make menu, every .C file in
 the program list is compiled into a .OBJ file. Then all of the .OBJ files
 are linked with .LIB files to create one .EXE file.

 If you choose the Build command, the NMAKE utility checks the time and date
 stamps on the source and object files. If the source code has not changed
 since the last time a Build command was executed, unchanged files are not
 recompiled. Consequently, the Build command is often faster than Rebuild
 All.


 Compiling and Linking from the Command Line

 You are not restricted to using the PWB environment to create executable
 programs. Programs can be compiled and linked with Microsoft C at the DOS or
 OS/2 command line.

 The CL.EXE program may be used to compile and link programs. PWB
 automatically executes CL, or you can manually execute it at the command
 line. Simply enter CL followed by a space and the name of the source file to
 create a .EXE program.

 In addition, a variety of command-line options can be used. For example,

   CL /AM IO.C

 causes the program to be compiled using the medium memory model instead of
 the default small model. Any compiler options should appear before the names
 of the files to be compiled.

 You can find a complete list of compiler and linker options in the C
 Reference or by typing

   CL /HELP

 to invoke the on-line reference system.

 You can also use CL to build multi-module programs by specifying all source
 files to be compiled:

   CL IO.C IOB.C

 This command builds a program called IO.EXE, because IO.C is listed first.

 Another way to build a multi-module program is to compile the two files and
 then manually link them:

   CL /c IO.C
   CL /c IOB.C
   LINK IO.OBJ IOB.OBJ

 The /c option instructs CL to compile but not link. Once the .OBJ files have
 been created, use the linker to create the executable file.

 Since a makefile named IO.MAK has already been created using PWB, you can
 also use the NMAKE utility to build IO.EXE. Simply pass it the name of the
 makefile:

   NMAKE /F IO.MAK

 If you don't provide /F and a file name, NMAKE searches for a file named
 MAKEFILE.

 For a complete list of compiler, linker, and NMAKE options, see Advanced
 Programming Techniques, the C Reference, or the on-line reference system.


 Debugging Programs

 PWB has a variety of resources available for debugging programs. They range
 from simple compile- and link-error messages to sophisticated source
 browsing and source- or assembly-level debugging.

 When compile-time errors occur, the cursor moves to the line that caused the
 first error and a brief description of the error appears in the reference
 bar. Use the Next Error and Previous Error commands in the Search menu to
 move the cursor to the lines where other errors occurred.

 To view a complete list of errors, choose the Compile Results command from
 the View menu. Use the Set Error command in the Search menu to select the
 error under the cursor as the current error. This command synchronizes the
 source and error windows so that the source-code line that contains the
 error appears in the source window.

 The Microsoft Advisor can be used to display on-line help about the error.
 In the Compile Results window, move the cursor to the error number and press
 F1.

 PWB incorporates a source-code browser and interfaces with the CodeView
 debugger. The Browser displays information about function and data
 relationships. CodeView is a window-oriented symbolic debugger that lets you
 step through your code and examine variables and data as the program
 executes.

 Before a program can take advantage of the Browser or CodeView, the
 appropriate debug or browse switches must be set with the C Compiler Options
 and Browse Options commands in the Options menu. As an example, build one of
 the sample programs previously listed with the debug options to experiment
 with the Browser and CodeView.


 Using the Browser

 The commands on the Browse menu are referred to collectively as the PWB
 Source Browser. These commands allow you to search a database comprising
 selected files, to get a list of references and definitions, build a call
 tree and outline, or create a list of relationships among program symbols.
 Figure 3.7 shows the functions called by  main  in IO.C.

 (This figure may be found in the printed book).

 Before using these commands, you must define the database the Source Browser
 is going to search.

 To define a database:


   1.  Generate a program list using the Set Program List command in the Make
       menu. The files contained in the program list make up the database.

   2.  Choose Browse Options from the Options menu. You must select the
       Generate Browse Information field in the dialog box to create the
       Source Browser database. The rest of the fields on this dialog box
       offer you choices of how to build the database; they are optional.

   3.  Build your program using the commands in the Make Menu. When you build
       the program, a file with the same program-list root name and a .BSC
       (Browser Source Cache) extension is created. This file contains
       reference information that the Browser uses.


 Once you have completed these steps, Browse Menu commands are ready for you
 to use.


   þ   The Goto Definition command provides a list of symbols and variables
       that occur within include files and modules. You can immediately open
       the file at the line number where the definition occurred by selecting
       the <OK> button.

   þ   The Goto Reference command displays a list of files and line numbers
       where  symbols and variables have been referenced in include files and
       modules.

   þ   The View Relationships command provides detailed information about
       various portions of your program. You can examine functions, macros,
       types, and variables by their use, definition, or inclusion in include
       files and modules.

   þ   The List References command displays references to functions, macros,
       types, and variables. You can move the cursor to a reference, and then
       use the Goto Definition or Goto Reference commands to show occurrences
       of the reference.

   þ   The Call Tree command displays a tree structure of function calls
       within the program.


 For additional information about the Browser, refer to the on-line reference
 system.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 You can create a Browser information file with the CL (command-line)
 compiler by using the /FR or /Fr options. This creates a .SBR file which can
 be converted to a .BSC file with the PWBRMAKE.EXE utility.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Debugging with CodeView

 PWB provides access to the Microsoft CodeView debugger. After a program has
 been built, CodeView can be used to step through the source code, displaying
 output, registers, and variables as each line is executed (see Figure 3.8).
 You can set breakpoints and watchpoints to further aid in debugging.
 CodeView uses the Microsoft Advisor to provide on-line help about its
 operation and options, in addition to information about any C keywords in
 the program you are debugging.

 (This figure may be found in the printed book).

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTES

 CodeView version 3.0 is compatible with releases of OS/2 later than version
 1.0. If you encounter problems exiting CodeView, you either have an older
 version of OS/2 or the wrong version of the DOSCALLS.DLL file.

 If you use CodeView from the OS/2 DOS compatibility box, be sure the /S
 (Swap Screen in Buffers) option is set in the CodeView Options dialog box.
 If the option is not set, the mouse cursor is not displayed while you are
 debugging.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Preparing a Debug Build

 It's easy to create a debug version of a program so it can be examined with
 CodeView.

 First, choose C Compiler Options from the Options menu, then select the Set
 Debug Options button. This dialog box contains a variety of settings for a
 debug build. Although most of the dialog box options can be set to your
 preference, you must check the CodeView option under the Debug Information
 heading, which is on by default. In addition, code optimization options,
 which are off by default, should be unchecked so that code movement does not
 affect debugging.

 The CodeView Options command in PWB's Options menu provides a variety of
 choices for configuring CodeView. These include two-monitor debugging,
 memory allocation, and the number of lines on the screen. For now, use the
 default settings initially displayed.

 In order for the compiler to build a program that contains the necessary
 CodeView information, you must check the Debug option, set in the dialog box
 displayed by the Build Options command in the Options menu. In addition, the
 CodeView option, which is on by default, must be selected in the Set Debug
 Options dialog box.

 To demonstrate how CodeView works, set the debug options as listed above,
 then rebuild the IO.C program using the Rebuild All command in the Make
 menu.


 Examining the Program

 After your program has been built with the appropriate debug options, choose
 the Debug command from the Run menu. PWB immediately transfers control to
 the CodeView debugger, loading the current project as indicated in the
 program list.

 When you switch from PWB to CodeView, the program appears in the source
 window. Choose the Source command in the Options menu or type the  S+
 command in CodeView's command window to display the code in C, the  S-
 command for assembly language, or the  S&  command for a combination of the
 two. With C or mixed-source options, a line number appears to the left of
 each line of source code as a reference.

 In addition to the source code, commands in the View menu show windows
 displaying memory, registers, and local variables. CodeView windows are
 similar to PWB windows in that they can be scrolled, sized, and closed.
 Multiple windows can appear on the screen at once, displaying a variety of
 information. A list of shortcut keys and buttons appears at the bottom of
 the screen.


 Setting Watch Expressions and Breakpoints

 Watch expressions and breakpoints are optional CodeView settings that
 display variable values and interrupt execution of the program.

 A "watch expression" is a variable within the program that CodeView
 continually watches. Watch expressions are displayed with the Watch command
 in the View menu. As the value of a variable changes, the value changes in
 the watch window.

 To add a variable to the watch expression list, select the variable and
 choose the Add Watch command from the Watch menu or use the W command in the
 command window. You can optionally enter the variable name in the dialog
 box. Watch expressions are removed with the Delete Watch command in the
 watch menu or with the Y command in the command window.

 To set a watch variable in the IO.C file, use the cursor to highlight the
 date  variable in the CodeView source window. Then choose the Add Watch
 command from the Watch menu. The  date  variable appears in the Expression
 text box. Press ENTER or click the OK button to store the watch variable.

 CodeView also incorporates a temporary watch option called a QuickWatch.
 Highlight a variable in the source window with the mouse or cursor. Choose
 the QuickWatch command from the Watch menu. A dialog box appears with the
 current value of the variable. You can add any QuickWatch variable to the
 watch window with the Add Watch dialog option.

 You can expand any structures or arrays that are set as watch expressions
 (identified with a "+" in the watch window) to show individual elements.
 Position the cursor on the variable name and either double-click the Left
 mouse button or press ENTER (see Figure 3.9).

 (This figure may be found in the printed book).

 A "breakpoint" is an instruction that tells CodeView to interrupt execution
 at a certain location or when an expression becomes true.

 Use breakpoints to gain control of the program before an error occurs and to
 quickly move to a part of the program you want to trace. When CodeView stops
 at a breakpoint, you can then single-step or trace through instructions
 until you find the problem.

 Set a breakpoint by positioning the cursor on the line at which you want the
 program to stop and then pressing F9. Alternatively, you can choose the Set
 Breakpoint command from the Watch menu. A dialog box presents a series of
 options for setting types of breakpoints. Breakpoints are modified or
 deleted with the Edit Breakpoints command in the Watch menu.

 Set a breakpoint in the IO.C file by moving the cursor in the CodeView
 source window to the line that reads

   printf( "A sample function.\n" );

 From the Watch menu, choose the Set Breakpoint command. The number of the
 line the cursor appears on is displayed in the dialog box. Press ENTER or
 click the OK button with the mouse to store the breakpoint. After the
 breakpoint has been set, the line it occurs on is highlighted.


 Running the Program

 CodeView runs your program and displays each source line as it executes. If
 an error occurs, CodeView stops at the instruction that caused the error.
 CodeView also halts execution at breakpoints.

 If a program requires arguments to be passed from the command line, these
 arguments can be entered with the Set Runtime Arguments command in the Run
 menu.

 Table 3.2 lists several CodeView commands for running a program.

 Table 3.2  CodeView Run Commands

ÖÚÄÄÄÄÄÚÄÄÄÄÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Key   Name    Use
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Key   Name    Use
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 F5    Go      Executes the program to the next breakpoint, error, or end of
               the program

 F8    Trace   Executes a single line

 F10   Step    Executes a single line, but doesn't trace into
               functions

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ



 Run commands can be entered by pressing the appropriate key or clicking the
 commands at the bottom of the screen. With the Trace and Step commands, each
 line is highlighted as it is executed. The Go command executes each line
 until it stops at an error, a breakpoint, or the end of the program. If you
 choose the Animate command, each line is highlighted as it executes. To
 force the run commands to start at the beginning of the program, use the
 Restart command in the Run menu.

 The Screen Swap setting in the Options menu controls display of the output.
 If the option is turned on, CodeView switches to the output screen after
 each line executes, and then switch back to the source window. You can turn
 the option off during portions of your program that don't access the screen
 to reduce the distracting flicker of switching screens. If you want to view
 the output screen longer, choose the Output command from the View menu.
 Press any key to exit the output screen and return to CodeView.

 In addition to single-stepping through a program, the Animate command in the
 Run menu automatically steps through the program, highlighting each line as
 it proceeds.


 Running IO.C

 To demonstrate some of these commands with the IO.C program, make the source
 window active by pressing F6 or by clicking its title bar, then choose the
 Restart command from the Run menu. This command clears memory and prepares
 the program to start execution at the first line of  main.

 Press F5 or select the Go button at the bottom of the screen to start the
 program. The program executes until it reaches the breakpoint set at the
 sample  function.

 Use F10 or the Step button to execute each statement until you come to the
 outsider  function. If you press F8 or the Trace button at the  outsider
 function, CodeView traces through each statement of the function. If you use
 the Step button or F10, CodeView executes the function without tracing
 through it and moves on to the next program statement.

 Continue stepping through the program until you reach the  gets ( date )
 statement. Press F10; CodeView switches to the output screen and prompts you
 to enter a date. Type today's date and press ENTER. CodeView regains control
 and moves to the next statement.

 Since  date  was set as a watch variable and now contains data, use the
 mouse or press F6 to make the watch window active. Move the cursor to  date
 and press ENTER. This expands the display of the array and shows all of the
 elements. Press ENTER again while the cursor is on  date  to contract the
 array.

 Because  date  is also a local variable, it is shown in the local window
 with all variables local to the current function. You can expand or contract
 data in the local and the watch windows .

 Another way to view the contents of  date  is to put the cursor on it in the
 CodeView source window and choose QuickWatch from the Watch menu. The  date
 variable is immediately displayed in its expanded form. Press ENTER or click
 the OK button to leave the dialog box.

 Press F10 to finish stepping through the program. A dialog box informs you
 that the program has completed execution normally. Press ENTER to clear the
 dialog box and complete your debugging session.


 Debugging IO.C

 To see how CodeView deals with a bug in a program, use the Exit command in
 the File menu to return to PWB, then add this function to the IO.C program,
 and call it from  main:

   void bounds_error(void)
   {
      int loop, the_num[10];

      for(loop = 0; loop < 15; loop++)
         the_num[loop] = loop; }

 Set the appropriate debug options, rebuild the program, and return to
 CodeView.

 Use the F8 Trace command to execute the program. The program runs until it
 reaches the  for  statement in the  bounds_error  function, where the array
 bounds are exceeded. The output window reports an error while a CodeView
 dialog box indicates the program has terminated. At this point you can
 return to PWB, locate the error, and correct it.


 Getting More Details

 PWB, the compiler, the linker, NMAKE, and CodeView all have other features
 and options that go beyond the scope of this introduction.

 Refer to Advanced Programming Techniques for information about PWB, NMAKE,
 CodeView, and other tools, and the C Reference for a comprehensive listing
 of all commands and options for the applications included with Microsoft C.


 In addition, information about any component of the Professional Development
 System can be accessed through the Microsoft Advisor reference system. For a
 complete discussion of the on-line reference, see Chapter 4.






 Chapter 4  Using the On-Line Reference
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

 Microsoft C offers two types of on-line reference systems:


   þ   The Microsoft Advisor, found within the Programmer's WorkBench (PWB)
       and CodeView environments.

   þ   The QuickHelp program, accessed from the OS/2 or DOS command line.


 Both systems provide the same information on important C topics and
 utilities provided with the Professional Development System, which include
 the C language, run-time libraries, CodeView, and PWB.

 The first section of this chapter, "Structure of the Microsoft Advisor,"
 outlines the structure and contents of the on-line reference database. The
 second section, "Navigating Through the Microsoft Advisor," takes you on a
 quick tour of the system. The third section, "Using QuickHelp," explains how
 to use the QuickHelp program and how it differs from the Microsoft Advisor.



 Structure of the Microsoft Advisor

 The Microsoft Advisor can be compared to a librarian managing a collection
 of books. Each book, or help file, has its own table of contents, index, and
 pages of information. The Advisor organizes the help files with a global
 contents and index. All of the files are listed, and their specific tables
 of contents and indexes can be accessed through the global references. The
 global contents screen is shown in Figure 4.1.

 (This figure may be found in the printed book).

 You can access a variety of information from the on-line reference system.
 Information regarding the C language, run-time libraries, errors, and the
 reference system itself is available.


 Navigating Through the Microsoft Advisor

 You request information about a topic in a window by positioning the cursor
 over it and pressing F1 or clicking the Right mouse button once. The help
 system then searches through the help files for information about the topic.
 If it finds the topic, the help system displays information in the help
 window. If help cannot be found for a particular word or symbol, a message
 informs you that no information is associated with the topic. Sometimes, a
 topic with the same name occurs in several help files. In such cases, a
 dialog box is displayed in which you can select the context of the topic.


 Using the Help Menu

 The simplest method for accessing the on-line reference is by using the
 commands found in the Help menu. All of these commands present information
 in the Help window.

 Command                           Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 Index                             Displays the global index of help-file
                                   categories (see Figure 4.2).

 Contents                          Displays the global contents screen for
                                   the categories found in the help files.

 Topic:                            Provides information about the topic
                                   that the cursor is currently positioned
                                   over. If information about the topic is
                                   available, the topic's name is appended
                                   to the Topic: command. Otherwise, this
                                   menu option is grayed.

 Help on Help                      Displays information about using the
                                   on-line reference itself.

 Next                              Is useful if a topic with the same name
                                   appears in more than one help file. This
                                   option locates the next occurrence of
                                   the topic name and displays the
                                   information associated with it.

 (This figure may be found in the printed book).


 Using the F1 Key

 You can use the F1 key to get information about any menu command or PWB
 dialog box, as well as information on C keywords, operators, and run-time
 library functions.


 Menu Help

 To view information about a menu item, first pull down the menu, then


   þ   Use the cursor keys to highlight the command, and press F1, or

   þ   Move the mouse cursor on the command and click the Right mouse button


 Figure 4.3 shows the help information for the Cut command in the Edit menu.


 (This figure may be found in the printed book).


 Keyword and Library-Function Help

 To view information about a C keyword, operator, or run-time library
 function,


   þ   Put the cursor on the keyword or function name, and press F1, or

   þ   Click the command with the Right mouse button



 Dialog-Box Help

 To view information about a PWB dialog box, simply press F1 while the dialog
 box is displayed, or click on the help button.


 Using Hyperlinks

 Hyperlinks are cross-references that connect related topic information.

 Hyperlinks enclosed by the < and > characters are called "buttons." Navigate
 through the on-line help system by using these buttons.

 You can press TAB to move to the next hyperlink button within the current
 help window. SHIFT+TAB moves back to the previous button. Typing any letter
 moves the cursor to the next button that begins with the letter; holding
 SHIFT down and typing a letter moves the cursor backward.

 The Microsoft Advisor also recognizes C keywords, library functions,
 constants defined by Microsoft C, and similar identifiers as hyperlinks, but
 they are unmarked hyperlinks. Unmarked hyperlinks are recognized by the
 Microsoft Advisor wherever they appear in the help-information text or in
 your source code. However, an unmarked hyperlink is not delimited with the <
 and > characters, and you can't move to it with the TAB key. An unmarked
 hyperlink can only be executed by placing the cursor on it and pressing F1,
 or pointing to it with the mouse cursor and clicking the Right mouse button.


 You can access a hyperlink in several ways. First move either the mouse or
 text cursor to a hyperlink, then either


   þ   Press F1

   þ   Click the Right mouse button

   þ   Click the Left mouse button twice (double-click)


 Highlighted button hyperlinks can also be executed by pressing ENTER or
 SPACEBAR.

 Any of these actions displays information about the topic the cursor is
 positioned on. If the topic isn't a hyperlink, a message informs you that no
 information on the topic could be found.

 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 NOTE

 CodeView uses the Right mouse button differently in the source window.
 Clicking the Right button in the source window executes the program to the
 line the mouse was clicked on. However, once the help window is displayed,
 the Right mouse button can be used to select hyperlinks.
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


 Using Help Windows and Dialog Boxes

 The Microsoft Advisor displays information in windows or dialog boxes. Help
 windows and dialog boxes function the same as other windows and dialog boxes
 found in PWB and CodeView. For a complete description of windows and dialog
 boxes, refer to Chapter 3, "Using the Programmer's WorkBench."


 Using the Help Window

 The help window displays various contents, indexes, and information about
 selected topics. Some screens of information are larger than the help
 window; information beyond the window borders can be viewed by using the
 scroll bars or the cursor-movement keys. The  - u -  symbol indicates the
 end of information in the help window.

 Navigating with Hyperlink Buttons - At the top of the help window is a row
 of buttons that are useful for moving through the reference system:

 Button                            Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 < Up >                            Moves upward in the hierarchy of help
                                   screens. Since information is ordered in
                                   a logical way, moving from the general
                                   to the specific, this command is useful
                                   for moving up the information tree.

 < Contents >                      Displays the global contents screen.
                                   This command is useful because it always
                                   returns you to a known point in the
                                   on-line help system hierarchy.

 < Index >                         Displays the global index list.
                                   Selecting an item from the list displays
                                   the index for that category.

 < Back >                          Moves you to the last on-line help
                                   screen you saw.

 Screens on a particular topic frequently are physically grouped together in
 a help file. You can press CTRL+F1 to display information about the next
 physical topic in the help file.

 Viewing the Previous Help Screen - The Microsoft Advisor remembers the last
 20 help screens you've accessed. To return to a previous screen, use the <
 Back > button or hold down the ALT key and press F1 as many times as
 necessary to return to the screen you want to see. The help screen that
 appears is active; you can ask for help on any of its hyperlinks or topics.


 You can always return to the global contents screen by pressing SHIFT+F1.

 Copying and Pasting Help Information - Any text that appears in the help
 window can easily be copied to another window. For example, to test an
 example program from the help window, you only have to copy it to the source
 window and compile it.

 To copy and paste using the keyboard, follow these steps:


   1.  Move the cursor to the beginning or the end of the text you want to
       select. Hold down the SHIFT key and move the cursor to the other end
       of the text. The text is now highlighted.

   2.  Execute the Copy command: Press ALT to activate the menus, E for Edit,
       then C for Copy. Note that the menu lists the shortcut command
       (CTRL+INS), which can be substituted for ALT+E, then C.

   3.  Press F6 to switch to another window. Position the cursor where you
       want to insert the text, and execute the Paste command: ALT+E then P,
       or use the SHIFT+INS shortcut. The text from the help window is
       inserted at the current cursor position.


 To copy and paste using the mouse, follow these steps:


   1.  Click the Left mouse button and drag the cursor (hold down the button
       while moving the mouse) to select the text you want to copy.

   2.  Choose Copy from the Edit menu (or press CTRL+INS).

   3.  Move the mouse cursor to the location where you want to insert the
       text, and click once. Then choose Paste from the Edit menu. The text
       from the help window is inserted at the current cursor position.


 Closing the Help Window - Once you're through working with the reference
 system, you can close the active help window and return to the source window
 by


   þ   Pressing ESC

   þ   Clicking the Close button in the upper left corner of the window with
       the Left mouse button



 Using Help Dialog Boxes

 Help dialog boxes contain information about menu commands and their dialog
 boxes. A help dialog box differs from a help window in that it is displayed
 over the source window and any other windows that are displayed. Unlike the
 help window, a help dialog box must be closed before you can execute any
 menu commands. The Cancel button in the lower right portion of the dialog
 box closes the help dialog box.

 To view information about any PWB dialog box, you can


   þ   Press F1

   þ   Click the Help button in the dialog box with the Left mouse button


 Either of these commands causes a help dialog box to appear. To close a help
 dialog box,


   þ   Press ESC

   þ   Click the dialog box's Cancel button by using the Left mouse button



 Accessing Different Types of Information

 This section presents some strategies for accessing the different types of
 information available within the on-line reference system.


 Keyword Information

 To get information about any keyword, operator, symbolic constant, or
 library function, display the appropriate index for the keyword, select the
 keyword's first letter from the index, then scroll down the list of entries
 and select the topic's hyperlink. If you know the exact name of a keyword,
 it is often quicker to simply type it in the source window and press F1 to
 locate it through an index.

 Information about keywords can also be viewed by using the arg command and
 entering the keyword with F1 in the arg command dialog box. Assuming that
 you have the arg function assigned to  alt+a, the following series of
 keystrokes displays help on the printf function:

   alt+a printf F1

 Figure 4.4 shows the information screen that then appears.

 (This figure may be found in the printed book).

 When information about a function is shown in the help window, two
 additional hyperlink buttons are displayed.


   þ   < Description > provides a detailed explanation of the function. When
       the information is displayed, the button changes to < Summary >. Click
       this button to return to the summarized information about the
       function.

   þ   < Example > displays C source code that provides an example of how the
       function is used.



 Topical Information

 The on-line reference system is useful when you want an overview of the
 available reference topics, or when you only have a general idea of what
 information you need. Start with the global contents screen, then select any
 hyperlinks that relate to the topic. You can traverse the hyperlinks until
 you locate the necessary information.


 Menu and Dialog-Box Information

 You can get information about any menu command or dialog box by pressing F1
 when the menu command is highlighted or the dialog box is displayed. This is
 helpful when you are first learning to use the Professional Development
 System and are not completely familiar with all of the features.


 Error Information

 The Microsoft Advisor provides information about compiler and linker error
 messages.

 To find the meaning of an error message using the keyboard,


   1.  Press F6 to move the cursor to the error window

   2.  Position the cursor on the error number

   3.  Press F1


 or with the mouse,


   1.  Position the mouse cursor on the error number

   2.  Click the Right mouse button


 Help on error messages is also available directly from the PWB source window
 by entering the arg command with the error number and its alphabetic prefix,
 and then pressing F1.


 Specifying Temporary Help Files

 You can temporarily load other help files using the Environment command in
 the PWB Options menu. The Microsoft Advisor searches help files you specify
 in this text box before it searches the standard Development System help
 files as specified by the HELPFILES environment variable. Use the help files
 text box to override (for the current session only) the help-file path
 defined in the HELPFILES variable. When programming with mixed languages,
 you may want to temporarily load the help files for each of the languages
 you're using.


 Using QuickHelp

 QuickHelp is a separate application that provides access to any help file.
 It uses the same help files as the Microsoft Advisor, and presents
 information about topics in the same way. QuickHelp is designed for the
 developer who prefers using command-line utilities or another editor, and
 doesn't have access to the Microsoft Advisor through PWB.

 Major utilities and applications that come with the Microsoft C package
 invoke QuickHelp and display related information if you use the /HELP
 switch. You can also use QuickHelp from the command line, as explained in
 the following sections. Once you are in the QuickHelp program, select which
 help file you want to view.


 Using the /HELP Switch

 You can get immediate information on major components of Microsoft C by
 using the /HELP switch.

 For example, to learn about the LIB utility, enter

   LIB /HELP

 QuickHelp will run and immediately display information about LIB.


 Using the QH Command

 You can also run QuickHelp by typing QH at the DOS or OS/2 command line.
 Specify an application to get help about, such as

   QH LIB.EXE

 In addition to information about programs, QuickHelp can also display
 information about run-time errors. You can type the error number with its
 alphabetic prefix after the QH command at the DOS or OS/2 command line.


 Opening and Closing Help Files

 If no file name is specified when QuickHelp is run, it looks for the
 environment variable HELPFILES, and opens all listed .HLP files. If the
 HELPFILES variable isn't present, all .HLP files in directories specified by
 the PATH environment variable are loaded.

 Choose the List Database command on the File menu to view a list of all the
 currently open help files.

 To open additional help files,


   þ   Choose the Open Database command from the File menu.

   þ   Type the fully qualified path name of the help file to be opened in
       the dialog box that appears. You can specify all help files in a
       directory with *.HLP.

   þ   Press ENTER or click the OK button with the Left mouse button.


 To close an open help file,


   þ   Choose the Close Database command from the File menu.

   þ   Use the mouse or keyboard to select which help file you would like to
       close from the list of help files displayed in the menu



 Displaying a Topic

 You can view information about a topic by using the Search command in the
 View menu. When topic information is displayed, it is shown in the same
 format as information presented by the Microsoft Advisor.

 To display a topic from any of the open help files,


   þ   Choose the Search command from the View menu

   þ   Type the topic you want information about in the Search dialog box
       (the search is not case sensitive)

   þ   Press ENTER or click the OK button with the Left mouse button


 QuickHelp begins searching for the topic in the open help files. If the
 topic cannot be found, a dialog box informs you that the search failed. If
 the search is successful, information about the topic is displayed in the
 QuickHelp window.


 Navigating Through Topics

 A series of commands on the View menu allow you to selectively display
 topics. These commands include the following:

 Command                           Description
 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
 View History                      Displays a list of all the topics that
                                   have recently been displayed. You can
                                   view a topic in the list by selecting it
                                   and clicking the Right mouse button or
                                   pressing ENTER.

 View Last                         Displays the last topic you looked at.

 View Back                         Moves backward one topic in the help
                                   file.

 View Next                         Displays the next topic in the help
                                   file.


 Using the QuickHelp Window

 The QuickHelp window (see Figure 4.5) is similar in function to the
 Microsoft Advisor help window, described earlier in this chapter.
 Information that doesn't fully fit in a window can be scrolled, and
 hyperlinks are used to display additional information.

 (This figure may be found in the printed book).

 The main differences between the two windows are


   þ   Information presented in QuickHelp cannot selectively be copied. See
       the section "Copying and Pasting in QuickHelp" that follows for more
       information.

   þ   The QuickHelp window cannot be closed.

   þ   Any information that appears on the screen can be sent to a printer by
       using the Print command in the File menu.



 Copying and Pasting in QuickHelp

 In order to transfer information, you must first specify a new file with the
 Rename Paste File command in the File menu. Once the file is specified,
 choose either the Current Window or the Current Topic command in the Paste
 menu to transfer the text to that file. Be sure to specify a new file when
 you paste, since QuickHelp overwrites text in an existing file.


 More About QuickHelp

 In addition to the features mentioned above, QuickHelp has a variety of
 other options such as changing the appearance of the help window, searching
 for text within topics, and controlling the function of the Right mouse
 button.

 To learn more about QuickHelp's features, make sure the QH.HLP file is
 loaded, then do one of the following:


   þ   Press F1 to view QuickHelp's on-line reference

   þ   Choose a menu command and press F1 or click the Right mouse button to
       get information about it

   þ   Refer to the C Reference guide for a list of QuickHelp options

