Microsoft Programmer's Library 1.3/Microsoft_Programmers_Library.7z/MPL/basic/b71strt.txt

Text File | 2013-11-08 | 159.5 KB | 4,474 lines

 BASIC Version 7.1 Getting Started








 ────────────────────────────────────────────────────────────────────────────

                    BASIC Version 7.1 Getting Started

 ────────────────────────────────────────────────────────────────────────────









 Microsoft Corporation   For IBM Personal Computers and Compatibles

 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.

 Copyright 1989, 1990 Microsoft Corporation. All rights reserved.

 Simultaneously published in the U.S. and Canada.

 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.

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

 Btrieve is a registered trademark of SoftCraft, Inc., a Novell
 Company.

 COMPAQ is a registered trademark of Compaq Computer Corporation.

 dBASE is a registered trademark of Ashton-Tate Corporation.

 IBM is a registered trademark of International Business Machines
 Corporation.

 Intel is a registered trademark of Intel Corporation.

 Lotus is a registered trademark of Lotus Development Corporation.



 Document No. DB06823-0590

 No. D704-72


 Guide to Keystrokes

 The following table lists the most commonly used keystrokes in the
 QuickBASIC Extended (QBX), Programmer's WorkBench (PWB), and CodeView
 environments. Unless stated otherwise, each keystroke has the same
 function in all three environments.


 Introduction
 ────────────────────────────────────────────────────────────────────────────

 Welcome to Microsoft BASIC version 7.1 Professional Development
 System. Microsoft BASIC includes the tools and files you'll need to
 create and debug large, sophisticated BASIC programs that run under the
 DOS and OS/2 operating systems. The Microsoft BASIC package includes the
 following:

 Microsoft QuickBASIC Extended (QBX) development environment

 Microsoft Programmer's WorkBench (PWB) development environment

 BASIC compiler (BC)

 Integrated Indexed Sequential Access Method (ISAM) package

 Major utilities:

   -  Microsoft Segmented-Executable Linker (LINK)
   -  Microsoft Library Manager (LIB)
   -  Microsoft Program-Maintenance Utility (NMAKE)
   -  Run-Time Module Build Utility (BUILDRTM)
   -  Microsoft Help File Creation Utility (HELPMAKE)
   -  Microsoft QuickHelp


   ■  Add-on libraries:
          Date/Time, Financial, and Format
   ■  Toolboxes: Matrix Math, Presentation Graphics, and User Interface


 Microsoft CodeView debugger and other mixed-language development
   tools

 Printed and online documentation


 Distribution of Run-Time Modules

 As described in Paragraph 5 of the Microsoft License Agreement
 included with this product, the following run-time modules may be
 distributed under the terms and conditions listed in the agreement:

 BRT71xxx.EXE, BRT71xxx.DLL, HELVB.FON, TMSRB.FON, MSHERC.COM,
 MOUSE.COM, PATCH87.EXE, FIXSHIFT.COM, PROISAM.EXE, PROISAMD.EXE,
 ISAMIO.EXE, ISAMCVT.EXE, ISAMPACK.EXE, and ISAMREPR.EXE.

 These modules can only be distributed in conjunction with and as a
 necessary and integrated component of your software product, in such a
 manner that they enhance or supplement the core value otherwise existing
 in your software product.

 The following copyright notice applies to this product for purposes
 of run-time module distribution:

 Portions(C) 1982-1990 Microsoft Corporation. All rights
 reserved.


 Documentation

 Microsoft BASIC 7.1 includes a full set of printed and online
 documentation.


 Printed Documentation

  Getting Started
 gets you up and running with Microsoft BASIC.

 The  Programmer's Guide
 provides information about programming concepts and techniques. The
 first part of the manual focuses on the features of the BASIC language,
 including such topics as control-flow structures, string processing, and
 error/event handling. The second part of the manual describes program
 development utilities supplied with Microsoft BASIC. These chapters give
 the syntax and command-line options for each utility, as well as
 illustrative examples. The appendixes contain the BASIC language
 definitions.

 The  BASIC Language Reference
 is divided into three parts. Each part begins with summary tables
 listing the functions and statements described in that part, followed by
 individual reference descriptions in alphabetical order.

   ■  Part 1, "Language Reference," describes Microsoft BASIC functions,
 statements, and metacommands.

   ■  Part 2, "Add-On-Library Reference," describes the functions in the
 add-on libraries.

   ■  Part 3, "BASIC Toolbox Reference," describes the procedures in the
 BASIC toolboxes.


 The appendixes describe keyboard/scan codes, reserved words,
 command-line tools, and error messages.


 Online Documentation

 Microsoft BASIC puts a complete online reference database at your
 fingertips with the new Microsoft Advisor online Help system. Online
 Help gives you context-sensitive Help for the BASIC language, QBX,
 command-line compiler options, error messages, and symbols in your
 programs. See Chapter 6, "Using Online Help," for more information.


 Document Conventions

 Microsoft documentation uses the term "OS/2" to refer to the OS/2
 systems--Microsoft Operating System/2 (MS OS/2) and IBM OS/2.
 Similarly, the term "DOS" refers to the

  and IBM Personal Computer DOS operating systems. The name of a
 specific operating system is used when it is necessary to note features
 that are unique to that system.

 This manual uses the following typographic conventions:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
 Example of convention                   Description
 ────────────────────────────────────────────────────────────────────────────
 setup                                   Words you type appear in this
                                         boldface font.

 BASIC.LIB, ADD.EXE, COPY, LINK          Uppercase (capital) letters
                                         indicate filenames and


 Example of convention                   Description
 ────────────────────────────────────────────────────────────────────────────

  SUB,  IF,  LOOP,  PRINT,  TIME$        Bold uppercase letters indicate
                                         language-specific keywords with


 Bad File Mode                           This font is used for error
                                         messages.





╓┌───────────────────────────────────────┌───────────────────────────────────╖
 ────────────────────────────────────────────────────────────────────────────
  handles                                Italic letters indicate
                                         placeholders for information you
                                         supply.


 ────────────────────────────────────────────────────────────────────────────

  disksize                               Items inside double square
                                         brackets are optional.

 { WHILE


 Ctrl key                                Initial capital letters are used
                                         for the names of keys and key
 .

 Alt+F1                                  A plus (+) indicates a combination
                                         of keys. For example, Alt+F1


 Down Arrow key                          The cursor movement ("arrow") keys
                                         are called direction keys.






╓┌───────────────────────────────────────┌───────────────────────────────────╖
 ────────────────────────────────────────────────────────────────────────────
 "defined term"                          Quotation marks usually indicate a
                                         new term defined in the


 Video Graphics Array (VGA)              Acronyms are usually spelled out
                                         the first time they are used.





 ────────────────────────────────────────────────────────────────────────────



 Chapter 1  New Features
 ────────────────────────────────────────────────────────────────────────────

 Microsoft BASIC combines powerful new language features with
 capacity, performance, and usability enhancements to provide a
 high-productivity development system for professional BASIC programmers.
 This chapter describes the new features for versions 7.0 and 7.1.
 Changes for version 7.1 are indicated by the words "Version 7.1" in the
 left margin.


 New Features in Version 7.1

 Microsoft BASIC version 7.1 extends BASIC's power under OS/2,
 improves its compatibility with other languages, and provides new
 language features:

   ■  BASIC's Indexed Sequential Access Method (ISAM) is now fully
 supported for OS/2.

   ■  The Programmer's WorkBench (PWB) provides a sophisticated development
 environment for mixed-language programming under DOS or OS/2.

   ■  The CodeView debugger version 3.0 contains many improvements to
 simplify the task of debugging large BASIC and mixed-language programs
 under DOS or OS/2.

   ■  QuickHelp provides access to the Microsoft Advisor Help system from
 the command line.

   ■  The new  REDIM PRESERVE
  statement lets you change the size of an array without erasing the data
 it contains.

   ■  BASIC now supports passing parameters by value within BASIC
 procedures and passing arrays containing fixed length strings as
 parameters.

   ■  BASIC is fully compatible with Microsoft C version 6.0.


 The rest of this chapter discusses the features new to Microsoft
 BASIC versions 7.0 and 7.1 in greater detail.


 Language Enhancements

 Microsoft BASIC contains major language enhancements designed for
 business, scientific, and general-purpose BASIC programming.


 Integrated ISAM

 The Indexed Sequential Access Method package provides a fast and
 simple method for accessing specific records in large and complex data
 files. Microsoft BASIC integrates all ISAM statements and functions with
 the BASIC language. BASIC ISAM includes statements for transaction
 processing and for data retrieval and manipulation.


 Version 7.1

 In version 7.1, ISAM statements and functions are supported for OS/2
 as well as DOS.

 Microsoft BASIC also includes several utilities for use with ISAM
 files created with BASIC:

   ■  ISAMCVT.EXE (DOS only) converts Btrieve and dBASE files for use with
 ISAM.

   ■  ISAMREPR.EXE repairs corrupted ISAM databases.

   ■  ISAMPACK.EXE compacts ISAM files to save disk space.

   ■  ISAMIO.EXE converts ASCII files to ISAM format and vice versa.




 For more information about ISAM, see Chapter 10, "Database
 Programming with ISAM," in the  Programmer's Guide.


 DOS File Management

 The  DIR$ and  CURDIR$ functions and the  CHDRIVE
 statement make it easier to manage DOS files from BASIC programs.

  DIR$ is similar to the DOS DIR command, except that the
 filenames are returned one at a time.  CURDIR$ returns the
 current directory specification, and  CHDRIVE changes the current
 drive.


 Currency Data Type

 The currency data type maintains to-the-penny precision while
 providing the speed of integer math for programming accounting tasks.
 Its internal representation as an integer gives this type a significant
 advantage in speed over the floating-point data type for operations such
 as addition and subtraction. For more information about the currency
 data type, see Chapter 15, "Optimizing Program Size and Speed," in the
  Programmer's Guide.


 Procedure-Level Error Handling

 Microsoft BASIC contains local error trapping and handling for
 procedures, making error handling much more efficient. In previous
 versions of BASIC, error-handling routines existed at the module level.
 When a handler was turned on, it was active for all procedures within
 the module.

 With Microsoft BASIC, you can create both module-level and
 procedure-level error handlers. The same error can invoke different
 error-handling routines, depending on which procedure is running. For
 example, you may want to invoke different error-handling routines for
  ERR code 54,  Bad File Mode, because the error has different
 meanings for different file operations. For more information on error
 handling, see Chapter 8, "Error Handling," in the  Programmer's Guide.


 Static Arrays in Records

 In previous versions of BASIC, you could create user-defined data
 structures that contained numeric and fixed-string data types by using
 the  TYPE%  ...  END TYPE statements. Now you can use static arrays
 in addition to numeric and string data types, which gives you more
 flexibility in building data structures.


 Preserve Data when Redimensioning an Array


 Version 7.1

 By adding the  PRESERVE  option to the  REDIM statement,
 you can preserve the data that exists in an array when changing its outer
 boundary.  This simplifies the dynamic control of the amount of memory
 consumed by an array. For details and an example, see the online Help on
 the  REDIM statement .


 Improved Parameter Passing


 Version 7.1

 With previous versions of BASIC, you could emulate passing parameters
 by value by surrounding the parameter with parentheses. Now you can use
 the  BYVAL keyword in  DECLARE,  SUB, and  FUNCTION
 statements for BASIC procedures. For details on passing parameters by
 value, see the online Help for the  DECLARE,  SUB, and
  FUNCTION statements.

 BASIC now also supports passing arrays containing fixed-length
 strings as parameters. For more information, see the online Help for the
  SUB and  FUNCTION statements.


 Improved COM Support with ERDEV$ and ERDEV

 With previous versions of BASIC, if you had a device timeout error,
 there was no way to find out which device timed out, or which control
 line caused the timeout. With Microsoft BASIC, information about the
 timeout is available through the  ERDEV$  and  ERDEV functions.
  ERDEV$ indicates whether a timeout is occurring on the communications port.
  ERDEV indicates the type of timeout error that occurred
 (that is, CTS, DSR, or DCD control-line errors). See the  OPEN COM
 statement in the  BASIC Language Reference for more information.


 Date/Time, Financial, and Format Add-On Libraries

 With these new libraries, you can use BASIC to perform
 spreadsheet-style calculations and formatting. For example, you can
 compute the number of days between two dates by converting the dates
 from month-day-year format to number format, and then subtracting. You
 can use financial functions to calculate double-declining balance
 depreciation, future value, net present value, internal rate of return,
 and other common financial calculations. For more information about
 Date/Time, Financial, and Format add-on libraries, see Part 2 of the
  BASIC Language Reference.


 Matrix Math Toolbox

 The new Matrix Math toolbox contains sample BASIC code for several
 common matrix math operations, including addition, subtraction,
 multiplication and division, matrix inversion, determinant calculation,
 and solution of simultaneous equations using Gaussian elimination. For
 more information about the Matrix Math toolbox, see Part 3 of the BASIC
 Language Reference.


 Presentation Graphics Toolbox

 You can use the Presentation Graphics toolbox to display charts and
 graphs from your programs. The Presentation Graphics toolbox includes
 procedures for pie charts, bar and column charts, line graphs, and
 scatter diagrams. Figure 1.1 shows an example of a column chart created
 with this toolbox.

 The toolbox also includes a set of special graphics fonts. For more
 information about Presentation Graphics, see Chapter 6, "Presentation
 Graphics," in the  Programmer's Guide.


 User Interface Toolbox

 With the new user interface code samples, you can design your own
 user interface using BASIC procedures. The code samples in this toolbox
 give you complete control of character-based window interfaces. For
 example, you could write a BASIC program with multiple windows, menu
 bars, dialog boxes, and mouse interaction. For more information about
 the User Interface toolbox, see Part 3 of the  BASIC Language
 Reference.


 C Version 6.0 Compatibility


 Version 7.1

 BASIC incorporates the C version 6.0 startup code. This makes BASIC
 fully compatible with the latest version of C. However, this can cause
 problems for mixed-language programmers who have earlier versions of C,
 FORTRAN, or Pascal. Compatible run-times for these languages are
 available free from Microsoft. Contact Product Support Services for more
 information.


 Capacity and Performance Enhancements

 Microsoft BASIC eliminates many of the capacity and performance
 barriers that formerly limited the size and sophistication of BASIC
 applications.


 Far String Support

 In previous versions of BASIC, all variable-length string data was
 stored in near memory. This relatively small portion of memory (64K
 maximum) also stores the rest of the simple variables--integers,
 floating-point numbers and fixed strings, all constants, the stack, and
 some run-time overhead. Even when the only variables you use are
 variable-length strings, your maximum data storage is limited.

 Microsoft BASIC supports "far strings," which enable you to store
 variable-length string data outside of near memory in multiple segments
 of far memory. This gives you a full 64K of string storage in the module
 level of the main module, plus several additional 64K blocks of storage,
 depending on how you write your program. Removing variable-length
 strings from near memory creates significantly more room for other
 simple variables. For more information on using far strings, see Chapter
 11, "Advanced String Storage," and Chapter 13, "Mixed-Language
 Programming with Far Strings," in the  Programmer's Guide.


 Overlay Support

 With overlays, you can write and run programs up to almost 16
 megabytes in size when compiling and linking from the command line. In
 an overlaid version of a program, specified parts of the program are
 only loaded if and when they are needed. Specifying overlays can be
 useful if you have compiled a program that is too large to load in
 memory. For more information about overlays, see Chapter 18, "Using LINK
 and LIB," in the  Programmer's Guide.


 Improved Granularity

 The extent to which BASIC run-time routines are divided into
 individually accessible pieces is called "granularity." With Microsoft
 BASIC's improved granularity, you can link with the minimum amount of
 library code needed to produce stand-alone programs. This gives you
 smaller compiled programs, saving disk space and memory. For more
 information, see

 15, "Optimizing Program Size and Speed," in the  Programmer's
 Guide.


 Optimized Code Generation

 Optimized code generation automatically makes compiled BASIC programs
 smaller and faster. Also, using a new compiler switch, you can tell the
 compiler to generate code for the 80286 (and later) microprocessor
 family, taking advantage of that family's machine instructions. For more
 information on optimized code generation, see Chapter 15, "Optimizing
 Program Size and Speed," in the  Programmer's Guide.


 Improved Alternate Math Package

 For target systems without an 80x87 math coprocessor, the alternate
 math package gives programs greatly improved speed. For example, if your
 application involves spreadsheet-style math without recursive
 calculations, using the alternate math package may give you a noticeable
 performance increase. For more information about the alternate math
 package, see Chapter 15, "Optimizing Program Size and Speed," in the
  Programmer's Guide.


 Improved IEEE Math Coprocessor Emulation

 For target systems with or without a math coprocessor, an improved
 coprocessor emulator gives you faster high-precision calculations.


 Improved Code Generation


 Version 7.1

 Relative jumps and short jumps to near targets are optimized,
 resulting in smaller, faster programs. This improvement affects all
 control statements.


 Environment and Usability Enhancements

 Microsoft BASIC offers two sophisticated development environments:
 Microsoft QuickBASIC Extended (QBX) and Microsoft Programmer's WorkBench
 (PWB). Both provide the following advanced features:

   ■  Integrated debugging capabilities within the environment and
 compatibility with CodeView version 3.0 for debugging and optimizing
 executable programs at a variety of levels

   ■  Support for expanded memory specification (EMS 4.0) to create large
 executable programs

   ■  Undo/Redo capabilities

   ■  Customizable menus and key assignments

   ■  Control of build options and target environment from the development
 environment

   ■  A comprehensive online Help system designed for professional
 programmers


 In addition to QBX and PWB, BASIC now includes the QuickHelp
 environment for viewing Microsoft Advisor online Help files.


 The QuickBASIC Extended Environment

 Microsoft QuickBASIC Extended (QBX) is an advanced development
 environment for programmers who write most or all of their code in
 BASIC. It provides line-by-line syntax checking and on-demand program
 execution without recompiling. QBX also provides the following key
 features:

   ■  QBX automatically uses expanded memory, if present, for any parts of
 your program source code that are less than 16K in size. The View SUBs
 command now enables you to determine whether a program unit
 (module-level code or procedure) will fit into expanded memory.

   ■  Historical Undo/Redo commands. You can use Undo to step back through
 your last 20 edits.

   ■  A customizable Utility menu. You can use the Utility menu to run DOS
 command-line programs or a custom editor, or for command-line compiling
 and overlay linking. You can even assign each menu item a shortcut
 key.

   ■  Customizable key assignments. If you prefer to use a set of editing
 commands other than the QBX defaults, you can change your key file to
 one of those provided, or you can create your own custom
 assignments.

   ■   nPrint to multiple printers or to a file.

   ■  Debug watch window capacity doubled (from 8 to 16 expressions).

   ■  Complete control of compiler switches for compiling from the
 environment.


 For information on using QBX, see Chapter 3,"Using QuickBASIC
 Extended."


 The Programmer's WorkBench Environment


 Version 7.1

 Microsoft Programmer's WorkBench (PWB) is an advanced development
 environment for programmers who often work in languages other than BASIC
 or who want to create, build, and debug their programs under OS/2. PWB
 also offers the following key features:

   ■  PWB runs in real or protected modes, so you can write BASIC programs
 under DOS or OS/2.

   ■  You can write programs in any Microsoft professional-level language
 and mix languages, such as BASIC and C, within the environment.

   ■  The Source Browser allows you to search selected files, list
 references and definitions, build a call tree and outline, and view a
 list of relationships among program symbols.

   ■  You can step through compiler errors and PWB will indicate where each
 error occurred in the source code.

   ■  PWB and CodeView are integrated, so you can switch from one to the
 other without exiting PWB.

   ■  Comprehensive Help is available on all command-line utilities and
 Microsoft languages installed on your system.


 For information on using PWB, see Chapter 4, "Using the Programmer's
 WorkBench." See the PWB online Help for detailed information on
 performing tasks and customizing the environment.


 The CodeView Debugger


 Version 7.1

 The CodeView debugger allows you to debug programs under DOS or OS/2.
 This is especially useful when you are using assembly language routines
 in a BASIC program. CodeView version 3.0 offers the following new
 features:

   ■  Comprehensive online Help on how to use CodeView. Help is also
 available on any installed Microsoft language or utility from within
 CodeView.

   ■  Automatic use of extended and expanded memory, if available.

   ■  Full integration with PWB and compatibility with programs created in
 QBX.


 For introductory information on how to debug programs using this
 environment, see Chapter 5, "Using The CodeView Debugger." For detailed
 information on how to perform tasks in CodeView and for information on
 how CodeView evaluates BASIC expressions, see the CodeView online
 Help.


 QuickHelp


 Version 7.1

 Microsoft QuickHelp reads Microsoft Advisor online Help files under
 DOS or OS/2. This provides you with an easy way to get Help on the
 command-line utilities and development environments without loading QBX,
 PWB, or CodeView.

 If you are using OS/2 or Microsoft Windows, you can run QuickHelp in
 one window and do your programming in another. This can be more
 convenient than using Help in the programming environment, which
 obscures part of the program you are working on.

 For more information on using QuickHelp, see Chapter 6, "Using
 Help."

 ────────────────────────────────────────────────────────────────────────────



 Chapter 2  Setup
 ────────────────────────────────────────────────────────────────────────────


 System Requirements

 Microsoft BASIC requires the following minimum configuration:

   ■  An IBM Personal Computer XT or compatible running DOS version 3.0 or
 later, or OS/2 version 1.1 or later.

   ■  A hard disk drive.

   ■  A 1.2M 5.25-inch floppy disk drive. (360K and 720K disk versions of
 this product are available from Microsoft. Contact Product Support
 Services for more information.)

   ■  640K of available memory.


 Microsoft BASIC supports the Microsoft Mouse and any other pointing
 devices fully compatible with the Microsoft Mouse.


 Setup Overview

 Your Microsoft BASIC package includes the SETUP.EXE file on Disk 1
 (Setup). You can use Setup in one of two ways:

   ■  Install all the files you need to run BASIC, including the QBX
 environment, mixed-language development tools, utilities, and
 libraries.

   ■  Selectively install files. Typically, these might include libraries
 or tools you did not choose to install the first time you used
 Setup.


 Setup offers you a series of choices, letting you specify where to
 install the files and what features and utilities you want to install.
 To conserve disk space, you may choose not to use all of BASIC's
 features at first. You can later run Setup to selectively install
 features you decide to add.


 Important

 You must run Setup to use Microsoft BASIC successfully. Setup
 decompresses files on the distribution disks (using UNPACK.EXE), builds
 libraries, and performs other operations to give you a usable BASIC
 environment. You cannot run BASIC by merely copying files from the
 distribution disks.


 Running Setup

 Setup contains information and Help screens to guide you through the
 setup process. The Setup Main menu points you to the various Setup
 screens where you can:

   ■  Specify paths and directories for installed files.

   ■  Specify libraries and run-time modules.

   ■  Specify ISAM support.

   ■  Specify files to install (for selective installation of specific
 files or parts of Microsoft BASIC).


 To run Setup, place Disk 1 (Setup) in disk drive A:, type
 a:setup

 at the system prompt, and then follow the instructions on your screen.
 Before running Setup, however, you should keep the following points in
 mind.


 Time Required to Install

 Set aside an uninterrupted block of time. You can exit Setup if you
 need to, but it will not retain any of the options you selected.
 Installing Microsoft BASIC requires anywhere from 30 minutes to three
 hours, depending on the speed of your processor, available disk space,
 and the options you chose. For best performance, you should remove any
 terminate-and-stay-resident (TSR) programs from memory before running
 Setup.

 Setup requires less time if you start it with the /BATCH option, as
 follows:

 A:SETUP /BATCH

 If you use /BATCH, Setup will operate the same way that it does
 without the option, with one exception. Instead of building BASIC
 run-times and libraries automatically, SETUP /BATCH creates a batch file
 named BUILD.BAT. You must run this batch file from the command line to
 complete the installation process.


 Amount of Disk Space Required

 The amount of disk space required varies depending on which features
 you choose to install. However, Setup determines the exact amount of
 space you need before proceeding with installation. It then checks
 available disk space. If you lack sufficient space, Setup prompts you to
 change the number of files to install. If you do not have sufficient
 disk space and you choose to continue, the installation may not be
 successful.


 Custom or Default Configuration

 The first time you install BASIC, you may not be sure which features
 you want to use. If this is the case, you may want to install with the
 default settings. You can always change these settings by running Setup
 again. To install the default configuration, choose Install with Current
 Options from the Setup Main menu, as shown in Figure 2.1, and then
 follow the instructions on your screen.

 I to install default configuration.


 Setup Will Not Install Until You Tell It To

 If you want to install only a few files or you want to change the
 configuration, you can browse through the various Setup screens and
 alter settings. You can spend as much time as you want; Setup takes no
 action until you choose Install with Current Options from the Setup Main
 menu.


 Files Installed

 During installation, Setup places a number of .EXE, .LIB and .OBJ
 files in the directories you specify, as well as documentation and
 sample-code files. Note that Setup may replace existing files.
 Therefore, it is a good idea to have Setup install files only to new
 directories, empty directories, or directories containing software you
 want to update.

 Some of the .OBJ files are stub files. Depending on how you want to
 use BASIC, you might want to delete these files after installation.
 Before doing so, however, you should read the section "How Setup Uses
 Stub Files" later in this chapter.


 After Running Setup

 After you install Microsoft BASIC, you may want to do the following
 tasks:

   ■  Create or modify the TOOLS.INI file

   ■  Modify your environment variables

   ■  Unpack individual files from the distribution disks



 Creating or Modifying TOOLS.INI

 Programmer's WorkBench, CodeView, QuickHelp, and NMAKE, all included
 with Microsoft BASIC, use the TOOLS.INI file for initialization
 information. Setup installs a file named TOOLS.PRE that contains
 preliminary settings for these applications. Setup places TOOLS.PRE in
 the \BC7\BINB directory by default.

 If you don't have an existing TOOLS.INI file, you can rename
 TOOLS.PRE and place it in a directory that is indicated by your INIT
 environment variable.

 If you already have a TOOLS.INI file and you have not previously
 installed any of these applications, you can append TOOLS.PRE to your
 existing TOOLS.INI file. For example:

 C:\INIT> COPY TOOLS.INI + \BC7\BINB\TOOLS.PRE

 If you have previously installed one or more of the applications
 mentioned above, you may want to selectively combine your existing
 TOOLS.INI settings with the additional settings in TOOLS.PRE.

 The TOOLS.PRE file contains information about modifying the initial
 settings for each of the applications. Online Help is also available
 from within PWB, CodeView, and QuickHelp on the TOOLS.INI topic.


 Modifying Your Environment Variables

 Setup creates two files that you can use to change your environment
 variables:

 for DOS, and NEW-VARS.CMD for OS/2. You can run these files from the
 command line, or you can append them to your AUTOEXEC.BAT file (DOS) or
 your CONFIG.SYS file (OS/2).

 If you are installing for OS/2, you should also modify the LIBPATH
 line in your CONFIG.SYS file to include the directory where Setup
 installed BASIC's dynamic-link libraries (DLLs). By default, Setup
 places these files in the \BC7\BINP directory. Since LIBPATH is not part
 of the environment, NEW-VARS.CMD cannot modify it. If you change
 LIBPATH, you will have to restart your system in order for it to take
 effect.


 Unpacking Individual Files

 The files provided on the Microsoft BASIC distribution disks are
 compressed to conserve space. A dollar sign ($) is added to the file
 extension to show that these files must be unpacked before they can be
 used. The file PACKING.LST contains a table showing how the modified
 file extensions correspond to the unpacked files.

 Setup automatically unpacks and installs all of the files you need to
 use the configuration you specified from the Setup menus. You can unpack
 individual files after Setup in order to modify your installation
 without rerunning Setup, to restore a file that was deleted, or to
 provide special support for mixed-language programming with Microsoft C
 version 6.0.

 To unpack a file from a distribution disk, use the following
 syntax:

  UNPACK  packed-filename  unpacked-filename

 For example, to unpack the PWB.HLP file, insert the disk containing
 the file in drive A: and type:

  UNPACK A:PWB.HL$ PWB.HLP

 To find a particular file on the distribution disks, look at the file
 PACKING.LST on Disk 1.


 Special Instructions for Microsoft C Users

 If you have installed Microsoft C version 6.0, you should replace the
 PWB executable files and language extensions provided with C with the
 ones provided with this version of BASIC. BASIC includes a later version
 of these files that supports the use of BASIC and C together in
 mixed-language programs.

 The PWB extensions for the C language, PWBC.MXT and PWBC.PXT, are
 provided with BASIC, but are not installed by Setup. You should unpack
 these files individually from the BASIC distribution disks and use them
 to replace the C-language extensions provided with C version 6.0.


 How Setup Uses Stub Files

 This section explains how you can produce smaller stand-alone
 programs using stub files. If you are eager to use BASIC, you can skip
 this section for now and read it later.

 A "stub file" replaces a BASIC library module with a module that
 performs little or no action. Stub files typically contain a small
 amount of code.

 The advantage of stub files is that if you know that you will never
 use a certain feature in your program (such as support for VGA screen
 modes), you can use the stub file to eliminate code for that feature.
 The result is that your programs require less memory and disk space.

 Stub files can be used for BASIC programs that use the BASIC run-time
 (BRT) module and for BASIC stand-alone executable files.


 Stub Files and the BRT Module

 BASIC programs can use the BRT module to support common routines. The
 use of the BRT module saves disk space by eliminating the need to add
 library routines to every executable file.

 Setup uses stub files to build the BRT module. It uses a different
 stub file (see the following sections) for each feature you decide not
 to support.

 Once installation is complete, most stub files have no further effect
 on the BRT module. You can delete them unless you plan to create
 stand-alone executable files, as described in the next section.


 Stub Files and Stand-Alone Programs

 You can produce stand-alone programs with the BASIC compiler by using
 the /O option. The advantage of stand-alone programs is that the BRT
 module need not be present for the program to run.

 Do not delete stub files if you want to produce stand-alone programs
 that use the smallest amount of memory. When you create a stand-alone
 program, you can specify stub files on the LINK command line. The effect
 is to cancel or reduce support for a feature and thus reduce executable
 size.

 For more information on stub files, see Chapter 15, "Optimizing
 Program Size and Speed," and Chapter 18, "Using LINK and LIB," in the
  Programmer's Guide.


 Graphics Support Stub Files

 The following list summarizes stub files that correspond to items in
 the second Specify Libraries and Run-Time Modules screen, Screen I/O and
 Graphics Support. Setup uses a designated stub file to build the BRT
 module if the corresponding menu item is turned  off
 .

╓┌──────────────┌─────────────┌──────────────┌──────────────┌────────────────╖
 To turn this        Link with        Having this
 option  off    this file           effect
 ────────────────────────────────────────────────────────────────────────────
 Full           TSCNIO sm

 Ctrl-Characte
 r I/O

 Graphic        NOGRAPH.OBJ   Removes
 Screen Mode                  support for
 Support                      all graphics
                              statements
                              and SCREEN


 CGA Graphics   NOCGA.OBJ     Removes
 Modes                         support for
 1-2                    SCREEN


 To turn this        Link with        Having this
 option  off    this file           effect
 ────────────────────────────────────────────────────────────────────────────

 Hercules       NOHERC.OBJ    Removes
 Graphics                     support for
 SCREEN Mode 3                SCREEN


 Olivetti       NOOGA.OBJ     Removes
 Graphics Mode                support for
 4                            SCREEN


 EGA Graphics   NOEGA.OBJ     Removes
 Modes                         support for
 7-10                   SCREEN


 VGA Graphics   NOVGA.OBJ     Removes
 Modes                        support for
 To turn this        Link with        Having this
 option  off    this file           effect
 ────────────────────────────────────────────────────────────────────────────
Modes                        support for
 11-12                  SCREEN







 Miscellaneous Support Stub Files

 The following list summarizes stub files that correspond to items in
 the third Specify Libraries and Run-Time Modules screen:

╓┌──────────────┌─────────────┌──────────────┌──────────────┌────────────────╖
                To link with  Turn this      this stub      Having this
                              option  off    file           effect
 ────────────────────────────────────────────────────────────────────────────
                To link with  Turn this      this stub      Having this
                              option  off    file           effect
 ────────────────────────────────────────────────────────────────────────────
 COM n


 LPT n


 INPUT          NOFLTIN.OBJ   Allows
 Floating-Poin                programs to
 t Values                     contain
                              INPUT


 Transcendenta  NOTRNEM m.

 l Math

 EMS Support    NOEMS.OBJ     Prevents a
 for Overlays                 program
                To link with  Turn this      this stub      Having this
                              option  off    file           effect
 ────────────────────────────────────────────────────────────────────────────
for Overlays                 program
                              linked for
                              overlays from
                              using EMS
                              memory. The


 EVENT          NOEVENT.OBJ   Removes
 Trapping                     support for
                              EVENT


 Full-Power     NOEDIT.OBJ    Limits
 INPUT Editor                 editing when
                              a user enters
                              data in
                              response to
                              an INPUT
                To link with  Turn this      this stub      Having this
                              option  off    file           effect
 ────────────────────────────────────────────────────────────────────────────
                             an INPUT


 Detailed       SMALLERR.OBJ  Reduces
 Error                        length of
 Messages                     run-time
                              error
                              messages.






 Other Special Files Installed by Setup

 In addition to stub files, Setup may install two other special files,
 depending on the configuration chosen. Both these files correspond to
 options in the third Specify Libraries and Run-Time Modules screen. As
 with stub files, Setup builds these files directly into the BRT module,
 but unlike stub files, you must turn the corresponding menu items on
  in order to link with the files. If you want to use them in a
 stand-alone program, include them on the command line when you link the
 program.

╓┌──────────────┌─────────────┌──────────────┌──────────────┌────────────────╖
                To link       Turn this      with this      Having this
                              option  on     file           effect
 ────────────────────────────────────────────────────────────────────────────
 Math           87.LIB        Provides most
 Coprocessor                  direct
 Required                     support for
                              machines that
                              have an
                              8087-family


 Overlays in    OVLDOS21.OBJ  Required for
 DOS 2.1                      a program
                To link       Turn this      with this      Having this
                              option  on     file           effect
 ────────────────────────────────────────────────────────────────────────────
DOS 2.1                      a program
                              with overlays
                              to work under
                              DOS 2.1.-






 Where to Go If You Need Additional Help

 If you need additional help with any of the options in the Setup
 program, you can use the following table to locate information in the
 printed documentation. If you just need a quick overview of the new
 features in Microsoft BASIC, be sure to read Chapter 1, "New Features,"
 if you haven't already done so.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
 For information on                See
 ────────────────────────────────────────────────────────────────────────────
 ISAM                               Programmer's Guide,

 Near and far strings               Programmer's Guide,

 Alternate and emulator math        Programmer's Guide,

 Overlays                           Programmer's Guide,

 Compiler options                   Programmer's Guide,

 Stub files                         Programmer's Guide,

 Add-on libraries                   BASIC Language Reference,

 Toolboxes                          BASIC Language Reference,





 ────────────────────────────────────────────────────────────────────────────


 Chapter 3  Using QuickBASIC Extended
 ────────────────────────────────────────────────────────────────────────────

 The QuickBASIC Extended (QBX) environment is a powerful tool for
 developing BASIC applications under DOS. This chapter introduces the QBX
 environment and covers the following information to get you started:

   ■  Starting QBX and using the default editing and command keys.

   ■  Creating and moving around in a program.

   ■  Compiling programs from within QBX.

   ■  Using symbol Help, watches, watchpoints, breakpoints, and CodeView
 support to locate and resolve errors in your program.

   ■  Adding items to the menu bar and changing the default editing and
 command key assignments.

   ■  Using the QBX command-line syntax.


 Running QBX

 To start QBX, type the following at the system prompt:

  QBX

 Figure 3.1 shows the QBX environment.



 All environment tasks within QBX can be accomplished by using either
 the mouse or the keyboard. The following table lists commonly used key
 combinations by category and task.

╓┌─────────────┌────────────┌───────────────────────────┌────────────────────╖
 Category                   To do this                  Press
 ────────────────────────────────────────────────────────────────────────────
 Edit                       Open a program              Alt+F, O
                            Save a program              Alt+F, S
                            Select text                 Shift+direction key
                            Copy selected text          Ctrl+Ins
                            Cut selected text           Shift+Del
                            Cut a single line           Ctrl+Y
                            Paste copied or cut text    Shift+Ins
                            Search for selected text    Ctrl+/
                            Repeat last search          F3
 Debug                      Execute program             Shift+F5
                            Execute to cursor position  F7
                            Execute next statement      F8
                            Execute next procedure      F10
                            Continue execution          F5
                            Add instant watch           Shift+F9
                            Set/clear a breakpoint      F9
 View/Windows  Next window  F6
                            Previous window             Shift+F6
                            View a SUB                  F2
 Category                   To do this                  Press
 ────────────────────────────────────────────────────────────────────────────
                           View a SUB                  F2
                            View the next SUB           Shift+F2
                            Display/hide output screen  F4
 Help                       Help on a topic             F1
                            Help on using Help          Shift+F1
                            Exit Help                   Esc
                            Redisplay last Help         Alt+F1




 Writing a Program

 After you start QBX, you can immediately begin writing a program. As
 you enter BASIC functions and statements, QBX interprets them and checks
 the syntax of each line. If you make a syntax error, QBX displays an
 error message dialog box and you must choose OK or press Esc to
 continue. QBX only checks for errors in syntax; to detect errors in
 logic, you must run your program. For example, type the following:

  Now = TIME$

 Press F5 to execute the program. QBX highlights  TIME$
  and displays a "Type mismatch" error. Choose OK and correct the line to
 read:

  Now$ = TIME$

 Now the program will execute without an error.

 QBX organizes your program by separating different procedures (SUB
 s and  FUNCTION
 s). When you save your program, QBX automatically adds DECLARE
  statements as needed. For example, type the following:

  SUB PrintTime

 When you press Enter, QBX creates a new procedure with SUB
 and  END SUB statements in the current window as follows:

 SUB PrintTime

 END SUB

 To see the organization of the program, press F2. QBX displays the
 View SUBs dialog box. This dialog box lets you move between procedures
 and the main module of your program. Press Esc to return to the
 PrintTime procedure.

 Add the following infinite loop between the  SUB and  END SUB
 statements:

  DOCLS
 LOCATE 2, 1
 PRINT "The time is: "; TIME$;
 SLEEP 1


 Now choose Split from the View menu to open another window. Display
 the main module in the top window by typing Shift+F2 (View Next SUB).
 After the last statement in the main module, type:

  CALL PrintTime
 Run the program by pressing F5.

 Press Ctrl+Break to interrupt the infinite loop and return to QBX.
 QBX highlights the last instruction executed (in this case, LOOP
 ).

 To save the program you just created:

    1.From the File menu, choose Save.

    2.Type the filename TIME.BAS, select Text Format, and press Enter.
 saves the file as text. Text format files can be used by PWB,
 CodeView, and other tools. Binary format files can only be used by QBX
 and the BASIC Compiler.


 Exit QBX by choosing Exit from the File menu. You can view the file
 you just saved by typing the following command from the command
 line:

  TYPE TIME.BAS

 The system displays the file as follows:
 DECLARE SUB PrintTime ()
 Now$ = TIME$
 Call PrintTime

 SUB PrintTime
     LOCATE 2
     PRINT "The time is: " + TIME$
     SLEEP 1
 END SUB

 Notice that QBX adds a  DECLARE statement and puts procedures
 after the main module in the file when it saves the file.


 Other Statements Added by QBX

 In addition to the  DECLARE statement, QBX automatically adds a
  DEF type statement to procedures under certain conditions.
 For example, if you start your program with a

 A-Z statement, QBX adds a copy of that statement to the beginning of
 each new procedure you create.

 If your program has existing procedures when you add a DEF type
 statement to the main (calling) module, those procedures are not changed.
 Only new procedures get the automatic  DEF type
 statements.

 Since the default data type in BASIC is single-precision, QBX will
 add a  DEFSNG statement to any previously existing procedures
 that did not already have a  DEF type statement.
 These statements can only be seen by saving the file as text and
 viewing it outside QBX. For this reason, it is a good idea to start
 your program with a  DEF type statement.


 Using the Immediate Window

 The Immediate window at the bottom of the screen in QBX is a useful
 tool for executing a few lines of BASIC code without running the
 currently loaded program. Each line that you type in the Immediate
 window is executed when you press Enter. For example:

 Run QBX. Press F6 to move the cursor to the Immediate window, and
 type:

  CLS"Today's date is: " + DATE$

 Each time you press Enter at the end of a line, QBX executes that
 line of code and displays the output screen. You can cut lines from your
 program and paste them into the Immediate window. You can then scroll to
 the beginning of the pasted line and execute them one at a time by
 pressing Enter after each.

 Lines typed in the Immediate window are not saved with your program.
 When you exit QBX, the Immediate window is cleared.


 Using Quick Libraries

 QBX uses special-format libraries called Quick libraries to make
 common routines available within the environment. To use a Quick
 library, you must specify it with the /L option when you start QBX. For
 example:

 QBX /L CHRTBEFR.QLB

 This command line starts QBX and loads the Presentation Graphics
 Quick library. The Presentation Graphics routines will be available to
 programs as you work in the environment.

 For more information on Quick libraries, see Chapter 19, "Creating
 and Using Quick Libraries," in the  Programmer's Guide.

 Important

 Quick libraries created for QuickBASIC version 4.5 or earlier must be
 recreated from the original source code, and non-BASIC routines included
 in Quick libraries may need rewriting or relinking. For programming
 considerations when writing Quick libraries and instructions on creating
 Quick libraries, see Chapter 19, "Creating and Using Quick Libraries,"
 in the  Programmer's Guide.


 Compiling a Program

 To compile a program from QBX, load a BASIC source file and choose
 Make EXE from the Run menu. Figure 3.2 shows the Make EXE File dialog
 box that QBX displays.


 By default, QBX uses the compiler options that cause your compiled
 program to run the way that it is interpreted within QBX. If a Quick
 library is loaded, QBX uses /O, /Ot, /Fs, /Lr, /FPi, /T, and /C:512 by
 default. If a Quick library is not loaded, QBX uses /O, /Ot, /Lr, /FPa,
 /T, and /C:512. For descriptions of the BASIC Compiler options, see
 online Help or Chapter 16, "Compiling with BC," in the
 Programmer's Guide.

 To change these defaults, you can select any of the displayed
 compiler options or you can type additional options in the Additional
 Options field.

 When you select Make EXE from the Make EXE File dialog box, QBX
 shells to DOS and runs the BASIC Compiler and LINK to build the
 executable file. If you have a Quick library loaded, QBX links your
 program with the object module library (.LIB) with the same base name as
 the loaded Quick library (.QLB).

 If an error occurs when compiling or linking, the build halts and the
 error is displayed; you can press any key to return to QBX.

 If the build is successful, you are returned to QBX.


 Debugging a Program

 To help locate errors in program logic, QBX provides the following
 features:

   ■  Symbol Help
   ■  Watches
   ■  Watchpoints
   ■  Breakpoints
   ■  CodeView support


 Symbol Help

 When you ask for Help on a symbol, QBX displays a schematic of where
 and how that symbol is used in your program. Figure 3.3 shows the Help
 screen that is displayed when you ask for Help on the Answer symbol in
 the BOOKLOOK.BAS program.



 Symbol Help is useful for resolving type mismatch errors and
 duplicate symbol names. Getting Help on a symbol makes it easy to
 determine a symbol's data type and the procedures in which it is
 used.


 Watches

 Watches let you observe the value of an expression as your program
 executes. This is especially helpful when your program yields unexpected
 results. Placing a watch on an expression and stepping through the
 program can help you locate where the problem is occurring.

 To add a watch:

    1.  Select the expression you want to observe.

    2.  From the Debug menu, choose Add Watch.
 expression's name and current value are displayed in a one-line
 window immediately below the menu bar.


 As you run your program, QBX updates the value in the Watch window
 whenever the value of the expression changes. For example, set a watch
 on N% in the following lines of code:

 FOR N% = 0 to 10 STEP 5
 NEXT N%

 Step through the procedure by pressing F8 five times. The value of N%
 displayed in the Watch window changes from 0 to 5 to 10.

 You can set an instant watch to view the current value of an
 expression without adding a watch. An instant watch shows only the
 current value of the expression.

 To set an instant watch:

    1.  Select the expression to view.

    2.  From the Debug menu, choose Instant Watch.
 The current value of the expression is displayed in a dialog box.

    3.  Choose Cancel to exit the dialog box without adding
 a watch or press Enter to add a watch for the expression.


 To remove a watch, choose Delete Watch from the Debug menu, then
 select the watch to remove.

 To remove all watches, choose Delete All Watch from the Debug
 menu.


 Watchpoints and Breakpoints

 "Watchpoints" are conditional statements that stop program execution
 when an expression is true (nonzero). "Breakpoints" are markers that
 stop program execution at a fixed location in the program. Watchpoints
 and breakpoints make it easier to get to a specific point in the logic
 or structure of the program while debugging.

 To set a watchpoint:

    1.  Select the expression to watch.

    2.  From the Debug menu, choose Watchpoint.
 When you run the program by pressing F5, QBX will halt the program and
 take you to the current statement as soon as the value of the expression
 becomes nonzero.



 To remove a watchpoint:

    1. From the Debug menu, choose Delete Watch.

    2. Select the watchpoint to remove and press Enter.



 To set a breakpoint:

    1. Place the cursor on a line of code where you want the program to stop
 executing.

    2. From the Debug menu, choose Toggle Breakpoint.
 When you run the program by pressing F5, QBX will halt the program as soon
 as it reaches line of code with the breakpoint.


 To remove a breakpoint, place the cursor on the line with the
 breakpoint and choose Toggle Breakpoint from the Debug menu.


 CodeView Support

 To use CodeView with programs created in QBX, you must save the
 source file in text format. CodeView cannot interpret files saved in QBX
 binary format.

 After saving your program, compile it specifying the CodeView option
 (/Zi or /Zd). You can then load the file into CodeView from the command
 line. For information on getting started with CodeView, see Chapter 5,
 "Using CodeView." For detailed information about the CodeView
 environment and how expressions are evaluated in CodeView, see the
 CodeView online Help.


 Customizing the Environment

 You can add items to the menu bar and remap key assignments within
 the QBX environment.


 Adding Items to the Menu Bar

 To add an item to the menu bar:

    1. From the Utility menu, choose Customize Menu.

    2. Select Add from the Customize Menu dialog box.

    3. Type the appropriate information in the displayed fields,
 and choose OK. For information about the field in the Customize Menu
 dialog box, press F1.


 The new item will appear on the Utility menu.


 Remapping Key Assignments

 The default QBX editing and command keys can be modified by loading
 one of the following files with the /K: option when you start QBX:

╓┌───────────────────┌───────────────────────────────────────────────────────╖
 Load this file      To change settings to those for this editor
 ────────────────────────────────────────────────────────────────────────────
 ME.KEY              Microsoft Editor
 BRIEF.KEY           BRIEF
 EPSILON.KEY         Epsilon
 QBX.KEY             QBX




 For example, to change the default settings to those of the Microsoft
 Editor, start QBX with the following command line:

  QBX /k:ME.KEY

 When you change the default key settings, the change is saved in
 QBX.INI and those settings become the new default.

 You can further customize these key assignments by using the MKKEY
 utility as follows:

    1.  Decode the key assignment file. For example:
 MKKEY -c ba -i QBX.KEY -o MYKEY.TXT

    2.  Edit the decoded file (in this case, MYKEY.TXT).

    3.  Encode the modified key assignment file. For example:
 MKKEY -c ab -i MYKEY.TXT -o MYKEY.KEY

    4.  Load the new key assignment file in QBX. For example:
 QBX /k:MYKEY.KEY


 For more information on customizing key assignments, see the online
 Help topic "Configuring Keys" from the Help table of contents in QBX.
 For more information about MKKEY, see Appendix C in the  BASIC Language
 Reference.


 Controlling the Environment

 You can control various aspects of the environment by using the QBX
 command-line options. The QBX command line has the following syntax:

 QBX  options  programname /CMD  string

╓┌───────────────────────────────────────┌───────────────────────────────────╖
 Option                                  Short description
 ────────────────────────────────────────────────────────────────────────────
 /AH                                     Allows dynamic arrays of records,
                                         fixed-length strings, and


 /B                                      Displays QBX in black and white.

 /C:  buffersize                         For use with the  OPEN COM
                                         statement. Sets the size of the
                                         buffer

 Option                                  Short description
 ────────────────────────────────────────────────────────────────────────────


 /Ea                                     Allows arrays in expanded memory.
                                         Do not use /Ea with the /Es


 /E: n                                   Limits the amount of expanded
                                         memory reserved for QBX use. If
                                         /E:


 /Es                                     Shares expanded memory between QBX
                                         Quick library and


 /G                                      Sets QBX to update a CGA screen as
                                         quickly as possible.

 /H                                      Displays the highest resolution
 Option                                  Short description
 ────────────────────────────────────────────────────────────────────────────
/H                                      Displays the highest resolution
                                         possible on your hardware.

 /K: keyfile                             Specifies a user-configurable key
                                         file to be loaded into QBX.

 /L  libraryname                         Loads a Quick library. If
                                         libraryname


 /MBF                                    Causes the QBX conversion
                                         functions to treat IEEE-format
                                         numbers


 /Nofrills                               Makes additional memory available
                                         for program use by reducing the


 Option                                  Short description
 ────────────────────────────────────────────────────────────────────────────

 /NOHI                                   Allows the use of a monitor that
                                         does not support high intensity.


 /CMD  string                            Passes string to the  COMMAND$
 function.




 ────────────────────────────────────────────────────────────────────────────


 Chapter 4  Using Programmer's WorkBench
 ────────────────────────────────────────────────────────────────────────────

 The Programmer's WorkBench (PWB) is an advanced development
 environment that features a powerful editor and integrates the compiler,
 LINK, NMAKE, and the CodeView debugger. PWB is intended for tasks, such
 as developing under OS/2, that are not supported by QBX. Unlike QBX, PWB
 does not interpret BASIC code. This means that some features available
 in QBX, such as the Immediate window and executing a program
 line-by-line, are not available. In PWB, you must use CodeView to debug
 programs.

 This chapter explains how to perform the following tasks:

   ■  Starting PWB and using keyboard commands.

   ■  Loading and saving a file, setting or clearing a program list, and
 using special features (such as marks and anchors) to help you write and
 modify your programs.

   ■  Selecting build options and creating an executable file.

   ■  Preparing a file for debugging, viewing compiler errors, using the
 source browser, and invoking CodeView.

   ■  Changing the default settings and key assignments, creating macros,
 and reducing the time it takes PWB to load.

   ■  Using the PWB command-line syntax.


 Note

 Setup installs PWB only if you choose to install mixed-language tools
 from the Specify Files to Install menu during Setup. If you did not
 choose mixed-language tools and you wish to use PWB, you should run
 Setup again with the mixed-language tools option chosen.


 Running PWB

 To start PWB for the first time, type:

  PWB

 Figure 4.1 shows the PWB environment.



 Important

 PWB includes extensive online Help. If you request Help and get an
 error message indicating that no Help files were open or that they could
 not be found, check your HELPFILES environment variable. HELPFILES can
 be set by running NEW-VARS.BAT (DOS) or

 (OS/2) from the command line before starting PWB. HELPFILES can also
 be set from within PWB by choosing Environment from the Options menu. If
 you set HELPFILES from within PWB, that setting will not have an effect
 in CodeView.

 Within PWB, environment tasks can be accomplished by using either the
 mouse or the keyboard. The following table lists commonly used default
 key combinations by category and task:

╓┌──────────────────┌──────────────────┌──────────────────┌──────────────────╖
 Category                              To do this         Press
 ────────────────────────────────────────────────────────────────────────────
 Category                              To do this         Press
 ────────────────────────────────────────────────────────────────────────────
 Edit                                  Select text        Shift+direction
                                                          key

                                       Copy selected      Ctrl+Ins
                                       text

                                       Cut selected text  Shift+Del

                                       Cut a single line  Ctrl+Y

                                       Paste copied or    Shift+Ins
                                       cut text

                                       Undo previous      Alt+Backspace
                                       edit

                                       Redo edit          Ctrl+Backspace

                                       Search forward     F3
 Category                              To do this         Press
 ────────────────────────────────────────────────────────────────────────────
                                      Search forward     F3

                                       Search backward    F4

 File operations    Open a program     Alt+F, O

                                       Save a program     Shift+F2

                                       Exit (save         Alt+F4
                                       changes)

                                       Quit (abandon      F9, F8
                                       changes)

                                       Refresh (abandon   Shift+F7
                                       changes)

                                       Load previous      F2
                                       file
 Category                              To do this         Press
 ────────────────────────────────────────────────────────────────────────────
                                      file

                                       Shell to system    Shift+F9

 Debug/Browse       Next               Ctrl+Num+
                    definition/refere
                    nce

                                       Previous           Ctrl+Num-
                                       definition/refere
                                       nce

                                       Next build error   Shift+F3

                                       Previous build     Shift+F4
                                       error

 Windows                               Next window        F6

 Category                              To do this         Press
 ────────────────────────────────────────────────────────────────────────────

                                       Previous window    Shift+F6

                                       Resize a window    Ctrl+F8

                                       Maximize a window  Ctrl+F10

 Help                                  Get Help on a      F1
                                       topic

                                       View table of      Shift+F1
                                       contents

                                       Exit Help          Esc

 Redisplay last     Alt+F1
 Help






 Writing a Program

 After you start PWB, you can immediately begin writing source code in
 the window that appears. PWB supports programming in BASIC, C, and other
 Microsoft languages. Unlike QBX, PWB does not interpret your program as
 you write it. Also unlike QBX, PWB does not check your BASIC syntax or
 automatically add  DECLARE  statements as you write your
 program. To check syntax in PWB, you must compile your program and view
 the compile results. For more information on how to do this, see the
 sections "Compiling and Linking a Program" and "Debugging a Program"
 later in this chapter.


 Loading and Saving a File

 To load a file in PWB, you can either type the filename on the
 command line when you start PWB or choose Open from the File menu within
 PWB.


 Note

 If you are planning to use PWB in combination with QBX, you must save
 your source files in text format from QBX before you try to load them in
 PWB. PWB cannot use files saved in QBX binary format.

 To save a file, choose Save from the File menu.

 PWB maintains a history of the files you have opened, which is
 displayed at the bottom of the File menu. To return to a file displayed
 in this list, choose its name from the File menu. Figure 4.2 shows the
 File menu with several files in history.



 When you edit a file and then exit PWB, the environment saves a list
 of the files you worked on in a special file named CURRENT.STS. PWB
 creates CURRENT.STS in the first directory indicated by your INIT
 environment variable. The next time you run PWB, it automatically opens
 the last file you worked on unless you explicitly specify a filename on
 the command line or use the /D or /DS options. For PWB command-line
 syntax and options, see the section "Controlling the Environment" later
 in this chapter.


 Navigating in a File

 PWB provides marks and anchors to help you navigate and edit large
 files. A "mark"
 is an invisible placeholder that you can set at a specified location in
 a file to go to that location quickly in the future. An "anchor" is a
 placeholder that determines the boundary of a block of selected text to
 cut, copy, or delete.


 Setting and Using Marks

 To set a mark:

    1. Place the cursor at the location you want to mark, then
 choose Define Mark from the Search menu.
 PWB displays the Define Mark dialog box.

    2. Type a name that you want to assign to the mark and press
 Enter. Note that spaces are not allowed in mark names.



 To go to a mark:

    1. From the Search menu, choose Goto Mark.
 displays the Go To Mark dialog box.

    2. Select the mark from the displayed list and choose OK.



 Creating and Using a Mark File

 Marks created as shown in the preceding section are temporary and are
 erased when you exit PWB. To create marks that can be reused, you must
 create a mark file or select an existing one before setting your
 marks.

 To create a new mark file:

    1. From the Search menu, choose Set Mark File.
 PWB displays the Set Mark File dialog box.

    2.Type the name of the mark file you wish to create and press
 Enter. (The mark file should have an .MRK file extension to help you
 identify it in the future.)

 PWB displays a dialog box asking if you want to create the file.

    3. Choose Yes.



 To select an existing mark file:

    1. From the Search menu, choose Set Mark File.
 PWB displays the Set Mark File dialog box.

    2. Select a mark file from the displayed list and choose OK.



 After you create a new mark file or select an existing one, it
 becomes the current mark file and any temporary marks are cleared. When
 you set new marks, they are added to the current mark file by
 default.


 Setting and Using Anchors

 Anchors help you select large blocks of text to cut, copy, or
 delete.

 To set an anchor, place the cursor at the position you wish to anchor
 and choose Set Anchor from the Edit menu. You can only set one anchor at
 a time; moving the cursor and choosing Set Anchor again resets the
 anchor to the new position.

 To select text between the current cursor position and the anchor,
 choose Select To Anchor from the Edit menu. PWB highlights the selected
 text.


 Programming with Multiple Files

 To work on a project containing multiple files, you must create a
 program list. A "program
 list" is a special PWB file that contains the build instructions and
 filenames for a project.

 To create a program list:

    1 From the Make menu, choose Set Program List.
 PWB displays the Set Program List dialog box.

    2. Type the name of the program list you wish to create and
 press Enter. (The filename should have an .MAK file extension to help you
 identify it in the future.)

 PWB displays a dialog box asking you if you want to create the file.

    3. Choose Yes.
 PWB displays the Edit Program List dialog box.

    4. Select the files to include in the project from the
 displayed list. Do not select BASIC include files (.BI), since they
 will be included when the program is compiled.

    5. Choose OK when you are done.



 Build options are maintained in a state file that is maintained along
 with the .MAK file. A "state file" is a file containing information
 about the PWB editing session, such as current build options and file
 history. The state file maintained with a .MAK file has the same base
 name as the .MAK file, but has a .STS filename extension. When you set a
 program list, build options revert to those last saved in the state
 file. For information on setting build options, see the section
 "Compiling and Linking a Program" later in this chapter.

 To use an NMAKE .MAK file in PWB, follow the procedure used to create
 a program list, but select the Use as a Non-PWB Makefile checkbox in the
 Set Program List dialog box before you press Enter in step 2.


 Note

 PWB .MAK files are not compatible with QBX .MAK files and vice versa.
 If you are working on a project in both environments, you should create
 a different .MAK file for each environment.


 Compiling and Linking a Program

 Executable files can be created directly from the PWB environment.
 Options can be saved for debug and release versions of the executable
 file. All of the environment, compiler, and LINK options are set from
 the Options menu.


 Changing Environment Variables

 To change environment variables from those in effect when PWB was
 run:

    1. From the Options menu, choose Environment.
 PWB displays the Environment Options dialog box.

    2. Type the new environment variables in the fields provided.
 Press Tab to move to the next option, and press Enter when you are done.



 The new environment variables take effect immediately and remain in
 effect until you exit PWB. To make permanent changes to environment
 variables, edit your AUTOEXEC.BAT file (DOS) or your CONFIG.SYS file
 (OS/2).


 Setting Debug or Release Version

 PWB maintains lists of debug and release options for compiling and
 linking a program. By default, debug options create an executable file
 for use with CodeView; release options create an optimized executable
 file without CodeView information. Setting release or debug version
 makes it easy to switch between the two sets of options quickly.

 To set whether the executable file will be a debug version or a
 release version:

    1. From the Options menu, choose Build Options.
 PWB displays the Build Options dialog box.

    2. Select Debug or Release from the dialog box.

    3. Choose OK.



 Debug and release version options are set from the compiler and LINK
 options dialog boxes. To change compiler and LINK options for debug or
 release versions, see "Setting Compiler Options" and "Setting LINK
 Options" later in this chapter.


 Setting Main Language and Initial Build Options

 Since PWB is a mixed-language programming environment, many of the
 build options that are valid in some languages are not valid in others.
 PWB provides you with a way to set a main programming language and to
 create default build options based on the target environment. When
 working with BASIC, you should always leave Main Language set to BASIC.
 When working exclusively in another language, such as C, you will want
 to change the Main Language.

 To change the Main Language:

    1. From the Options menu, choose Build Options.
 PWB displays the Build Options dialog box.

    2. Select Set Main Language.
 PWB displays the Set Main Language dialog box.

    3.Select a language from the displayed list, and choose OK.

    4.Select Set Initial Build Options box.
 PWB displays the Set Initial Build Options dialog box.

    5.Select the line from the displayed list that best describes the
 executable file you want to build, and choose OK.

    6.Choose OK again.



 Three valid initial build options are provided for BASIC. You can
 save your current build options to create a new group of initial build
 options that you can use with future projects. To create a new group of
 initial build options for BASIC:

    1. Set Main Language to BASIC (see the preceding procedure).

    2. Set the build options. These include the settings for the debug
 and release versions of compiler, LINK, and Source Browser options.

    3. From the Options menu, choose Build Options.
 PWB displays the Build Options dialog box.

    4. Select Save Current Build Options.
 PWB displays the Save Current Build Options dialog box.

    5. Type a name to identify your current build settings,
 and press Enter.

    6. Choose OK.


 PWB saves initial build options in your state file. (For more
 information on state files, see the section "Reducing Load Time" later
 in this chapter.) After initial build options are saved, they are
 available from the Set Initial Build Options dialog box.


 Setting Compiler Options

 To set the BASIC compiler options within PWB:

    1. From the Options menu, choose BASIC Compiler Options.
 PWB displays the BASIC Compiler Options dialog box.

    2. Select the appropriate displayed options, then select Set Debug
 Options or Set Release Options.

    3. Select the appropriate options from the BASIC Compiler Debug/Release
 Options dialog box, and choose OK.

    4. Type any additional options you wish to specify in the Additional
 Options field, and choose OK.



 Note

 It is possible to set options in the Additional Options field that
 conflict with the options specified in the BASIC Compiler Options dialog
 box. Conflicting options will cause the compile to fail.


 Setting LINK Options

 To set LINK options within PWB:

    1. From the Options menu, choose LINK Options.
 PWB displays the LINK Options dialog box.

    2. Select the appropriate displayed options, then select Set Debug
 Options or Set Release Options.

    3. Select the appropriate options from the LINK Debug/Release Options
 dialog box, and choose OK.

    4. Type any additional options or libraries you wish to specify in the
 Additional Libraries and Additional Options fields, and choose OK.


 Note

 Some LINK options, such as /INCREMENTAL and /TINY, are not valid for
 BASIC and will cause the build to fail. For a list of the valid LINK
 options and their uses, see Chapter 18, "Using LINK and LIB," in the
  Programmer's Guide.


 Building an Executable File

 PWB offers four choices from the Make menu for building an executable
 file. These selections allow you to:

   ■  Compile or compile and link a single file.

   ■  Compile changed files and relink with unchanged object files in a
 project.

   ■  Compile and link all files (changed and unchanged) in a project.


 For information on creating a project, see the section "Programming
 with Multiple Files" earlier in this chapter.


 Compiling a Single File

 Compiling a single file can be used as a first step in debugging a
 new program or as preparation for compiling and linking files in a
 program list.

 To compile a single file:

    1. Open the file to be compiled.

    2. Set the compiler options.

    3. From the Make menu, choose Compile File.
 PWB compiles the file. Any errors, are displayed in the Compile Results
 window.

    4. PWB displays a dialog box confirming that the compile has
 completed. Select one of the buttons or press Esc to return to the active
 window.



 Compiling and Linking a Single File

 To compile and link a single-file program:

    1. Open the file to compile and link.

    2. Set build, compiler, and link options as needed.

    3. From the Make Menu, choose Build or Rebuild All. The Build
 command recompiles the file if it has changed since it was last compiled,
 then links the file with the appropriate library to create an executable
 file. Rebuild All compiles the file whether or not it has changed, then
 links the file with the appropriate library to create an executable
 file.

 If the build fails, PWB displays compile or LINK errors in the Compile
 Results window.

    4. PWB displays a dialog box confirming that the build has completed.
 Select one of the buttons or press Esc to return to the active
 window.



 Compiling and Linking Files in a Project

 PWB gives you two options for compiling and linking the files in a
 project: you can recompile only files that have changed and link with
 unchanged object files, or compile and link all files whether or not
 they have changed.

 To compile and link files in a project:

    1. Set or create a program list for the project (see "Programming
 with Multiple Files" earlier in this chapter).

    2. Set build, compiler, and link options as needed.

    3. From the Make Menu, select Build or Rebuild All. Build compiles
 only changed files in the project and links them with existing (unchanged)
 object files. Rebuild All compiles and links all files in the project.

 If the build fails, PWB displays compile or LINK errors in the Compile
 Results window.

    4. PWB displays a dialog box confirming that the build has completed.
 Select one of the buttons or press Esc to return to the active window.


 The preceding procedure uses the same compiler options for all files
 in the program list. To build a project using different compile options
 for a single file within that project:

    1. From the Make menu, choose Clear Program List.

    2. From the File menu, choose Open to open the file to compile.

    3. Set the compiler options for the file.

    4. From the Make menu, choose Compile.

    5. From the Make menu, choose Set Program List and select the program
 list for the project.

    6. From the Make Menu, choose Build.
 PWB does not recompile the file you compiled in step 4, since it has not
 changed. It will, however, recompile any changed files using the compile
 options last set for the program list, then link the objects with the
 appropriate library to create an executable file.



 Debugging a Program

 PWB provides the following diagnostic tools to help you locate
 errors, debug, and maintain your programs:

   ■  Compile Results window

   ■  Source browser

   ■  CodeView support



 Viewing Compiler Results

 If errors occur when you compile or build a program, PWB displays the
 errors in the Compile Results window, as shown in Figure 4.3.


 PWB automatically takes you to the location in your source file where
 the first error occurred. To go to the next error, press Shift+F3. To
 return to the previous error, press Shift+F4.

 To close the Compiler Results window, choose Compile Results from the
 View menu.


 Using the Source Browser

 The PWB Source Browser provides a way to view relationships within a
 program and to quickly locate specific procedures, variables, and
 constants.

 In order to use the Source Browser, it must be turned on before
 compiling and linking. Once the Source Browser is on and the program has
 been compiled and linked, the selections on the Browse menu become
 active. The Browse menu is shown in Figure 4.4.


 Browser Terminology

 Since the Source Browser can be used with programs written in
 languages other than BASIC, some of the terms the Browser uses to refer
 to symbols may not be familiar. Keep in mind the following
 equivalents:

╓┌───────────────────────────────┌───────────────────────────────────────────╖
 Source Browser term             BASIC equivalent
 ────────────────────────────────────────────────────────────────────────────
 Source Browser term             BASIC equivalent
 ────────────────────────────────────────────────────────────────────────────
 Functions                       Procedures ( SUB

 Types                           User-defined types
 Macros                          Constants




 Turning On the Source Browser

 To generate information for the PWB Source Browser, you must turn on
 browse information and compile the program:

    1. From the Options menu, choose Browse Options.
 PWB displays the Browse Options dialog box.

    2. Select Generate Browse Information and any additional options.

    3. Choose OK.

    4. Compile and link the program.


 By default, PWB creates full browser information by compiling with
 the /FBx option. The /FBx option generates browser information for
 global and local definitions. To generate information for global
 definitions only, thus reducing the size of the resulting Browser files,
 you can perform the following steps before compiling and linking:

    1. From the Options menu, choose BASIC Compiler Options.
 PWB displays the BASIC Compiler Options dialog box.

    2. Select Set Debug Options or Set Debug/Release Options.

    3. From the Set Options dialog box, choose Restricted Browse Info /FBr,
 and choose OK.

    4. Choose OK again.


 When you compile and link from PWB with the Source Browser turned on,
 the BASIC compiler generates a Browser information file with an .SBR
 extension. PWB then uses PWBRMAKE.EXE to convert this file into one
 which the Browser can read. This new file has a .BSC file extension.


 Locating Program Symbols

 The Source Browser helps you quickly find where procedures,
 variables, user-defined types, and constants are defined and referred
 to.

 To locate a definition:

    1. From the Browse menu, choose Goto Definition.
 PWB displays the Goto Definition dialog box as shown in Figure 4.5.

    2. Select the item you wish to locate from the Names list box.
 PWB displays the locations where the definition occurs in the Defined in:
 list box.

    3. Select the occurrence of the definition you wish to go to
 from the  Defined in: list box.

    4. Choose OK.

 PWB takes you to the location in the file where the selected definition
 occurs.




 To locate a reference:

    1. From the Browse menu, choose Goto Reference.
 PWB displays the Goto Reference dialog box.

    2. Select the item to locate from the Names list box.
 PWB displays the locations where the reference occurs in the Referenced
 in: list box.

    3. Select the occurrence of the reference you wish to go to
 from the  Referenced in: list box.

    4. Choose OK.
 PWB takes you to the location in the file where the selected reference
 occurs.


 To go to the next reference or definition of a symbol, press
 Ctrl+Keypad Plus Sign (+).

 To return to the previous reference or definition of a symbol, press
 Ctrl+Keypad Minus Sign (-)


 Viewing Relationships Between Symbols

 The Source Browser helps you view relationships between procedures,
 variables, user-defined types, and constants. These relationships
 include where a symbol is defined and used, where a procedure is called,
 what calls are made by a procedure or module, etc.

 To view how a single symbol relates to the rest of the program:

    1. From the Browse menu, choose View Relationship.
 PWB displays the View Relationship dialog box, as shown in Figure
 4.6.

    2. Select Program Symbols from the Operation list box.

    3. Select the symbol you want to view from the list box.

    4. Select the operation you want to perform from the Operation list
 box.

    5. Choose OK.


 To redisplay all the symbols, select Program Symbols from the
 Operation list box and choose OK.


 To view a listing of the different types of symbols and where they
 are used:

    1. From the Browse menu, choose List References.
 PWB displays the List References dialog box.

    2. Select the types of symbols to list.

    3. Choose OK.
 PWB creates a file named  containing the call tree and displays
 it in the active window, as shown in Figure 4.7.

 To view an outline of where procedures are called (referred to as a
 "call tree"):

    1. From the Browse menu, choose Call Tree.
 PWB displays the Call Tree dialog box.

    2. Select a file to view from the Files list box or a procedure
 to view from the Functions list box.

    3. Choose OK.
 PWB creates a file named  containing the listing and displays it
 in the active window, as shown in Figure 4.8.


 To view an outline of a program:

    1. From the Browse menu, choose Outline.
 PWB displays the Outline dialog box.

    2. Select the file to view from the File List list box.

    3. Select the type of symbols you want to include in the
 outline from the options under the Show Only label.

    4. Choose OK.
 PWB creates a file named  containing the outline and displays it
 in the active window, as shown in Figure 4.9.



 Hint

 By default, the  file replaces the current program file in
 the active window. You can set PWB to create a new window for the
 file by choosing Split Window from the Browse menu before
 viewing symbol relationships.


 Using CodeView

 To start CodeView from PWB:

    1. Build an executable file using the CodeView options for the
 compiler (/Zi or /Zd) and linker (/CO). These are set by default if you
 are building a debug version of the program. See the section "Setting
 Debug or Release Version" earlier in this chapter.

    2. From the Options menu, choose CodeView Options to set the CodeView
 command-line options.

    3. From the Run menu, choose Debug.
 PWB exits and loads CodeView.


 When you exit CodeView, PWB is restarted.

 For more information on using CodeView to debug your programs, see
 Chapter 5, "Using CodeView."


 Customizing the Environment

 Within PWB you can customize many features of the environment, such
 as screen colors, editor behavior, and key assignments. You can also
 define new functions as macros and assign them to keystrokes.


 Changing Editing Settings

 To change how the environment looks and behaves:

    1. From the Options menu, choose Editor Settings.
 PWB displays the current editor settings in the active window.

    2. Scroll down to see all of the settings. Online Help is
 available for each of the settings.

    3. Change the settings as appropriate. The new settings take
 effect when you move the cursor to the next line.


 To make the changes permanent, choose Save from the File menu. PWB
 saves the changes to the TOOLS.INI file. If you do not save the changes,
 they are discarded when you exit PWB.

 To return to the current file, press F2.


 Assigning Keystrokes

 To change key assignments or to assign new functions to keys:

    1. From the Options menu, choose Key Assignments.
 PWB displays the current key assignments in the active window.

    2. Scroll down to see all of the assignments. Online Help is
 available for each of the editor functions.

    3. Change the key assignments as appropriate. The new
 assignments take effect when you move the cursor to the next line.


 To make the changes permanent, choose Save from the File menu. PWB
 saves the changes to the TOOLS.INI file. If you do not save the changes,
 they are discarded when you exit PWB.

 To return to the current file, press F2.

 The key assignments are divided into sections for each part of PWB. A
 label at the beginning of each section indicates where the assignments
 are used. For example, the [pwb] tag indicates that the subsequent
 assignments apply to the entire PWB environment; the [pwb-pwbbasic] tag
 indicates assignments that apply only to the BASIC Compiler selection
 from the Options menu; and the [pwb-pwbhelp] tag indicates settings that
 apply to the online Help system.

 A table of key assignments unused by PWB is included after the
 [pwb-pwbutils] tag. These key combinations may be used for currently
 unassigned editor functions or for new functions created as macros.


 Creating Macros

 To record a macro:

    1. From the Edit menu, choose Record On.
 PWB displays the Set Macro Record dialog box.

    2. Type the name you want to assign to the macro in the Name field.

    3. Tab to the Key Assignment field and type the names of the
 keystrokes you want to assign to the macro. If you place the cursor
 between the braces, { }, and press the key sequence you want to assign
 to the macro, the correct description of the key sequence is displayed
 in the field to the right.

    4. Choose OK.

    5. Perform the actions you want to record.

    6. Choose Record On again to end the recording.


 To make the recorded macro permanent:

    1. From the Edit menu, choose Edit Macro.
 PWB displays the currently defined macros in the active window.

    2. From the File menu, choose Save.

    3. Press F2 to return to the current file.



 When you make a macro permanent, PWB writes the macro definition and
 key assignment to your TOOLS.INI file. To modify the macro after you
 have made it permanent, you must edit the TOOLS.INI file.

 Examining macro definitions in TOOLS.INI is a good way to learn the
 syntax of macros. Example macros are included in the TOOLS.PRE file
 included with BASIC. Online Help is also available on how to create and
 modify macros in PWB.


 Reducing Load Time

 When you start PWB, it automatically reads your TOOLS.INI file and a
 state file named CURRENT.STS from the directory defined in your INIT
 environment variable. Together, these files control the editor settings,
 macro definitions, and key assignments used by PWB. Since reading these
 files takes time, you can reduce load time by:

   ■  Keeping the PWB entries in TOOLS.INI as short as possible.

   ■  Keeping CURRENT.STS as small as possible.

   ■  Not reading one or both of these files when you start PWB.



 PWB also automatically loads any extension files it finds whose
 filenames start with the letters "PWB" in the directory from which you
 start PWB. These extension files make certain functions, such as the
 BASIC Compiler options, available in the environment. You can further
 reduce load time by disabling this auto-load feature and explicitly
 loading only the extensions you need.


 Minimizing TOOLS.INI

 The entries for PWB in your TOOLS.INI file appear after the [pwb]
 label in that file. TOOLS.INI can be edited and saved in the same way as
 any other file. Macros and settings that you may not use can be
 commented out by placing a semicolon (;) as the first character on the
 line. Lines that have been commented out are not read when PWB starts
 and will reduce load time slightly.


 Minimizing CURRENT.STS

 PWB creates the CURRENT.STS file to save file history and some editor
 settings (such as build options and file history). This file can be kept
 small by reducing the number of files you keep in history and by keeping
 the default editor settings. To reduce the number of files PWB keeps in
 history, you can reduce the number assigned to the tmpsav switch after
 the [pwb] label in the TOOLS.INI file. Reducing this number reduces the
 number of files that can be recalled from the File menu without using
 the Open File dialog box.


 Ignoring TOOLS.INI and CURRENT.STS

 You can prevent PWB from reading TOOLS.INI or CURRENT.STS or both
 files by using one of the /D options when you start PWB from the command
 line. The /DS option prevents CURRENT.STS from being read. The /DT
 option prevents TOOLS.INI from being read. The /DST option prevents both
 files from being read. Although these options prevent the information in
 these files from being available to PWB, they can be useful for some
 programming tasks.

 Starting PWB with /DS is especially useful when working with a
 program list, since PWB creates a startup file to save the editor
 settings for each program list you create. When you set a program list,
 PWB automatically reads the new editor settings from the startup file
 for the program list. This file has the same base name as your .MAK
 file, but has an .STS filename extension. For more information on PWB
 command-line options, see the section "Controlling the Environment"
 later in this chapter.


 Loading PWB Extensions Explicitly

 PWB does not automatically load its extensions if you include the /DA
 option when you start PWB from the command line. This significantly
 reduces the time it takes to start PWB, but also limits the features
 that are available in the environment. You can restore features by
 explicitly loading extensions through settings in the TOOLS.INI file.
 For example:

 [pwb - .BAS .BI]

 LOAD: C:\BC7\BIN\PWBBASIC.MXT;C:\BC7\BIN\PWBUTILS.MXT

 These lines explicitly load the BASIC and utilities PWB extensions
 when you edit a file with the .BAS or .BI filename extension. If these
 lines exist in your TOOLS.INI file and you start PWB with the following
 command line, only the BASIC functions are available:

 PWB /DA test.bas

 The following table lists the filenames of the PWB extensions and
 describes the functions they provide:

╓┌───────────┌───────────┌───────────┌─┌───────────┌───────────┌─┌───────────╖
 Real-mode   Protected-  Provides
 file        mode file   support
                         for
 ────────────────────────────────────────────────────────────────────────────
 PWBBASIC.M  PWBBASIC.P  BASIC
 XT          XT          Compiler
                         functions.

 Real-mode   Protected-  Provides
 file        mode file   support
                         for

 PWBROWSE.M  PWBROWSE.P  Source
 XT          XT          Browser
                         functions.

 PWBC.MXT    PWBC.PXT    C Compiler    included                  disks, but
                         functions.    on the                    is not
                         This file     BASIC                     installed
                         is            distributi                by Setup.
                                       on

 PWBHELP.MX  PWBHELP.PX  Online
 T           T           Help
                         functions.

 PWBUTILS.M  PWBUTILS.P  LINK,                     build
 XT          XT          NMAKE,                    functions.
                         CodeView,
 Real-mode   Protected-  Provides
 file        mode file   support
                         for
                        CodeView,
                         and






 Controlling the Environment

 The full syntax for starting PWB from the command line is as
 follows:

 PWB  options  programname   programname ...

 Unlike QBX,  programname  must include its filename extension if one
 exists. If you specify more than one  programname, the first
 name you specify is the first file PWB edits. The remaining files are
 loaded if you select choose Next from the File menu.

╓┌───────────────────────────────────────┌───────────────────────────────────╖
 Option                                  Action
 ────────────────────────────────────────────────────────────────────────────
 /e  string                              Executes the PWB commands
                                         specified in  string


 /t  file                                Indicates that the specified  file



 /DA | S | T                             Prevents PWB initialization files
                                         from being read at startup. The


 /PF  file


 /r                                      Specifies that all files opened
 Option                                  Action
 ────────────────────────────────────────────────────────────────────────────
/r                                      Specifies that all files opened
                                         are read-only.

 /m  position                            Puts the cursor at the file
                                         location specified by position


 PWB /m 120.50 BOOKLOOK.BAS

                                         The preceding command line loads
                                         the file BOOKLOOK.BAS and places


 /?                                      Lists the command-line options for
                                         running PWB.



 ────────────────────────────────────────────────────────────────────────────



 Chapter 5  Using CodeView
 ────────────────────────────────────────────────────────────────────────────

 The Microsoft CodeView debugger helps you locate, identify, and
 resolve bugs in programs under DOS or OS/2. CodeView can help you debug
 programs compiled from within QBX or PWB, or from the command line.
 CodeView can be accessed directly from the Programmer's WorkBench (PWB).
 Together, PWB and CodeView provide a complete development system for
 mixed-language and OS/2 program development.

 This chapter describes:

   ■   Preparing your programs for debugging with CodeView.

   ■   Running CodeView.

   ■   Debugging a program.

   ■   Controlling the flow of execution while debugging.

   ■   Displaying and changing variables.

   ■   Advanced CodeView debugging techniques.

   ■   Customizing CodeView using the TOOLS.INI file.

   ■   Controlling CodeView with command-line options.



 Preparing BASIC Files for CodeView

 CodeView can debug programs created with any editor or environment.
 QBX and PWB provide CodeView options for compiling within the
 environment. With QBX, however, you must save your source file in text
 format before compiling with the CodeView option. Source files saved in
 QBX binary format are not compatible with CodeView.


 Programming Style

 To make it easier to debug programs in CodeView, you should avoid the
 following programming practices:

   ■   Using the colon (:) to place multiple BASIC statements on a single
 line.

   ■   CodeView can step through a program one line at a time. If more
 than one statement occurs on a line, CodeView treats the line as a
 single statement.

   ■   Placing executable statements in include files.

   ■   You cannot trace through executable statements that occur in an
 include file. Placing executable statements in include files is not a
 good programming practice.

   ■   Using non-unique array names.

   ■   Arrays should be named uniquely. If a variable has the same name
 as an array in your program, CodeView assumes that symbol is a variable,
 not an array. You will not be able to perform some operations on that
 array from the CodeView Command window.



 Compiling and Linking

 To debug a program in CodeView, you must compile the program with the
 /Zi or /Zd options and link using the /CO option. The /Zi option makes
 the executable file larger. You can reduce the size of programs by
 compiling with /Zd. You will not be able to view symbols in the Local
 window within CodeView, however.

 You should not use the optimize (/Ot) option when compiling a program
 for use with CodeView. Although CodeView can debug an executable file
 compiled with /Ot, you will not be able to pause program execution on
 lines containing  SUB,  FUNCTION, or  DEF FN statements.

 Object files compiled for use with CodeView must be linked using the
 /CO option. When linking in DOS, you cannot use the /EXEPACK and /CO
 together. If your program needs to be packed to fit in memory, use the
 CVPACK utility to compress the executable file for debugging.

 The syntax for CVPACK is:

 CVPACK /HELP | /P  filename

 If you specify the /P option, CVPACK rewrites the file as compactly
 as possible. If you don't specify the /P, CVPACK rewrites the file as
 quickly as possible. In either case, the program takes up the same
 amount of memory.


 Running CodeView

 To start CodeView from the command line, use the CV real-mode or CVP
 protected-mode command and specify an executable file. For example:

 CV TEST.EXE

 To start CodeView from PWB in real or protected mode, choose Debug
 from the Run menu. By default, CodeView displays three windows, as shown
 in Figure 5.1.


 The "Local window" displays the current symbols along with their
 addresses, types, and values. This window is empty until you begin
 executing your program.

 The "Source window" displays the program's source code. Since the
 program loaded in CodeView is a compiled executable program, you cannot
 make changes to the source from within CodeView. The Source window shows
 you where you are in a program and lets you execute the program
 statement-by-statement.

 The "Command window" lets you enter CodeView commands and display and
 evaluate BASIC expressions. Although you cannot make changes to a
 program from CodeView, you can use the Command window to change the
 value of variables, write data to memory, and perform a variety of other
 tasks. CodeView supports a limited number of BASIC intrinsic functions
 which can be called from the Command window. See the CodeView online
 Help on BASIC intrinsic functions for more information.


 Important

 CodeView includes extensive online Help. If you request Help and get
 an error message indicating that no Help files were open or that they
 could not be found, check your HELPFILES environment variable. HELPFILES
 can be set by running NEW-VARS.BAT (DOS) or NEW-VARS.CMD (OS/2) from the
 command line before starting CodeView.

 HELPFILES in the PWB environment has no effect in CodeView.

 Within CodeView, environment tasks can be performed by using either
 the mouse or the keyboard. The following table lists commonly used key
 combinations by category and task. The Command window equivalent is
 given where one exists. (See the online Help on CodeView commands for a
 complete list and description of CodeView commands.)


 Note

 The Edit tasks are used to copy and paste expressions, values, and
 blocks of memory. You cannot Paste into the Source window.


 Debugging Your Program

 CodeView is similar to QuickBASIC Extended (QBX) in that you can
 watch the value of variables while you execute parts of your program.
 Like QBX, you can execute one line at a time, one procedure at a time,
 or up to a specific location. Unlike QBX, you cannot rewrite your
 program within CodeView.

 CodeView also lets you directly manipulate the values stored in
 variables and in memory.


 Running Your Program

 To execute a single line of code, press F8.

 To execute a line of code or without tracing into procedures, press
 F10.

 To quickly execute up to a specific location in a program:

    1. In the Source window, scroll to the location at which to stop.

    2. Click the right mouse button at that location.
 CodeView executes up to that location at normal execution speed.


 To run a program one line at a time:

    1. From the Run menu, choose Animate.
 CodeView immediately begins executing the program.

    2. Press any key to stop.



 Important

 When you run your BASIC program in CodeView under DOS, you will not
 be able to use the DOS Shell command from the File menu. This is because
 BASIC reserves all remaining conventional memory while the program is
 running. To be able to use the DOS Shell command you should terminate or
 restart your BASIC program.


 Viewing Current Data

 When you start executing a program in CodeView, the debugger
 automatically displays all current variables in the Local window. The
 Local window shows the address, data type, name, and value of each
 variable in the current procedure. For example:

 2FCE:0062  STRING         FULLNAME$ = "Dan Quayle"

 The value 2FCE:0062 is the address of the variable in memory, STRING
 is the data type, FULLNAME$ is the variable name, and "Dan Quayle" is
 the current value of the variable.

 For arrays and user-defined data types, CodeView displays a summary
 line. For example:

 +2FCE:0070 INTEGER    AZ%[array] = ?CANNOT DISPLAY
 +2FCE:004a type  TESTRECOR FILEBUFFER = {...}

 The plus sign (+) to the left of the memory address shows that there
 is more information. To see the elements in the structure TESTRECOR,
 select the TESTRECOR line. The line expands as follows:

 -2FCE:0070 type    TESTRECOR FILEBUFFER
     STRING * 20    NAMEFIELD = "Jeff Webb"
     SINGLE *       SCOREFIELD = "1370"

 The minus sign (-) to the left of the memory address shows that the
 line is fully expanded.

 You cannot expand BASIC arrays. Instead, you must set watches on
 elements in the array to see their values.


 Using Watches

 Watches let you observe the value of a variable or expression as your
 program executes. Since CodeView displays the value of local variables
 in the Local window, CodeView's watches are mainly useful when the Local
 window is not displayed or for observing array elements and
 expressions.

 To add a variable to the Watch window:

    1. Place the cursor on the variable and press Ctrl+W.
 CodeView displays the Add Watch dialog box.

    2. Choose OK.
 CodeView adds the variable to the Watch window, as shown in Figure 5.2.


 A variable may be followed by the message "Watch Expression Not in
 Context." This message appears when program execution has not yet
 reached the statement in which the variable is defined. Global
 variables, which can be watched from anywhere in the program, never
 cause CodeView to display this message.

 To remove a variable from the Watch window, place the cursor on any
 line in the Watch window and press Ctrl+Y to delete the line.

 You can place as many variables as you like in the Watch window; the
 quantity is limited only by available memory. CodeView automatically
 updates all watched variables as the program runs. This can slow
 execution speed considerably.


 Displaying Expressions in the Watch Window

 The Add Watch dialog box prompts for an expression, not simply a
 variable name. As this suggests, you can enter an expression (that is,
 any valid combination of variables, constants, and operators) for
 CodeView to evaluate and display.

 You are not limited to evaluating BASIC expressions. The Language
 command from the Options menu offers a choice of BASIC, C, or FORTRAN
 evaluation for all expressions. The ability to select the language
 evaluator is especially useful when debugging mixed-language
 programs.

 By reducing several variables to a single, easily read value, an
 expression can be easier to interpret than the components that comprise
 it.


 Displaying Array Elements Dynamically

 You  can display a single element of an array using a specific
 subscript. You can also specify a variable array element, which changes
 as some other variable changes. For example, suppose that the loop
 variable p is a subscript for the array CatalogPrice@. The Watch window
 expression CatalogPrice@(p) displays only the array element currently
 specified by p, not the entire array.

 You can mix constant and variable subscripts. For example, the
 expression BigArray%(3,i) displays the element in the third row of the
 array to which the index variable i points.


 Using Quick Watch

 A quick watch shows the current value of a variable. This is useful
 for quickly finding the value of a variable at some point in the program
 without adding it to the Watch window.

 To display a quick watch:

    1. Place the cursor on the variable to watch.

    2. From the Watch menu, choose Quick Watch (or press Shift+F9).
 CodeView displays the Quick Watch dialog box with the value of the
 variable.


 The Quick Watch display automatically expands user-defined types to
 their first level. You can expand or contract an element just as you
 would in the Watch window by placing the cursor on the appropriate line
 and pressing Enter.


 Displaying Memory

 You can view data at specific memory addresses using CodeView.

 To display memory, choose Memory from the View menu. CodeView
 displays the Memory window, as shown in Figure 5.3.


 Up to two Memory windows can be open at once.

 By default, memory is displayed as hexadecimal byte values, with 16
 bytes per line. At the end of each line is a second display of the same
 memory in ASCII form. Values that correspond to printable ASCII
 characters (decimal 32 through 127) are displayed in that form. Values
 outside this range are shown as periods.

 Byte values are not always the most convenient way to view memory. If
 the area of memory you're examining contains character strings or
 floating-point values, you might prefer to view them in a directly
 readable form.

 To change the way data is displayed in the current Memory window:

    1. From the Options menu, choose Memory Window.
 CodeView displays the Memory Window Options dialog box.

    2. Select the format for display, and choose OK.


 You can also directly cycle through these display formats by pressing
 F3.

 If a section of memory cannot be displayed as a valid floating-point
 number, the number shown includes the characters NAN (not a number).


 Displaying the Processor Registers

 To view processor registers, choose Register from the View menu.
 CodeView opens a window on the right side of the screen, as shown in
 Figure 5.4. The current values of the microprocessor's registers appear
 in this window.

 At the bottom of the window is a group of mnemonics representing the
 processor flags. When you first open the Register window, all values are
 shown in normal-intensity video. Any subsequent changes are marked in
 high-intensity video. For example, suppose the overflow flag is not set
 when the Register window is first opened. The corresponding mnemonic is
 NV and appears in light gray. If the overflow flag is subsequently set,
 the mnemonic changes to OV and appears in bright white.

 Choosing the 386 Instructions command (DOS only) from the Options
 menu displays the registers as 32-bit values if your computer uses an
 80386 processor. Selecting this command a second time reverts to a
 16-bit display. This command is not available in protected mode; the
 registers are shown in 16-bit display only.

 You can also display the registers of an 8087/287/387 coprocessor in
 a separate window by choosing the 8087 command from the View menu. If
 your program uses the coprocessor emulator, the emulated registers are
 displayed instead.


 Modifying the Values of Variables, and Memory

 You can easily change the values of numeric variables, registers, or
 memory locations displayed in the Watch, Local, Memory, Register, or
 8087 window. Simply place the cursor at the value you want to change and
 edit it to the appropriate value. To undo the last change you made,
 press Alt+Backspace. You cannot directly change the value of string
 variables.

 The starting address of each line of memory displayed is shown at the
 left of the Memory window, in  segment: address  form.
 Altering the address automatically shifts the display to the
 corresponding section of memory. If that section is not used by your
 program, memory locations are displayed as double question marks
 (??).

 When you select Byte display from the Memory Window Options dialog
 box, CodeView presents both a hexadecimal and an ASCII representation of
 the data in memory. (Byte display is the default.) You can change data
 in memory either by entering new hex values over the hexadecimal
 representation of your data or by entering character values over the
 character representation.

 To toggle a processor flag, click left on its mnemonic. You can also
 place the cursor on a mnemonic, then press any key (except Tab or
 Spacebar). Repeat to restore the flag to its previous setting.

 The effect of changing a register, flag, or memory location may vary
 from no effect at all to crashing the operating system. You should be
 cautious when altering  machine-level
  values; most of the items you would want to change can be altered from
 the Local or Watch window.

 Direct manipulation of register values can be valuable, however, when
 you are debugging a BASIC program that calls assembly language routines.
 You can change register values to test assumptions before making changes
 in your source code and recompiling.


 Setting Breakpoints

 You can skip over the parts of the program that you don't want to
 examine by specifying one or more lines as breakpoints .
  When you start the program by pressing F5, the program executes at full
 speed up to the first breakpoint, then pauses. Pressing F5 continues
 program execution up to the next breakpoint, and so on.

 You can set as many breakpoints as you like (limited only by
 available memory). There are two ways to set breakpoints:

   ■   Double-click anywhere on the desired breakpoint line. The selected
 line is highlighted to show that it is a breakpoint. (CodeView
 highlights lines that have been selected as breakpoints.) To remove the
 breakpoint, double-click on the line a second time.

   ■   Place the cursor anywhere on the line at which you want execution to
 pause. Press F9 to select the line as a breakpoint. Press F9 a second
 time to remove the breakpoint.


 A breakpoint line must be a program line that represents executable
 code. You cannot select a blank line, a comment line, or a declaration
 line (such as a variable declaration) as a breakpoint.

 A breakpoint can also be set at a function or an explicit address. To
 set a breakpoint at a function, enter its name in the Set Breakpoint
 dialog box. To set a breakpoint at an address, enter the address in
  segment: offset form.

 Once execution has paused, you can continue execution by pressing
 F5.


 Setting Conditional Breakpoints

 CodeView lets you set conditional statements that stop execution when
 an expression becomes true or changes value. (QBX refers to these
 conditional breakpoints as "watchpoints.")

 To set a conditional breakpoint:

    1. From the Watch menu, choose Set Breakpoint.
 CodeView displays the Set Breakpoint dialog box, as shown in Figure 5.5.

    2. Select one of the conditional break options from the dialog box, such
 as Break When Expression is True.
 If you select one of the Break at Location options, CodeView takes you
 to the line number displayed in the Location field when the breakpoint
 is reached. If you select one of the other two options, CodeView takes
 you to the last statement that was executed.

    3. Choose OK.


 Note

 When a breakpoint is tied to a variable, CodeView must check the
 variable's value after each machine instruction is executed. This slows
 execution greatly. For maximum speed when debugging, either tie
 conditional breakpoints to specific lines, or set conditional
 breakpoints only after you have reached the section of code that needs
 to be debugged.


 Replaying a Debug Session

 CodeView can automatically create a history file with all the
 debugging instructions and input data you entered when testing a
 program. This history file is used to replay the debug session to a
 specific point.

 To record a debug session, choose History On from the Run menu.

 To stop recording, choose History On a second time.

 Recordings can be used to keep track of debugging. You can quit after
 a long debugging session, then pick up the session later in the same
 place.

 The principal use of recording a debug session is to allow you to
 back up when you make an error or overshoot the section of code with the
 bug. For example, you may have to execute a function manually many times
 before its bug appears. If you then enter a command that alters the
 machine's or program's status and thereby lose the information you need
 to find the cause of the bug, you have to restart the program and
 manually repeat every debugging step to return to that point. Even
 worse, if you don't remember the exact sequence of events that exposed
 the bug, it could take hours to find your way back.

 Recording your session eliminates this problem. Choosing Undo from
 the Run menu automatically restarts the program and rapidly executes
 every debug command up to (but not including) the last one you entered.
 You can repeat this process as many times as you like until you return
 to the desired point in execution.

 To add steps to an existing recorded session, choose History On, then
 select Replay. When replay has completed, perform whatever new debugging
 steps you want, then select History On a second time to terminate
 recording. The new tape contains both the original and the added
 commands.


 Note

 CodeView records only those mouse commands that apply to CodeView.
 Mouse commands recognized by the application being debugged are not
 recorded.


 Replay Limitations Under OS/2

 There are some limitations to dynamic replay when debugging under
 OS/2:

   ■   n The program must not respond to asynchronous events. (Replay under
 OS/2 Presentation Manager is not currently supported because it violates
 this restriction.)

   ■   Breakpoints must be specified at specific source lines or for
 specific symbols (rather than by absolute addresses), or replay may
 fail.

   ■   Single-thread programs behave normally during replay. However, one of
 the threads in a multithread program may cause an asynchronous event,
 violating the first restriction. Multithread programs are, therefore,
 more likely to fail during replay.

   ■   Multiprocess replay will fail. Each new process invokes a new
 CodeView session. The existence of multiple sessions makes it
 impractical to record the sequence of events if you execute commands in
 a session other than the original.



 Advanced CodeView Techniques

 Once you are comfortable displaying and changing variables, stepping
 through the program, and using dynamic replay, you may want to
 experiment with advanced techniques.


 Setting Command-Line Arguments

 If your program retrieves command-line arguments, you can specify
 them with the Set Runtime Arguments command from the Run menu. Enter the
 arguments in the Command Line field before you begin execution.
 (Arguments entered after execution begins cause an automatic
 restart.)


 Multiple Source Windows

 You can open two Source windows simultaneously. The windows can
 display two different sections of the same program, or one can show the
 high-level listing and the other the assembly language listing. In the
 latter case, the contents of the windows are synchronized. The next
 assembly language instruction to be executed matches the next line of
 source code.

 You can move freely between these windows, executing a single line of
 source code or a single assembly instruction at a time.


 Using Breakpoints Efficiently

 Breakpoints slow execution when debugging. You can increase
 CodeView's speed by using the /R command-line switch if you have an
 80386-based computer. This switch enables the 386's four debug
 registers, which support breakpoint checking in hardware rather than in
 software.


 Printing Selected Items

 To print all or part of the contents of any window:

    1. From the File menu, choose Print.
 CodeView displays the Print dialog box.

    2. Select the information to print and whether to append the
 information to an existing file or to overwrite the file.
 By default, print output is to the file CODEVIEW.LST in the current
 directory. If you want the output to go to a printer, enter the
 appropriate device name (such as LPT1: or COM2:) in the To File Name
 field.

    3. Choose OK.



 Handling Register Variables

 A register variable is stored in one of the microprocessor's
 registers, rather than in RAM. This speeds access to the variable.

 A conventional variable can become a register variable when the
 compiler stores an often-used variable, such as a loop variable, in a
 register to speed execution.

 Register variables can cause problems during debugging. As with local
 variables, they are only visible within the function where they are
 defined. In addition, a register variable may not always be displayed
 with its current value.


 Redirecting CodeView Input and Output

 The Command window accepts DOS-like commands that redirect input and
 output. These commands can also be included on the command line that
 invokes CodeView. Whatever follows the /C option on the command line is
 treated as a CodeView command to be immediately executed at startup. For
 example:

 CV /c infile; t >outfile myprog

 This command line redirects input to infile, which can contain
 startup commands for CodeView. When CodeView exhausts all commands in
 the input file, focus automatically shifts to the Command window. Output
 is sent to outfile and echoed to the Command window. The t must precede
 the  >   command for output to be sent to the Command window.

 Redirection is a useful way to automate CodeView startup. It also
 lets you keep a viewable record of command-line input and output, a
 feature not available with dynamic replay. (No record is kept of mouse
 operations.) Some applications (particularly interactive ones) may need
 modification to allow for redirection of input to the application
 itself.


 Customizing CodeView with the TOOLS.INI File

 The TOOLS.INI file customizes the behavior and user interface of
 several Microsoft products. You should place it in a directory pointed
 to the INIT environment variable. (If you do not use the INIT
 environment variable, CodeView looks for TOOLS.INI only in its source
 directory.)

 The CodeView section of TOOLS.INI is preceded by the following
 line:

 [cv]

 If you are running the protected-mode version of CodeView, use  [cvp]
  instead. If you run both versions, include both: [cv cvp].

 Most of the TOOLS.INI customizations control screen colors, but you
 can also specify options, such as startup commands or the name of the
 file receiving CodeView output. Online Help contains full information
 about all TOOLS.INI switches for CodeView.


 Controlling CodeView with Command-Line Options

 The following options can be added to the command line that invokes
 CodeView:

 Option   Effect
 /2       Two-monitor debugging. One display shows the output of the
          application; the other shows CodeView.

 /25      Display in 25-line mode.

 /43      Display in 43-line mode. (EGA or VGA only)

 /50      Display in 50-line mode. (VGA only)

 /B       Display in black and white.

 /C commands:  All items following this switch are treated as CodeView
 commands to be executed immediately upon startup. Commands must be
 separated with a semicolon (;).

 /D buffersize:  Use disk overlays, where  buffersize
 is the decimal size of the overlay buffer, in kilobytes. The acceptable
 range is 16K to 128K, with the default size 64K. (DOS only)

 /E       Use expanded memory for symbolic information. (DOS only)

 /F       Flip screen video pages. When your application does not use
          graphics, up to eight video screen pages are available.
          Switching from CodeView to the output screen is accomplished
          more quickly than swapping (/S) by directly selecting the
          appropriate video page. Cannot be used with /S. (DOS only)

 /I[0|1]  /I0 enables nonmaskable-interrupt and 8259-interrupt trapping.
          This enables Ctrl+C and Ctrl+Break for PCs that CodeView does
          not recognize as IBM-compatible. /I or /I1 turns off interrupt
          trapping. (DOS only)

 /K       Use this option if you encounter a deadlock situation because
          the keyboard buffer is full when you restart the program you
          are debugging, exit CodeView before your program finishes
          execution, or debug an application that does not accept
          keystrokes.

 /L dlls: Load DLLs specified. DLLs must be separated by a
 semicolon (;). (OS/2 only)

 /M       Disable the mouse for CodeView. Does not affect the use of the
          mouse in the application being debugged.

 /N[0|1]  /N0 enables nonmaskable-interrupt trapping. This enables Ctrl+C
          and Ctrl+Break for PCs that CodeView does not recognize as
          IBM-compatible. /N or /N1 turns off interrupt trapping.only)

 /O       Debug child processes ( offspring). (OS/2 only)

 /R       Use 386 hardware debug registers. (DOS only)

 /S       Swap screen in buffers. When your program uses graphics, all
          eight screen buffers must be used. Switching from CodeView
          to the output screen is accomplished by saving the previous
          screen in a buffer. Cannot be used with /F. (DOS only)

 /X       Use extended memory for symbolic information. (DOS only)



 ────────────────────────────────────────────────────────────────────────────



 Chapter 6  Using Online Help
 ────────────────────────────────────────────────────────────────────────────

 The Microsoft Advisor online Help system is more than a learning
 tool--it's a reference database designed especially for
 professional programmers. Help gives you instant reference information
 about the BASIC language, development environments, compiler options,
 utilities, and error messages. You can also copy sample code from a Help
 screen and paste it directly into your BASIC source file. Using the
 Microsoft Help File Creation utility (HELPMAKE), you can even create
 your own Help files.

 This chapter describes:
   ■   Installing Help.
   ■   Organization of Help.
   ■   Navigating in Help.
   ■   Copying and pasting Help information.
   ■   Creating your own Help files.
   ■   Using QuickHelp.


 Installing Help

 Use the Setup program to install Help. In the Specify Files to
 Install menu, turn on the Help Files for Chosen Tools check box. Setup
 includes all the Help files you need when it installs Microsoft
 BASIC.

 At this point, you can use online Help in the QuickBASIC Extended
 (QBX) environment. To use Help in the Programmer's WorkBench (PWB),
 CodeView, and QuickHelp environments, you must specify where each of
 these applications should look for their Help files by setting the
 HELPFILES environment variable. HELPFILES can be set in several
 different places. PWB, CodeView, and QuickHelp search the following
 locations in the order shown and use the first HELPFILES setting they
 find:

   ■    1. Environment selection from the PWB Options menu.
 (This only has an effect in PWB.)

   ■    2. TOOLS.INI file.

   ■    3. AUTOEXEC.BAT file (DOS) or CONFIG.SYS file (OS/2).


 If HELPFILES is not set in one of these locations, PWB and QuickHelp
 will search for help files in the current directory and in the
 directories listed in the PATH environment variable.

 You can set HELPFILES and other environment variables for a session
 by running the

 (DOS) or NEW-VARS.CMD (OS/2) file from the command line. You may want
 to incorporate the settings in these files into your AUTOEXEC.BAT (DOS)
 or CONFIG.SYS (OS/2) files. For information on how to do this, see the
 section "After Running Setup" in Chapter 2.


 Help Topics and Hyperlinks

 Online Help is organized as a set of topics. Instead of thumbing
 through a manual, you can move from one topic to another related topic
 by using links (or cross-references). Help remembers the last 20 screens
 you've viewed, so you can retrace your path at any time.


 Explicit Cross-References

 Explicit cross-references, called "hyperlinks," are tied to a word or
 phrase at a specific location in Help. You simply select a hyperlink,
 using the mouse or keyboard, to move to a new screen of related
 information.

 Special characters set off hyperlink buttons. Figure 6.1 shows
 examples.


 To move forward between hyperlinks, press the Tab key; Shift+Tab
 moves you backward. You can also type the first letter of a hyperlink to
 move to that hyperlink.


 Implicit Cross-References

 All BASIC keywords (functions, statements, operators, and
 metacommands) are implicit cross-references. Implicit cross-references
 have no special formatting. For example, the word "open" provides
 context-sensitive help on the  OPEN
  statement wherever it appears, whether in your programs or in a Help
 screen. To use an implicit cross-reference, place the cursor on or
 immediately following the keyword, and then press F1 or click the right
 mouse button.


 Help Categories

 There are five categories of help:
   ■   Using Help
   ■   Keyword and symbol Help
   ■   Topic-based Help
   ■   Programming environment Help
   ■   Error message Help



 Using Help

 You can get information about the online Help system itself at any
 time by choosing the Using Help command from the Help menu. The Using
 Help screen provides a quick overview of the Help system and gives
 instructions for accessing Help with the keyboard or mouse.


 Keyword and Symbol Help

 Online Help provides context-sensitive help for BASIC keywords and
 for symbols in your program, such as procedures and variables.


 Keyword Help

 Keywords include functions, statements, operators, and metacommands.
 Every keyword in Microsoft BASIC is an implicit cross-reference. To get
 information on any BASIC keyword (in your program or within the online
 Help system), place the cursor on the keyword, and press F1 or click the
 right mouse button. For example, type   do
   in the QBX View window, and then press F1. The Syntax screen for the
  DO ... LOOP statement appears, as shown in Figure 6.2.


 If you want to see a programming example using the  DO ... LOOP
 statement, move to the Help window, then choose the Example hyperlink.
 If you need additional information, choose the Details hyperlink.


 Note

 You can browse the complete list of BASIC keywords by choosing the
 Keywords by Task hyperlink from the BASIC Help Table of Contents
 screen.


 Symbol Help

 To get information on any symbol in your program from QBX, position
 the cursor anywhere on the symbol and then press F1 or click the right
 mouse button. The Help system will identify the symbol (variable,
 function, etc.) and where it is used in your program. This type of Help
 is only available in QBX.

 To view symbol information in PWB, you must use the Source Browser.
 For instructions on using the Source Browser, see Chapter 4, "Using
 PWB."


 Topic-Based Help

 You can use the Help system to get an overview of available topics
 when you have a general idea of the information you need. For example,
 suppose you want to learn about QBX's customizable keystrokes, but you
 don't know where to look. Choose the Contents hyperlink in any Help
 window, or choose Contents from the Help menu. The BASIC Help Table of
 Contents screen appears, as shown in Figure 6.3.


 The BASIC Help Table of Contents screen is broken into five
 subgroups: Orientation, Language Elements, Command-Line Options, Quick
 Reference, and Keys.


 Programming Environment Help

 You can get context-sensitive Help on any menu command or dialog box.
 For example, to learn about the Create File command in the QBX File
 menu:

    1 Open the File menu.

    2 Press the Down direction key to highlight Create File
 (do not press Enter), and then press F1. The Help screen for the Create
 File command appears, as shown in Figure 6.4.


 You can also get help about a dialog box. Press F1 or click the Help
 button to display information about the dialog box.


 Error Message Help

 Whenever you encounter an error message, you can press F1 to get help
 on the cause of the error. Most error message Help screens contain
 suggestions on how to avoid the error.


 Navigating in the Help System

 The following table summarizes Help keystrokes.

╓┌───────────────────────────────────────┌───────────────────────────────────╖
 Press this key                          To do this
 ────────────────────────────────────────────────────────────────────────────
 F1                                      Get Help on the selected item.

 Shift+F1                                In QBX, get help on using the Help
                                         system. In PWB, CodeView, and
 Press this key                          To do this
 ────────────────────────────────────────────────────────────────────────────
                                        system. In PWB, CodeView, and


 Alt+F1                                  Display previous Help screen. You
                                         can retrace your path through


 Esc                                     Close the Help window.

 PgDn                                    Scroll Help information down when
                                         the Help window is active.

 PgUp                                    Scroll Help information up when
                                         the Help window is active.

 Tab                                     Move to the next hyperlink in the
                                         active Help window.

 Shift+Tab                               Move to the previous hyperlink in
 Press this key                          To do this
 ────────────────────────────────────────────────────────────────────────────
Shift+Tab                               Move to the previous hyperlink in
                                         the active Help window..





 Copying and Pasting Help Information

 You can copy any text that appears in the Help window to another
 window. To test a sample program from the Help window, just copy it to
 the program window and then choose Start (QBX) or Execute (PWB) from the
 Run menu.

 To copy and paste, follow these steps:

    1 Select the text you want to copy.

    2 Press Ctrl+Ins.

    3 In the program window, place the cursor where you want to
 insert the text, and then press Shift+Ins.


 Creating Custom Help Files

 The HELPMAKE utility allows you to create or modify Help files for
 use with Microsoft products. For example, you could write Help text
 describing a new function you have written for a Quick library. You can
 then display Help information about your function just as you would
 display Microsoft-supplied Help information.

 HELPMAKE translates Help text files into a Help database accessible
 from the QBX programming environment or other Microsoft language
 products. You can either create Help files from scratch, or you can use
 HELPMAKE to decompress the Microsoft-supplied Help database and then
 modify it.

 For complete information on building your own Help system, see
 Chapter 22, "Customizing Online Help," in the  Programmer's
 Guide, or select HELPMAKE from the main Help Table of
 Contents in PWB.


 Using QuickHelp

 Microsoft QuickHelp lets you read Microsoft Advisor Help files
 without running a programming environment. This is useful if you are
 running Microsoft Windows or OS/2 and you want to keep Help information
 open in a window at all times. QuickHelp is also useful for reading Help
 databases that you have created for your own applications.

 To start QuickHelp, type:

  QH


 QuickHelp searches for Help files in the paths and the order
 described in the section "Installing Help" earlier in this chapter. In
 addition, QuickHelp also uses the QH environment variable to define
 additional directories to search. For example:

 SET HELPFILES=C:\BC7\HELP

 SET QH=C:\LANMAN\HELP

 If these lines are entered from the command line, QuickHelp will
 search in C:\BC7\HELP and C:\LANMAN\HELP for Help files. PWB and
 CodeView, however, will not search in C:\LANMAN\HELP unless it is
 included in the HELPFILES environment variable.


 ────────────────────────────────────────────────────────────────────────────



 Chapter 7  Memory Management in DOS
 ────────────────────────────────────────────────────────────────────────────

 This chapter explains how to increase the amount of memory available
 under DOS to help you create the largest possible running applications
 using each of the Microsoft BASIC environments. It shows you how to take
 advantage of extended and expanded memory by using one or more of the
 three device drivers included in the package: HIMEM.SYS, SMARTDRV.SYS,
 or RAMDRIVE.SYS.


 Overview

 You can use a variety of techniques to make more memory available for
 program use, such as:

   ■   Removing all unnecessary memory-resident programs and device drivers.
 (Check your CONFIG.SYS and AUTOEXEC.BAT files to see what you have
 installed.)

   ■   Using extended and/or expanded memory. Extended and expanded memory
 are available through the use of add-on memory boards. Some system
 boards have extended or expanded memory built in as well. Add-on memory
 boards include extended memory, expanded memory, and some boards that
 can be configured for either. Expanded and extended memory are used in
 different ways:

   - Extended memory. You can use the HIMEM.SYS device driver provided
 with this package or another extended-memory driver.

   - Expanded-memory emulators. Many extended-memory drivers
 can use some or all memory to emulate expanded memory. Information in
 this chapter about expanded-memory hardware applies to expanded-memory
 emulators as well.

   - Expanded memory. Expanded memory provides up to 1.2
 megabytes of buffer space to the ISAM portion of a BASIC program.

 You can use extended and expanded memory at the same time.
 However, only one expanded-memory driver and one extended-memory manager
 can run on the system. Use an expanded-memory emulator only if you have
 no expanded-memory hardware.



 Using Extended Memory (XMS)

 Extended memory requires an 80286 or later processor. The
 extended-memory device drivers compatible with BASIC observe the
 Extended Memory Specification (XMS), version 2.0 and higher. You can use
 the HIMEM.SYS device driver provided in this package, or you can use
 your own extended-memory driver if it supports XMS version 2.0 or
 higher.


 The HIMEM.SYS Device Driver

 The HIMEM.SYS device driver provides a 64K area immediately above one
 megabyte called the High Memory Area (HMA). Only one piece of software
 can reside in HMA.

 You must have DOS version 3.0 or later to run HIMEM.SYS. To install
 HIMEM.SYS, place the following statement in your CONFIG.SYS file:

 device=[ drive:][ path]HIMEM.SYS [/HMAMIN= tsrmin]
   [/NUMHANDLES= handles][/SHADOW=[ON | OFF]][/MACHINE= machine]

 In the preceding syntax,  tsrmin  is the minimum size, in kilobytes,
 that a memory-resident program must have to be placed in HMA. The default
 value of 0 lets any memory-resident program request use of this area
 for extended memory.

 The  handles  field sets the maximum number of Extended Memory
 Block handles that HIMEM.SYS supports. Each piece of software that you load
 into extended memory above HMA requires an additional handle. The handles
 field defaults to 32 and must be between 1 and 128. Each additional handle
 requires 6 bytes of memory.

 The /SHADOW option enables or disables shadow RAM. Some computers
 make ROM  faster by "shadowing" it in RAM -- that is, copying the
 ROM code into RAM memory at startup. This uses some extended memory. On
 systems with 384K of extended memory, HIMEM.SYS automatically disables
 shadowing. You can use /SHADOW=ON to explicitly enable shadowing on
 systems with less than 384K of extended memory.

 The /MACHINE option tells HIMEM.SYS what type of computer you are
 using. In most cases, HIMEM.SYS automatically detects the type of
 machine you are using. Currently, the only system which requires this
 switch is the Acer 1100. If you are using this system, you should use
 the option /MACHINE:ACER1100.


 Other Extended-Memory Device Drivers

 In general, extended-memory device drivers make memory available by
 using three kinds of addresses:

   ■   A 64K area starting at address FFFF:0010, just above conventional
 memory.

   ■   Addresses above this 64K area. This region can be accessed by
 temporarily switching into protected mode, then copying the contents to
 a lower address.

   ■   Unused addresses above 640K but below one megabyte. These are areas
 reserved by the system but currently unused.


 HIMEM.SYS supports the first two kinds of addressing.

 Some extended-memory device drivers can move memory-resident programs
 into the third area--unused addresses below one megabyte. Doing so
 makes more conventional memory available.

 For example, if you have an 80386 processor and the 386MAX.SYS device
 driver (from Qualitas, Inc.), you may be able to move the ISAM TSR into
 unused address space. This requires a sufficiently large contiguous area
 of memory and is dependent on your system configuration. Install
 386MAX.SYS in your CONFIG.SYS file, and then execute the following
 DOS-level commands:

     386MAX loadhigh
     PROISAMD
     386MAX loadlow

 The first command directs the 386MAX driver to load software into
 high memory (above 640K). PROISAMD is the full version of the ISAM
 memory-resident program (database creation and access). The third
 command restores normal loading.


 Using Expanded Memory (EMS)

 Expanded memory is compatible with all 8086-family processors. It is
 implemented by a paging mechanism to swap up to 64K into an
 8086-addressable area. The expanded-memory device drivers compatible
 with BASIC observe the Lotus-Intel-Microsoft (LIM) Expanded Memory
 Specification (EMS). To ensure compatibility with QBX and ISAM, use
 device drivers that support the LIM 4.0 specification.

 To use expanded memory, you must install an expanded-memory device
 driver in your CONFIG.SYS file. Hardware manufacturers supply a device
 driver with their expanded memory board. Two of the device drivers
 included in this package, RAMDRIVE.SYS and SMARTDRV.SYS, can be used
 with expanded memory.


 Note

 All of the features described in this section also apply to
 expanded-memory emulators.


 Using RAMDRIVE

 The RAMDRIVE.SYS device driver lets you use a portion of your
 computer's memory as an additional hard disk. This disk is referred to
 as a RAM disk or virtual disk and is much faster than a physical hard
 disk.

 You can place a RAM disk in conventional, extended, or expanded
 memory. On most machines, RAMDRIVE.SYS runs fastest with expanded
 memory. RAMDRIVE.SYS always uses some conventional memory. The exact
 amount depends on your hardware configuration and varies between
 systems.

 The system reads and writes to the RAM disk almost as fast as to main
 memory. If you set the TMP environment variable to a directory on a RAM
 disk, a number of programming tools (notably LINK and ISAM) will use the
 RAM disk to hold temporary files, thus speeding up operations. You can
 also copy libraries and frequently used executable files to RAMdrive at
 the beginning of a session to increase speed. Placing source files on
 the RAM disk is risky since all information is deleted from the RAM disk
 when you reboot.

 To install RAMDRIVE.SYS, include the following command line in your
 CONFIG.SYS file:

 device=[ drive:][ path]RAMDRIVE.SYS[disksize]
  [sectorsize][entries][{/A | /E | /U}]


 The following list explains the meaning of each option:

 Option         Description
 disksize       Disk size in kilobytes. The default size is 64K, the
                minimum is 16K, and the maximum is 4096K.

 sectorsize     Sector size in bytes. The default size is 512 bytes. The
                other legal values are 128, 256, and 1024. If in doubt,
                use the default.

 entries        Limits the number of root directory entries (files and
                subdirectories). The default size is 64, the minimum is
                2, and the maximum is 1024.

 /A             Uses expanded memory. (This memory must conform to the
                4.0 specification.) If you use /A, you cannot use /E
                or /U.

 /E             Uses extended memory, making use of addresses above the
                one-megabyte address space. If you use /E, you cannot
                use /A or /U.

 /U             Applicable only to AT 6300 PLUS motherboard. Specifies
                that some or all of the 384K of extra memory on an AT
                6300 PLUS motherboard is to be used as an extra RAM drive.
                1K of the 384K is reserved as overhead for RAMDRIVE.SYS.
                If you use /U, you cannot use /A or /E.



 Note

 Any use of RAMDRIVE.SYS or SMARTDRV.SYS uses some conventional
 memory.

 The versions of RAMDRIVE.SYS and SMARDRV.SYS provided with BASIC are
 compatible with Windows version 3.0. They are not compatible with
 Windows versions 2.11 and earlier.


 Using SMARTDrive

 The SMARTDRV.SYS device driver lets you use a portion of your
 computer's memory as a disk-cache area. This mechanism serves as a
 temporary holding area for recently accessed data from the hard disk,
 which significantly reduces data-access time if the desired information
 is in cache.

 You can place the SMARTDrive disk cache in either extended or
 expanded memory.

 To install SMARTDRV.SYS, include the following command line in your
 CONFIG.SYS file:

 device=[drive:][path]SMARTDRV.SYS[normal cachesize]
    [minimum cachesize][/A]


 The following list explains the meaning of each option:


 Option               Description
 ----------------------------------------------------------------------
 normalcachesize      Size of the disk cache in kilobytes. The default
                      size is 256K for extended memory and all of
                      available memory for expanded memory. Several
                      megabytes is a typical size for a disk cache;
                      you'll generally see little difference in
                      performance unless the cache is well over 500K
                      in size.

 minimumcachesize     The smallest disk cache in kilobytes. Windows
                      will reduce disk cache to this number when running
                      in real mode.to make more memory available for its
                      own use.

 /A                   Uses expanded memory. If this option is not present,
                      then SMARTDrive attempts to use extended memory.



 Generally, the memory assigned to SMARTDRV.SYS cannot be used by
 other software. However, CodeView and Windows can share memory with
 SMARTDrive. Any remaining memory is used for disk-cache operations.


 ISAM Use of Expanded Memory

 By default, ISAM uses about 1.2 megabytes of expanded memory for
 buffer space (or as much as available, whichever is less). This helps to
 free conventional memory and improves performance by providing far more
 buffers than could exist in conventional memory.

 Depending on how much expanded memory you have, ISAM's use of 1.2
 megabytes may affect the performance of other programs that need this
 memory. To limit the amount of expanded memory that ISAM uses, use the
 /Ie command-line option with the BASIC Compiler or when starting the
 ISAM memory-resident program:

 /Ie: emsreserve

 In the syntax above,  emsreserve is the number of kilobytes to
 reserve for other software. The setting /Ie:-1 is a special value that
 disables ISAM's use of expanded memory altogether.

 For example, the following command line starts the ISAM
 memory-resident program and reserves 800K of expanded memory for other
 software, such as QBX or CodeView:

 PROISAMD /Ie:800

 Use /Ie in conjunction with the QBX /Es option if your program code
 or a loaded Quick library manages expanded memory. (See "Competing Use
 of Expanded Memory" later in this chapter.)

 Several other options affect how ISAM handles buffers. For complete
 documentation on how to configure and install ISAM, as well as how the
 number of buffers affects programs, see Chapter 10, "Database
 Programming with ISAM," in the  Programmer's Guide.


 Considerations for QBX

 The QBX environment and ISAM together require 450K to run (QBX itself
 requires over 300K). If you have 640K of conventional memory, QBX will
 support a moderate-sized program without trouble, but large programs may
 require the use of extended or expanded memory, especially if you use
 ISAM.


 Using the /NOFRILLS Option

 You can use the /NOFRILLS option (abbreviated as /NOF) to make
 additional memory available for program use. However, using /NOFRILLS
 reduces the functionality of the QBX environment.

 When you start QBX and use the /NOF command-line option, QBX uses
 about 19K less memory but does not support any of the following
 menus:

   ■   Utility menu
   ■   Options menu
   ■   Help menu


 The /NOF option does not change the structure of the menu bar or
 status line, but the three menus are unavailable and cannot be
 opened.


 Extended Memory

 QBX uses extended memory by moving approximately 60K of its own
 executable code out of conventional memory. All the code removed
 represents space freed for use by your programs.

 When using the HIMEM.SYS device driver, you should set  tsrmin
 to 63 (64,512 bytes) to ensure that QBX has access to the high-memory
 area. The  handles field has no effect on QBX, since these
 handles give access to addresses higher than the 64K area which QBX can
 use.

 For example, the following entry in your CONFIG.SYS file installs
 HIMEM.SYS and ensures that extended memory is available for QBX:

 device=C:\DEVICE\HIMEM.SYS /HMAMIN=63


 Expanded Memory

 When you start the QBX environment, expanded memory may have already
 been allocated to memory-resident programs, most notably ISAM. QBX uses
 as much of the the remaining expanded memory as it needs.

 You can limit the amount of expanded memory used by QBX by using the
 /E: command-line option:

 /E: emslimit

 In the preceding syntax,  emslimit
 determines the maximum amount of expanded memory that QBX will use, in
 kilobytes. A value of 0 disables QBX usage of expanded memory and can
 improve the execution speed of some operations.

 Assuming some expanded memory is available, QBX takes advantage of
 the memory in two ways:

   ■   QBX automatically moves each unit of program code smaller than 16K
 into expanded memory. Each procedure is a unit of code. The module-level
 code also constitutes a unit of code.

 To see how large each procedure is, use the View SUBs command
 (press F2). This command lists each unit of code together with size in
 kilobytes, rounded to the nearest kilobyte. You can determine which
 units are larger than 16K and should be divided into smaller units (see
 Figure 7.1). To guarantee best results, View SUBs should show sizes
 ranging from 0 to 15, inclusive.

   ■   If you give the /Ea command-line option, QBX moves arrays into
 expanded memory if they do not contain variable-length strings and are
 smaller than 16K. This option has a drawback: arrays residing in
 expanded memory cannot be passed to modules written in other languages
 (although you can pass array elements). Therefore, you may not want to
 use /Ea with mixed-language programs.

 This option affects all types of arrays except arrays of variable-
 length strings, which are not placed in expanded memory.


 The following QBX command line allows 500K of expanded memory to be
 used and moves arrays out of conventional memory:

 QBX /E:500 /Ea


 Note

 Once inside the QBX environment, you can determine how much expanded
 memory is actually available to QBX by executing the statement
 FRE(-3).


 Competing Use of Expanded Memory

 A Quick library can make use of expanded memory directly by using
 assembly code that calls the expanded-memory interrupt. However, Quick
 libraries that do this must compete with QBX for use of the memory. QBX
 will use as many 16K pages of expanded memory as required, according to
 the rules described in the previous section (assuming that the memory is
 available).

 In order to use expanded memory for Quick libraries, you need to keep
 two things in mind:

   ■   You must use the /Es command-line option when starting QBX. This
 option saves and restores the EMS state before and after every ISAM
 statement or call to a Quick library. This save-and-restore operation
 involves significant overhead, so don't use it unless you have a Quick
 library that manages expanded memory.

   ■   You may want to limit QBX use of expanded memory by using the /E:
 command-line option. This option is not always necessary, because QBX
 does not reserve more memory than it can use. However, the /E: option is
 useful for guaranteeing that your program always has the expanded memory
 it needs.


 The following example enables saving and restoring of the EMS state,
 and restricts the QBX environment to using at most 500K of expanded
 memory:

 QBX /E:500 /Es


 Considerations for Programmer's WorkBench

 PWB uses disk-based virtual memory for loaded source files. This
 means that the size of the program you create is limited only by the
 amount of free disk space you have and the amount of memory available
 for compiling and linking the program. It is possible, however, to run
 out of memory for PWB itself if you load a large number of PWB
 extensions or have a memory-resident program, such as PROISAM, loaded.

 You can make more memory available in PWB by not automatically
 loading the extension files. The /DA options disables the auto-load
 function. You can then explicitly load only the extensions you need by
 customizing your TOOLS.INI file. For more information, see the section
 "Loading PWB Extensions Explicitly" in Chapter 4.


 Considerations for CodeView

 When you debug a program in CodeView, three components compete for
 memory:

   ■   The program being debugged
   ■   The program's symbolic information
   ■   CodeView itself


 To make the most memory available to the executable being debugged,
 CodeView automatically uses expanded memory, extended memory, or disk
 overlays. In addition, CodeView provides a utility for compressing
 program symbol information (CVPACK). For more information on CVPACK, see
 Chapter 5, "Using CodeView."


 Extended Memory

 If HIMEM.SYS or another extended-memory device driver is installed,
 CodeView automatically places all of the program symbol information and
 all but 16K of CodeView itself in extended memory, leaving the remaining
 conventional memory available for program execution.

 The /X option is not required to use extended memory with CodeView,
 but if you specify /X and an extended memory driver is not installed,
 CodeView displays an error.


 Expanded Memory

 If extended memory is not available and RAMDRIVE.SYS. SMARTDRV.SYS,
 or a compatible expanded memory manager is installed, CodeView uses
 available expanded memory for program symbol information and for
 CodeView overlays.

 In order for CodeView to use expanded memory, no single module's
 symbol information can exceed 48K. If symbol information exceeds this
 limit, try reducing filename information by not specifying paths when
 you compile and using /Zd instead of /Zi.

 The /E option is not required to use expanded memory with CodeView,
 but if you specify /E and an expanded memory driver is not installed,
 CodeView displays an error.


 Overlays

 If extended or expanded memory are not available, CodeView uses 64K
 disk overlays for its executable. You can use the /Dbuffersize
  option to improve performance by reducing the size of the overlay,
 making more memory available, or increasing the size of the overlay.

 CodeView will not use overlays smaller than 16K nor larger than 128K.
 Therefore, the minimum effective value for  buffersize
  is 16 and the maximum is 128.