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

Text File | 2013-11-08 | 872.7 KB | 24,289 lines

 Microsoft QuickBASIC:  Programming in BASIC


 ════════════════════════════════════════════════════════════════════════════


 Microsoft(R) QuickBASIC:  Programming in BASIC

 For IBM(R) 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.

   (C)Copyright Microsoft Corporation, 1987, 1988. All rights reserved.

   Simultaneously published in the U.S. and Canada.

   Printed and bound in the United States of America.

   Microsoft, MS, MS-DOS, CodeView, GW-BASIC, and XENIX

   are registered trademarks of Microsoft Corporation.

   Hayes is a registered trademark of Hayes Microcomputer Products, Inc.

   IBM and PS/2 are registered trademarks of International Business Machines
   Corporation.

   Intel is a registered trademark of Intel Corporation.

   ProKey is a trademark of RoseSoft, Inc.

   SideKick and SuperKey are registered trademarks of Borland International,
   Inc.

   WordStar is a registered trademark of MicroPro International Corporation.



 ────────────────────────────────────────────────────────────────────────────
 Contents

 Introduction
            The QuickBASIC Language
            The QuickBASIC Environment
            Using This Manual
              Selected Programming Topics
              The Heart of BASIC
              Appendixes
            Document Conventions
            Programming Style in this Manual

 PART 1  SELECTED PROGRAMMING TOPICS

 Chapter 1  Control-Flow Structures
            1.1  Changing Statement Execution Order
            1.2  Boolean Expressions
            1.3  Decision Structures
                 1.3.1  Block IF...THEN...ELSE
                 1.3.2  SELECT CASE
                        1.3.2.1  Using the SELECT CASE Statement
                        1.3.2.2  SELECT CASE Versus ON...GOSUB
            1.4  Looping Structures
                 1.4.1  FOR...NEXT Loops
                        1.4.1.1  Exiting a FOR...NEXT Loop with EXIT FOR
                        1.4.1.2  Pausing Program Execution with FOR...NEXT
                 1.4.2  WHILE...WEND Loops
                 1.4.3  DO...LOOP Loops
                        1.4.3.1  Loop Tests: One Way to Exit DO...LOOP
                        1.4.3.2  EXIT DO: An Alternative Way to Exit
                                 DO...LOOP
            1.5  Sample Applications
                 1.5.1  Checkbook-Balancing Program (CHECK.BAS)
                 1.5.2  Carriage-Return and Line-Feed Filter (CRLF.BAS)

 Chapter 2  SUB and FUNCTION Procedures
            2.1  Procedures: Building Blocks for Programming
            2.2  Comparing Procedures with Subroutines and Functions
                 2.2.1  Comparing SUB with GOSUB
                        2.2.1.1  Local and Global Variables
                        2.2.1.2  Use in Multiple-Module Programs
                        2.2.1.3  Operating on Different Sets of Variables
                 2.2.2  Comparing FUNCTION with DEF FN
                        2.2.2.1  Local and Global Variables
                        2.2.2.2  Changing Variables Passed to the Procedure
                        2.2.2.3  Calling the Procedure within Its
                                 Definition
                        2.2.2.4  Use in Multiple-Module Programs
            2.3  Defining Procedures
            2.4  Calling Procedures
                 2.4.1  Calling a FUNCTION Procedure
                 2.4.2  Calling a SUB Procedure
            2.5  Passing Arguments to Procedures
                 2.5.1  Parameters and Arguments
                 2.5.2  Passing Constants and Expressions
                 2.5.3  Passing Variables
                        2.5.3.1  Passing Simple Variables
                        2.5.3.2  Passing an Entire Array
                        2.5.3.3  Passing Individual Array Elements
                        2.5.3.4  Using Array-Bound Functions
                        2.5.3.5  Passing an Entire Record
                        2.5.3.6  Passing Individual Elements of a Record
                 2.5.4  Checking Arguments with the DECLARE Statement
                        2.5.4.1  When QuickBASIC Does Not Generate a DECLARE
                                 Statement
                        2.5.4.2  Developing Programs outside the QuickBASIC
                                 Environment
                        2.5.4.3  Using Include Files for Declarations
                        2.5.4.4  Declaring Procedures in Quick Libraries
                 2.5.5  Passing Arguments by Reference
                 2.5.6  Passing Arguments by Value
            2.6  Sharing Variables with SHARED
                 2.6.1  Sharing Variables with Specific Procedures in a
                        Module
                 2.6.2  Sharing Variables with All Procedures in a Module
                 2.6.3  Sharing Variables with Other Modules
                 2.6.4  The Problem of Variable Aliasing
            2.7  Automatic and STATIC Variables
            2.8  Preserving Values of Local Variables with the STATIC
                 Statement
            2.9  Recursive Procedures
                 2.9.1  The Factorial Function
                 2.9.2  Adjusting the Size of the Stack
            2.10  Transferring Control to Another Program with CHAIN
            2.11  Sample Application: Recursive Directory Search
                  (WHEREIS.BAS)

 Chapter 3  File and Device I/O
            3.1  Printing Text on the Screen
                 3.1.1  Screen Rows and Columns
                 3.1.2  Displaying Text and Numbers with PRINT
                 3.1.3  Displaying Formatted Output with PRINT USING
                 3.1.4  Skipping Spaces and Advancing to a Specific Column
                 3.1.5  Changing the Number of Columns or Rows
                 3.1.6  Creating a Text Viewport
            3.2  Getting Input from the Keyboard
                 3.2.1  The INPUT Statement
                 3.2.2  The LINE INPUT Statement
                 3.2.3  The INPUT$ Function
                 3.2.4  The INKEY$ Function
            3.3  Controlling the Text Cursor
                 3.3.1  Positioning the Cursor
                 3.3.2  Changing the Cursor's Shape
                 3.3.3  Getting Information about the Cursor's Location
            3.4  Working with Data Files
                 3.4.1  How Data Files Are Organized
                 3.4.2  Sequential and Random-Access Files
                 3.4.3  Opening a Data File
                        3.4.3.1  File Numbers in BASIC
                        3.4.3.2  File Names in BASIC
                 3.4.4  Closing a Data File
                 3.4.5  Using Sequential Files
                        3.4.5.1  Records in Sequential Files
                        3.4.5.2  Putting Data in a New Sequential File
                        3.4.5.3  Reading Data from a Sequential File
                        3.4.5.4  Adding Data to a Sequential File
                        3.4.5.5  Other Ways to Write Data to a Sequential
                                 File
                        3.4.5.6  Other Ways to Read Data from a Sequential
                                 File
                 3.4.6  Using Random-Access Files
                        3.4.6.1  Records in Random-Access Files
                        3.4.6.2  Adding Data to a Random-Access File
                        3.4.6.7  Reading Data Sequentially
                        3.4.6.8  Using Record Numbers to Retrieve Records
                 3.4.7  Binary File I/O
                        3.4.7.1  Comparing Binary Access and Random Access
                        3.4.7.2  Positioning the File Pointer with SEEK
            3.5  Working with Devices
                 3.5.1  Differences between Device I/O and File I/O
                 3.5.2  Communications through the Serial Port
            3.6  Sample Applications
                 3.6.1  Perpetual Calendar (CAL.BAS)
                 3.6.2  Indexing a Random-Access File (INDEX.BAS)
                 3.6.3  Terminal Emulator (TERMINAL.BAS)

 Chapter 4  String Processing
            4.1  Strings Defined
            4.2  Variable- and Fixed-Length Strings
                 4.2.1  Variable-Length Strings
                 4.2.2  Fixed-Length Strings
            4.3  Combining Strings
            4.4  Comparing Strings
            4.5  Searching for Strings
            4.6  Retrieving Parts of Strings
                 4.6.1  Retrieving Characters from the Left Side of a
                        String
                 4.6.2  Retrieving Characters from the Right Side of a
                        String
                 4.6.3  Retrieving Characters from Anywhere in a String
            4.7  Generating Strings
            4.8  Changing the Case of Letters
            4.9  Strings and Numbers
            4.10 Changing Strings
            4.11 Sample Application: Converting a String to a Number
                  (STRTONUM.BAS)

 Chapter 5  Graphics
            5.1  What You Need for Graphics Programs
            5.2  Pixels and Screen Coordinates
            5.3  Drawing Basic Shapes: Points, Lines, Boxes, and Circles
                 5.3.1  Plotting Points with PSET and PRESET
                 5.3.2  Drawing Lines and Boxes with LINE
                        5.3.2.1  Using the STEP Option
                        5.3.2.2  Drawing Boxes
                        5.3.2.3  Drawing Dotted Lines
            5.4  Drawing Circles and Ellipses with CIRCLE
                 5.4.1  Drawing Circles
                 5.4.2  Drawing Ellipses
                 5.4.3  Drawing Arcs
                 5.4.4  Drawing Pie Shapes
                 5.4.5  Drawing Shapes to Proportion with the Aspect Ratio
            5.5  Defining a Graphics Viewport
            5.6  Redefining Viewport Coordinates with WINDOW
                 5.6.1  The Order of Coordinate Pairs
                 5.6.2  Keeping Track of View and Physical Coordinates
            5.7  Using Colors
                 5.7.1  Selecting a Color for Graphics Output
                 5.7.2  Changing the Foreground or Background Color
                 5.7.3  Changing Colors with PALETTE and PALETTE USING
            5.8  Painting Shapes
                 5.8.1  Painting with Colors
                 5.8.2  Painting with Patterns: Tiling
                        5.8.2.1  Pattern-Tile Size in Different Screen
                                 Modes
                        5.8.2.2  Creating a Single-Color Pattern in Screen
                                 Mode 2
                        5.8.2.3  Creating a Multicolor Pattern in Screen Mode
                                 1
                        5.8.2.4  Creating a Multicolor Pattern in Screen Mode
                                 8
            5.9  DRAW: a Graphics Macro Language
            5.10 Basic Animation Techniques
                 5.10.1  Saving Images with GET
                 5.10.2  Moving Images with PUT
                 5.10.3  Animation with GET and PUT
                 5.10.4  Animating with Screen Pages
            5.11 Sample Applications
                 5.11.1  Bar-Graph Generator (BAR.BAS)
                 5.11.2  Color in a Figure Generated Mathematically
                         (MANDEL.BAS)
                 5.11.3  Pattern Editor (EDPAT.BAS)

 Chapter 6  Error and Event Trapping
            6.1  Error Trapping
                 6.1.1  Activating Error Trapping
                 6.1.2  Writing an Error-Handling Routine
                        6.1.2.1  Using ERR to Identify Errors
                        6.1.2.2  Returning from an Error-Handling Routine
            6.2  Event Trapping
                 6.2.1  Detecting Events by Polling
                 6.2.2  Detecting Events by Trapping
                 6.2.3  Specifying the Event to Trap and Activating Event
                        Trapping
                 6.2.4  Events That BASIC Can Trap
                 6.2.5  Suspending or Disabling Event Trapping
                 6.2.6  Trapping Keystrokes
                        6.2.6.1  Trapping User-Defined Keys
                        6.2.6.2  Trapping User-Defined Shifted Keys
                 6.2.7  Trapping Music Events
            6.3  Error and Event Trapping in SUB or FUNCTION Procedures
            6.4  Trapping across Multiple Modules
                 6.4.1  Event Trapping across Modules
                 6.4.2  Error Trapping across Modules
            6.5  Trapping Errors and Events in Programs Compiled with BC
            6.6  Sample Application: Trapping File-Access Errors
                 (FILERR.BAS)

 Chapter 7  Programming with Modules
            7.1  Why Use Modules?
            7.2  Main Modules
            7.3  Modules Containing Only Procedures
            7.4  Creating a Procedures-Only Module
            7.5  Loading Modules
            7.6  Using the DECLARE Statement with Multiple Modules
            7.7  Accessing Variables from Two or More Modules
            7.8  Using Modules During Program Development
            7.9  Compiling and Linking Modules
            7.10 Quick Libraries
                 7.10.1  Creating Quick Libraries
            7.11 Tips for Good Programming with Modules

 PART 2  HEART OF BASIC

 Chapter 8  Statement and Function Summary
            ABS Function
            ASC Function
            ATN Function
            BEEP Statement
            BLOAD Statement
            BSAVE Statement
            CALL Statement (BASIC Procedures)
            CALL, CALLS Statement (Non-BASIC Procedures)
            CALL INT86OLD Statements
            CALL ABSOLUTE Statement
            CALL INTERRUPT Statements
            CDBL Function
            CHAIN Statement
            CHDIR Statement
            CHR$ Function
            CINT Function
            CIRCLE Statement
            CLEAR Statement
            CLNG Function
            CLOSE Statement
            CLS Statement
            COLOR Statement
            COM Statements
            COMMAND$ Function
            COMMON Statement
            CONST Statement
            COS Function
            CSNG Function
            CSRLIN Function
            CVI, CVS, CVL, CVD Functions
            CVSMBF, CVDMBF Functions
            DATA Statement
            DATE$ Function
            DATE$ Statement
            DECLARE Statement (BASIC Procedures)
            DECLARE Statement (Non-BASIC Procedures)
            DEF FN Statement
            DEF SEG Statement
            DEFtype Statements
            DIM Statement
            DO...LOOP Statements
            DRAW Statement
            END Statement
            ENVIRON$ Function
            ENVIRON Statement
            EOF Function
            ERASE Statement
            ERDEV, ERDEV$ Functions
            ERR, ERL Functions
            ERROR Statement
            EXIT Statement
            EXP Function
            FIELD Statement
            FILEATTR Function
            FILES Statement
            FIX Function
            FOR...NEXT Statement
            FRE Function
            FREEFILE Function
            FUNCTION Statement
            GET Statement──File I/O
            GET Statement──Graphics
            GOSUB...RETURN Statements
            GOTO Statement
            HEX$ Function
            IF...THEN...ELSE Statements
            INKEY$ Function
            INP Function
            INPUT$ Function
            INPUT Statement
            INPUT # Statement
            INSTR Function
            INT Function
            IOCTL$ Function
            IOCTL Statement
            KEY Statements
            KEY(n) Statements
            KILL Statement
            LBOUND Function
            LCASE$ Function
            LEFT$ Function
            LEN Function
            LET Statement
            LINE Statement
            LINE INPUT Statement
            LINE INPUT # Statement
            LOC Function
            LOCATE Statement
            LOCK...UNLOCK Statement
            LOF Function
            LOG Function
            LPOS Function
            LPRINT, LPRINT USING Statements
            LSET Statement
            LTRIM$ Function
            MID$ Function
            MID$ Statement
            MKD$, MKI$, MKL$, MKS$ Functions
            MKDIR Statement
            MKSMBF$, MKDMBF$ Functions
            NAME Statement
            OCT$ Function
            ON ERROR Statement
            ON event Statements
            ON UEVENT GOSUB Statement
            ON...GOSUB, ON...GOTO Statements
            OPEN Statement
            OPEN COM Statement
            OPTION BASE Statement
            OUT Statement
            PAINT Statement
            PALETTE, PALETTE USING Statements
            PCOPY Statement
            PEEK Function
            PEN Function
            PEN ON, OFF, and STOP Statements
            PLAY Function
            PLAY Statement
            PLAY ON, OFF, and STOP Statements
            PMAP Function
            POINT Function
            POKE Statement
            POS Function
            PRESET Statement
            PRINT Statement
            PRINT #, PRINT # USING Statements
            PRINT USING Statement
            PSET Statement
            PUT Statement──File I/O
            PUT Statement──Graphics
            RANDOMIZE Statement
            READ Statement
            REDIM Statement
            REM Statement
            RESET Statement
            RESTORE Statement
            RESUME Statement
            RETURN Statement
            RIGHT$ Function
            RMDIR Statement
            RND Function
            RSET Statement
            RTRIM$ Function
            RUN Statement
            SADD Function
            SCREEN Function
            SCREEN Statement
            SEEK Function
            SEEK Statement
            SELECT CASE Statement
            SETMEM Function
            SGN Function
            SHARED Statement
            SHELL Statement
            SIN Function
            SLEEP Statement
            SOUND Statement
            SPACE$ Function
            SPC Function
            SQR Function
            STATIC Statement
            STICK Function
            STOP Statement
            STR$ Function
            STRIG Function and Statement
            STRIG ON, OFF, and STOP Statements
            STRING$ Function
            SUB Statements
            SWAP Statement
            SYSTEM Statement
            TAB Function
            TAN Function
            TIME$ Function
            TIME$ Statement
            TIMER Function
            TIMER ON, OFF, and STOP Statements
            TRON/TROFF Statements
            TYPE Statement
            UBOUND Function
            UCASE$ Function
            UEVENT Statement
            UNLOCK Statement
            VAL Function
            VARPTR, VARSEG Functions
            VARPTR$ Function
            VIEW Statement
            VIEW PRINT Statement
            WAIT Statement
            WHILE...WEND Statement
            WIDTH Statement
            WINDOW Statement
            WRITE Statement
            WRITE # Statement

 Chapter 9  Quick-Reference Tables
            9.1  Summary of Control-Flow Statements
            9.2  Summary of Statements Used in BASIC Procedures
            9.3  Summary of Standard I/O Statements
            9.4  Summary of File I/O Statements
            9.5  Summary of String-Processing Statements and Functions
            9.6  Summary of Graphics Statements and Functions
            9.7  Summary of Trapping Statements and Functions

 Appendix A  Converting BASICA Programs to QuickBASIC

 Appendix B  Differences from Previous Versions of QuickBASIC

 Appendix C  Limits in QuickBASIC

 Appendix D  Keyboard Scan Codes and ASCII Character Codes

 Appendix E  BASIC Reserved Words

 Appendix F  Metacommands

 Appendix G  Compiling and Linking from DOS

 Appendix H  Creating and Using Quick Libraries

 Appendix I  Error Messages

 Figures
 Figure 1.1  Logic of FOR...NEXT Loop with Positive STEP
 Figure 1.2  Logic of FOR...NEXT Loop with Negative STEP
 Figure 1.3  Logic of WHILE...WEND Loop
 Figure 1.4  Logic of DO WHILE...LOOP
 Figure 1.5  Logic of DO UNTIL...LOOP
 Figure 1.6  Logic of DO...LOOP WHILE
 Figure 1.7  Logic of DO...LOOP UNTIL
 Figure 2.1  Parameters and Arguments
 Figure 3.1  Text Output on Screen
 Figure 3.2  Records in Sequential Files
 Figure 3.3  Records in a Random-Access File
 Figure 5.1  Coordinates of Selected Pixels in Screen Mode 2
 Figure 5.2  How Angles Are Measured for CIRCLE
 Figure 5.3  The Aspect Ratio In Screen Mode 1
 Figure 5.4  WINDOW Contrasted with WINDOW SCREEN
 Figure 5.5  Patterned Circle
 Figure 6.1  Program Flow of Control with RESUME
 Figure 6.2  Program Flow of Control with RESUME NEXT
 Figure 7.1  Main Module Showing Module-Level Code and Procedures
 Figure H.1  Make Library Dialog Box

 Tables
 Table 1.1  Relational Operators Used in Basic
 Table 1.2  Block IF...THEN...ELSE Syntax and Example
 Table 1.3  SELECT CASE Syntax and Example
 Table 1.4  FOR...NEXT Syntax and Example
 Table 1.5  WHILE...WEND Syntax and Example
 Table 1.6  DO...LOOP Syntax and Example: Test at the Beginning
 Table 1.7  DO...LOOP Syntax and Example: Test at the End
 Table 3.1  Devices Supported by BASIC for I/O
 Table 5.1  Color Palettes in Screen Mode 1
 Table 5.2  Background Colors in Screen Mode 1
 Table 5.3  Binary to Hexadecimal Conversion
 Table 5.4  The Effect of Different Action Options in Screen Mode 2
 Table 5.5  The Effect of Different Action Options on Color in Screen Mode 1
 (Palette 1)
 Table 6.1  BC Command-Line Options for Error and Event Trapping
 Table 9.1  Statements Used in Looping and Decision-Making
 Table 9.2  Statements Used in Procedures
 Table 9.3  Statements and Functions Used for Standard I/O
 Table 9.4  Statements and Functions Used for Data-File I/O
 Table 9.5  Statements and Functions Used for Processing Strings
 Table 9.6  Statements and Functions Used for Graphics Output
 Table 9.7  Statements andn Functions Used in Error and Event Trapping
 Table A.1  Statements Requiring Modification
 Table B.1  Features of Microsoft QuickBASIC Version 4.5
 Table B.2  Menus with New Commands in QuickBASIC Version 4.5
 Table B.3  Editing-Key Changes
 Table B.4  QB and BC Options Not Used in QuickBASIC Versions 4.0 or 4.5
 Table B.5  Options Introduced in Version 4.0 for the QB and BC Commands
 Table B.6  Debugging-Key Changes
 Table B.7  Changes to the BASIC Language
 Table C.1  QuickBASIC Limits
 Table G.1  Input to the BC Command
 Table G.2  Input to the LINK Command
 Table G.3  Input to the LIB Command
 Table I.1  Run-Time Error Codes



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

   Microsoft(R) QuickBASIC 4.5 is a major advance in making BASIC both more
   powerful and easier to use. It provides the most advanced BASIC yet
   offered for microcomputers, supported by an operating environment that
   allows you to focus on program creation──not the mechanics of writing or
   debugging.


 The QuickBASIC Language

   If you already know how to program in BASICA (or a similar interpreted
   BASIC), you'll appreciate the enhanced language features QuickBASIC
   provides to make it easier to write and maintain your software. For
   example:

   ■ The SELECT CASE statement cleanly transfers control to any block of code
     without the use of nested IF...THEN...ELSE statements. SELECT CASE
     permits an exceptionally wide range of test expressions, so you can
     create exactly the comparison you need.

   ■ QuickBASIC's SUB and FUNCTION procedures allow you to place groups of
     program statements into subprograms that your main program can call
     repeatedly. QuickBASIC's modularity makes it easy to save these
     procedures and reuse them in other programs.

   ■ QuickBASIC procedures are fully recursive──a procedure can call itself
     repeatedly. This simplifies the programming of many numerical and
     sorting algorithms that are best expressed recursively.

   ■ You can define your own data types, made up of any combination of
     integer, real, and string variables. Related variables can be
     conveniently grouped under a single name, which simplifies passing them
     to a procedure or writing them to a file.

   ■ QuickBASIC supports binary file access. Your programs can read and
     manipulate files in any format because binary I/O can directly access
     any byte in the file.

   QuickBASIC is a powerful development tool for professional use. Yet it is
   also the ideal language for beginning and intermediate programmers──people
   who aren't professional programmers but need a language that helps them
   reach their programming goals efficiently.


 The QuickBASIC Environment

   QuickBASIC isn't just an outstanding language. It is also an integrated
   programming environment that significantly simplifies writing and
   debugging software:

   ■ As you type in your program, a smart editor checks each line for syntax
     errors. When you are ready to run, press a single key to execute the
     program instantly. If something is wrong, use the full-screen editor to
     correct the problem, then run the program again.

   ■ You can debug your programs without exiting QuickBASIC. The integrated
     debugger lets you examine and alter variables, execute any part of the
     program, or halt execution when a particular condition is met. All these
     things happen within the QuickBASIC environment; you don't have to alter
     the program or add PRINT statements.

   ■ QuickBASIC 4.5 has two new commands to make the debugger even more
     powerful: the Instant Watch command and the Break on Errors command.

   ■ Also new to QuickBASIC 4.5 is the Microsoft QB Advisor, our on-line
     help. The QB Advisor is always at hand, whether you are writing,
     running, or debugging. Just place the cursor on the keyword or
     user-defined name you want to know more about, then press F1. The QB
     Advisor describes the syntax of BASIC statements and functions, explains
     how to use them, and even provides usable programming examples.


 Using This Manual

   This manual is in three parts. Part 1, "Selected Programming Topics,"
   provides information on specific programming techniques and strategies.
   Part 2, "Heart of BASIC," and the appendixes contain important reference
   material.

 Selected Programming Topics

   Each chapter in this first section focuses on a single programming area.
   Studying this material will help you to quickly master

   ■ Control-flow structures

   ■ SUB and FUNCTION procedures

   ■ File and device input and output

   ■ String processing

   ■ Graphics

   ■ Error and event trapping

   ■ Programming with modules

   The presentation of each topic is straightforward and easy to understand,
   with many short programming examples that demonstrate how each part of
   BASIC works. The progression is from simple to more complex topics, so you
   can work through this material at your own pace without worrying about the
   order in which to study it. The focus throughout is on utility, not
   theory──how you can solve common programming problems with QuickBASIC.

   In addition to the short examples, the chapters contain complete working
   programs that demonstrate the programming principles presented in that
   chapter. For your convenience, these programs are also included on your
   QuickBASIC release disks.

   If you're an experienced BASIC programmer, you'll probably want to browse
   through the table of contents for a topic that catches your interest. If
   you're a novice programmer, though, you should probably work through each
   chapter from beginning to end. If you have never programmed in any
   language, you should start with Chapter 4 of Learning to Use Microsoft
   QuickBASIC, "Interlude: BASIC for Beginners."

   Regardless of your interests or background, these seven chapters will help
   you learn almost everything you need to know to write sophisticated BASIC
   applications.

 The Heart of BASIC

   The second part of this manual, the "Heart of BASIC," is a handy,
   two-part quick reference to BASIC statements and functions.

   Chapter 8, "Statement and Function Summary," is an alphabetically
   arranged summary of every BASIC keyword, describing its action or use and
   displaying its syntax. If your memory needs jogging on statement or
   function use, turn to this section.

   In Chapter 9, "Quick-Reference Tables," the most commonly used BASIC
   statements and functions are displayed in six sections in table form, with
   each statement given a brief description. The contents of these sections
   match the material presented in Chapters 1 through 6 of "Selected
   Programming Topics." If you are trying to figure out how to accomplish a
   particular programming task, turn to this section.

 Appendixes

   The third section of this manual is a group of appendixes containing
   reference information on

   ■ Converting BASICA programs

   ■ Differences from previous versions

   ■ Limits in QuickBASIC

   ■ Keyboard scan codes and ASCII codes

   ■ BASIC reserved words

   ■ Metacommands

   ■ Compiling and linking from DOS

   ■ Creating and using Quick libraries

   ■ Error messages


 Document Conventions

   This manual uses the following typographic conventions:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
   Example of Convention    Description
   ──────────────────────────────────────────────────────────────────────────
   QB.LIB, ADD.EXE, COPY,   Uppercase (capital) letters indicate file names
   LINK, /X                 and DOS-level commands. Uppercase is also used
                            for command-line options (unless the application
                            accepts only lowercase).

   SUB, IF, LOOP, PRINT,    Bold capital letters indicate language-specific
   WHILE, TIME$             keywords with special meaning to Microsoft BASIC.
   Example of Convention    Description
   ──────────────────────────────────────────────────────────────────────────
  WHILE, TIME$             keywords with special meaning to Microsoft BASIC.
                            Keywords are a required part of statement syntax,
                            unless they are enclosed in double brackets as
                            explained below. In programs you write, you must
                            enter keywords exactly as shown. However, you can
                            use uppercase letters or lowercase letters.

   CALL NewProc(arg1!,      This kind of type is used for program examples,
   var2%)                   program output, and error messages within the
                            text.

   '$INCLUDE:'BC.BI'        A column of three dots indicates that part of the
     .                      example program has been intentionally omitted.
     .
     .
   CHAIN "PROG1"
   END

   ' Make one pass          The apostrophe (single right quotation mark)
   Example of Convention    Description
   ──────────────────────────────────────────────────────────────────────────
  ' Make one pass          The apostrophe (single right quotation mark)
                            marks the beginning of a comment in sample
                            programs.

   filespec                 Italic letters indicate placeholders for
                            information you must supply, such as a file name.
                            Italics are also occasionally used in the text
                            for emphasis.

   [[optional-item]]        Items inside double square brackets are optional.

   {choice1 | choice2}      Braces and a vertical bar indicate a choice among
                            two or more items. You must choose one of the
                            items unless all of the items are also enclosed
                            in double square brackets.

   repeating elements...    Three dots following an item indicate that more
                            items having the same form may appear.

   Example of Convention    Description
   ──────────────────────────────────────────────────────────────────────────

   ALT+F1                   Capital letters are used for the names of keys
                            and key sequences, such as ENTER and CTRL+R.

                            A plus (+) indicates a combination of keys. For
                            example, CTRL+E means to hold down the CTRL key
                            while pressing the E key.

                            The carriage-return key, sometimes marked with a
                            bent arrow, is referred to as ENTER.

                            The cursor movement ("arrow") keys on the numeric
                            keypad are called DIRECTION keys. Individual
                            DIRECTION keys are referred to by the direction
                            of the arrow on the key top (LEFT, RIGHT, UP,
                            DOWN) or the name on the key top (PGUP, PGDN).

                            The key names used in this manual correspond to
                            the names on the IBM(R) Personal Computer keys.
   Example of Convention    Description
   ──────────────────────────────────────────────────────────────────────────
                           the names on the IBM(R) Personal Computer keys.
                            Other machines may use different names.

   "defined term"           Quotation marks usually indicate a new term
                            defined in the text.

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


   The syntax below (for the "LOCK...UNLOCK" statements) illustrates many of
   the typographic conventions in this manual:

   LOCK[[#]]filenumber[[,{record|[[start]] TO end}]] . . .
   UNLOCK[[#]]filenumber[[,{record |[[start]] TO end}]]

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Throughout this manual, the term "DOS" refers to both the MS-DOS(R) and
     IBM Personal Computer DOS operating systems. The name of a specific
     operating system is used when it is necessary to note features that are
     unique to that system. The term "BASICA" refers to interpreted versions
     of BASIC in general.
   ──────────────────────────────────────────────────────────────────────────


 Programming Style in this Manual

   The following guidelines were used in writing programs in this manual and
   on the distribution disks. These guidelines are only recommendations for
   program readability; you are not obliged to follow them when writing your
   own programs.

   ■ Keywords and symbolic constants appear in uppercase letters:

     ' PRINT, DO, LOOP, UNTIL are keywords:
     PRINT "Title Page"
     DO LOOP UNTIL Response$ = "N"

     ' FALSE and TRUE are symbolic constants
     ' equal to 0 and -1, respectively:
     CONST FALSE = 0, TRUE = NOT FALSE

   ■ Variable names are in lowercase with an initial capital letter; variable
     names with more than one syllable may contain other capital letters to
     clarify the division:

     NumRecords% = 45
     DateOfBirth$ = "11/24/54"

   ■ Line labels are used instead of line numbers. The use of line labels is
     restricted to event-trapping and error-handling routines, as well as
     DATA statements when referenced with RESTORE:

     ' TimerHandler and ScreenTwoData are line labels:
     ON TIMER GOSUB TimerHandler
     RESTORE ScreenTwoData

   ■ As noted in the preceding section, a single apostrophe (') introduces
     comments:

     ' This is a comment; these two lines
     ' are ignored when the program is running.

   ■ Control-flow blocks and statements in procedures or subroutines are
     indented from the enclosing code:

     SUB GetInput STATIC
        FOR I% = 1 TO 10
           INPUT X
           IF X > 0 THEN
              .
              .
              .
           ELSE
              .
              .
              .
           END IF
        NEXT I%
     END SUB



 ────────────────────────────────────────────────────────────────────────────
 PART 1  SELECTED PROGRAMMING TOPICS
 ────────────────────────────────────────────────────────────────────────────

   Part 1 introduces the fundamentals of programming in BASIC. Simpler topics
   are covered first.

   Chapter 1 discusses the control-flow structures that direct your
   program's execution. Chapter 2 is about QuickBASIC SUB and FUNCTION
   procedures, two very powerful programming tools. Chapter 3 describes the
   ways you can use QuickBASIC to work with the data your program accepts and
   produces. Chapter 4 covers the use of text strings, and Chapter 5
   presents QuickBASIC's graphics capabilities.

   More advanced topics are covered in the last two chapters. Chapter 6
   looks at error and event trapping, and Chapter 7 tells you how to use
   programming with modules to your advantage.



 ────────────────────────────────────────────────────────────────────────────
 Chapter 1  Control-Flow Structures

   This chapter shows you how to use control-flow structures──specifically,
   loops and decision statements──to control the flow of your program's
   execution. Loops make a program execute a sequence of statements however
   many times you want. Decision statements let the program decide which of
   several alternative paths to take.

   When you are finished with this chapter, you will know how to do the
   following tasks related to using loops and decision statements in your
   BASIC programs:

   ■ Compare expressions using relational operators

   ■ Combine string or numeric expressions with logical operators and
     determine if the resulting expression is true or false

   ■ Create branches in the flow of the program with the statements
     IF...THEN...ELSE and SELECT CASE

   ■ Write loops that repeat statements a specific number of times

   ■ Write loops that repeat statements while or until a certain condition is
     true


 1.1  Changing Statement Execution Order

   Left unchecked by control-flow statements, a program's logic flows through
   statements from left to right, top to bottom. While some very simple
   programs can be written with only this unidirectional flow, most of the
   power and utility of any programming language comes from its ability to
   change statement execution order with decision structures and loops.

   With a decision structure, a program can evaluate an expression, then
   branch to one of several different groups of related statements (statement
   blocks) depending on the result of the evaluation. With a loop, a program
   can repeatedly execute statement blocks.

   If you are coming to this version of BASIC after programming in BASICA,
   you will appreciate the added versatility of these additional control-flow
   structures:

   ■ The block IF...THEN...ELSE statement

   ■ The SELECT CASE statement

   ■ The DO...LOOP and EXIT DO statements

   ■ The EXIT FOR statement, which provides an alternative way to exit
     FOR...NEXT loops


 1.2  Boolean Expressions

   A Boolean expression is any expression that returns the value "true" or
   "false." BASIC uses Boolean expressions in certain kinds of decision
   structures and loops. The following IF...THEN...ELSE statement contains a
   Boolean expression, X < Y:

   IF X < Y THEN CALL Procedure1 ELSE CALL Procedure2

   In the previous example, if the Boolean expression is true (if the value
   of the variable X is in fact less than the value of the variable Y), then
   Procedure1 is executed; otherwise (if X is greater than or equal to Y),
   Procedure2 is executed.

   The preceding example also demonstrates a common use of Boolean
   expressions: comparing two other expressions (in this case, X and Y) to
   determine the relationship between them. These comparisons are made with
   the relational operators shown in Table 1.1.

   Table 1.1  Relational Operators Used in BASIC
   Operator                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   =                        Equal

   < >                      Not equal

   <                        Less than

   <=                       Less than or equal to

   >                        Greater than

   >=                       Greater than or equal to
   ──────────────────────────────────────────────────────────────────────────

   You can use these relational operators to compare string expressions. In
   this case "greater than," "less than," and so on refer to alphabetical
   order. For example, the following expression is true, since the word
   "deduce" comes alphabetically before the word "deduct":

   "deduce" < "deduct"

   Logical operators

   Boolean expressions also frequently use the "logical operators" AND, OR,
   NOT, XOR, IMP, and EQV. These operators allow you to construct compound
   tests from one or more Boolean expressions. For example,

   expression1 AND expression2

   is true only if expression1 and expression2 are both true. Thus, in the
   following example, the message All sorted is printed only if both the
   Boolean expressions X <= Y and Y <= Z are true:

   IF (X <= Y) AND (Y <= Z) THEN PRINT "All sorted"

   The parentheses around the Boolean expressions in the last example are not
   really necessary, since relational operators such as <= are evaluated
   before logical operators such as AND. However, parentheses make a complex
   Boolean expression more readable and ensure that its components are
   evaluated in the order that you intend.

   BASIC uses the numeric values -1 and 0 to represent true and false,
   respectively. You can see this by asking BASIC to print a true expression
   and a false expression, as in the next example:

   x = 5
   y = 10
   PRINT x < y  ' Evaluate, print a "true"  Boolean expression.
   PRINT x > y  ' Evaluate, print a "false" Boolean expression.

   Output

   -1
    0

   The value -1 for true makes more sense when you consider how BASIC's NOT
   operator works: NOT inverts each bit in the binary representation of its
   operand, changing 1 bits to 0 bits, and 0 bits to 1 bits. Therefore, since
   the integer value 0 (false) is stored internally as a sequence of sixteen
   0 bits, NOT 0 (true) is stored internally as sixteen 1 bits, as shown
   below:

   0000000000000000

   TRUE = NOT FALSE = 1111111111111111

   In the two's-complement method that BASIC uses to store integers, sixteen
   1 bits represent the value -1.

   Note that BASIC outputs -1 when it evaluates a Boolean expression as true;
   however, BASIC considers any nonzero value to be true, as shown by the
   output from the following example:

   INPUT "Enter a value: ", x

   IF x THEN PRINT x "is true."

   Output

   Enter a value: 2
    2 is true.

   The NOT operator in BASIC is a "bitwise" operator. Some programming
   languages, such as C and Pascal, have both a bitwise NOT operator and a
   "logical" NOT operator. The distinction is as follows:

   ■ A bitwise NOT returns false (0) only for the value -1.

   ■ A logical NOT returns false (0) for any true (nonzero) value.

   In BASIC, for any true expression not equal to -1, NOT expression returns
   another true value, as shown by the following list:

   Value of expression      Value of NOT expression
   ──────────────────────────────────────────────────────────────────────────
    1                       -2

    2                       -3

   -2                        1

   -1                        0
   ──────────────────────────────────────────────────────────────────────────

   So beware: NOT expression is false only if expression evaluates to a value
   of -1. If you define Boolean constants or variables for use in your
   programs, use -1 for true.

   You can use the values 0 and -1 to define helpful mnemonic Boolean
   constants for use in loops or decisions. This technique is used in many of
   the examples in this manual, as shown in the following program fragment,
   which sorts the elements of an array named Amount in ascending order:

   ' Define symbolic constants to use in program:
   CONST FALSE = 0, TRUE = NOT FALSE
   .
   .
   .

   DO
      Swaps = FALSE
      FOR I = 1 TO TransacNum - 1
         IF Amount(I) < Amount(I+1) THEN
            SWAP Amount(I), Amount(I+1)
            Swaps = TRUE
         END IF
      NEXT I
   LOOP WHILE Swaps        ' Keep looping while Swaps is TRUE.
   .
   .
   .


 1.3  Decision Structures

   Based on the value of an expression, decision structures cause a program
   to take one of the following two actions:

   1. Execute one of several alternative statements within the decision
      structure itself

   2. Branch to another part of the program outside the decision structure

   In BASICA, decision-making is handled solely by the single-line
   IF...THEN[[...ELSE]] statement. In its simplest form (IF...THEN) the
   expression following the IF keyword is evaluated. If the expression is
   true, the program executes the statements following the THEN keyword; if
   the expression is false, the program continues with the next line after
   the IF...THEN statement. Lines 50 and 70 from the following BASICA program
   fragment show examples of IF...THEN:

   30  INPUT A
   40  ' If A is greater than 100, print a message and branch
   45  ' back to line 30; otherwise, go on to line 60:
   50  IF A > 100 THEN PRINT "Too big": GOTO 30
   60  ' If A is equal to 100, branch to line 300;
   65  ' otherwise, go on to line 80:
   70  IF A = 100 THEN GOTO 300
   80  PRINT A/100: GOTO 30
   .
   .
   .

   By adding the ELSE clause to an IF...THEN statement, you can have your
   program take one set of actions (those following the THEN keyword) if an
   expression is true, and another set of actions (those following the ELSE
   keyword) if it is false. The next program fragment shows how ELSE works in
   an IF...THEN...ELSE statement:

   10 INPUT "What is your password"; Pass$
   15 ' If user enters "sword", branch to line 50;
   20 ' otherwise, print a message and branch back to line 10:
   30 IF Pass$="sword" THEN 50 ELSE PRINT "Try again": GOTO 10
   .
   .
   .

   While BASICA's single-line IF...THEN...ELSE is adequate for simple
   decisions, it can lead to virtually unreadable code in cases of more
   complicated ones. This is especially true if you write your programs so
   all alternative actions take place within the IF...THEN...ELSE statement
   itself or if you nest IF...THEN... ELSE statements (that is, if you put
   one IF...THEN...ELSE inside another, a perfectly legal construction). As
   an example of how difficult it is to follow even a simple test, consider
   the next fragment from a BASICA program:

   10 ' The following nested IF...THEN...ELSE statements print
   15 ' different output for each of the following four cases:
   20 '    1) A <= 50, B <= 50     3)  A > 50, B <= 50
   25 '    2) A <= 50, B > 50      4)  A > 50, B > 50
   30
   35 INPUT A, B
   40
   45 ' Note: even though line 70 extends over several physical
   50 ' lines on the screen, it is just one "logical line"
   55 ' (everything typed before the <ENTER> key was pressed).
   60 ' BASICA wraps long lines on the screen.
   65
   70  IF A <= 50 THEN IF B <= 50 THEN PRINT "A <= 50, B <= 50"
   ELSE PRINT "A <= 50, B > 50" ELSE IF B <= 50 THEN PRINT "A >
   50, B <= 50" ELSE PRINT "A > 50, B > 50"

   To avoid the kind of complicated statement shown above, BASIC now includes
   the block form of the IF...THEN...ELSE statement, so that a decision is no
   longer restricted to one logical line. The following shows the same BASICA
   program rewritten to use block IF...THEN...ELSE:

   INPUT A, B
   IF A <= 50 THEN
      IF B <= 50 THEN
         PRINT "A <= 50, B <= 50"
      ELSE
         PRINT "A <= 50, B > 50"
      END IF
   ELSE
      IF B <= 50 THEN
         PRINT "A > 50, B <= 50"
      ELSE
         PRINT "A > 50, B > 50"
      END IF
   END IF

   QuickBASIC also provides the SELECT CASE...END SELECT (referred to as
   SELECT CASE) statement for structured decisions.

   Both the block IF...THEN...ELSE statement and the SELECT CASE statement
   allow the appearance of your code to be based on program logic, rather
   than requiring many statements to be crowded onto one line. This gives you
   increased flexibility while you are programming, as well as improved
   program readability and ease of maintenance when you are done.

 1.3.1  Block IF...THEN...ELSE

   Table 1.2 shows the syntax of the block IF...THEN...ELSE statement and
   gives an example of its use.

   Table 1.2  Block IF...THEN...ELSE Syntax and Example
   Syntax                               Example
   ──────────────────────────────────────────────────────────────────────────
   IF condition1 THEN                   IF X > 0 THEN
     [[statementblock-1]]                 PRINT "X is positive"
   [[ELSEIF condition2 THEN               PosNum = PosNum + 1
     [[statementblock-2]]]]             ELSEIF X < 0 THEN
   .                                      PRINT "X is negative"
   .                                      NegNum = NegNum + 1
   .                                    ELSE
   [[ELSE                                 PRINT "X is zero"
     [[statementblock-n]]]]             END IF
   END IF
   ──────────────────────────────────────────────────────────────────────────

   The arguments condition1, condition2, and so on are expressions. They can
   be any numeric expression──in which case true becomes any nonzero value,
   and false is zero──or they can be Boolean expressions, in which case true
   is -1 and false is zero. As explained in Section 1.2, Boolean expressions
   typically compare two numeric or string expressions using one of the
   relational operators such as < or >=.

   Each IF, ELSEIF, and ELSE clause is followed by a block of statements.
   None of the statements in the block can be on the same line as the IF,
   ELSEIF, or ELSE clause; otherwise, BASIC considers it a single-line
   IF...THEN statement.

   BASIC evaluates each of the expressions in the IF and ELSEIF clauses from
   top to bottom, skipping over statement blocks until it finds the first
   true expression. When it finds a true expression, it executes the
   statements corresponding to the expression, then branches out of the block
   to the statement following the END IF clause.

   If none of the expressions in the IF or ELSEIF clauses is true, BASIC
   skips to the ELSE clause, if there is one, and executes its statements.
   Otherwise, if there is no ELSE clause, the program continues with the next
   statement after the END IF clause.

   The ELSE and ELSEIF clauses are both optional, as shown in the following
   example:

   ' If the value of X is less than 100, do the two statements
   ' before END IF; otherwise, go to the INPUT statement
   ' following END IF:

   IF X < 100 THEN
      PRINT X
      Number = Number + 1
   END IF
   INPUT "New value"; Response$
   .
   .
   .

   A single block IF...THEN...ELSE can contain multiple ELSEIF statements, as
   shown below:

   IF C$ >= "A" AND C$ <= "Z" THEN
      PRINT "Capital letter"
   ELSEIF C$ >= "a" AND C$ <= "z" THEN
      PRINT "Lowercase letter"
   ELSEIF C$ >= "0" AND C$ <= "9" THEN
      PRINT "Number"
   ELSE
      PRINT "Not alphanumeric"
   END IF

   At most, only one block of statements is executed, even if more than one
   condition is true. For example, if you enter the word ace as input to the
   next example, it prints the message Input too short but does not print the
   message Can't start with an a:

   INPUT Check$
   IF LEN(Check$) > 6 THEN
      PRINT "Input too long"
   ELSEIF LEN(Check$) < 6 THEN
      PRINT "Input too short"
   ELSEIF LEFT$(Check$, 1) = "a" THEN
      PRINT "Can't start with an a"
   END IF

   IF...THEN...ELSE statements can be nested; in other words, you can put an
   IF...THEN...ELSE statement inside another IF...THEN...ELSE statement, as
   shown here:

   IF X > 0 THEN
      IF Y > 0 THEN
         IF Z > 0 THEN
            PRINT "All are greater than zero."
         ELSE
            PRINT "Only X and Y greater than zero."
         END IF
      END IF
   ELSEIF X = 0 THEN
      IF Y = 0 THEN
         IF Z = 0 THEN
            PRINT "All equal zero."
         ELSE
            PRINT "Only X and Y equal zero."
         END IF
      END IF
   ELSE
      PRINT "X is less than zero."
   END IF

 1.3.2  SELECT CASE

   The SELECT CASE statement is a multiple-choice decision structure similar
   to the block IF...THEN...ELSE statement. Block IF...THEN...ELSE can be
   used anywhere SELECT CASE can be used.

   The major difference between the two is that SELECT CASE evaluates a
   single expression, then executes different statements or branches to
   different parts of the program based on the result. In contrast, a block
   IF...THEN...ELSE can evaluate completely different expressions.

   Examples

   The following examples illustrate the similarities and differences between
   the SELECT CASE and IF...THEN...ELSE statements. Here is an example of
   using block IF...THEN...ELSE for a multiple-choice decision:

   INPUT X
   IF X = 1 THEN
      PRINT "One"
   ELSEIF X = 2 THEN
      PRINT "Two"
   ELSEIF X = 3 THEN
      PRINT "Three"
   ELSE
      PRINT "Must be integer from 1-3."
   END IF

   The above decision is rewritten using SELECT CASE below:

   INPUT X
   SELECT CASE X
      CASE 1
         PRINT "One"
      CASE 2
         PRINT "Two"
      CASE 3
         PRINT "Three"
      CASE ELSE
         PRINT "Must be integer from 1-3."
   END SELECT

   The following decision can be made either with the SELECT CASE or the
   block IF...THEN...ELSE statement. The comparison is more efficient with
   the IF...THEN...ELSE statement because different expressions are being
   evaluated in the IF and ELSEIF clauses.

   INPUT X, Y
   IF X = 0 AND Y = 0 THEN
      PRINT "Both are zero."
   ELSEIF X = 0 THEN
      PRINT "Only X is zero."
   ELSEIF Y = 0 THEN
      PRINT "Only Y is zero."
   ELSE
      PRINT "Neither is zero."
   END IF

   1.3.2.1  Using the SELECT CASE Statement

   Table 1.3 shows the syntax of a SELECT CASE statement and an example.

   Table 1.3  SELECT CASE Syntax and Example
   Syntax                               Example
   ──────────────────────────────────────────────────────────────────────────
   SELECT CASE expression               INPUT TestValue
     CASE expressionlist1               SELECT CASE TestValue
       [[statementblock-1]]               CASE 1, 3, 5, 7, 9
     [[CASE expressionlist2                 PRINT "Odd"
       [[statementblock-2]]]]             CASE 2, 4, 6, 8
     .                                      PRINT "Even"
     .                                    CASE IS < 1
     .                                      PRINT "Too low"
     [[CASE ELSE                          CASE IS > 9
       [[statementblock-n]]]]               PRINT "Too high"
   END SELECT                             CASE ELSE
                                            PRINT "Not an integer"
                                        END SELECT

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

   The expressionlist arguments following a CASE clause can be one or more of
   the following, separated by commas:

   ■ A numeric expression or a range of numeric expressions

   ■ A string expression or a range of string expressions

   To specify a range of expressions, use the following syntax for the CASE
   statement:

   CASE expression TO expression CASE IS relational-operator expression

   The relational-operator is any of the operators shown in Table 1.1. For
   example, if you use CASE 1 TO 4, the statements associated with this case
   are executed when the expression in the SELECT CASE statement is greater
   than or equal to 1 and less than or equal to 4. If you use CASE IS < 5,
   the associated statements are executed only if expression is less than 5.

   If you are expressing a range with the TO keyword, be sure to put the
   lesser value first. For example, if you want to test for a value between
   -5 and -1, write the CASE statement as follows:

   CASE -5 TO -1

   However, the following statement is not a valid way to specify the range
   from -5 to -1, so the statements associated with this case are never
   executed:

   CASE -1 TO -5

   Similarly, a range of string constants should list the string that comes
   first alphabetically:

   CASE "aardvark" TO "bear"

   Multiple expressions or ranges of expressions can be listed for each CASE
   clause, as in the following lines:

   CASE 1 TO 4, 7 TO 9, WildCard1%, WildCard2%
   CASE IS = Test$, IS = "end of data"
   CASE IS < LowerBound, 5, 6, 12, IS > UpperBound
   CASE IS < "HAN", "MAO" TO "TAO"

   If the value of the SELECT CASE expression appears in the list following a
   CASE clause, only the statements associated with that CASE clause are
   executed. Control then jumps to the first executable statement following
   END SELECT, not the next block of statements inside the SELECT CASE
   structure, as shown by the output from the next example (where the user
   enters 1):

   INPUT x
   SELECT CASE x
      CASE 1
         PRINT "One, ";
      CASE 2
         PRINT "Two, ";
      CASE 3
         PRINT "Three, ";
   END SELECT
   PRINT "that's all"

   Output

   ? 1
   One, that's all

   If the same value or range of values appears in more than one CASE clause,
   only the statements associated with the first occurrence are executed, as
   shown by the next example's output (where the user has entered ABORIGINE):

   INPUT Test$
   SELECT CASE Test$
      CASE "A" TO "AZZZZZZZZZZZZZZZZZ"
         PRINT "An uppercase word beginning with capital A"
      CASE IS < "A"
         PRINT "Some sequence of nonalphabetic characters"
      CASE "ABORIGINE"
         ' This case is never executed since ABORIGINE
         ' falls within the range in the first CASE clause:
         PRINT "A special case"
   END SELECT

   Output

   ? ABORIGINE
   An uppercase word beginning with capital A

   If you use a CASE ELSE clause, it must be the last CASE clause listed in
   the SELECT CASE statement. The statements between a CASE ELSE clause and
   an END SELECT clause are executed only if the expression does not match
   any of the other CASE selections in the SELECT CASE statement. In fact, it
   is a good idea to have a CASE ELSE statement in your SELECT CASE block to
   handle unforeseen values for expression. However, if there is no CASE ELSE
   statement and no match is found in any CASE statement for expression, the
   program continues execution.

   Example

   The following program fragment demonstrates a common use of the SELECT
   CASE statement: it prints a menu on the screen, then branches to different
   subprograms based on the number typed by the user.

   DO                ' Start menu loop.

      CLS                  ' Clear screen.

      ' Print five menu choices on the screen:
      PRINT "MAIN MENU" : PRINT
      PRINT "1)  Add New Names"
      PRINT "2)  Delete Names"
      PRINT "3)  Change Information"
      PRINT "4)  List Names"
      PRINT
      PRINT "5)  EXIT"

      ' Print input prompt:
      PRINT : PRINT "Type your selection (1 to 5):"

      ' Wait for the user to press a key. INPUT$(1)
      ' reads one character input from the keyboard:
      Ch$ = INPUT$(1)

      ' Use SELECT CASE to process response:
      SELECT CASE Ch$

         CASE "1"
            CALL AddData
         CASE "2"
            CALL DeleteData
         CASE "3"
            CALL ChangeData
         CASE "4"
            CALL ListData
         CASE "5"
            EXIT DO         ' The only way to exit the menu loop
         CASE ELSE
            BEEP
      END SELECT

   LOOP                     ' End menu loop.

   END

   ' Subprograms AddData, DeleteData, ChangeData, and ListData:
   .
   .
   .

   1.3.2.2  SELECT CASE Versus ON...GOSUB

   You can use the more versatile SELECT CASE statement as a replacement for
   the old ON expression {GOSUB| GOTO} statement. The SELECT CASE statement
   has many advantages over the ON...GOSUB statement, as summarized below:

   ■ The expression in SELECT CASE expression can evaluate to either a string
     or numeric value. The expression given in the statement ON
     expression{GOSUB| GOTO} must evaluate to a number within the range 0 to
     255.

   ■ The SELECT CASE statement branches to a statement block immediately
     following the matching CASE clause. In contrast, ON expression GOSUB
     branches to a subroutine in another part of the program.

   ■ CASE clauses can be used to test an expression against a range of
     values. When the range is quite large, this is not easily done with ON
     expression{GOSUB| GOTO}, especially as shown in the following fragments.

   In the fragment below, the ON...GOSUB statement branches to one of the
   subroutines 50, 100, or 150, depending on the value input by the user:

   X% = -1
   WHILE X%
      INPUT "Enter choice (0 to quit): ", X%
      IF X% = 0 THEN END
      WHILE X% < 1 OR X% > 12
         PRINT "Must be value from 1 to 12"
         INPUT "Enter choice (0 to quit): ", X%
      WEND
      ON x% GOSUB 50,50,50,50,50,50,50,50,100,100,100,150
   WEND
   .
   .
   .

   Contrast the preceding example with the next one, which uses a SELECT CASE
   statement with ranges of values in each CASE clause:

   DO
      INPUT "Enter choice (0 to quit): ", X%
      SELECT CASE X%
         CASE 0
            END
         CASE 1 TO 8       ' Replaces "subroutine 50"
                           ' in preceding example
         CASE 9 TO 11      ' Replaces "subroutine 100"
                           ' in preceding example
         CASE 12           ' Replaces "subroutine 150"
                           ' in preceding example
         CASE ELSE         ' Input was out of range.
            PRINT "Must be value from 1 to 12"
         END SELECT
   LOOP


 1.4  Looping Structures

   Looping structures repeat a block of statements (the loop), either for a
   specified number of times or until a certain expression (the loop
   condition) is true or false.

   Users of BASICA are familiar with two looping structures, FOR...NEXT and
   WHILE...WEND, which are discussed in Sections 1.4.1 and 1.4.2,
   respectively. QuickBASIC has extended the available loop structures with
   the DO...LOOP statement, discussed in Section 1.4.3.

 1.4.1  FOR...NEXT Loops

   A FOR...NEXT loop repeats the statements enclosed in the loop a definite
   number of times, counting from a starting value to an ending value by
   increasing or decreasing a loop counter. As long as the loop counter has
   not reached the ending value, the loop continues to execute. Table 1.4
   shows the syntax of the FOR...NEXT statement and gives an example of its
   use.

   Table 1.4  FOR...NEXT Syntax and Example
   Syntax                               Example
   ──────────────────────────────────────────────────────────────────────────
   FOR counter = start TO end [[STEP    FOR I% = 1 to 10
   stepsize]]                             Array%(I%) = I%
     [[statementblock-1]]               NEXT
     [[EXIT FOR
     [[statementblock-2]]]]
   NEXT[[counter]]
   ──────────────────────────────────────────────────────────────────────────

   In a FOR...NEXT loop, the counter variable initially has the value of the
   expression start. After each repetition of the loop, the value of counter
   is adjusted. If you leave off the optional STEP keyword, the default value
   for this adjustment is one; that is, one is added to counter each time the
   loop executes. If you use STEP, then counter is adjusted by the amount
   stepsize. The stepsize argument can be any numeric value; if it is
   negative, the loop counts down from start to end. After the counter
   variable is increased or decreased, its value is compared with end. At
   this point, if either of the following is true, the loop is completed:

   ■ The loop is counting up (stepsize is positive) and counter is greater
     than end.

   ■ The loop is counting down (stepsize is negative) and counter is less
     than end.

   Figure 1.1 shows the logic of a FOR...NEXT loop when the value of
   stepsize is positive.


   ┌────────────────────────────────────┐
   │                                    │
   │   Figure 1.1 can be found on       │
   │   page 20 of the printed manual.   │
   │                                    │
   └────────────────────────────────────┘

   Figure 1.1  Logic of FOR...NEXT Loop with Positive STEP

   Figure 1.2 shows the logic of a FOR...NEXT loop when the value of
   stepsize is negative.


   ┌────────────────────────────────────┐
   │                                    │
   │   Figure 1.2 can be found on       │
   │   page 21 of the printed manual.   │
   │                                    │
   └────────────────────────────────────┘

   Figure 1.2  Logic of FOR...NEXT Loop with Negative STEP

   A FOR...NEXT statement always "tests at the top," so if one of the
   following conditions is true, the loop is never executed:

   ■ Step size is positive, and the initial value of start is greater than
     the value of end:

     ' Loop never executes, because I% starts out greater
     ' than 9:
     FOR I% = 10 TO 9
       .
       .
       .
     NEXT I%

   ■ Step size is negative, and the initial value of start is less than the
     value of end:

     ' Loop never executes, because I% starts out less than 9:
     FOR I% =  -10 TO -9 STEP -1
       .
       .
       .
     NEXT I%

   You don't have to use the counter argument in the NEXT clause; however, if
   you have several nested FOR...NEXT loops (one loop inside another),
   listing the counter arguments can be a helpful way to keep track of what
   loop you are in.

   Here are some general guidelines for nesting FOR...NEXT loops:

   ■ If you use a loop counter variable in a NEXT clause, the counter for a
     nested loop must appear before the counter for any enclosing loop. In
     other words, the following is a legal nesting:

     FOR I = 1 TO 10
        FOR J = -5 TO 0
        .
        .
        .
        NEXT J
     NEXT I

     However, the following is not a legal nesting:

     FOR I = 1 TO 10
        FOR J = -5 TO 0
        .
        .
        .
        NEXT I
     NEXT J

   ■ If you use a separate NEXT clause to end each loop, then the number of
     NEXT clauses must always be the same as the number of FOR clauses.

   ■ If you use a single NEXT clause to terminate several levels of
     FOR...NEXT loops, then the loop-counter variables must appear after the
     NEXT clause in "inside-out" order:

     NEXT innermost-loopcounter,... , outermost-loopcounter

     In this case, the number of loop-counter variables in the NEXT clause
     must be the same as the number of FOR clauses.

   Examples

   The three program fragments below illustrate different ways of nesting
   FOR... NEXT loops to produce the identical output that follows. The first
   example shows nested FOR...NEXT loops with loop counters and separate NEXT
   clauses for each loop:

   FOR I = 1 TO 2
      FOR J = 4 TO 5
         FOR K = 7 TO 8
            PRINT I, J, K
         NEXT K
      NEXT J
   NEXT I

   The following example also uses loop counters but only one NEXT clause for
   all three loops:

   FOR I = 1 TO 2
      FOR J = 4 TO 5
         FOR K = 7 TO 8
            PRINT I, J, K
   NEXT K, J, I

   The final example shows nested FOR...NEXT loops without loop counters:

   FOR I = 1 TO 2
      FOR J = 4 TO 5
         FOR K = 7 TO 8
            PRINT I, J, K
         NEXT
      NEXT
   NEXT

   Output

    1             4             7
    1             4             8
    1             5             7
    1             5             8
    2             4             7
    2             4             8
    2             5             7
    2             5             8

   1.4.1.1  Exiting a FOR...NEXT Loop with EXIT FOR

   Sometimes you may want to exit a FOR...NEXT loop before the counter
   variable reaches the ending value of the loop. You can do this with the
   EXIT FOR statement. A single FOR...NEXT loop can have any number of EXIT
   FOR statements, and the EXIT FOR statements can appear anywhere within the
   loop. The following fragment shows one use for an EXIT FOR statement:

   ' Print the square roots of the numbers from 1 to 30,000.
   ' If the user presses any key while this loop is executing,
   ' control exits from the loop:
   FOR I% = 1 TO 30000
      PRINT SQR(I%)
      IF INKEY$ <> "" THEN EXIT FOR
   NEXT
   .
   .
   .

   EXIT FOR exits only the smallest enclosing FOR...NEXT loop in which it
   appears. For example, if the user pressed a key while the following nested
   loops were executing, the program would simply exit the innermost loop. If
   the outermost loop were still active (that is if the value of I% <= 100),
   control would pass right back to the innermost loop:

   FOR I% = 1 TO 100
      FOR J% = 1 TO 100
         PRINT I% / J%
         IF INKEY$ <> "" THEN EXIT FOR
      NEXT J%
   NEXT I%

   1.4.1.2  Pausing Program Execution with FOR...NEXT

   Many BASICA programs use an empty FOR...NEXT loop such as the following to
   insert a pause in a program:

   .
   .
   .
   ' There are no statements in the body of this loop;
   ' all it does is count from 1 to 10,000
   ' using integers (whole numbers).
   FOR I% = 1 TO 10000: NEXT
   .
   .
   .

   For very short pauses or pauses that do not have to be some exact
   interval, using FOR...NEXT is fine. The problem with using an empty
   FOR...NEXT loop in this way is that different computers, different
   versions of BASIC, or different compile-time options can all affect how
   quickly the arithmetic in a FOR... NEXT loop is performed. So the length
   of a pause can vary widely. QuickBASIC's SLEEP statement now provides a
   better alternative. (See Chapter 8, "Statement and Function Summary," for
   the syntax of SLEEP.)

 1.4.2  WHILE...WEND Loops

   The FOR...NEXT statement is useful when you know ahead of time exactly how
   many times a loop should be executed. When you cannot predict the precise
   number of times a loop should be executed, but do know the condition that
   will end the loop, the WHILE...WEND statement is useful. Instead of
   counting to determine if it should keep executing a loop, WHILE...WEND
   repeats the loop as long as the loop condition is true.

   Table 1.5 shows the syntax of the WHILE...WEND statement and an example.

   Table 1.5  WHILE...WEND Syntax and Example
   Syntax                               Example
   ──────────────────────────────────────────────────────────────────────────
   WHILE condition                      INPUT R$
     [[statementblock]]                 WHILE R$ <> "Y" AND R$ <> "N"
   WEND                                   PRINT "Answer must be Y or N."
                                          INPUT R$
                                        WEND
   ──────────────────────────────────────────────────────────────────────────

   Example

   The following example assigns an initial value of ten to the variable X,
   then successively halves that value and keeps halving it until the value
   of X is less than .00001:

   X = 10

   WHILE X > .00001
      PRINT X
      X = X/2
   WEND

   Figure 1.3 illustrates the logic of a WHILE...WEND loop.


   ┌────────────────────────────────────┐
   │                                    │
   │   Figure 1.3 can be found on       │
   │   page 26 of the printed manual.   │
   │                                    │
   └────────────────────────────────────┘

   Figure 1.3  Logic of WHILE...WEND Loop

 1.4.3  DO...LOOP Loops

   Like the WHILE...WEND statement, the DO...LOOP statement executes a block
   of statements an indeterminate number of times; that is, exiting from the
   loop depends on the truth or falsehood of the loop condition. Unlike
   WHILE...WEND, DO...LOOP allows you to test for either a true or false
   condition. You can also put the test at either the beginning or the end of
   the loop.

   Table 1.6 shows the syntax of a loop that tests at the loop's beginning.

   Table 1.6  DO...LOOP Syntax and Example: Test at the Beginning
   Syntax                               Example
   ──────────────────────────────────────────────────────────────────────────
   DO[[{WHILE| UNTIL} condition]]       DO UNTIL INKEY$ <> ""
     [[statementblock-1]]                 ' An empty loop that
     [[EXIT DO                            ' pauses until a key
     [[statementblock-2]]]]               ' is pressed
   LOOP                                 LOOP
   ──────────────────────────────────────────────────────────────────────────

   Figures 1.4 and 1.5 illustrate the two kinds of DO...LOOP statements
   that test at the beginning of the loop.


   ┌────────────────────────────────────┐
   │                                    │
   │   Figure 1.4 can be found on       │
   │   page 27 of the printed manual.   │
   │                                    │
   └────────────────────────────────────┘

   Figure 1.4  Logic of DO WHILE...LOOP


   ┌────────────────────────────────────┐
   │                                    │
   │   Figure 1.5 can be found on       │
   │   page 28 of the printed manual.   │
   │                                    │
   └────────────────────────────────────┘

   Figure 1.5  Logic of DO UNTIL...LOOP

   Table 1.7 shows the syntax of a loop that tests for true or false at the
   end of the loop.

   Table 1.7  DO...LOOP Syntax and Example: Test at the End
   Syntax                               Example
   ──────────────────────────────────────────────────────────────────────────
   DO                                   DO
     [[statementblock-1]]                 INPUT "Change: ", Ch
     [[EXIT DO                            Total = Total + Ch
     [[statementblock-2]]]]             LOOP WHILE Ch <> 0
   LOOP[[{WHILE| UNTIL} condition]]
   ──────────────────────────────────────────────────────────────────────────

   Figures 1.6 and 1.7 illustrate the two kinds of DO...LOOP statements
   that test at the end of the loop.


   ┌────────────────────────────────────┐
   │                                    │
   │   Figure 1.6 can be found on       │
   │   page 29 of the printed manual.   │
   │                                    │
   └────────────────────────────────────┘

   Figure 1.6  Logic of DO...LOOP WHILE


   ┌────────────────────────────────────┐
   │                                    │
   │   Figure 1.7 can be found on       │
   │   page 30 of the printed manual.   │
   │                                    │
   └────────────────────────────────────┘

   Figure 1.7  Logic of DO...LOOP UNTIL

   1.4.3.1  Loop Tests: One Way to Exit DO...LOOP

   You can use a loop test at the end of a DO...LOOP statement to create a
   loop in which the statements always execute at least once. With the
   WHILE...WEND statement, you sometimes have to resort to the trick of
   presetting the loop variable to some value in order to force the first
   pass through the loop. With DO...LOOP, such tricks are no longer
   necessary. The examples below illustrate both approaches:

   ' WHILE...WEND loop tests at the top, so assigning "Y"
   ' to Response$ is necessary to force execution of the
   ' loop at least once:
   Response$ = "Y"
   WHILE UCASE$(Response$) = "Y"
      .
      .
      .
      INPUT "Do again"; Response$
   WEND

   ' The same loop using DO...LOOP to test after the
   ' body of the loop:
   DO
      .
      .
      .
      INPUT "Do again"; Response$
   LOOP WHILE UCASE$(Response$) = "Y"

   You can also rewrite a condition expressed with WHILE using UNTIL instead,
   as in the following:

   ' =======================================================
   '                  Using DO WHILE NOT...LOOP
   ' =======================================================

   ' While the end of file 1 has not been reached, read
   ' a line from the file and print it on the screen:
   DO WHILE NOT EOF(1)
      LINE INPUT #1, LineBuffer$
      PRINT LineBuffer$
   LOOP

   ' =======================================================
   '                    Using DO UNTIL...LOOP
   ' =======================================================

   ' Until the end of file 1 has been reached, read
   ' a line from the file and print it on the screen:
   DO UNTIL EOF(1)
      LINE INPUT #1, LineBuffer$
      PRINT LineBuffer$
   LOOP

   1.4.3.2  EXIT DO: An Alternative Way to Exit DO...LOOP

   Inside a DO...LOOP statement, other statements are executed that
   eventually change the loop-test condition from true to false or false to
   true, ending the loop. In the DO...LOOP examples presented so far, the
   test has occurred either at the beginning or the end of the loop. However,
   by using the EXIT DO statement to exit from the loop, you can move the
   test elsewhere inside the loop. A single DO...LOOP can contain any number
   of EXIT DO statements, and the EXIT DO statements can appear anywhere
   within the loop.

   Example

   The following example opens a file and reads it, one line at a time, until
   the end of the file is reached or until it finds the pattern input by the
   user. If it finds the pattern before getting to the end of the file, an
   EXIT DO statement exits the loop.

   INPUT "File to search: ", File$
   IF File$ = "" THEN END

   INPUT "Pattern to search for: ", Pattern$
   OPEN File$ FOR INPUT AS #1

   DO UNTIL EOF(1)    ' EOF(1) returns a true value if the
                      ' end of the file has been reached.
      LINE INPUT #1, TempLine$
      IF INSTR(TempLine$, Pattern$) > 0 THEN

         ' Print the first line containing the pattern and
         ' exit the loop:
         PRINT TempLine$
         EXIT DO
      END IF
   LOOP


 1.5  Sample Applications

   The sample applications for this chapter are a checkbook-balancing program
   and a program that ensures that every line in a text file ends with a
   carriage-return and line-feed sequence.

 1.5.1  Checkbook-Balancing Program (CHECK.BAS)

   This program prompts the user for the starting checking-account balance
   and all transactions──withdrawals or deposits──that have occurred. It then
   prints a sorted list of the transactions and the final balance in the
   account.

   Statements and Functions Used

   The program demonstrates the following statements discussed in this
   chapter:

   ■ DO...LOOP WHILE

   ■ FOR...NEXT

   ■ EXIT FOR

   ■ Block IF...THEN...ELSE

   Program Listing

   DIM Amount(1 TO 100)
   CONST FALSE = 0, TRUE = NOT FALSE

   CLS
   ' Get account's starting balance:
   INPUT "Type starting balance, then press <ENTER>: ", Balance

   ' Get transactions. Continue accepting input
   ' until the input is zero for a transaction,
   ' or until 100 transactions have been entered:
   FOR TransacNum% = 1 TO 100
      PRINT TransacNum%;
      PRINT ") Enter transaction amount (0 to end): ";
      INPUT "", Amount(TransacNum%)
      IF Amount(TransacNum%) = 0 THEN
         TransacNum% = TransacNum% - 1
         EXIT FOR
      END IF
   NEXT

   ' Sort transactions in ascending order,
   ' using a "bubble sort":
   Limit% = TransacNum%
   DO
      Swaps% = FALSE
      FOR I% = 1 TO (Limit% - 1)

         ' If two adjacent elements are out of order,
         ' switch those elements:
         IF Amount(I%) < Amount(I% + 1) THEN
            SWAP Amount(I%), Amount(I% + 1)
            Swaps% = I%
         END IF
      NEXT I%

      ' Sort on next pass only to where last switch was made:
      Limit% = Swaps%

   ' Sort until no elements are exchanged:
   LOOP WHILE Swaps%

   ' Print the sorted transaction array. If a transaction
   ' is greater than zero, print it as a "CREDIT"; if a
   ' transaction is less than zero, print it as a "DEBIT":
   FOR I% = 1 TO TransacNum%
      IF Amount(I%) > 0 THEN
         PRINT USING "CREDIT: $$#####.##"; Amount(I%)
      ELSEIF Amount(I%) < 0 THEN
         PRINT USING "DEBIT: $$#####.##"; Amount(I%)
      END IF

      ' Update balance:
      Balance = Balance + Amount(I%)
   NEXT I%

   ' Print the final balance:
   PRINT
   PRINT "--------------------------"
   PRINT USING "Final Balance: $$######.##"; Balance
   END

 1.5.2  Carriage-Return and Line-Feed Filter (CRLF.BAS)

   Some text files are saved in a format that uses only a carriage return
   (return to the beginning of the line) or a line feed (advance to the next
   line) to signify the end of a line. Many text editors expand this single
   carriage return (CR) or line feed (LF) to a carriage-return and line-feed
   (CR-LF) sequence whenever you load the file for editing. However, if you
   use a text editor that does not expand a single CR or LF to CR-LF, you may
   have to modify the file so it has the correct sequence at the end of each
   line.

   The following program is a filter that opens a file, expands a single CR
   or LF to a CR-LF combination, then writes the adjusted lines to a new
   file. The original contents of the file are saved in a file with a .BAK
   extension.

   Statements and Functions Used

   This program demonstrates the following statements discussed in this
   chapter:

   ■ DO...LOOP WHILE

   ■ DO UNTIL...LOOP

   ■ Block IF...THEN...ELSE

   ■ SELECT CASE...END SELECT

   To make this program more useful, it contains the following constructions
   not discussed in this chapter:

   ■ A FUNCTION procedure named Backup$ that creates the file with the .BAK
     extension.

     See Chapter 2, "SUB and FUNCTION Procedures," for more information on
     defining and using procedures.

   ■ An error-handling routine named ErrorHandler to deal with errors that
     could occur when the user enters a file name. For instance, if the user
     enters the name of a nonexistent file, this routine prompts for a new
     name. Without this routine, such an error would end the program.

     See Chapter 6, "Error and Event Trapping," for more information on
     trapping errors.

   Program Listing

   DEFINT A-Z             ' Default variable type is integer.

   ' The Backup$ FUNCTION makes a backup file with
   ' the same base as FileName$ plus a .BAK extension:
   DECLARE FUNCTION Backup$ (FileName$)

   ' Initialize symbolic constants and variables:
   CONST FALSE = 0, TRUE = NOT FALSE

   CarReturn$ = CHR$(13)
   LineFeed$ = CHR$(10)

   DO
      CLS

      ' Input the name of the file to change:
      INPUT "Which file do you want to convert"; OutFile$

      InFile$ = Backup$(OutFile$)  ' Get backup file's name.

      ON ERROR GOTO ErrorHandler   ' Turn on error trapping.

      NAME OutFile$ AS InFile$     ' Rename input file as
                                   ' backup file.

      ON ERROR GOTO 0              ' Turn off error trapping.

      ' Open backup file for input and old file for output:
      OPEN InFile$ FOR INPUT AS #1
      OPEN OutFile$ FOR OUTPUT AS #2

      ' The PrevCarReturn variable is a flag set to TRUE
      ' whenever the program reads a carriage-return character:
      PrevCarReturn = FALSE

   ' Read from input file until reaching end of file:
      DO UNTIL EOF(1)

         ' This is not end of file, so read a character:
         FileChar$ = INPUT$(1, #1)

         SELECT CASE FileChar$

         CASE CarReturn$        ' The character is a CR.

            ' If the previous character was also a
            ' CR, put a LF before the character:
            IF PrevCarReturn THEN
                FileChar$ = LineFeed$ + FileChar$
            END IF

            ' In any case, set the PrevCarReturn
            ' variable to TRUE:
            PrevCarReturn = TRUE

        CASE LineFeed$         ' The character is a LF.

            ' If the previous character was not a
            ' CR, put a CR before the character:
            IF NOT PrevCarReturn THEN
                FileChar$ = CarReturn$ + FileChar$
            END IF

            ' Set the PrevCarReturn variable to FALSE:
            PrevCarReturn = FALSE

         CASE ELSE              ' Neither a CR nor a LF.

            ' If the previous character was a CR,
            ' set the PrevCarReturn variable to FALSE
            ' and put a LF before the current character:
            IF PrevCarReturn THEN
                  PrevCarReturn = FALSE
                  FileChar$ = LineFeed$ + FileChar$
            END IF

         END SELECT

         ' Write the character(s) to the new file:
         PRINT #2, FileChar$;
      LOOP

      ' Write a LF if the last character in the file was a CR:
      IF PrevCarReturn THEN PRINT #2, LineFeed$;

   CLOSE                        ' Close both files.
      PRINT "Another file (Y/N)?"  ' Prompt to continue.

      ' Change the input to uppercase (capital letter):
      More$ = UCASE$(INPUT$(1))

   ' Continue the program if the user entered a "y" or a "Y":
   LOOP WHILE More$ = "Y"
   END

   ErrorHandler:           ' Error-handling routine
      CONST NOFILE = 53, FILEEXISTS = 58

      ' The ERR function returns the error code for last error:
      SELECT CASE ERR
         CASE NOFILE       ' Program couldn't find file
                           ' with input name.

            PRINT "No such file in current directory."
            INPUT "Enter new name: ", OutFile$
            InFile$ = Backup$(OutFile$)
            RESUME
         CASE FILEEXISTS   ' There is already a file named
                           ' <filename>.BAK in this directory:
                           ' remove it, then continue.
            KILL InFile$
            RESUME
         CASE ELSE         ' An unanticipated error occurred:
                           ' stop the program.
            ON ERROR GOTO 0
      END SELECT

   ' ======================== BACKUP$ =========================
   '   This procedure returns a file name that consists of the
   '   base name of the input file (everything before the ".")
   '   plus the extension ".BAK"
   ' ==========================================================

   FUNCTION Backup$ (FileName$) STATIC

      ' Look for a period:
      Extension = INSTR(FileName$, ".")

      ' If there is a period, add .BAK to the base:
      IF Extension > 0 THEN
         Backup$ = LEFT$(FileName$, Extension - 1) + ".BAK"

      ' Otherwise, add .BAK to the whole name:
      ELSE
         Backup$ = FileName$ + ".BAK"
      END IF
   END FUNCTION



 ────────────────────────────────────────────────────────────────────────────
 Chapter 2  SUB and FUNCTION Procedures

   This chapter explains how to simplify your programming by breaking
   programs into smaller logical components. These components──known as
   "procedures"──can then become building blocks that let you enhance and
   extend the BASIC language itself.

   When you are finished with this chapter, you will know how to perform the
   following tasks with procedures:

   ■ Define and call BASIC procedures

   ■ Use local and global variables in procedures

   ■ Use procedures instead of GOSUB subroutines and DEF FN functions

   ■ Pass arguments to procedures and return values from procedures

   ■ Write recursive procedures (procedures that can call themselves)

   Although you can create a BASIC program with any text editor, the
   QuickBASIC editor makes it especially easy to write programs that contain
   procedures. Also, in most cases QuickBASIC automatically generates a
   DECLARE statement when you save your program. (Using a DECLARE statement
   ensures that only the correct number and type of arguments are passed to a
   procedure and allows your program to call procedures defined in separate
   modules.)


 2.1  Procedures: Building Blocks for Programming

   As used in this chapter, the term "procedure" covers both SUB...END SUB
   and FUNCTION...END FUNCTION constructions. Procedures are useful for
   condensing repeated tasks. For example, suppose you are writing a program
   that you eventually intend to compile as a stand-alone application and you
   want the user of this application to be able to pass several arguments to
   the application from the command line. It then makes sense to turn this
   task──breaking the string returned by the COMMAND$ function into two or
   more arguments──into a separate procedure. Once you have this procedure up
   and running, you can use it in other programs. In essence, you are
   extending BASIC to fit your individual needs when you use procedures.

   These are the two major benefits of programming with procedures:

   1. Procedures allow you to break your programs into discrete logical
      units, each of which can be more easily debugged than can an entire
      program without procedures.

   2. Procedures used in one program can be used as building blocks in other
      programs, usually with little or no modification.

   You can also put procedures in your own Quick library, which is a special
   file that you can load into memory when you start QuickBASIC. Once the
   contents of a Quick library are in memory with QuickBASIC, any program
   that you write has access to the procedures in the library. This makes it
   easier for all of your programs both to share and save code. (See Appendix
   H, "Creating and Using Quick Libraries," for more information on how to
   build Quick libraries.)


 2.2  Comparing Procedures with Subroutines and Functions

   If you are familiar with earlier versions of BASIC, you might think of a
   SUB...END SUB procedure as being roughly similar to a GOSUB...RETURN
   subroutine. You will also notice some similarities between a FUNCTION...
   END FUNCTION procedure and a DEF FN...END DEF function. However,
   procedures have many advantages over these older constructions, as shown
   in Sections 2.2.1 and 2.2.2 below.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     To avoid confusion between a SUB procedure and the target of a GOSUB
     statement, SUBprocedures are referred to in this manual as
     "subprograms," while statement blocks accessed by
     GOSUB...RETURN statements are referred to as "subroutines."
   ──────────────────────────────────────────────────────────────────────────

 2.2.1  Comparing SUB with GOSUB

   Although use of the GOSUB subroutine does help break programs into
   manageable units, SUB procedures have a number of advantages over
   subroutines, as discussed below.

   2.2.1.1  Local and Global Variables

   In SUB procedures, all variables are local by default; that is, they exist
   only within the scope of the SUB procedure's definition. To illustrate,
   the variable named I in the Test subprogram below is local to Test, and
   has no connection with the variable named I in the module-level code:

   I = 1
   CALL Test
   PRINT I  ' I still equals 1.
   END

   SUB Test STATIC
         I = 50
   END SUB

   A GOSUB has a major drawback as a building block in programs: it contains
   only "global variables." With global variables, if you have a variable
   named I inside your subroutine, and another variable named I outside the
   subroutine but in the same module, they are one and the same. Any changes
   to the value of I in the subroutine affect I everywhere it appears in the
   module. As a result, if you try to patch a subroutine from one module into
   another module, you may have to rename subroutine variables to avoid
   conflict with variable names in the new module.

   2.2.1.2  Use in Multiple-Module Programs

   A SUB can be defined in one module and called from another. This
   significantly reduces the amount of code required for a program and
   increases the ease with which code can be shared among a number of
   programs.

   A GOSUB subroutine, however, must be defined and used in the same module.

   2.2.1.3  Operating on Different Sets of Variables

   A SUB procedure can be called any number of times within a program, with a
   different set of variables being passed to it each time. This is done by
   calling the SUB with an argument list. (See Section 2.5, "Passing
   Arguments to Procedures," for more information on how to do this.) In the
   next example, the subprogram Compare is called twice, with different pairs
   of variables passed to it each time:

   X = 4: Y = 5

   CALL Compare (X, Y)

   Z = 7: W = 2
   CALL Compare (Z, W)
   END

   SUB Compare (A, B)
      IF A < B THEN SWAP A, B
   END SUB

   Calling a GOSUB subroutine more than once in the same program and having
   it operate on a different set of variables each time is difficult. The
   process involves copying values to and from global variables, as shown in
   the next example:

   X = 4: Y = 5
   A = X: B = Y
   GOSUB Compare
   X = A: Y = B

   Z = 7 : W = 2
   A = Z : B = W
   GOSUB Compare
   Z = A : W = B
   END

   Compare:
      IF A < B THEN SWAP A, B
   RETURN

 2.2.2  Comparing FUNCTION with DEF FN

   While the multiline DEF FN function definition answers the need for
   functions more complex than can be squeezed on a single line, FUNCTION
   procedures give you this capability plus the additional advantages
   discussed below.

   2.2.2.1  Local and Global Variables

   By default, all variables within a FUNCTION procedure are local to it,
   although you do have the option of using global variables. (See Section
   2.6, "Sharing Variables with SHARED," for more information on procedures
   and global variables.)

   In a DEF FN function, variables used within the function's body are global
   to the current module by default (this is also true for GOSUB
   subroutines). However, you can make a variable in a DEF FN function local
   by putting it in a STATIC statement.

   2.2.2.2  Changing Variables Passed to the Procedure

   Variables are passed to FUNCTION procedures by reference or by value. When
   you pass a variable by reference, you can change the variable by changing
   its corresponding parameter in the FUNCTION. For example, after the call
   to GetRemainder in the next program, the value of X is 2, since the value
   of Mis 2 at the end of the FUNCTION:

   X = 89
   Y = 40
   PRINT GetRemainder(X, Y)
   PRINT X, Y                ' X is now 2.
   END

   FUNCTION GetRemainder (M, N)
      GetRemainder = M MOD N
      M = M \ N
   END FUNCTION

   Variables are passed to a DEF FN function only by value, so in the next
   example, FNRemainder changes M without affecting X :

   DEF FNRemainder (M, N)
      FNRemainder = M MOD N
      M = M \ N
   END DEF

   X = 89
   Y = 40
   PRINT FNRemainder(X, Y)

   PRINT X,Y   ' X is still
               ' 89.

   See Sections 2.5.5 and 2.5.6 for more information on the distinction
   between passing by reference and by value.

   2.2.2.3  Calling the Procedure within Its Definition

   A FUNCTION procedure can be "recursive"; in other words, it can call
   itself within its own definition. (See Section 2.9 for more information
   on how procedures can be recursive.) A DEF FN function cannot be
   recursive.

   2.2.2.4  Use in Multiple-Module Programs

   You can define a FUNCTION procedure in one module and use it in another
   module. You need to put a DECLARE statement in the module in which the
   FUNCTION is used; otherwise, your program thinks the FUNCTION name refers
   to a variable. (See Section 2.5.4, "Checking Arguments with the DECLARE
   Statement," for more information on using DECLARE this way.)

   A DEF FN function can only be used in the module in which it is defined.
   Unlike SUB or FUNCTION procedures, which can be called before they appear
   in the program, a DEF FN function must always be defined before it is used
   in a module.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     The name of a FUNCTION procedure can be any valid BASIC variable name,
     except one beginning with the letters FN. The name of a DEF FN function
     must always be preceded by FN.
   ──────────────────────────────────────────────────────────────────────────


 2.3  Defining Procedures

   BASIC procedure definitions have the following general syntax:

   {SUB| FUNCTION} procedurename[[(parameterlist)]] [[STATIC]]
     [[statementblock-1]]
     [[EXIT{SUB| FUNCTION}
       [[statementblock-2]]]]
   END{SUB| FUNCTION}

   The following list describes the parts of a procedure definition:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
   Part                     Description
   ──────────────────────────────────────────────────────────────────────────
   {SUB | FUNCTION}         Marks the beginning of a SUB or FUNCTION
                            procedure, respectively.

   procedurename            Any valid variable name up to 40 characters long.
                            The same name cannot be used for both a SUB and a
                            FUNCTION.
   Part                     Description
   ──────────────────────────────────────────────────────────────────────────
                           FUNCTION.

   parameterlist            A list of variables, separated by commas, that
                            shows the number and type of arguments to be
                            passed to the procedure. (Section 2.5.1 explains
                            the difference between parameters and arguments.)

   STATIC                   If you use the STATIC attribute, local variables
                            are STATIC; that is, they retain their values
                            between calls to the procedure.
                            If you omit the STATIC attribute, local variables
                            are "automatic" by default; that is, they are
                            initialized to zeros or null strings at the start
                            of each procedure call.
                            See Section 2.7, "Automatic and STATIC
                            Variables," for more information.

   END{SUB| FUNCTION}       Ends a SUB or FUNCTION definition. To run
                            correctly, every procedure must have exactly one
   Part                     Description
   ──────────────────────────────────────────────────────────────────────────
                           correctly, every procedure must have exactly one
                            END{SUB| FUNCTION} statement.
                            When your program encounters an END SUB or END
                            FUNCTION, it exits the procedure and returns to
                            the statement immediately following the one that
                            called the procedure. You can also use one or
                            more optional EXIT{SUB| FUNCTION} statements
                            within the body of a procedure definition to exit
                            from the procedure.
   ──────────────────────────────────────────────────────────────────────────


   All valid BASIC expressions and statements are allowed within a procedure
   definition except the following:

   ■ DEF FN...END DEF, FUNCTION...END FUNCTION, or SUB...END SUB

     It is not possible to nest procedure definitions or to define a DEF FN
     function inside a procedure. However, a procedure can call another
     procedure or a DEF FN function.

   ■ COMMON

   ■ DECLARE

   ■ DIM SHARED

   ■ OPTION BASE

   ■ TYPE...END TYPE

   Example

   The following example is a FUNCTION procedure named IntegerPower :

   FUNCTION IntegerPower& (X&, Y&) STATIC
      PowerVal& = 1
      FOR I& = 1 TO Y&
         PowerVal& = PowerVal& * X&
      NEXT I&
      IntegerPower& = PowerVal&
   END FUNCTION


 2.4  Calling Procedures

   Calling a FUNCTION procedure is different from calling a SUB procedure, as
   shown in the next two sections.

 2.4.1  Calling a FUNCTION Procedure

   You call a FUNCTION procedure the same way you use an intrinsic BASIC
   function such as ABS, that is, by using its name in an expression, as
   shown here:

   ' Any of the following statements
   ' would call a FUNCTION named "ToDec" :
   PRINT 10 * ToDec
   X = ToDec
   IF ToDec = 10 THEN PRINT "Out of range."

   A FUNCTION can return values by changing variables passed to it as
   arguments. (See Section 2.5.5, "Passing Arguments by Reference," for an
   explanation of how this is done.) Additionally, a FUNCTION returns a
   single value in its name, so the name of a FUNCTION must agree with the
   type it returns. For example, if a FUNCTION returns a string value, either
   its name must have the dollar sign ($) type-declaration character appended
   to it or it must be declared as having the string type in a preceding
   DEFSTR statement.

   Example

   The following program shows a FUNCTION that returns a string value. Note
   that the type-declaration suffix for strings ($) is part of the procedure
   name.

   Banner$ = GetInput$       ' Call the FUNCTION and assign the
                             ' return value to a string variable.
   PRINT Banner$             ' Print the string.
   END

   ' ======================= GETINPUT$ ========================
   '    The $ type-declaration character at the end of this
   '    FUNCTION name means that it returns a string value.
   ' ==========================================================

   FUNCTION GetInput$ STATIC

      ' Return a string of 10 characters read from the
      ' keyboard, echoing each character as it is typed:
      FOR I% = 1 TO 10
         Char$ = INPUT$(1)     ' Get the character.
         PRINT Char$;          ' Echo the character on the
                               ' screen.
         Temp$ = Temp$ + Char$ ' Add the character to the
                               ' string.
      NEXT
      PRINT
      GetInput$ = Temp$    ' Assign the string to the FUNCTION.
   END FUNCTION

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     The program example above is written for use in the QB environment only.
     It cannot be compiled using the BC command from DOS.
   ──────────────────────────────────────────────────────────────────────────

 2.4.2  Calling a SUB Procedure

   A SUB procedure differs from a FUNCTION procedure in that a SUB cannot be
   called by using its name within an expression. A call to a SUB is a
   stand-alone statement, like BASIC's CIRCLE statement. Also, a SUB does not
   return a value in its name as does a FUNCTION. However, like a FUNCTION, a
   SUB can modify the values of any variables passed to it. (Section 2.5.5,
   "Passing Arguments by Reference," explains how this is done.)

   There are two ways to call a SUB procedure:

   1. Put its name in a CALL statement:

      CALL PrintMessage

   2. Use its name as a statement by itself:

      PrintMessage

   If you omit the CALL keyword, don't put parentheses around arguments
   passed to the SUB:

   ' Call the ProcessInput subprogram with CALL and pass the
   ' three arguments First$, Second$, and NumArgs% to it:
   CALL ProcessInput  (First$, Second$, NumArgs%)



   ' Call the ProcessInput subprogram without CALL and pass
   ' it the same arguments (note no parentheses around the
   ' argument list):
   ProcessInput  First$, Second$, NumArgs%


   See Section 2.5 for more information on passing arguments to procedures.

   If your program calls SUB procedures without using CALL, and if you are
   not using QuickBASIC to write the program, you must put the name of the
   SUB in a DECLARE statement before it is called:

   DECLARE SUB CheckForKey
   .
   .
   .
   CheckForKey

   You need to be concerned about this only if you are developing programs
   outside QuickBASIC, since QuickBASIC automatically inserts DECLARE
   statements wherever they are needed when it saves a program.


 2.5  Passing Arguments to Procedures

   Sections 2.5.1-2.5.4 explain how to tell the difference between
   parameters and arguments, how to pass arguments to procedures, and how to
   check arguments to make sure they are of the correct type and quantity.

 2.5.1  Parameters and Arguments

   The first step in learning about passing arguments to procedures is
   understanding the difference between the terms "parameter" and "argument":

   Parameter                Argument
   ──────────────────────────────────────────────────────────────────────────
   A variable name that     A constant, variable, or expression passed to a
   appears in a SUB,        SUB or FUNCTION when the SUB or FUNCTION is
   FUNCTION, or DECLARE     called
   statement
   ──────────────────────────────────────────────────────────────────────────

   In a procedure definition, parameters are placeholders for arguments. As
   shown in Figure 2.1, when a procedure is called, arguments are plugged
   into the variables in the parameter list, with the first parameter
   receiving the first argument, the second parameter receiving the second
   argument, and so on.


   ┌───────────────────────────────────────────────────────────────────┐
   │                                                                   │
   │                                            Arguments              │
   │                                       ┌────────┴─────────┐        │
   │ Procedure call───────── CALL TestSub   (A%,  B!,  "text")         │
   │                         ∙               │     │      │            │
   │                         ∙               │     │      │            │
   │                         ∙                                      │
   │ Procedure definition ── SUB TestSub    (P1%,  P2!,   P3$)  STATIC │
   │                                       └────────┬─────────┘        │
   │                                            Parameters             │
   │                                                                   │
   └───────────────────────────────────────────────────────────────────┘

   Figure 2.1  Parameters and Arguments

   Figure 2.1 also demonstrates another important rule: although the names
   of variables in an argument list and a parameter list do not have to be
   the same, the number of parameters and the number of arguments do.
   Furthermore, the type (string, integer numeric, single-precision numeric,
   and so on) should be the same for corresponding arguments and parameters.
   (See Section 2.5.4, "Checking Arguments with the DECLARE Statement," for
   more information on how to ensure that arguments and parameters agree in
   number and type.)

   A parameter list consists of any of the following, all separated by
   commas:

   ■ Valid variable names, except for fixed-length strings

     For example, x$ and x AS STRING are both legal in a parameter list,
     since they refer to variable-length strings. However, x AS STRING * 10
     refers to a fixed-length string 10 characters long and cannot appear in
     a parameter list. (Fixed-length strings are perfectly all right as
     arguments passed to procedures. See Chapter 4, "String Processing," for
     more information on fixed-length and variable-length strings.)

   ■ Array names followed by left and right parentheses

   An argument list consists of any of the following, all separated by
   commas:

   ■ Constants

   ■ Expressions

   ■ Valid variable names

   ■ Array names followed by left and right parentheses

   Examples

   The following example shows the first line of a subprogram definition with
   a parameter list:

   SUB TestSub (A%, Array(), RecVar AS RecType, Cs$)

   The first parameter, A%, is an integer; the second parameter, Array(), is
   a single-precision array, since untyped numeric variables are single
   precision by default; the third parameter, RecVar, is a record of type
   RecType; and the fourth parameter, Cs$, is a string.

   The CALL TestSub line in the next example calls the TestSub subprogram and
   passes it four arguments of the appropriate type:

   TYPE RecType
      Rank AS STRING * 12
      SerialNum AS LONG
   END TYPE

   DIM RecVar AS RecType

   CALL TestSub (X%, A(), RecVar, "Daphne")

 2.5.2  Passing Constants and Expressions

   Constants──whether string or numeric──can appear in the list of arguments
   passed to a procedure. Naturally, a string constant must be passed to a
   string parameter and a numeric constant to a numeric parameter, as shown
   in the next example:

   CONST SCREENWIDTH = 80
   CALL PrintBanner (SCREENWIDTH, "Monthly Status Report")
   .
   .
   .
   SUB PrintBanner (SW%, Title$)
      .
      .
      .
   END SUB

   If a numeric constant in an argument list does not have the same type as
   the corresponding parameter in the SUB or FUNCTION statement, then the
   constant is coerced to the type of the parameter, as you can see by the
   output from the next example:

   CALL test(4.6, 4.1)
   END

   SUB test (x%, y%)
      PRINT x%, y%
   END SUB

   Output

    5             4

   Expressions resulting from operations on variables and constants can also
   be passed to a procedure. As is the case with constants, numeric
   expressions that disagree in type with their parameters are coerced into
   agreement, as shown here:

   Checker A! + 25!, NOT BooleanVal%

   ' In the next call, putting parentheses around the
   ' long-integer variable Bval& makes it an expression.
   ' The (Bval&) expression is coerced to a short integer
   ' in the Checker SUB:
   Checker A! / 3.1, (Bval&)
   .
   .
   .
   END

   SUB Checker (Param1!, Param2%)
      .
      .
      .
   END SUB

 2.5.3  Passing Variables

   This section discusses how to pass simple variables, complete arrays,
   elements of arrays, records, and elements of records to procedures.

   2.5.3.1  Passing Simple Variables

   In both argument and parameter lists, you can declare the type for a
   simple variable in one of the following three ways:

   1. Append one of the following type-declaration suffixes to the variable
      name: %, &, !, #, or $.

   2. Declare the variable in a declare variablename AS type clause, where
      the placeholder declare can be either DIM, COMMON, REDIM, SHARED, or
      STATIC, and type can be either INTEGER, LONG, SINGLE, DOUBLE, STRING,
      or STRING * n. For example:

      DIM A AS LONG

   3. Use a DEFtype statement to set the default type.

   No matter which method you choose, corresponding variables must have the
   same type in both the argument and parameter lists, as shown in the
   following example.

   Example

   In this example, two arguments are passed to the FUNCTION procedure. The
   first is an integer giving the length of the string returned by the
   FUNCTION, while the second is a character that is repeated to make the
   string.

   FUNCTION CharString$(A AS INTEGER, B$) STATIC
      CharString$ = STRING$(A%, B$)
   END FUNCTION

   DIM X AS INTEGER
   INPUT "Enter a number (1 to 80): ", X
   INPUT "Enter a character: ", Y$

   ' Print a string consisting of the Y$ character, repeated
   ' X number of times:
   PRINT CharString$(X, Y$)
   END

   Output

   Enter a number (1 to 80): 21
   Enter a character: #
   #####################

   2.5.3.2  Passing an Entire Array

   To pass all the elements of an array to a procedure, put the array's name,
   followed by left and right parentheses, in both the argument and parameter
   lists.

   Example

   This example shows how to pass all the elements of an array to a
   procedure:

   DIM Values(1 TO 5) AS INTEGER

   ' Note empty parentheses after array name when calling
   ' procedure and passing array:
   CALL ChangeArray (1, 5, Values())
   CALL PrintArray (1, 5, Values())
   END

   ' Note empty parentheses after P parameter:

   SUB ChangeArray (Min%, Max%, P() AS INTEGER) STATIC
      FOR I% = Min% TO Max%
         P(I%) = I% ^ 3
      NEXT I%
   END SUB

   SUB PrintArray (Min%, Max%, P() AS INTEGER) STATIC
      FOR I% = Min% TO Max%
         PRINT P(I%)
      NEXT I%
      PRINT
   END SUB

   2.5.3.3  Passing Individual Array Elements

   If a procedure does not require an entire array, you can pass individual
   elements of the array instead. To pass an element of an array, use the
   array name followed by the appropriate subscripts inside parentheses.

   Example

   The SqrVal Array(4,2) statement in the following example passes the
   element in row 4, column 2 of the array to the SqrVal subprogram (note how
   the subprogram actually changes the value of this array element):

   DIM Array(1 TO 5,1 TO 3)

   Array(4,2) = -36
   PRINT Array(4,2)
   SqrVal Array(4,2)
   PRINT Array(4,2)     ' The call to SqrVal has changed
                        ' the value of Array(4,2).
   END
   SUB SqrVal(A) STATIC
      A = SQR(ABS(A))
   END SUB

   Output

   -36
    6

   2.5.3.4  Using Array-Bound Functions

   The LBOUND and UBOUND functions are a useful way to determine the size of
   an array passed to a procedure. The LBOUND function finds the smallest
   index value of an array subscript, while the UBOUND function finds the
   largest one. These functions save you the trouble of having to pass the
   upper and lower bounds of each array dimension to a procedure.

   Example

   The subprogram in the following example uses the LBOUND function to
   initialize the variables Row and Col to the lowest subscript values in
   each dimension of A. It also uses the UBOUND function to limit the number
   of times the FOR loop executes to the number of elements in the array.

   SUB PrintOut(A(2)) STATIC
      FOR Row = LBOUND(A,1) TO UBOUND(A,1)
         FOR Col = LBOUND(A,2) TO UBOUND(A,2)
            PRINT A(Row,Col)
         NEXT Col
      NEXT Row
   END SUB

   2.5.3.5  Passing an Entire Record

   To pass a complete record (a variable declared as having a user-defined
   type) to a procedure, complete the following steps:

   1. Define the type (StockItem in this example):

      TYPE StockItem
         PartNumber  AS STRING *  6
         Description AS STRING * 20
         UnitPrice   AS SINGLE
         Quantity    AS INTEGER
      END TYPE

   2. Declare a variable (StockRecord) with that type:

      DIM StockRecord AS StockItem

   3. Call a procedure (FindRecord) and pass it the variable you have
      declared:

      CALL FindRecord(StockRecord)

   4. In the procedure definition, give the parameter the same type as the
      variable:

      SUB FindRecord (RecordVar AS StockItem) STATIC
         .
         .
         .
      END SUB

   2.5.3.6  Passing Individual Elements of a Record

   To pass an individual element in a record to a procedure, put the name of
   the element (recordname.elementname) in the argument list. Be sure, as
   always, that the corresponding parameter in the procedure definition
   agrees with the type of that element.

   Example

   The following example shows how to pass the two elements in the record
   variable StockItem to the PrintTag SUB procedure. Note how each parameter
   in the SUB procedure agrees with the type of the individual record
   elements.

   TYPE StockType
      PartNumber AS STRING * 6
      Descrip AS STRING * 20
      UnitPrice AS SINGLE
      Quantity AS INTEGER
   END TYPE

   DIM StockItem AS StockType

   CALL PrintTag (StockItem.Descrip, StockItem.UnitPrice)
   .
   .
   .
   END

   SUB PrintTag (Desc$, Price AS SINGLE)
      .
      .
      .
   END SUB

 2.5.4  Checking Arguments with the DECLARE Statement

   If you are using QuickBASIC to write your program, you will notice that
   QuickBASIC automatically inserts a DECLARE statement for each procedure
   whenever you save the program. Each DECLARE statement consists of the word
   DECLARE, followed by the words SUB or FUNCTION, the name of the procedure,
   and a set of parentheses. If the procedure has no parameters, then the
   parentheses are empty. If the procedure has parameters, then the
   parentheses enclose a parameterlist that specifies the number and type of
   the arguments to be passed to the procedure. This parameterlist has the
   same format as the list in the definition line of the SUB or FUNCTION.

   The purpose of the parameterlist in a DECLARE statement is to turn on
   "type checking" of arguments passed to the procedure. That is, every time
   the procedure is called with variable arguments, those variables are
   checked to be sure they agree with the number and type of the parameters
   in the DECLARE statement.

   QuickBASIC puts all procedure definitions at the end of a module when it
   saves a program. Therefore, if there were no DECLARE statements, when you
   tried to compile this program with the BC command you would run into a
   problem known as "forward reference" (calling a procedure before it is
   defined). By generating a prototype of the procedure definition, DECLARE
   statements allow your program to call procedures that are defined later in
   a module, or in another module altogether.

   Examples

   The next example shows an empty parameter list in the DECLARE statement,
   since no arguments are passed to GetInput$:

   DECLARE FUNCTION GetInput$ ()
   X$ = GetInput$

   FUNCTION GetInput$ STATIC
      GetInput$ = INPUT$(10)
   END FUNCTION

   The next example shows a parameter list in the DECLARE statement, since an
   integer argument is passed to this version of GetInput$ :

   DECLARE FUNCTION GetInput$ (X%)
   X$ = GetInput$ (5)

   FUNCTION GetInput$ (X%) STATIC
      GetInput$ = INPUT$(X%)
   END FUNCTION

   2.5.4.1  When QuickBASIC Does Not Generate a DECLARE Statement

   In certain instances, QuickBASIC does not generate DECLARE statements in
   the module that calls a procedure.

   QuickBASIC cannot generate a DECLARE statement in one module for a
   FUNCTION procedure defined in another module if the module is not loaded.
   In such a case, you must type the DECLARE statement yourself at the
   beginning of the module where the FUNCTION is called; otherwise,
   QuickBASIC considers the call to the FUNCTION to be a variable name.

   QuickBASIC does not generate a DECLARE statement for a SUB procedure in
   another module, whether that module is loaded or not. The DECLARE
   statement is not needed unless you want to call the SUB procedure without
   using the keyword CALL, however.

   QuickBASIC also cannot generate a DECLARE statement for any procedure in a
   Quick library. You must add one to the program yourself.

   2.5.4.2  Developing Programs outside the QuickBASIC Environment

   If you are writing your programs with your own text editor and then
   compiling them outside the QuickBASIC environment with the BC and LINK
   commands, be sure to put DECLARE statements in the following three
   locations:

   1. At the beginning of any module that calls a FUNCTION procedure before
      it is defined:

      DECLARE FUNCTION Hypot (X!, Y!)

      INPUT X, Y
      PRINT Hypot(X, Y)
      END

      FUNCTION Hypot (A, B) STATIC
         Hypot = SQR(A ^ 2 + B ^ 2)
      END FUNCTION

   2. At the beginning of any module that calls a SUB procedure before it is
      defined and does not use CALL when calling the SUB:

      DECLARE SUB PrintString (X, Y)
      INPUT X, Y

      PrintString X, Y     ' Note: no parentheses around
                           ' arguments
      END

      SUB PrintString (A,B) STATIC

         ' Convert the numbers to strings, remove any leading
         ' blanks from the second number, and print:
         PRINT STR$(A) + LTRIM$(STR$(B))
      END SUB

      When you call a SUB procedure with CALL, you don't have to declare the
      SUB first:

      A$ = "466"
      B$ = "123"
      CALL PrintString(A$, B$)
      END

      SUB PrintString (X$, Y$) STATIC
         PRINT VAL(X$) + VAL(Y$)
      END SUB

   3. At the beginning of any module that calls a SUB or FUNCTION procedure
      defined in another module (an "external procedure")

   If your procedure has no parameters, remember to put empty parentheses
   after the name of the procedure in the DECLARE statement, as in the next
   example:

   DECLARE FUNCTION GetHour$ ()
   PRINT GetHour$
   END

   FUNCTION GetHour$ STATIC
      GetHour$ = LEFT$(TIME$,2)
   END FUNCTION

   Remember, a DECLARE statement can appear only at the module level, not the
   procedure level. A DECLARE statement affects the entire module in which it
   appears.

   2.5.4.3  Using Include Files for Declarations

   If you have created a separate procedure-definition module that defines
   one or more SUB or FUNCTION procedures, it is a good idea to make an
   include file to go along with this module. This include file should
   contain the following:

   ■ DECLARE statements for all the module's procedures.

   ■ TYPE...END TYPE record definitions for any record parameters in this
     module's SUB or FUNCTION procedures.

   ■ COMMON statements listing variables shared between this module and other
     modules in the program. (See Section 2.6.3, "Sharing Variables with
     Other Modules," for more information on using COMMON for this purpose.)

   Every time you use the definition module in one of your programs, insert a
   $INCLUDE metacommand at the beginning of any module that invokes
   procedures in the definition module. When your program is compiled, the
   actual contents of the include file are substituted for the $INCLUDE
   metacommand.

   A simple rule of thumb is to make an include file for every module and
   then use the module and the include file together as outlined above. The
   following list itemizes some of the benefits of this technique:

   ■ A module containing procedure definitions remains truly modular──that
     is, you don't have to copy all the DECLARE statements for its procedures
     every time you call them from another module; instead, you can just
     substitute one $INCLUDE metacommand.

   ■ In QuickBASIC, using an include file for procedure declarations
     suppresses automatic generation of DECLARE statements when you save a
     program.

   ■ Using an include file for declarations avoids problems with getting one
     module to recognize a FUNCTION in another module. (See Section 2.5.4.1,
     "When QuickBASIC Does Not Generate a DECLARE Statement," for more
     information.)

   You can take advantage of QuickBASIC's facility for generating DECLARE
   statements when creating your include file. The following steps show you
   how to do this:

   1. Create your module.

   2. Within that module, call any SUB or FUNCTION procedures you have
      defined.

   3. Save the module to get automatic DECLARE statements for all the
      procedures.

   4. Reedit the module, removing the procedure calls and moving the DECLARE
      statements to a separate include file.

   See Appendix F, "Metacommands," for more information on the syntax and
   usage of the $INCLUDE metacommand.

   Example

   The following fragments illustrate how to use a definition module and an
   include file together:

   ' =========================================================
   '                        MODDEF.BAS
   ' This module contains definitions for the PROMPTER and
   ' MAX! procedures.
   ' =========================================================

   FUNCTION Max! (X!, Y!) STATIC
      IF X! > Y! THEN Max! = X! ELSE Max! = Y!
   END FUNCTION

   SUB Prompter (Row%, Column%, RecVar AS RecType) STATIC
      LOCATE Row%, Column%
      INPUT "Description: ", RecVar.Description
      INPUT "Quantity:    ", RecVar.Quantity
   END SUB

   ' =========================================================
   '                        MODDEF.BI
   '  This is an include file that contains DECLARE statements
   '  for the PROMPTER and MAX! procedures (as well as a TYPE
   '  statement defining the RecType user type). Use this file
   '  whenever you use the MODDEF.BAS module.
   ' =========================================================

   TYPE RecType
      Description AS STRING * 15
      Quantity AS INTEGER
   END TYPE

   DECLARE FUNCTION Max! (X!, Y!)
   DECLARE SUB Prompter (Row%, Column%, RecVar AS RecType)

   ' ============================================================
   '                         SAMPLE.BAS
   '   This module is linked with the MODDEF.BAS module, and
   '   calls the PROMPTER and MAX! procedures in MODDEF.BAS.
   ' ============================================================

   ' The next line makes the contents of the MODDEF.BI include
   ' file part of this module as well:
   ' $INCLUDE: 'MODDEF.BI'
   .
   .
   .
   INPUT A, B
   PRINT Max!(A, B)        ' Call the Max! FUNCTION in MODDEF.BAS
   .
   .
   .
   Prompter 5, 5, RecVar   ' Call the Prompter SUB in MODDEF.BAS
   .
   .
   .

   ──────────────────────────────────────────────────────────────────────────
   IMPORTANT
     While it is good programming practice to put procedure declarations in
     an include file, do not put the procedures themselves (SUB...END SUB or
     FUNCTION...END FUNCTION blocks) in an include file. Procedure
     definitions are not allowed inside include files in QuickBASIC Version
     4.5. If you have used include files to define SUB procedures in programs
     written with QuickBASIC Versions 2.0 or 3.0, either put these
     definitions in a separate module or incorporate them into the module
     where they are called.
   ──────────────────────────────────────────────────────────────────────────

   2.5.4.4  Declaring Procedures in Quick Libraries

   A convenient programming practice is to put all the declarations for
   procedures in a Quick library into one include file. With the $INCLUDE
   metacommand you can then incorporate this include file into programs using
   the library. This saves you the trouble of copying all the relevant
   DECLARE statements every time you use the library.

 2.5.5  Passing Arguments by Reference

   By default, variables──whether simple scalar variables, arrays and array
   elements, or records──are passed "by reference" to FUNCTION and SUB
   procedures. Here is what is meant by passing variables by reference:

   ■ Each program variable has an address, or a location in memory where its
     value is stored.

   ■ Calling a procedure and passing variables to it by reference calls the
     procedure and passes it the address of each variable. Thus, the address
     of the variable and the address of its corresponding parameter in the
     procedure are one and the same.

   ■ Therefore, if the procedure modifies the value of the parameter, it also
     modifies the value of the variable that is passed.

   If you do not want a procedure to change the value of a variable, pass the
   procedure the value contained in the variable, not the address. This way,
   changes are made only to a copy of the variable, not the variable itself.
   See the next section for a discussion of this alternative way of passing
   variables.

   Example

   In the following program, changes made to the parameter A$ in the Replace
   procedure also change the argument Test$:

   Test$ = "a string with all lowercase letters."
   PRINT "Before subprogram call: "; Test$
   CALL Replace (Test$, "a")
   PRINT "After subprogram call: "; Test$
   END

   SUB Replace (A$, B$) STATIC
      Start = 1
      DO

         ' Look for B$ in A$, starting at the character
         ' with position "Start" in A$:
         Found = INSTR(Start, A$, B$)
         ' Make every occurrence of B$ in A$
         ' an uppercase letter:
         IF Found > 0 THEN
            MID$(A$,Found) = UCASE$(B$)
            Start = Start + 1
         END IF
      LOOP WHILE Found > 0
   END SUB

   Output

   Before subprogram call: a string with all lowercase letters.
   After subprogram call: A string with All lowercAse letters.

 2.5.6  Passing Arguments by Value

   Passing an argument "by value" means the value of the argument is passed,
   rather than its address. In BASIC procedures, passing a variable by value
   is simulated by copying the variable into a temporary location, then
   passing the address of this temporary location. Since the procedure does
   not have access to the address of the original variable, it cannot change
   the original variable; it makes all changes to the copy instead.

   You can pass expressions as arguments to procedures, as in the following:

   ' A + B is an expression; the values of A and B
   ' are not affected by this procedure call:
   CALL Mult(A + B, B)

   Expressions are always passed by value (see Section 2.5.2, "Passing
   Constants and Expressions," for more information).

   Example

   One way to pass a variable by value is to enclose it in parentheses, thus
   making it an expression. As you can see from the output that follows,
   changes to the SUB procedure's local variable Y are passed back to the
   module-level code as changes to the variable B. However, changes to X in
   the procedure do not affect the value of A, since A is passed by value.

   A = 1
   B = 1
   PRINT "Before subprogram call, A ="; A; ", B ="; B

   ' A is passed by value, and B is passed by reference:
   CALL Mult((A), B)
   PRINT "After subprogram call, A ="; A; ", B ="; B
   END

   SUB Mult (X, Y) STATIC
      X = 2 * X
      Y = 3 * Y
      PRINT "In subprogram, X ="; X; ", Y ="; Y
   END SUB

   Output

   Before subprogram call, A = 1 , B = 1
   In subprogram, X = 2 , Y = 3
   After subprogram call, A = 1 , B = 3


 2.6  Sharing Variables with SHARED

   In addition to passing variables through argument and parameter lists,
   procedures can also share variables with other procedures and with code at
   the module level (that is, code within a module but outside of any
   procedure) in one of the two ways listed below:

   1. Variables listed in a SHARED statement within a procedure are shared
      only between that procedure and the module-level code. Use this method
      when different procedures in the same module need different
      combinations of module-level variables.

   2. Variables listed in a module-level COMMON SHARED, DIM SHARED, or REDIM
      SHARED statement are shared between the module-level code and all
      procedures within that module. This method is most useful when all
      procedures in a module use a common set of variables.

   You can also use the COMMON or COMMON SHARED statement to share variables
   among two or more modules. Sections 2.6.1-2.6.3 discuss these three ways
   to share variables.

 2.6.1  Sharing Variables with Specific Procedures in a Module

   If different procedures within a module need to share different variables
   with the module-level code, use the SHARED statement within each
   procedure.

   Arrays in SHARED statements consist of the array name followed by a set of
   empty parentheses ( ):

   SUB JustAnotherSub STATIC
      SHARED ArrayName ()
      .
      .
      .

   If you give a variable its type in an AS type clause, then the variable
   must also be typed with the AS type clause in a SHARED statement:

   DIM Buffer AS STRING * 10
   .
   .
   .
   END

   SUB ReadRecords STATIC
      SHARED Buffer AS STRING * 10
      .
      .
      .
   END SUB

   Example

   In the next example, the SHARED statements in the GetRecords and
   InventoryTotal procedures show the format of a shared variable list:

   ' =========================================================
   '                   MODULE-LEVEL CODE
   ' =========================================================
   TYPE RecType
      Price AS SINGLE
      Desc AS STRING * 35
   END TYPE

   DIM RecVar(1 TO 100) AS RecType   ' Array of records

   INPUT "File name: ", FileSpec$
   CALL GetRecords
   PRINT InventoryTotal
   END

   ' =========================================================
   '                   PROCEDURE-LEVEL CODE
   ' =========================================================
   SUB GetRecords STATIC

   ' Both FileSpec$ and the RecVar array of records
   ' are shared with the module-level code above:
      SHARED FileSpec$, RecVar() AS RecType
      OPEN FileSpec$ FOR RANDOM AS #1
      .
      .
      .
   END SUB

   FUNCTION InventoryTotal STATIC

   ' Only the RecVar array is shared with the module-level
   ' code:
      SHARED RecVar() AS RecType
      .
      .
      .
   END FUNCTION

 2.6.2  Sharing Variables with All Procedures in a Module

   If variables are declared at the module level with the SHARED attribute in
   a COMMON, DIM, or REDIM statement (for example, by using a statement of
   the form COMMON SHARED variablelist), then all procedures within that
   module have access to those variables; in other words, the SHARED
   attribute makes variables global throughout a module.

   The SHARED attribute is convenient when you need to share large numbers of
   variables among all procedures in a module.

   Examples

   These statements declare variables shared among all procedures in one
   module:

   COMMON SHARED A, B, C
   DIM SHARED Array(1 TO 10, 1 TO 10) AS UserType
   REDIM SHARED Alpha(N%)

   In the following example, the module-level code shares the string
   arrayStrArray and the integer variables Min and Max with the two SUB
   procedures FillArray and PrintArray :

   ' =========================================================
   '                    MODULE-LEVEL CODE
   ' =========================================================
   DECLARE SUB FillArray ()
   DECLARE SUB PrintArray ()

   ' The following DIM statements share the Min and Max
   ' integer variables and the StrArray string array
   ' with any SUB or FUNCTION in this module:
   DIM SHARED StrArray (33 TO 126) AS STRING * 5
   DIM SHARED Min AS INTEGER, Max AS INTEGER

   Min = LBOUND(StrArray)
   Max = UBOUND(StrArray)

   FillArray               ' Note the absence of argument lists.
   PrintArray
   END
   ' =========================================================
   '                    PROCEDURE-LEVEL CODE
   ' =========================================================
   SUB FillArray STATIC

      ' Load each element of the array from 33 to 126
      ' with a 5-character string, each character of which
      ' has the ASCII code I%:
      FOR I% = Min TO Max
         StrArray(I%) = STRING$(5, I%)
      NEXT

   END SUB

   SUB PrintArray STATIC
      FOR I% = Min TO Max
         PRINT StrArray(I%)
      NEXT
   END SUB

   Partial output

   !!!!!
   """""
   #####
   $$$$$
   %%%%%
   &&&&&
   ""'
   {{{{{
   .
   .
   .

   If you are using your own text editor to write your programs and directly
   compiling those programs outside the QuickBASIC development environment,
   note that variable declarations with the SHARED attribute must precede the
   procedure definition. Otherwise, the value of any variable declared with
   SHARED is not available to the procedure, as shown by the output from the
   next example. (If you are using QuickBASIC to create your programs, this
   sequence is not required, since QuickBASIC automatically saves programs in
   the correct order.)

   DEFINT A-Z

   FUNCTION Adder (X, Y) STATIC
      Adder = X + Y + Z
   END FUNCTION

   DIM SHARED Z
   Z = 2
   PRINT Adder (1, 3)
   END

   Output

    4

   The next example shows how you should save the module shown above, with
   the definition of Adder following the DIM SHARED Z statement:

   DEFINT A-Z

   DECLARE FUNCTION Adder (X, Y)

   ' The variable Z is now shared with Adder:
   DIM SHARED Z
   Z = 2
   PRINT Adder (1, 3)
   END

   FUNCTION Adder (X, Y) STATIC
      Adder = X + Y + Z
   END FUNCTION

   Output

    6

 2.6.3  Sharing Variables with Other Modules

   If you want to share variables across modules in your program, list the
   variables in COMMON or COMMON SHARED statements at the module level in
   each module.

   Examples

   The following example shows how to share variables between modules by
   using a COMMON statement in the module that calls the SUB procedures, as
   well as a COMMON SHARED statement in the module that defines the
   procedures. With COMMON SHARED, all procedures in the second module have
   access to the common variables:

   ' =========================================================
   '                      MAIN MODULE
   ' =========================================================

   COMMON A, B
   A = 2.5
   B = 1.2
   CALL Square
   CALL Cube
   END
   ' =========================================================
   '           Module with Cube and Square Procedures
   ' =========================================================

   ' NOTE: The names of the variables (X, Y) do not have to be
   ' the same as in the other module (A, B). Only the types
   ' have to be the same.

   COMMON SHARED X, Y  ' This statement is at the module level.
                       ' Both X and Y are shared with the CUBE
                       ' and SQUARE procedures below.
   SUB Cube STATIC
      PRINT "A cubed   ="; X ^ 3
      PRINT "B cubed   ="; Y ^ 3
   END SUB

   SUB Square STATIC
      PRINT "A squared ="; X ^ 2
      PRINT "B squared ="; Y ^ 2
   END SUB

   The following example uses named COMMON blocks at the module levels and
   SHARED statements within procedures to share different sets of variables
   with each procedure:

   ' =========================================================
   '                        MAIN MODULE
   ' Prints the volume and density of a filled cylinder given
   ' the input values
   ' =========================================================

   COMMON /VolumeValues/ Height, Radius, Volume
   COMMON /DensityValues/ Weight, Density

   INPUT "Height of cylinder in centimeters: ", Height
   INPUT "Radius of cylinder in centimeters: ", Radius
   INPUT "Weight of filled cylinder in grams: ", Weight

   CALL VolumeCalc
   CALL DensityCalc

   PRINT "Volume is"; Volume; "cubic centimeters."
   PRINT "Density is"; Density; "grams/cubic centimeter."
   END

   ' =========================================================
   '     Module with DensityCalc and VolumeCalc Procedures
   ' =========================================================

   COMMON /VolumeValues/ H, R, V
   COMMON /DensityValues/ W, D

   SUB VolumeCalc STATIC

      ' Share the Height, Radius, and Volume variables
      ' with this procedure:
      SHARED H, R, V
      CONST PI = 3.141592653589#
      V = PI * H * (R ^ 2)
   END SUB

   SUB DensityCalc STATIC

      ' Share the Weight, Volume, and Density variables
      ' with this procedure:
      SHARED W, V, D
      D = W / V
   END SUB

   Output

   Height of cylinder in centimeters: 100
   Radius of cylinder in centimeters: 10
   Weight of filled cylinder in grams: 10000
   Volume is 31415.93 cubic centimeters.
   Density is .3183099 grams/cubic centimeter.

 2.6.4  The Problem of Variable Aliasing

   "Variable aliasing" is sometimes a problem in long programs containing
   many variables and procedures. Variable aliasing is the situation where
   two or more names refer to the same location in memory. It occurs:

   ■ When the same variable appears more than once in the list of arguments
     passed to a procedure.

   ■ When a variable passed in an argument list is also accessed by the
     procedure by means of the SHARED statement or the SHARED attribute.

   To avoid aliasing problems, double-check variables shared with a procedure
   to make sure they don't also appear in a procedure call's argument list.
   Also, don't pass the same variable twice, as in the next statement:

   ' X is passed twice; this will lead to aliasing problems
   ' in the Test procedure:
   CALL Test(X, X, Y)

   Example

   The following example illustrates how variable aliasing can occur. Here
   the variable A is shared between the module-level code and the SUB
   procedure with the DIM SHARED statement. However, A is also passed by
   reference to the SUB as an argument. Therefore, in the subprogram, A and X
   both refer to the same location in memory. Thus, when the subprogram
   modifies X, it is also modifying A, and vice versa.

   DIM SHARED A
   A = 4
   CALL PrintHalf(A)
   END

   SUB PrintHalf (X) STATIC
      PRINT "Half of"; X; "plus half of"; A; "equals";
      X = X / 2            ' X and A now both equal 2.
      A = A / 2            ' X and A now both equal 1.
      PRINT A + X
   END SUB

   Output

   Half of 4 plus half of 4 equals 2


 2.7  Automatic and STATIC Variables

   When the STATIC attribute appears on a procedure-definition line, it means
   that local variables within the procedure are STATIC; that is, their
   values are preserved between calls to the procedure.

   Leaving off the STATIC attribute makes local variables within the
   procedure "automatic" by default; that is, you get a fresh set of local
   variables each time the procedure is called.

   You can override the effect of leaving off the STATIC attribute by using
   the STATIC statement within the procedure, thus making some variables
   automatic and others STATIC (see Section 2.8 for more information).

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     The SHARED statement also overrides the default for variables in a
     procedure (local STATIC or local automatic), since any variable
     appearing in a SHARED statement is known at the module level and thus is
     not local to the procedure.
   ──────────────────────────────────────────────────────────────────────────


 2.8  Preserving Values of Local Variables with the STATIC Statement

   Sometimes you may want to make some local variables in a procedure STATIC
   while keeping the rest automatic. List those variables in a STATIC
   statement within the procedure.

   Also, putting a variable name in a STATIC statement is a way of making
   absolutely sure that the variable is local, since a STATIC statement
   overrides the effect of a module-level SHARED statement.

   A STATIC statement can appear only within a procedure. An array name in a
   STATIC statement must be followed by a set of empty parentheses ( ). Also,
   you must dimension any array that appears in a STATIC statement before
   using the array, as shown in the next example:

   SUB SubProg2
      STATIC Array() AS INTEGER
      DIM Array(-5 TO 5, 1 TO 25) AS INTEGER
      .
      .
      .
   END SUB

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     If you give a variable its type in an AS type clause, then the AS type
     clause must appear along with the variable's name in both the STATIC and
     DIM statements.
   ──────────────────────────────────────────────────────────────────────────

   Example

   The following example shows how a STATIC statement preserves the value of
   the string variable Y$ throughout successive calls to TestSub:

   DECLARE SUB TestSub ()
   FOR I% = 1 TO 5
      TestSub              ' Call TestSub five times.
   NEXT I%
   END

   SUB TestSub             ' Note: no STATIC attribute

     ' Both X$ and Y$ are local variables in TestSub (that is,
     ' their values are not shared with the module-level code).
     ' However since X$ is an automatic variable, it is
     ' reinitialized to a null string every time TestSub is
     ' called. In contrast, Y$ is STATIC, so it retains the
     ' value it had from the last call:
      STATIC Y$
      X$ = X$ + "*"
      Y$ = Y$ + "*"
      PRINT X$, Y$
   END SUB

   Output

   *             *
   *             **
   *             ***
   *             ****
   *             *****


 2.9  Recursive Procedures

   Procedures in BASIC can be recursive. A recursive procedure is one that
   can call itself or call other procedures that in turn call the first
   procedure.

 2.9.1  The Factorial Function

   A good way to illustrate recursive procedures is to consider the factorial
   function from mathematics. One way to define n! ("n factorial") is with
   the following formula:

   n! = n * (n-1) * (n-2) * ... * 2 * 1

   For example, 5 factorial is evaluated as follows:

   5! = 5 * 4 * 3 * 2 * 1 = 120

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Do not confuse the mathematical factorial symbol (!) used in this
     discussion with the single-precision type-declaration suffix used by
     BASIC.
   ──────────────────────────────────────────────────────────────────────────

   Factorials lend themselves to a recursive definition as well:

   n! = n * (n-1)!

   This leads to the following progression:

   5! = 5 * 4!
   4! = 4 * 3!
   3! = 3 * 2!
   2! = 2 * 1!
   1! = 1 * 0!

   Recursion must always have a terminating condition. With factorials this
   terminating condition occurs when 0! is evaluated──by definition, 0! is
   equal to 1.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Although a recursive procedure can have STATIC variables by default (as
     in the next example), it is often preferable to let automatic variables
     be the default instead. In this way, recursive calls will not overwrite
     variable values from a preceding call.
   ──────────────────────────────────────────────────────────────────────────

   Example

   The following example uses a recursive FUNCTION procedure to calculate
   factorials:

   DECLARE FUNCTION Factorial# (N%)
   Format$ = "###_! = ###################"
   DO
      INPUT "Enter number from 0 - 20 (or -1 to end): ", Num%
      IF Num% >= 0 AND Num% <= 20 THEN
         PRINT USING Format$; Num%; Factorial#(Num%)
      END IF
   LOOP WHILE Num% >= 0
   END

   FUNCTION Factorial# (N%) STATIC

      IF N% > 0 THEN  ' Call Factorial# again
                       ' if N is greater than zero.
         Factorial# = N% * Factorial#(N% - 1)

      ELSE            ' Reached the end of recursive calls
                      ' (N% = 0), so "climb back up the ladder."
         Factorial# = 1
      END IF
   END FUNCTION

 2.9.2  Adjusting the Size of the Stack

   Recursion can eat up a lot of memory, since each set of automatic
   variables in a SUB or FUNCTION procedure is saved on the stack. (Saving
   variables this way allows a procedure to continue with the correct
   variable values after control returns from a recursive call.)

   If you have a recursive procedure with many automatic variables, or a
   deeply nested recursive procedure, you may need to adjust the size of the
   stack with a CLEAR , , stacksize statement, where stacksize is the number
   of bytes from the stack you want to reserve. Otherwise, while your program
   is running you may get the error message Out of stack space.

   The following steps outline one way to estimate the amount of memory a
   recursive procedure needs:

   1. Insert a single quotation mark to temporarily turn the recursive call
      into a comment line so that the procedure will be invoked only once
      when the program runs.

   2. Call the FRE(-2) function (which returns the total unused stack space)
      just before you call the recursive procedure. Also call the FRE(-2)
      function right at the end of the recursive procedure. Use PRINT
      statements to display the returned values.

   3. Run the program. The difference in values is the amount of stack space
      (in bytes) used by one call to the procedure.

   4. Estimate the maximum number of times the procedure is likely to be
      invoked, then multiply this value by the stack space consumed by one
      call to the procedure. The result is totalbytes.

   5. Reserve the amount of stack space calculated in step 4:

      CLEAR , , totalbytes


 2.10  Transferring Control to Another Program with CHAIN

   Unlike procedure calls, which occur within the same program, the CHAIN
   statement simply starts a new program. When a program chains to another
   program, the following sequence occurs:

   1. The first program stops running.

   2. The second program is loaded into memory.

   3. The second program starts running.

   The advantage of using CHAIN is that it enables you to split a program
   with large memory requirements into several smaller programs.

   The COMMON statement allows you to pass variables from one program to
   another program in a chain. A common programming practice is to put these
   COMMON statements in an include file, and then use the $INCLUDE
   metacommand at the beginning of each program in the chain.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Don't use a COMMON /blockname /variablelist statement (a "named COMMON
     block") to pass variables to a chained program, since variables listed
     in named COMMON blocks are not preserved when chaining. Use a blank
     COMMON block (COMMON variablelist) instead.
   ──────────────────────────────────────────────────────────────────────────

   Example

   This example, which shows a chain connecting three separate programs, uses
   an include file to declare variables passed in common among the programs:

   ' ============ CONTENTS OF INCLUDE FILE COMMONS.BI ========
   DIM Values(10)
   COMMON Values(), NumValues

   ' ======================= MAIN.BAS ========================

   ' Read in the contents of the COMMONS.BI file:
   ' $INCLUDE: 'COMMONS.BI'

      ' Input the data:
      INPUT "Enter number of data values (<=10): ", NumValues
      FOR I = 1 TO NumValues
         Prompt$ = "Value ("+LTRIM$(STR$(I))+")? "
         PRINT Prompt$;
         INPUT "", Values(I)
      NEXT I

      ' Have the user specify the calculation to do:
      INPUT "Calculation (1=st. dev., 2=mean)? ", Choice

      ' Now, chain to the correct program:
      SELECT CASE Choice

         CASE 1:             ' Standard Deviation
            CHAIN "STDEV"

         CASE 2:             ' Mean
            CHAIN "MEAN"
      END SELECT
   END

   ' ======================= STDEV.BAS =======================
   ' Calculates the standard deviation of a set of data
   ' =========================================================

   ' $INCLUDE: 'COMMONS.BI'

      Sum   = 0   ' Normal sum
      SumSq = 0   ' Sum of values squared

      FOR I = 1 TO NumValues
         Sum   = Sum   + Values(I)
         SumSq = SumSq + Values(I) ^ 2
      NEXT I

      Stdev = SQR(SumSq / NumValues - (Sum / NumValues) ^ 2)
      PRINT "The Standard Deviation of the samples is: " Stdev
   END

   ' ======================== MEAN.BAS =======================
   ' Calculates the mean (average) of a set of data
   ' =========================================================

   ' $INCLUDE: 'COMMONS.BI'

      Sum = 0

      FOR I = 1 TO NumValues
         Sum = Sum + Values(I)
      NEXT

      Mean = Sum / NumValues
      PRINT "The mean of the samples is: " Mean
   END


 2.11  Sample Application: Recursive Directory Search (WHEREIS.BAS)

   The following program uses a recursive SUB procedure, ScanDir, to scan a
   disk for the file name input by the user. Each time this program finds the
   given file, it prints the complete directory path to the file.

   Statements and Functions Used

   This program demonstrates the following statements and keywords discussed
   in this chapter:

   ■ DECLARE

   ■ FUNCTION...END FUNCTION

   ■ STATIC

   ■ SUB...END SUB

 Program Listing

 DEFINT A-Z

 ' Declare symbolic constants used in program:
 CONST EOFTYPE = 0, FILETYPE = 1, DIRTYPE = 2, ROOT = "TWH"

 DECLARE SUB ScanDir (PathSpec$, Level, FileSpec$, Row)

 DECLARE FUNCTION MakeFileName$ (Num)
 DECLARE FUNCTION GetEntry$ (FileNum, EntryType)

 CLS
 INPUT "File to look for"; FileSpec$
 PRINT
 PRINT "Enter the directory where the search should start"
 PRINT "(optional drive + directories). Press <ENTER> to "
 PRINT "begin search in root directory of current drive."
 PRINT
 INPUT "Starting directory"; PathSpec$
 CLS

 RightCh$ = RIGHT$(PathSpec$, 1)

 IF PathSpec$ = "" OR RightCh$ = ":" OR RightCh$ <> "\" THEN
    PathSpec$ = PathSpec$ + "\"
 END IF

 FileSpec$ = UCASE$(FileSpec$)
 PathSpec$ = UCASE$(PathSpec$)
 Level = 1
 Row = 3

 ' Make the top level call (level 1) to begin the search:
 ScanDir PathSpec$, Level, FileSpec$, Row

 KILL ROOT + ".*"        ' Delete all temporary files created
                         ' by the program.

 LOCATE Row + 1, 1: PRINT "Search complete."
 END

 ' ======================= GETENTRY ========================
 '    This procedure processes entry lines in a DIR listing
 '    saved to a file.

 '    This procedure returns the following values:

 '       GetEntry$       A valid file or directory name
 '       EntryType       If equal to 1, then GetEntry$
 '                       is a file.
 '                       If equal to 2, then GetEntry$
 '                       is a directory.
 ' =========================================================

 FUNCTION GetEntry$ (FileNum, EntryType) STATIC

    ' Loop until a valid entry or end-of-file (EOF) is read:
    DO UNTIL EOF(FileNum)
       LINE INPUT #FileNum, EntryLine$
       IF EntryLine$ <> "" THEN

          ' Get first character from the line for test:
          TestCh$ = LEFT$(EntryLine$, 1)
          IF TestCh$ <> " " AND TestCh$ <> "." THEN EXIT DO
       END IF
    LOOP

    ' Entry or EOF found, decide which:
    IF EOF(FileNum) THEN         ' EOF, so return EOFTYPE
       EntryType = EOFTYPE       ' in EntryType.
       GetEntry$ = ""

    ELSE                         ' Not EOF, so it must be a
                                 ' file or a directory.

       ' Build and return the entry name:
       EntryName$ = RTRIM$(LEFT$(EntryLine$, 8))

       ' Test for extension and add to name if there is one:
       EntryExt$ = RTRIM$(MID$(EntryLine$, 10, 3))
       IF EntryExt$ <> "" THEN
          GetEntry$ = EntryName$ + "." + EntryExt$
       ELSE
          GetEntry$ = EntryName$
       END IF

       ' Determine the entry type, and return that value
       ' to the point where GetEntry$ was called:
       IF MID$(EntryLine$, 15, 3) = "DIR" THEN
          EntryType = DIRTYPE            ' Directory
       ELSE
          EntryType = FILETYPE           ' File
       END IF

    END IF

 END FUNCTION

 ' ===================== MAKEFILENAME$ =====================
 '    This procedure makes a file name from a root string
 '    ("TWH," defined as a symbolic constant at the module
 '    level) and a number passed to it as an argument (Num).
 ' =========================================================

 FUNCTION MakeFileName$ (Num) STATIC

    MakeFileName$ = ROOT + "." + LTRIM$(STR$(Num))

 END FUNCTION

 ' ======================= SCANDIR =========================
 '   This procedure recursively scans a directory for the
 '   file name entered by the user.

 '   NOTE: The SUB header doesn't use the STATIC keyword
 '         since this procedure needs a new set of variables
 '         each time it is invoked.
 ' =========================================================

 SUB ScanDir (PathSpec$, Level, FileSpec$, Row)

    LOCATE 1, 1: PRINT "Now searching"; SPACE$(50);
    LOCATE 1, 15: PRINT PathSpec$;

    ' Make a file specification for the temporary file:
    TempSpec$ = MakeFileName$(Level)

    ' Get a directory listing of the current directory,
    ' and save it in the temporary file:
    SHELL "DIR " + PathSpec$ + " > " + TempSpec$

    ' Get the next available file number:
    FileNum = FREEFILE

    ' Open the DIR listing file and scan it:
    OPEN TempSpec$ FOR INPUT AS #FileNu

 ' Process the file, one line at a time:
    DO

       ' Input an entry from the DIR listing file:
       DirEntry$ = GetEntry$(FileNum, EntryType)

       ' If entry is a file:
       IF EntryType = FILETYPE THEN

          ' If the FileSpec$ string matches,
          ' print entry and exit this loop:
          IF DirEntry$ = FileSpec$ THEN
            LOCATE Row, 1: PRINT PathSpec$; DirEntry$;
            Row = Row + 1
            EntryType = EOFTYPE
          END IF

       ' If the entry is a directory, then make a recursive
       ' call to ScanDir with the new directory:
       ELSEIF EntryType = DIRTYPE THEN
          NewPath$ = PathSpec$ + DirEntry$ + "\"
          ScanDir NewPath$, Level + 1, FileSpec$, Row
          LOCATE 1, 1: PRINT "Now searching"; SPACE$(50);
          LOCATE 1, 15: PRINT PathSpec$;
       END IF

    LOOP UNTIL EntryType = EOFTYPE

    ' Scan on this DIR listing file is finished, so close it:
    CLOSE FileNum
 END SUB



 ────────────────────────────────────────────────────────────────────────────
 Chapter 3  File and Device I/O

   This chapter shows you how to use BASIC input and output (I/O) functions
   and statements. These statements permit your programs to access data
   stored in files and to communicate with devices attached to your system.

   The chapter includes material on a variety of programming tasks related to
   retrieving, storing, and formatting information. The relationship between
   data files and physical devices such as screens and keyboards is also
   covered.

   When you are finished with this chapter, you will know how to perform the
   following programming tasks:

   ■ Print text on the screen

   ■ Get input from the keyboard for use in a program

   ■ Create data files on disk

   ■ Store records in data files

   ■ Read records from data files

   ■ Read or modify data in files that are not in American Standard Code for
     Information Interchange (ASCII) format

   ■ Communicate with other computers through the serial port


 3.1  Printing Text on the Screen

   This section explains how to accomplish the following tasks:

   ■ Display text on the screen with PRINT

   ■ Display formatted text on the screen with PRINT USING

   ■ Skip spaces in a row of printed text with SPC

   ■ Skip to a given column in a row of printed text with TAB

   ■ Change the number of rows or columns appearing on the screen with WIDTH

   ■ Open a text viewport with VIEW PRINT

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Output that appears on the screen is sometimes referred to as "standard
     output." You can redirect standard output by using the DOS command-line
     symbols > or >>, thus sending output that would have gone to the screen
     to a different output device (such as a printer) or to a disk file. (See
     your DOS documentation for more information on redirecting output.)
   ──────────────────────────────────────────────────────────────────────────

 3.1.1  Screen Rows and Columns

   To understand how text is printed on the screen, it helps to think of the
   screen as a grid of "rows" and "columns." The height of one row slightly
   exceeds the height of a line of printed output, while the width of one
   column is just wider than the width of one character. A standard screen
   configuration in text mode (nongraphics) is 80 columns wide by 25 rows
   high. Figure 3.1 shows how each character printed on the screen occupies a
   unique cell in the grid, a cell that can be identified by pairing a row
   argument with a column argument.

   The bottom row of the screen is not usually used for output, unless you
   use a LOCATE statement to display text there. (See Section 3.3,
   "Controlling the Text Cursor," for more information on LOCATE.)

 3.1.2  Displaying Text and Numbers with PRINT


 ┌───────────────────────────────────────────────────────────────────┐
 │                                                                   │
 │                                                                   │
 │        ──────────────── Columns ──────────────                  │
 │     ┌────────────────────────                                     │
 │     │     1   2   3   4   5   6   7   8   9                       │
 │    │   ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬─                    │
 │  │  │ 1 │   │   │   │   │   │   │   │   │   │                     │
 │  │  │   ├───┼───┼───┼───┼───┼───┼───┼───┼───┼─                    │
 │  │  │ 2 │   │   │   │ H │ E │ L │ L │ O │   │                     │
 │Rows │   ├───┼───┼───┼──\┼───┼───┼───┼───┼───┼─                    │
 │  │  │ 3 │   │   │   │   │\──┼───┼───┼───┼───┼── This output starts│
 │  │  │   ├───┼───┼───┼───┼───┼───┼───┼───┼───┼─  in row 2, column 4│
 │  │    4 │   │   │   │   │   │   │   │   │   │                     │
 │  │      ├───┼───┼───┼───┼───┼───┼───┼───┼───┼─                    │
 │        │   │   │   │   │   │   │   │   │   │                     │
 │                                                                   │
 └───────────────────────────────────────────────────────────────────┘

 Figure 3.1  Text Output on Screen

   By far the most commonly used statement for output to the screen is the
   PRINT statement. With PRINT, you can display numeric or string values, or
   a mixture of the two. In addition, PRINT with no arguments prints a blank
   line.

   The following are some general comments about PRINT:

   ■ PRINT always prints numbers with a trailing blank space. If the number
     is positive, the number is also preceded by a space; if the number is
     negative, the number is preceded by a minus sign.

   ■ The PRINT statement can be used to print lists of expressions.
     Expressions in the list can be separated from other expressions by
     commas, semicolons, one or more blank spaces, or one or more tab
     characters. A comma causes PRINT to skip to the beginning of the next
     "print zone," or block of 14 columns, on the screen. A semicolon (or any
     combination of spaces and/or tabs) between two expressions prints the
     expressions on the screen next to each other, with no spaces in between
     (except for the built-in spaces for numbers).

   ■ Ordinarily, PRINT ends each line of output with a new-line sequence (a
     carriage-return and line-feed). However, a comma or semicolon at the end
     of the list of expressions suppresses this; the next printed output from
     the program appears on the same line unless it is too long to fit on
     that line.

   ■ PRINT wraps an output line that exceeds the width of the screen onto the
     next line. For example, if you try to print a line that is 100
     characters long on an 80-column screen, the first 80 characters of the
     line show up on one row, followed by the next 20 characters on the next
     row. If the 100-character line didn't start at the left edge of the
     screen (for example, if it followed a PRINT statement ending in a comma
     or semicolon), then the line would print until it reached the 80th
     column of one row and continue in the first column of the next row.

   Example

   The output from the following program shows some of the different ways you
   can use PRINT:

   A = 2
   B = -1
   C = 3
   X$ = "over"
   Y$ = "there"

   PRINT A, B, C
   PRINT B, A, C
   PRINT A; B; C
   PRINT X$; Y$
   PRINT X$, Y$;
   PRINT A, B
   PRINT
   FOR I = 1 TO 8
      PRINT X$,
   NEXT

   Output

    2            -1             3
   -1             2             3
    2 -1  3
   overthere
   over          there 2       -1

   over          over          over          over          over
   over          over          over

 3.1.3  Displaying Formatted Output with PRINT USING

   The PRINT USING statement gives greater control than PRINT over the
   appearance of printed data, especially numeric data. Through the use of
   special characters embedded in a format string, PRINT USING allows you to
   specify information such as how many digits from a number (or how many
   characters from a string) are displayed, whether or not a plus (+) sign or
   a dollar sign ($) appears in front of a number, and so forth.

   Example

   The example that follows gives you a sample of what can be done with PRINT
   USING. You can list more than one expression after the PRINT USING format
   string. As is the case with PRINT, the expressions in the list can be
   separated from one another by commas, semicolons, spaces, or tab
   characters.

   X = 441.2318

   PRINT USING "The number with 3 decimal places ###.###";X
   PRINT USING "The number with a dollar sign $$##.##";X
   PRINT USING "The number in exponential format #.###^^^^";X
   PRINT USING "Numbers with plus signs +###  "; X; 99.9

   Output

   The number with 3 decimal places 441.232
   The number with a dollar sign $441.23
   The number in exponential format 0.441E+03
   Numbers with plus signs +441  Numbers with plus signs +100

   Consult the QB Advisor for more on PRINT USING.

 3.1.4  Skipping Spaces and Advancing to a Specific Column

   By using the SPC(n) statement in a PRINT statement, you can skip n spaces
   in a row of printed output, as shown by the output from the next example:

   PRINT "         1         2         3"
   PRINT "123456789012345678901234567890"
   PRINT "First Name"; SPC(10); "Last Name"

   Output

   1         2         3
   123456789012345678901234567890
   First Name          Last Name

   By using the TAB(n) statement in a PRINT statement, you can skip to the
   nth column (counting from the left side of the screen) in a row of printed
   output. The following example uses TAB to produce the same output as that
   shown above:

   PRINT "         1         2         3"
   PRINT "123456789012345678901234567890"
   PRINT "First Name"; TAB(21); "Last Name"

   Neither SPC nor TAB can be used by itself to position printed output on
   the screen; they can only appear in PRINT statements.

 3.1.5  Changing the Number of Columns or Rows

   You can control the maximum number of characters that appear in a single
   row of output by using the WIDTH columns statement. The WIDTH columns
   statement actually changes the size of characters that are printed on the
   screen, so that more or fewer characters can fit on a row. For example,
   WIDTH 40 makes characters wider, so the maximum row length is 40
   characters. WIDTH 80 makes characters narrower, so the maximum row length
   is 80 characters. The numbers 40 and 80 are the only valid values for the
   columns argument.

   On machines equipped with an Enhanced Graphics Adapter (EGA) or Video
   Graphics Adapter (VGA), the WIDTH statement can also control the number of
   rows that appear on the screen as follows:

   WIDTH[[columns]] [[,rows]]

   The value for rows may be 25, 30, 43, 50, or 60, depending on the type of
   display adapter you use and the screen mode set in a preceding SCREEN
   statement.

 3.1.6  Creating a Text Viewport

   So far, the entire screen has been used for text output. However, with the
   VIEW PRINT statement, you can restrict printed output to a "text
   viewport," a horizontal slice of the screen. The syntax of the VIEW PRINT
   statement is:

   VIEW PRINT[[topline TO bottomline]]

   The values for topline and bottomline specify the locations where the
   viewport will begin and end.

   A text viewport also gives you control over on-screen scrolling. Without a
   viewport, once printed output reaches the bottom of the screen, text or
   graphics output that was at the top of the screen scrolls off and is lost.
   However, after a VIEW PRINT statement, scrolling takes place only between
   the top and bottom lines of the viewport. This means you can label the
   displayed output at the top and/or bottom of the screen without having to
   worry that the labeling will scroll it off if too many lines of data
   appear. You can also use the CLS 2 statement to clear just the text
   viewport, leaving the contents of the rest of the screen intact. See
   Section 5.5, "Defining a Graphics Viewport," to learn how to create a
   viewport for graphics output on the screen.

   Example

   You can see the effects of a VIEW PRINT statement by examining the output
   from the next example:

   CLS
   LOCATE 3, 1
   PRINT "This is above the text viewport; it doesn't scroll."

   LOCATE 4, 1
   PRINT STRING$(60, "_")       ' Print horizontal lines above
   LOCATE 11, 1
   PRINT STRING$(60, "_")       ' and below the text viewport.

   PRINT "This is below the text viewport."

   VIEW PRINT 5 TO 10             ' Text viewport extends from
                                  ' lines 5 to 10.

   FOR I = 1 TO 20                ' Print numbers and text in
      PRINT I; "a line of text"   ' the viewport.
   NEXT

   DO: LOOP WHILE INKEY$ = ""     ' Wait for a key press.
   CLS 2                          ' Clear just the viewport.
   END

   Output (Before User Presses Key)

   ┌───────────────────────────────────────────────────────────────────┐
   │                                                                   │
   │                                                                   │
   │  This is above the text viewport: it doesn't scroll.              │
   │  ───────────────────────────────────────────────────────────────  │
   │  16 a line of text                                                │
   │  17 a line of text                                                │
   │  18 a line of text                                                │
   │  19 a line of text                                                │
   │  20 a line of text                                                │
   │                                                                   │
   │                                                                   │
   │  ───────────────────────────────────────────────────────────────  │
   │  This is below the text viewport.                                 │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   └───────────────────────────────────────────────────────────────────┘

   Output (After User Presses Key)

   ┌───────────────────────────────────────────────────────────────────┐
   │                                                                   │
   │                                                                   │
   │   This is above the text viewport: it doesn't scroll.             │
   │   ───────────────────────────────────────────────────────────     │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   │   ───────────────────────────────────────────────────────────     │
   │   This is below the text viewport.                                │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   └───────────────────────────────────────────────────────────────────┘


 3.2  Getting Input from the Keyboard

   This section shows you how to use the following statements and functions
   to enable your BASIC programs to accept input entered from the keyboard:

   ■ INPUT

   ■ LINE INPUT

   ■ INPUT$

   ■ INKEY$

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Input typed at the keyboard is often referred to as "standard input."
     You can use the DOS symbol < to direct standard input to your program
     from a file or other input device instead of from the keyboard. (See
     your DOS documentation for more information on redirecting input.)
   ──────────────────────────────────────────────────────────────────────────

 3.2.1  The INPUT Statement

   The INPUT statement takes information typed by the user and stores it in a
   list of variables, as shown in the following example:

   INPUT A%, B, C$
   INPUT D$
   PRINT A%, B, C$, D$

   Output

   ? 6.6,45,a string
   ? "two, three"
    7             45           a string      two, three

   Here are some general comments about INPUT:

   ■ An INPUT statement by itself prompts the user with a question mark (?)
     followed by a blinking cursor.

   ■ The INPUT statement is followed by one or more variable names. If there
     are more than one variable, they are separated by commas.

   ■ The number of constants entered by the user after the INPUT prompt must
     be the same as the number of variables in the INPUT statement itself.

   ■ The values the user enters must agree in type with the variables in the
     list following INPUT. In other words, enter a number if the variable is
     designated as having the type integer, long integer, single precision,
     or double precision. Enter a string if the variable is designated as
     having the type string.

   ■ Since constants in an input list must be separated by commas, an input
     string constant containing one or more commas should be enclosed in
     double quotes. The double quotes ensure that the string is treated as a
     unit and not broken into two or more parts.

   If the user breaks any of the last three rules, BASIC prints the error
   message Redo from start. This message reappears until the input agrees in
   number and type with the variable list.

   If you want your input prompt to be more informative than a simple
   question mark, you can make a prompt appear, as in the following example:

   INPUT "What is the correct time (hour, min)"; Hr$, Min$

   This prints the following prompt:

   What is the correct time (hour, min)?

   Note the semicolon between the prompt and the input variables. This
   semicolon causes a question mark to appear as part of the prompt.
   Sometimes you may want to eliminate the question mark altogether; in this
   case, put a comma between the prompt and the variable list:

   INPUT "Enter the time (hour, min): ", Hr$, Min$

   This prints the following prompt:

   Enter the time (hour, min):

 3.2.2  The LINE INPUT Statement

   If you want your program to accept lines of text with embedded commas,
   leading blanks, or trailing blanks, yet you do not want to have to remind
   the user to enclose the input in double quotes, use the LINE INPUT
   statement. The LINE INPUT statement, as its name implies, accepts a line
   of input (terminated by pressing the ENTER key) from the keyboard and
   stores it in a single string variable. Unlike INPUT, the LINE INPUT
   statement does not print a question mark by default to prompt for input;
   it does, however, allow you to display a prompt string.

   The following example shows the difference between INPUT and LINE INPUT:

   ' Assign the input to three separate variables:
   INPUT "Enter three values separated by commas: ", A$, B$, C$

   ' Assign the input to one variable (commas not treated
   ' as delimiters between input):
   LINE INPUT "Enter the same three values: ", D$

   PRINT "A$ = "; A$
   PRINT "B$ = "; B$
   PRINT "C$ = "; C$
   PRINT "D$ = "; D$

   Output

   Enter 3 values separated by commas: by land, air, and sea
   Enter the same three values: by land, air, and sea
   A$ = by land
   B$ = air
   C$ = and sea
   D$ = by land, air, and sea

   With both INPUT and LINE INPUT, input is terminated when the user presses
   the ENTER key, which also advances the cursor to the next line. As the
   next example shows, a semicolon between the INPUT keyword and the prompt
   string keeps the cursor on the same line:

   INPUT "First value: ", A
   INPUT; "Second value: ", B
   INPUT "    Third value: ", C

   The following shows some sample input to the preceding program and the
   positions of the prompts:

   First value: 5
   Second value: 4     Third value: 3

 3.2.3  The INPUT$ Function

   Both INPUT and LINE INPUT wait for the user to press the ENTER key before
   they store what is typed; that is, they read a line of input, then assign
   it to program variables. In contrast, the INPUT$(number) function doesn't
   wait for the enter key to be pressed; it just reads a specified number of
   characters. For example, the following line in a program reads three
   characters typed by the user, then stores the three-character string in
   the variable Test$:

   Test$ = INPUT$(3)

   Unlike the INPUT statement, the INPUT$ function does not prompt the user
   for data, nor does it echo input characters on the screen. Also, since
   INPUT$ is a function, it cannot stand by itself as a complete statement.
   INPUT$ must appear in an expression, as in the following:

   INPUT x              ' INPUT is a statement.

   PRINT INPUT$(1)      ' INPUT$ is a function, so it must
   Y$ = INPUT$(1)       ' appear in an expression.

   The INPUT$ function reads input from the keyboard as an unformatted stream
   of characters. Unlike INPUT or LINE INPUT, INPUT$ accepts any key pressed,
   including control keys like ESC or BACKSPACE. For example, pressing the
   ENTER key five times assigns five carriage-return characters to the Test$
   variable in the next line:

   Test$ = INPUT$(5)

 3.2.4  The INKEY$ Function

   The INKEY$ function completes the list of BASIC's keyboard-input functions
   and statements. When BASIC encounters an expression containing the INKEY$
   function, it checks to see if the user has pressed a key since one of the
   following:

   ■ The last time it found an expression with INKEY$

   ■ The beginning of the program, if this is the first time INKEY$ appears

   If no key has been pressed since the last time the program checked, INKEY$
   returns a null string (""). If a key has been pressed, INKEY$ returns the
   character corresponding to that key.

   Example

   The most important difference between INKEY$ and the other statements and
   functions discussed in this section is that INKEY$ lets your program
   continue doing other things while it checks for input. In contrast, LINE
   INPUT, INPUT$, and INPUT suspend program execution until there is input,
   as show in this example:

   PRINT "Press any key to start. Press any key to end."

   ' Don't do anything else until the user presses a key:
   Begin$ = INPUT$(1)

   I = 1

   ' Print the numbers from one to one million.
   ' Check for a key press while the loop is executing:
   DO
      PRINT I
      I = I + 1

   ' Continue looping until the value of the variable I is
   ' greater than one million or until a key is pressed:
   LOOP UNTIL I > 1000000 OR INKEY$ <> ""


 3.3  Controlling the Text Cursor

   When you display printed text on the screen, the text cursor marks the
   place on the screen where output from the program──or input typed by the
   user──will appear next. In the next example, after the INPUT statement
   displays its 12-letter prompt, First name:, the cursor waits for input in
   row 1 at column 13:

   ' Clear the screen; start printing in row one, column one:
   CLS
   INPUT "First name: ", FirstName$

   In the next example, the semicolon at the end of the second PRINT
   statement leaves the cursor in row 2 at column 27:

   CLS
   PRINT

   ' Twenty-six characters are in the next line:
   PRINT "Press any key to continue.";
   PRINT INPUT$(1)

   Sections 3.3.1-3.3.3 show how to control the location of the text cursor,
   change its shape, and get information about its location.

 3.3.1  Positioning the Cursor

   The input and output statements and functions discussed so far do not
   allow much control over where output is displayed or where the cursor is
   located after the output is displayed. Input prompts or output always
   start in the far left column of the screen and descend one row at a time
   from top to bottom unless a semicolon is used in the PRINT or INPUT
   statements to suppress the carriage-return and line-feed sequence.

   The SPC and TAB statements, discussed in Section 3.1.4, "Skipping Spaces
   and Advancing to a Specific Column," give some control over the location
   of the cursor by allowing you to move it to any column within a given row.

   The LOCATE statement extends this control one step further. The syntax for
   LOCATE is

   LOCATE[[row]][[,[[column]][[,[[cursor]][[,[[start]][[,stop]]]]]]]]

   Using the LOCATE statement allows you to position the cursor in any row or
   column on the screen, as shown by the output from the next example:

   CLS
   FOR Row = 9 TO 1 STEP -2
      Column = 2 * Row
      LOCATE Row, Column
      PRINT "12345678901234567890";
   NEXT

   Output

   12345678901234567890

       12345678901234567890

           12345678901234567890

               12345678901234567890

                   12345678901234567890

 3.3.2  Changing the Cursor's Shape

   The optional cursor, start, and stop arguments shown in the syntax for the
   LOCATE statement also allow you to change the shape of the cursor and make
   it visible or invisible. A value of 1 for cursor makes the cursor visible,
   while a value of 0 makes the cursor invisible. The start and stop
   arguments control the height of the cursor, if it is on, by specifying the
   top and bottom "pixel" lines, respectively, for the cursor. (Any character
   on the screen is composed of lines of pixels, which are dots of light on
   the screen.) If a cursor spans the height of one row of text, then the
   line of pixels at the top of the cursor has the value 0, while the line of
   pixels at the bottom has a value of 7 or 13, depending on the type of
   display adapter you have. (For monochrome the value is 13; for color it is
   7.)

   You can turn the cursor on and change its shape without specifying a new
   location for it. For example, the following statement keeps the cursor
   wherever it is at the completion of the next PRINT or INPUT statement,
   then makes it half a character high:

   LOCATE , , 1, 2, 5    ' Row and column arguments both optional

   The following examples show different cursor shapes produced using
   different start and stop values on a color display. Each LOCATE statement
   shown in the left column is followed by the statement

   INPUT "PROMPT:", X$

   Statement                            Input Prompt and Cursor Shape
   ──────────────────────────────────────────────────────────────────────────
   LOCATE, , 1, 0, 7                    PROMPT:█

   LOCATE, , 1, 0, 3                    PROMPT:▀

   LOCATE, , 1, 4, 7                    PROMPT:

   LOCATE, , 1, 6, 2                    PROMPT:(see page 94 of printed
                                        manual)
   ──────────────────────────────────────────────────────────────────────────

   In the preceding examples, note that making the start argument bigger than
   the stop argument results in a two-piece cursor.

 3.3.3  Getting Information about the Cursor's Location

   You can think of the functions CSRLIN and POS(n) as the inverses of the
   LOCATE statement: whereas LOCATE tells the cursor where to go, CSRLIN and
   POS(n) tell your program where the cursor is. The CSRLIN function returns
   the current row and the POS(n) function returns the current column of the
   cursor's position.

   The argument n for POS(n) is what is known as a "dummy" argument; that is,
   n is a placeholder that can be any numeric expression. For example, POS(0)
   and POS(1) both return the same value.

   Example

   The following example uses the POS(n) function to print 50 asterisks in
   rows of 13 asterisks:

   FOR I% = 1 TO 50
      PRINT "*";                  ' Print an asterisk and keep
                                  ' the cursor on the same line.
      IF POS(1) > 13 THEN PRINT   ' If the cursor's position
                                  ' is past column 13, advance
                                  ' to the next line.
   NEXT

   Output

   *************
   *************
   *************
   ***********


 3.4  Working with Data Files

   Data files are physical locations on your disk where information is
   permanently stored. The following three tasks are greatly simplified by
   using data files in your BASIC programs:

   1. Creating, manipulating, and storing large amounts of data

   2. Accessing several sets of data with one program

   3. Using the same set of data in several different programs

   The sections that follow introduce the concepts of records and fields and
   contrast different ways to access data files from BASIC. When you have
   completed Sections 3.4.1-3.4.7, you should know how to do the following:

   ■ Create new data files

   ■ Open existing files and read their contents

   ■ Add new information to an existing data file

   ■ Change the contents of an existing data file

 3.4.1  How Data Files Are Organized

   A data file is a collection of related blocks of information, or
   "records." Each record in a data file is further subdivided into "fields"
   or regularly recurring items of information within each record. If you
   compare a data file with a more old-fashioned way of storing information──
   for example, a folder containing application forms filled out by job
   applicants at a particular company──then a record is analogous to one
   application form in that folder. To carry the comparison one step further,
   a field is analogous to an item of information included on every
   application form, such as a Social Security number.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     If you do not want to access a file using records but instead want to
     treat it as an unformatted sequence of bytes, then read Section 3.4.7,
     "Binary File I/O."
   ──────────────────────────────────────────────────────────────────────────

 3.4.2  Sequential and Random-Access Files

   The terms "sequential file" and "random-access file" refer to two
   different ways to store and access data on disk from your BASIC programs.
   A simplified way to think of these two kinds of files is with the
   following analogy: a sequential file is like a cassette tape, while a
   random-access file is like an LP record. To find a song on a cassette
   tape, you have to start at the beginning and fast-forward through the tape
   sequentially until you find the song you are looking for──there is no way
   to jump right to the song you want. This is similar to the way you have to
   find information in a sequential file: to get to the 500th record, you
   first have to read records 1 through 499.

   In contrast, if you want to play a certain song on an LP, all you have to
   do is lift the tone arm of the record player and put the needle down right
   on the song: you can randomly access anything on the LP without having to
   play all the songs before the one you want. Similarly, you can call up any
   record in a random-access file just by specifying its number, greatly
   reducing access time.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Although there is no way to jump directly to a specific record in a
     sequential file, the SEEK statement lets you jump directly to a specific
     byte in the file (to "fast forward" or "rewind" the tape, to extend the
     preceding analogy). See Section 3.4.7, "Binary File I/O," for more
     information on how to do this.
   ──────────────────────────────────────────────────────────────────────────

 3.4.3  Opening a Data File

   Before your program can read, modify, or add to a data file, it must first
   open the file. BASIC does this with the OPEN statement. The OPEN statement
   can be used to create a new file. The following list describes the various
   uses of the OPEN statement:

   ■ Create a new data file and open it so records can be added to it

     ' No file named PRICE.DAT is in the current directory:
     OPEN "Price.Dat" FOR OUTPUT AS #1

   ■ Open an existing data file so new records overwrite any data already in
     the file

     ' A file named PRICE.DAT is already in the current
     ' directory; new records can be written to it, but all
     ' old records are lost:
     OPEN "Price.Dat" FOR OUTPUT AS #1

   ■ Open an existing data file so new records are added to the end of the
     file, preserving data already in the file

     OPEN "Price.Dat" FOR APPEND AS #1

     The APPEND mode will also create a new file if a file with the given
     name does not already appear in the current directory.

   ■ Open an existing data file so old records can be read from it

     OPEN "Price.Dat" FOR INPUT AS #1

     See Section 3.4.5, "Using Sequential Files," for more information about
     the INPUT, OUTPUT, and APPEND modes.

   ■ Open an existing data file (or create a new one if a file with that name
     doesn't exist), then read or write fixed-length records to and from the
     file

     OPEN "Price.Dat" FOR RANDOM AS #1

     See Section 3.4.6, "Using Random-Access Files," for more information
     about this mode.

   ■ Open an existing data file (or create a new one if a file with that name
     doesn't exist), then read data from the file or add new data to the
     file, starting at any byte position in the file

     OPEN "Price.Dat" FOR BINARY AS #1

     See Section 3.4.7, "Binary File I/O," for more information about this
     mode.

     3.4.3.1  File Numbers in BASIC

   The OPEN statement does more than just specify a mode for data I/O for a
   particular file (OUTPUT, INPUT, APPEND, RANDOM, or BINARY); it also
   associates a unique file number with that file. This file number, which
   can be any integer from 1 to 255, is then used by subsequent file I/O
   statements in the program as a shorthand way to refer to the file. As long
   as the file is open, this number remains associated with the file. When
   the file is closed, the file number is freed for use with another file.
   (See Section 3.4.4 for information on how files are closed.) Your BASIC
   programs can open more than one file at a time.

   The FREEFILE function can help you find an unused file number. This
   function returns the next available number that can be associated with a
   file in an OPEN statement. For example, FREEFILE might return the value 3
   after the following OPEN statements:

   OPEN "Test1.Dat" FOR RANDOM AS #1
   OPEN "Test2.Dat" FOR RANDOM AS #2
   FileNum = FREEFILE
   OPEN "Test3.Dat" FOR RANDOM AS #FileNum

   The FREEFILE function is particularly useful when you create your own
   library procedures that open files. With FREEFILE, you don't have to pass
   information about the number of open files to these procedures.

   3.4.3.2  File Names in BASIC

   File names in OPEN statements can be any string expression, composed of
   any combination of the following characters:

   ■ The letters a-z and A-Z

   ■ The numbers 0-9

   ■ The following special characters:

     ( ) { } @ # $ % ^ & ! - _ ' ~

   The string expression can also contain an optional drive specification, as
   well as a complete or partial path specification. This means your BASIC
   program can work with data files on another drive or in a directory other
   than the one where the program is running. For example, the following OPEN
   statements are all valid:

   OPEN "..\Grades.Qtr" FOR INPUT AS #1

   OPEN "a:\salaries\1987.man" FOR INPUT AS #2

   FileName$ = "TempFile"
   OPEN FileName$ FOR OUTPUT AS #3

   BaseName$ = "Invent"
   OPEN BaseName$ + ".DAT" FOR OUTPUT AS #4

   DOS also imposes its own restrictions on file names: you can use no more
   than eight characters for the base name (everything to the left of an
   optional period) and no more than three characters for the extension
   (everything to the right of an optional period). Long file names in BASIC
   programs are truncated in the following fashion:

   File Name in Program     Resulting File Name in DOS
   ──────────────────────────────────────────────────────────────────────────
   Prog@Data@File           PROG@DAT.A@F
                            The BASIC name is more than 11 characters long,
                            so BASIC takes the first 8 letters for the base
                            name, inserts a period (.), and uses the next 3
                            letters as the extension. Everything else is
                            discarded.

   Mail#.Version1           MAIL#.VER
                            The base name (Mail#) is shorter than eight
                            characters, but the extension (Version1) is
                            longer than three, so the extension is shortened
                            to three characters.

   RELEASE_NOTES.BAK        Gives the run-time error message Bad file name.
                            The base name must be shorter than eight
                            characters if you are going to include an
                            explicit extension (.BAK in this case).
   ──────────────────────────────────────────────────────────────────────────

   DOS is not case sensitive, so lowercase letters in file names are
   converted to all uppercase (capital) letters. Therefore, you should not
   rely on the mixing of lowercase and uppercase to distinguish between
   files. For example, if you already had a file on the disk named
   INVESTOR.DAT, the following OPEN statement would overwrite that file,
   destroying any information already stored in it:

   OPEN "Investor.Dat" FOR OUTPUT AS #1

 3.4.4  Closing a Data File

   Closing a data file has two important results: first, it writes any data
   currently in the file's buffer (a temporary holding area in memory) to the
   file; second, it frees the file number associated with that file for use
   by another OPEN statement.

   Use the CLOSE statement within a program to close a file. For example, if
   the file Price.Dat is opened with the statement

   OPEN "Price.Dat" FOR OUTPUT AS #1

   then the statement CLOSE #1 ends output to Price.Dat. If Price.Dat is
   opened with

   OPEN "Price.Dat" FOR OUTPUT AS #2

   then the appropriate statement for ending output is CLOSE #2. A CLOSE
   statement with no file-number arguments closes all open files.

   A data file is also closed when either of the following occurs:

   ■ The BASIC program performing I/O ends (program termination always closes
     all open data files).

   ■ The program performing I/O transfers control to another program with the
     RUN statement.

 3.4.5  Using Sequential Files

   This section discusses how records are organized in sequential data files
   and then shows how to read data from, or write data to, an open sequential
   file.

   3.4.5.1  Records in Sequential Files

   Sequential files are ASCII (text) files. This means you can use any word
   processor to view or modify a sequential file. Records are stored in
   sequential files as a single line of text, terminated by a carriage-return
   and line-feed (CR-LF) sequence. Each record is divided into fields, or
   repeated chunks of data that occur in the same order in every record.
   Figure 3.2 shows how three records might appear in a sequential file.


   ┌──────────────────────────────────────────────────────────────────┐
   │  Record 1                                                        │
   │  ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐                     │
   │  │"│M│c│G│u│i│r│e│"│,│"│M│a│n│a│g│e│r│"│,│5│                     │
   │  └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴───┘                     │
   │  └────────┬────────┘ └────────┬────────┘ └┬┘                     │
   │        Field 1             Field 2     Field 3                   │
   │                                                                  │
   │  Record 2                                                        │
   │  ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐                             │
   │  │"│R│o│s│s│"│,│"│E│d│i│t│o│r│"│,│7│                             │
   │  └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘                             │
   │  └─────┬─────┘ └───────┬───────┘ └┬┘                             │
   │     Field 1         Field 2     Field 3                          │
   │                                                                  │
   │  Record 3                                                        │
   │  ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐           │
   │  │"│S│h│o│s│t│a│k│o│v│i│c│h│"│,│"│W│r│i│t│e│r│"│,│1│2│           │
   │  └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘           │
   │  └─────────────┬─────────────┘ └───────┬───────┘ └─┬─┘           │
   │             Field 1                 Field 2     Field 3          │
   └──────────────────────────────────────────────────────────────────┘

   Figure 3.2  Records in Sequential Files

   Note that each record in a sequential file can be a different length;
   moreover, fields can be different lengths in different records.

   The kind of variable in which a field is stored determines where that
   field begins and ends. (See Sections 3.4.5.2-3.4.5.6 for examples of
   reading and storing fields from records.) For example, if your program
   reads a field into a string variable, then any of the following can signal
   the end of that field:

   ■ Double quotes (") if the string begins with double quotes

   ■ Comma (,) if the string does not begin with double quotes

   ■ CR-LF if the field is at the end of the record

   On the other hand, if your program reads a field into a numeric variable,
   then any of the following can signal the end of that field:

   ■ Comma

   ■ One or more spaces

   ■ CR-LF

     3.4.5.2  Putting Data in a New Sequential File

   You can add data to a new sequential file after first opening it to
   receive records with an OPEN filename FOR OUTPUT statement. Use the WRITE
   # statement to write records to the file.

   You can open sequential files for reading or for writing but not for both
   at the same time. If you are writing to a sequential file and want to read
   back the data you stored, you must first close the file, then reopen it
   for input.

   Example

   The following short program creates a sequential file named Price.Dat,
   then adds data entered at the keyboard to the file. The OPEN statement in
   this program both creates the file and readies it to receive records. The
   WRITE # then writes each record to the file. Note that the number used in
   the WRITE # statement is the same number given to the file name Price.Dat
   in the OPEN statement.

   ' Create a file named Price.Dat
   ' and open it to receive new data:

   OPEN "Price.Dat" FOR OUTPUT AS #1

   DO
      ' Continue putting new records in Price.Dat until the
      ' user presses ENTER without entering a company name:
      INPUT "Company (press <ENTER> to quit): ", Company$

      IF Company$ <> "" THEN

         ' Enter the other fields of the record:
         INPUT "Style: ", Style$
         INPUT "Size: ", Size$
         INPUT "Color: ", Clr$
         INPUT "Quantity: ", Qty

         ' Put the new record in the file
         ' with the WRITE # statement:
         WRITE #1, Company$, Style$, Size$, Clr$, Qty
      END IF
   LOOP UNTIL Company$ = ""

   ' Close Price.Dat (this ends output to the file):
   CLOSE #1
   END

   ──────────────────────────────────────────────────────────────────────────
   WARNING
     If, in the preceding example, you already had a file named Price.Dat on
     the disk, the OUTPUT mode given in the OPEN statement would erase the
     existing contents of Price.Dat before writing any new data to it. If you
     want to add new data to the end of an existing file without erasing what
     is already in it, use the APPEND mode of OPEN. See Section 3.4.5.4,
     "Adding Data to a Sequential File," for more information on this mode.
   ──────────────────────────────────────────────────────────────────────────

   3.4.5.3  Reading Data from a Sequential File

   You can read data from a sequential file after first opening it with the
   statement OPEN filename FOR INPUT. Use the INPUT # statement to read
   records from the file one field at a time. (See Section 3.4.5.6, "Other
   Ways to Read Data from a Sequential File," for information on other
   file-input statements and functions you can use with a sequential file.)

   Example

   The following program opens the Price.Dat data file created in the
   previous example and reads the records from the file, displaying the
   complete record on the screen if the quantity for the item is less than
   the input amount.

   The INPUT #1 statement reads one record at a time from Price.Dat,
   assigning the fields in the record to the variables Company$, Style$,
   Size$, Clr$, and Qty. Since this is a sequential file, the records are
   read in order from the first one entered to the last one entered.

   The EOF (end-of-file) function tests whether the last record has been read
   by INPUT #. If the last record has been read, EOF returns the value -1
   (true), and the loop for getting data ends; if the last record has not
   been read, EOF returns the value 0 (false), and the next record is read
   from the file.

   OPEN "Price.Dat" FOR INPUT AS #1

   INPUT "Display all items below what level"; Reorder

   DO UNTIL EOF(1)
      INPUT #1, Company$, Style$, Size$, Clr$, Qty
      IF Qty < Reorder THEN
         PRINT  Company$, Style$, Size$, Clr$, Qty
      END IF
   LOOP
   CLOSE #1
   END

   3.4.5.4  Adding Data to a Sequential File

   As mentioned earlier, if you have a sequential file on disk and want to
   add more data to the end of it, you cannot simply open the file in output
   mode and start writing data. As soon as you open a sequential file in
   output mode, you destroy its current contents. You must use the append
   mode instead, as shown in the next example:

   OPEN "Price.Dat" FOR APPEND AS #1

   In fact, APPEND is always a safe alternative to OUTPUT, since the append
   mode creates a new file if one with the name specified doesn't already
   exist. For example, if a file named Price.Dat did not reside on disk, the
   example statement above would make a new file with that name.

   3.4.5.5  Other Ways to Write Data to a Sequential File

   The preceding examples all use the WRITE # statement to write records to a
   sequential file. There is, however, another statement you can use to write
   sequential file records: PRINT #.

   The best way to show the difference between these two data-storage
   statements is to examine the contents of a file created with both. The
   following short fragment opens a file named Test.Dat then places the same
   record in it twice, once with WRITE # and once with PRINT #. After running
   this program you can examine the contents of Test.Dat with the DOS TYPE
   commands:

   OPEN "Test.Dat" FOR OUTPUT AS #1
   Nm$ = "Penn, Will"
   Dept$ = "User Education"
   Level = 4
   Age = 25
   WRITE #1, Nm$, Dept$, Level, Age
   PRINT #1, Nm$, Dept$, Level, Age
   CLOSE #1

   Output

   "Penn, Will","User Education",4,25
   Penn, Will    User Education               4             25

   The record stored with WRITE # has commas that explicitly separate each
   field of the record, as well as quotes enclosing each string expression.
   On the other hand, PRINT # has written an image of the record to the file
   exactly as it would appear on screen with a simple PRINT statement. The
   commas in the PRINT # statement are interpreted as meaning "advance to the
   next print zone" (a new print zone occurs every 14 spaces, starting at the
   beginning of a line), and quotes are not placed around the string
   expressions.

   At this point, you may be wondering what difference these output
   statements make, except in the appearance of the data within the file. The
   answer lies in what happens when your program reads the data back from the
   file with an INPUT # statement. In the following example, the program
   reads the record stored with WRITE # and prints the values of its fields
   without any problem:

   OPEN "Test.Dat" FOR INPUT AS #1

   ' Input the first record,
   ' and display the contents of each field:
   INPUT #1, Nm$, Dept$, Level, Age
   PRINT Nm$, Dept$, Level, Age

   ' Input the second record,
   ' and display the contents of each field:
   INPUT #1, Nm$, Dept$, Level, Age
   PRINT Nm$, Dept$, Level, Age

   CLOSE #1

   Output

   Penn, Will    User Education               4             25

   However, when the program tries to input the next record stored with PRINT
   #, it produces the error message Input past end of file. Without double
   quotes enclosing the first field, the INPUT # statement sees the comma
   between Penn and Will as a field delimiter, so it assigns only the last
   name Penn to the variable Nm$. INPUT # then reads the rest of the line
   into the variable Dept$. Since all of the record has now been read, there
   is nothing left to put in the variables level and age. The result is the
   error message Input past end of file.

   If you are storing records that have string expressions and you want to
   read these records later with the INPUT # statement, follow one of these
   two rules of thumb:

   1. Use the WRITE # statement to store the records.

   2. If you want to use the PRINT # statement, remember it does not put
      commas in the record to separate fields, nor does it put quotes around
      strings. You have to put these field separators in the PRINT #
      statement yourself.

   For example, you can avoid the problems shown in the preceding example by
   using PRINT # with quotation marks surrounding each field containing a
   string expression, as in the example below.

   Example

   ' 34 is ASCII value for double-quote character:

   Q$ = CHR$(34)

   ' The next four statements all write the record to the
   ' file with double quotes around each string field:

   PRINT #1, Q$ Nm$ Q$ Q$ Dept$ Q$ Level Age
   PRINT #1, Q$ Nm$ Q$;Q$ Dept$ Q$;Level;Age
   PRINT #1, Q$ Nm$ Q$,Q$ Dept$ Q$,Level,Age
   WRITE #1, Nm$, Dept$, Level, Age

   Output to File

   "Penn, Will""User Education" 4  25
   "Penn, Will""User Education" 4  25
   "Penn, Will"  "User Education"      4             25
   "Penn, Will","User Education",4,25

   3.4.5.6  Other Ways to Read Data from a Sequential File

   In the preceding sections, INPUT # is used to read a record (one line of
   data from a file), assigning different fields in the record to the
   variables listed after INPUT #. This section explores alternative ways to
   read data from sequential files, both as records (LINE INPUT #) and as
   unformatted sequences of bytes (INPUT$).

 The LINE INPUT # Statement

   With the LINE INPUT # statement, your program can read a line of text
   exactly as it appears in a file without interpreting commas or quotes as
   field delimiters. This is particularly useful in programs that work with
   ASCII text files.

   The LINE INPUT # statement reads an entire line from a sequential file (up
   to a carriage-return and line-feed sequence) into a single string
   variable.

   Examples

   The following short program reads each line from the file Chap1.Txt and
   then echoes that line to the screen:

   ' Open Chap1.Txt for sequential input:
   OPEN "Chap1.Txt" FOR INPUT AS #1

   ' Keep reading lines sequentially from the file until
   ' there are none left in the file:

   DO UNTIL EOF(1)

      ' Read a line from the file and store it
      ' in the variable LineBuffer$:
      LINE INPUT #1, LineBuffer$

      ' Print the line on the screen:
      PRINT LineBuffer$
   LOOP

   The preceding program is easily modified to a file-copying utility that
   prints each line read from the specified input file to another file,
   instead of to the screen:

   ' Input names of input and output files:

   INPUT "File to copy: ", FileName1$
   IF FileName1$ = "" THEN END
   INPUT "Name of new file: ", FileName2$
   IF FileName2$ = "" THEN END

   ' Open first file for sequential input:
   OPEN FileName1$ FOR INPUT AS #1

   ' Open second file for sequential output:
   OPEN FileName2$ FOR OUTPUT AS #2

   ' Keep reading lines sequentially from first file
   ' until there are none left in the file:
   DO UNTIL EOF(1)

      ' Read a line from first file and store it in the
      ' variable LineBuffer$:
      LINE INPUT #1, LineBuffer$

      ' Write LineBuffer$ to the second file:
      PRINT #2, LineBuffer$

   LOOP

 The INPUT$ Function

   Yet another way to read data from sequential files (and, in fact, from any
   file) is to use the INPUT$ function. Whereas INPUT # and LINE INPUT # read
   a line at a time from a sequential file, INPUT$ reads a specified number
   of characters from a file, as shown in the following examples:

   Statement                Action
   ──────────────────────────────────────────────────────────────────────────
   X$ = INPUT$(100, #1)     Reads 100 characters from file number 1 and
                            assigns all of them to the string variable X$

   Test$ = INPUT$(1, #2)    Reads one character from file number 2 and
                            assigns it to the string variable Test$

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

   The INPUT$ function without a file number always reads input from standard
   input (usually the keyboard).

   The INPUT$ function does what is known as "binary input"; that is, it
   reads a file as an unformatted stream of characters. For example, it does
   not see a carriage-return and line-feed sequence as signaling the end of
   an input operation. Therefore, INPUT$ is the best choice when you want
   your program to read every single character from a file or when you want
   it to read a binary, or non-ASCII, file.

   Example

   The following program copies the named binary file to the screen, printing
   only alphanumeric and punctuation characters in the ASCII range 32 to 126,
   as well as tabs, carriage returns, and line feeds:

   ' 9 is ASCII value for horizontal tab, 10 is ASCII
   value
   ' for line feed, and 13 is ASCII value for carriage return:
   CONST LINEFEED = 10, CARRETURN = 13, TABCHAR = 9

   INPUT "Print which file: ", FileName$
   IF FileName$ = "" THEN END

   OPEN FileName$ FOR INPUT AS #1

   DO UNTIL EOF(1)
      Character$ = INPUT$(1, #1)
      CharVal = ASC(Character$)
      SELECT CASE CharVal
         CASE 32 TO 126
            PRINT Character$;
         CASE TABCHAR, CARRETURN
            PRINT Character$;
         CASE LINEFEED
            IF OldCharVal <> CARRETURN THEN PRINT Character$;
         CASE ELSE
            ' This is not one of the characters this program
            ' is interested in, so don't print anything.
      END SELECT
      OldCharVal = CharVal
   LOOP

 3.4.6  Using Random-Access Files

   This section discusses how records are organized in random-access data
   files, then shows you how to read data from and write data to a file
   opened for random access.

   3.4.6.1  Records in Random-Access Files

   Random-access records are stored quite differently from sequential
   records. Each random-access record is defined with a fixed length, as is
   each field within the record. These fixed lengths determine where a record
   or field begins and ends, as there are no commas separating fields, and no
   carriage-return and line-feed sequences between records. Figure 3.3 shows
   how three records might appear in a random-access file.


                  Record 1                               Record 2
   ┌──────────────────┴──────────────────┐┌─────────────────┴─────────────────
   ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬
   │M│c│G│u│i│r│e│ │ │ │M│a│n│a│g│e│r│5│ │R│o│s│s│ │ │ │ │ │ │E│d│i│t│o│r│ │3│
   └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴
   └─────────┬─────────┘└─────┬──────┘└─┬┘└────────┬─────────┘└─────┬──────┘└─
          Field 1          Field 2   Field 3     Field 1         Field 2   Fie

   Figure 3.3  Records in a Random-Access File

   If you are storing records containing numbers, using random-access files
   saves disk space when compared with using sequential files. This is
   because sequential files save numbers as a sequence of ASCII characters
   representing each digit, whereas random-access files save numbers in a
   compressed binary format.

   For example, the number 17,000 is represented in a sequential file using
   five bytes, one for each digit. However, if 17,000 is stored in an integer
   field of a random-access record, it takes only two bytes of disk space.

   In general, integers in random-access files take two bytes, long integers
   and single-precision numbers take four bytes, and double-precision numbers
   take eight bytes.

   3.4.6.2  Adding Data to a Random-Access File

   To write a program that adds data to a random-access file, follow these
   steps:

   1. Define the fields of each record.

   2. Open the file in random-access mode and specify the length of each
      record.

   3. Get input for a new record and store the record in the file.

   Each of these steps is now considerably easier than it was in BASICA, as
   you can see from the examples that follow.

 Defining Fields

   You can define your own record with a TYPE...END TYPE statement, which
   allows you to create a composite data type that mixes string and numeric
   elements. This is a big advantage over the earlier method of setting up
   records with a FIELD statement, which required that each field be defined
   as a string. By defining a record with TYPE...END TYPE, you eliminate the
   need to use the functions that convert numeric data to strings (MKtype$,
   MKSMBF$, and MKDMBF$) and strings to numeric data (CVtype, CVSMBF, and
   CVDMBF).

   The following fragments contrast these two methods of defining records:

   ■ Record defined with TYPE...END TYPE

     ' Define the RecordType structure:
     TYPE RecordType
        Name AS STRING * 30
        Age AS INTEGER
        Salary AS SINGLE
     END TYPE

     ' Declare the variable RecordVar
     ' as having the type RecordType:
     DIM RecordVar AS RecordType

     .
     .
     .

   ■ Record defined with FIELD

     ' Define the lengths of the fields
     ' in the temporary storage buffer:
     FIELD #1,30 AS Name$,2 AS Age$,4 AS Salary$
     .
     .
     .

 Opening the File and Specifying Record Length

   Since the length of a random-access record is fixed, you should let your
   program know how long you want each record to be; otherwise, record length
   defaults to 128 bytes.

   To specify record length, use the LEN = clause in the OPEN statement. The
   next two fragments, which continue the contrasting examples started above,
   show how to use LEN =.

   ■ Specifying the record length for a record that is defined with the
     statement TYPE...END TYPE

     .
     .
     .
     ' Open the random-access file and specify the length
     ' of one record as being equal to the length of the
     ' RecordVar variable:
     OPEN "EMPLOYEE.DAT" FOR RANDOM AS #1 LEN = LEN(RecordVar)
     .
     .
     .

   ■ Specifying record length for a record defined with FIELD

     .
     .
     .
     ' Open the random-access file and specify the length
     ' of a record:
     OPEN "EMPLOYEE.DAT" FOR RANDOM AS #1 LEN = 31
     .
     .
     .

   As you can see, when you use FIELD, you have to add the lengths of each
   field yourself (FirstName$ is 10 bytes, LastName$ is 15 bytes, Age$ is 2
   bytes, Salary$ is 4 bytes, so the record is 10+15+2+4 or 31 bytes long).
   With TYPE...END TYPE, you no longer have to do these calculations.
   Instead, just use the LEN function to calculate the length of the variable
   you have created to hold your records (RecordVar, in this case).

 Inputting Data and Storing the Record

   You can input data directly into the elements of a user-defined record
   without having to worry about left- or right-justification of input within
   a field with LSET or RSET. Compare the following two fragments, which
   continue the examples started above, to see the amount of code this
   approach saves you.

   ■ Entering data for a random-access record and storing the record using
     TYPE...END TYPE.

     .
     .
     .

     ' Enter the data:
     INPUT "First name"; RecordVar.FirstName
     INPUT "Last name"; RecordVar.LastName
     INPUT "Age"; RecordVar.Age
     INPUT "Salary"; RecordVar.Salary
     ' Store the record:
     PUT #1, , RecordVar

     .
     .
     .

   ■ Entering data for a random-access record and storing the record using
     FIELD

     .
     .
     .

     ' Enter the data:
     INPUT "First name"; FirstNm$
     INPUT "Last name"; LastNm$
     INPUT "Age"; AgeVal%
     INPUT "Salary"; SalaryVal!

     ' Left justify the data in the storage-buffer fields,
     ' using the MKI$ and MKS$ functions to convert numbers
     ' to file strings:
     LSET FirstName$ = FirstNm$
     LSET LastName$ = LastNm$
     LSET Age$ = MKI$(AgeVal%)
     LSET Salary$ = MKS$(SalaryVal!)

     ' Store the record:
     PUT #1

     .
     .
     .

 Putting It All Together

   The following program puts together all the steps outlined above──defining
   fields, specifying record length, inputting data, and storing the input
   data──to open a random-access data file named STOCK.DAT and add records to
   it:

   DEFINT A-Z

   ' Define structure of a single record in the random-access
   ' file. Each record will consist of four fixed-length fields
   ' ("PartNumber", "Description", "UnitPrice", "Quantity"):
   TYPE StockItem
      PartNumber AS STRING *  6
      Description AS STRING * 20
      UnitPrice AS SINGLE
      Quantity AS INTEGER
   END TYPE

   ' Declare a variable (StockRecord) using the above type:
   DIM StockRecord AS StockItem

   ' Open the random-access file, specifying the length of one
   ' record as the length of the StockRecord variable:
   OPEN "STOCK.DAT" FOR RANDOM AS #1 LEN=LEN(StockRecord)

   ' Use LOF() to calculate the number of records already in
   ' the file, so new records will be added after them:
   RecordNumber = LOF(1) \ LEN(StockRecord)

   ' Now, add new records:
   DO

      ' Input data for a stock record from keyboard and store
      ' in the different elements of the StockRecord variable:
      INPUT "Part Number? ", StockRecord.PartNumber
      INPUT "Description? ", StockRecord.Description
      INPUT "Unit Price ? ", StockRecord.UnitPrice
      INPUT "Quantity   ? ", StockRecord.Quantity

      RecordNumber = RecordNumber + 1

      ' Write data in StockRecord to a new record in the file:
      PUT #1, RecordNumber, StockRecord



      ' Check to see if more data are to be read:
      INPUT "More (Y/N)? ", Resp$
   LOOP UNTIL UCASE$(Resp$) = "N"

   ' All done; close the file and end:
   CLOSE  #1
   END

   If the STOCK.DAT file already existed, this program would add more records
   to the file without overwriting any that were already in the file. The
   following key statement makes this work:

   RecordNumber = LOF(1) \ LEN(StockRecord)

   Here is what happens:

   1. The LOF(1) function calculates the total number of bytes in the file
      STOCK.DAT. If STOCK.DAT is new or has no records in it, LOF(1) returns
      the value 0.

   2. The LEN(StockRecord) function calculates the number of bytes in one
      record. (StockRecord is defined as having the same structure as the
      user-defined type StockItem.)

   3. Therefore, the number of records is equal to the total bytes in the
      file divided by the bytes in one record.

   This is another advantage of having a fixed-length record. Since each
   record is the same size, you can always use the above formula to calculate
   the number of records in the file. Obviously, this would not work with a
   sequential file, since sequential records can have different lengths.

   3.4.6.7  Reading Data Sequentially

   Using the technique outlined in the preceding section for calculating the
   number of records in a random-access file, you can write a program that
   reads all the records in that file.

   Example

   The following program reads records sequentially (from the first record
   stored to the last) from the STOCK.DAT file created in the previous
   section:

   ' Define a record structure (type) for random-access
   ' file records:
   TYPE StockItem
      PartNumber AS STRING *  6
      Description AS STRING * 20
      UnitPrice AS SINGLE
      Quantity AS INTEGER
   END TYPE

   ' Declare a variable (StockRecord) using the above type:
   DIM StockRecord AS StockItem

   ' Open the random-access file:
   OPEN "STOCK.DAT" FOR RANDOM AS #1 LEN = LEN(StockRecord)

   ' Calculate number of records in the file:
   NumberOfRecords = LOF(1) \ LEN(StockRecord)

   ' Read the records and write the data to the screen:
   FOR RecordNumber = 1 TO NumberOfRecords

      ' Read the data from a new record in the file:
      GET #1, RecordNumber, StockRecord



      ' Print the data to the screen:
      PRINT "Part Number: ", StockRecord.PartNumber
      PRINT "Description: ", StockRecord.Description
      PRINT "Unit Price : ", StockRecord.UnitPrice
      PRINT "Quantity   : ", StockRecord.Quantity

   NEXT

   ' All done; close the file and end:
   CLOSE #1
   END

   It is not necessary to close STOCK.DAT before reading from it. Opening a
   file for random access lets you write to or read from the file with a
   single OPEN statement.

   3.4.6.8  Using Record Numbers to Retrieve Records

   You can read any record from a random-access file by specifying the
   record's number in a GET statement. You can write to any record in a
   random-access file by specifying the record's number in a PUT statement.
   This is one of the major advantages that random-access files have over
   sequential files, since sequential files do not permit direct access to a
   specific record.

   The sample-application program INDEX.BAS, listed in Section 3.6.2, shows
   a technique that quickly finds a particular record by searching an index
   of record numbers.

   Example

   The following fragment shows how to use GET with a record number:

   DEFINT A-Z           ' Default variable type is integer.
   CONST FALSE = 0, TRUE = NOT FALSE

   TYPE StockItem
      PartNumber AS STRING *  6
      Description AS STRING * 20
      UnitPrice AS SINGLE
      Quantity AS INTEGER
   END TYPE

   DIM StockRecord AS StockItem

   OPEN "STOCK.DAT" FOR RANDOM AS #1 LEN=LEN(StockRecord)

   NumberOfRecords = LOF(1) \ LEN(StockRecord)
   GetMoreRecords = TRUE

   DO
      PRINT "Enter record number for part you want to see ";
      PRINT "(0 to end): ";
      INPUT "", RecordNumber

      IF RecordNumber > 0 AND RecordNumber < NumberOfRecords THEN

         ' Get the record whose number was entered and store
         ' it in StockRecord:
         GET #1, RecordNumber, StockRecord

         ' Display the record:
         .
         .
         .
         ELSEIF RecordNumber = 0 THEN
         GetMoreRecords = FALSE
      ELSE
         PRINT "Input value out of range."
      END IF
   LOOP WHILE GetMoreRecords
   END

 3.4.7  Binary File I/O

   Binary access is a third way──in addition to random access and sequential
   access──to read or write a file's data. Use the following statement to
   open a file for binary I/O:

   OPEN file FOR BINARY AS #filenum

   Binary access is a way to get at the raw bytes of any file, not just an
   ASCII file. This makes it very useful for reading or modifying files saved
   in a non-ASCII format, such as Microsoft Word files or executable (.EXE)
   files.

   Files opened for binary access are treated as an unformatted sequence of
   bytes. Although you can read or write a record (a variable declared as
   having a user-defined type) to a file opened in the binary mode, the file
   itself does not have to be organized into fixed-length records. In fact,
   binary I/O does not have to deal with records at all, unless you consider
   each byte in a file as a separate record.

   3.4.7.1  Comparing Binary Access and Random Access

   The binary-access mode is similar to the random-access mode in that you
   can both read from and write to a file after a single OPEN statement.
   (Binary thus differs from sequential access, where you must first close a
   file and then reopen it if you want to switch between reading and
   writing.) Also, like random access, binary access lets you move backwards
   and forwards within an open file. Binary access even supports the same
   statements used for reading and writing random-access files:

   {GET| PUT} [[#]]filenumber, [[position]], variable

   Here, variable can have any type, including a variable-length string or a
   user-defined type, and position points to the place in the file where the
   next GET or PUT operation will take place. (The position is relative to
   the beginning of the file; that is, the first byte in the file has
   position one, the second byte has position two, and so on.) If you leave
   off the position argument, successive GET and PUT operations move the file
   pointer sequentially through the file from the first byte to the last.

   The GET statement reads a number of bytes from the file equal to the
   length of variable. Similarly, the PUT statement writes a number of bytes
   to the file equal to the length of variable. For example, if variable has
   integer type, then GET reads two bytes into variable; if variable has
   single-precision type, GET reads four bytes. Therefore, if you don't
   specify a position argument in a GET or PUT statement, the file pointer is
   moved a distance equal to the length of variable.

   The GET statement and INPUT$ function are the only ways to read data from
   a file opened in binary mode. The PUT statement is the only way to write
   data to a file opened in binary mode.

   Binary access, unlike random access, enables you to move to any byte
   position in a file and then read or write any number of bytes you want. In
   contrast, random access can only move to a record boundary and read a
   fixed number of bytes (the length of a record) each time.

   3.4.7.2  Positioning the File Pointer with SEEK

   If you want to move the file pointer to a certain place in a file without
   actually performing any I/O, use the SEEK statement. Its syntax is

   SEEK filenumber, position

   After a SEEK statement, the next read or write operation in the file
   opened with filenumber begins at the byte noted in position.

   The counterpart to the SEEK statement is the SEEK function, with this
   syntax:

   SEEK(filenumber)

   The SEEK function tells you the byte position where the very next read or
   write operation begins. (If you are using binary I/O to access a file, the
   LOC and SEEK functions give similar results, but LOC returns the position
   of the last byte read or written, while SEEK returns the position of the
   next byte to be read or written.)

   The SEEK statement and function also work on files opened for sequential
   or random access. With sequential access, both the statement and the
   function behave the same as they do with binary access; that is, the SEEK
   statement moves the file pointer to specific byte positions, and the SEEK
   function returns information about the next byte to read or write.

   However, if a file is opened for random access, the SEEK statement can
   move the file pointer only to the beginning of a record, not to a byte
   within a record. Also, when used with random-access files, the SEEK
   function returns the number of the next record rather than the position of
   the next byte.

   Example

   The following program opens a QuickBASIC Quick library, then reads and
   prints the names of BASIC procedures and other external symbols contained
   in the library. This program is in the file named QLBDUMP.BAS on the
   QuickBASIC distribution disks.

   ' This program prints the names of Quick library procedures.
   DECLARE SUB DumpSym (SymStart AS INTEGER, QHdrPos AS LONG)

   TYPE ExeHdr                     ' Part of DOS .EXE header
       other1    AS STRING * 8     ' Other header information
       CParHdr   AS INTEGER        ' Size of header in paragraphs
       other2    AS STRING * 10    ' Other header information
       IP          AS INTEGER      ' Initial IP value
       CS          AS INTEGER      ' Initial (relative) CS value
   END TYPE

   TYPE QBHdr                      ' QLB header
       QBHead    AS STRING * 6     ' QB specific heading
       Magic     AS INTEGER        ' Magic word: identifies file as a Quick li
       SymStart  AS INTEGER        ' Offset from header to first code symbol
       DatStart  AS INTEGER        ' Offset from header to first data symbol
   END TYPE

   TYPE QbSym                      ' QuickLib symbol entry
       Flags     AS INTEGER        ' Symbol flags
       NameStart AS INTEGER        ' Offset into name table
       other     AS STRING * 4     ' Other header information
   END TYPE

   DIM EHdr AS ExeHdr, Qhdr AS QBHdr, QHdrPos AS LONG

   INPUT "Enter Quick library file name: ", FileName$
   FileName$ = UCASE$(FileName$)
   IF INSTR(FileName$,".QLB") = 0 THEN FileName$ = FileName$ + ".QLB"
   INPUT "Enter output file name or press ENTER for screen: ", OutFile$
   OutFile$ = UCASE$(OutFile$)
   IF OutFile$ = "" THEN OutFile$ = "CON"
   OPEN FileName$ FOR BINARY AS #1
   OPEN OutFile$ FOR OUTPUT AS #2

   GET #1, , EHdr                    ' Read the EXE format header.
   QHdrPos = (EHdr.CParHdr + EHdr.CS) * 16 + EHdr.IP + 1

   GET #1, QHdrPos, Qhdr             ' Read the QuickLib format header.
   IF Qhdr.Magic <> &H6C75 THEN PRINT "Not a QB UserLibrary": END

   PRINT #2, "Code Symbols:": PRINT #2,
   DumpSym Qhdr.SymStart, QHdrPos    ' dump code symbols
   PRINT #2,
   PRINT #2, "Data Symbols:": PRINT #2, ""
   DumpSym Qhdr.DatStart, QHdrPos    ' dump data symbols
   PRINT #2,

   END

   SUB DumpSym (SymStart AS INTEGER, QHdrPos AS LONG)
      DIM QlbSym AS QbSym
      DIM NextSym AS LONG, CurrentSym AS LONG

      ' Calculate the location of the first symbol entry,
      ' then read that entry:
      NextSym = QHdrPos + Qhdr.SymStart
      GET #1, NextSym, QlbSym

   DO
         NextSym = SEEK(1)           ' Save the location of the next symbol.
         CurrentSym = QHdrPos + QlbSym.NameStart
         SEEK #1, CurrentSym         ' Use SEEK to move to the name
                                     ' for the current symbol entry.
         Prospect$ = INPUT$(40, 1)   ' Read the longest legal string,
                                     ' plus one additional byte for
                                     ' the final null character (CHR$(0)).

         ' Extract the null-terminated name:
         SName$ = LEFT$(Prospect$, INSTR(Prospect$, CHR$(0)))

         ' Print only those names that do not begin with "__", "$", or "b$"
         ' as these names are usually considered reserved:
         T$ = LEFT$(SName$, 2)
         IF T$ <> "__" AND LEFT$(SName$, 1) <> "$" AND UCASE$(T$) <> "B$" THEN
            PRINT #2, "  " + SName$
         END IF

         GET #1, NextSym, QlbSym     ' Read a symbol entry.
      LOOP WHILE QlbSym.Flags        ' Flags=0 (false) means end of table.

   END SUB


 3.5  Working with Devices

   Microsoft BASIC supports device I/O. This means certain computer
   peripherals can be opened for I/O just like data files on disk. Input from
   or output to these devices can be done with the statements and functions
   listed in Table 9.4, "Statements and Functions Used for Data-File I/O,"
   with the exceptions noted in Section 3.5.1, "Differences between Device
   I/O and File I/O." Table 3.1 lists the devices supported by BASIC.

   Table 3.1  Devices Supported by BASIC for I/O
   Name                     Device                  I/O Mode Supported
   ──────────────────────────────────────────────────────────────────────────
   COM1:                    First serial port       Input and output

   COM2:                    Second serial port      Input and output

   CONS:                    Screen                  Output only

   KYBD:                    Keyboard                Input only

   LPT1:                    First printer           Output only

   LPT2:                    Second printer          Output only

   LPT3:                    Third printer           Output only

   SCRN:                    Screen                  Output only

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

 3.5.1  Differences between Device I/O and File I/O

   Certain functions and statements used for file I/O are not allowed for
   device I/O, while other statements and functions behave differently. These
   are some of the differences:

   ■ The CONS:, SCRN:, and LPTn: devices cannot be opened in the input or
     append modes.

   ■ The KYBD: device cannot be opened in the output or append modes.

   ■ The EOF, LOC, and LOF functions cannot be used with the CONS:, KYBD:,
     LPTn:, or SCRN: devices.

   ■ The EOF, LOC, and LOF functions can be used with the COMn: serial
     device; however, the values these functions return have a different
     meaning than the values they return when used with data files. (See
     Section 3.5.2 for an explanation of what these functions do when used
     with COMn:.)

   Example

   The following program shows how the devices LPT1: or SCRN: can be opened
   for output using the same syntax as that for data files. This program
   reads all the lines from the file chosen by the user and then prints the
   lines on the screen or the printer according to the user's choice.

   CLS
   ' Input the name of the file to look at:
   INPUT "Name of file to display: ", FileNam$

   ' If no name is entered, end the program;
   ' otherwise, open the given file for reading (INPUT):
   IF FileNam$ = "" THEN END ELSE OPEN FileNam$ FOR INPUT AS #1

   ' Input choice for displaying file (Screen or Printer);
   ' continue prompting for input until either the "S" or "P"
   ' keys are pressed:
   DO
      ' Go to row 2, column 1 on the screen and print prompt:
      LOCATE 2, 1, 1
      PRINT "Send output to screen (S), or to printer (P): ";

      ' Print over anything after the prompt:
      PRINT SPACE$(2);

      ' Relocate cursor after the prompt, and make it visible:
      LOCATE 2, 47, 1
      Choice$ = UCASE$(INPUT$(1))     ' Get input.
      PRINT Choice$
   LOOP WHILE Choice$ <> "S" AND Choice$ <> "P"

   ' Depending on the key pressed, open either the printer
   ' or the screen for output:
   SELECT CASE Choice$
      CASE "P"
         OPEN "LPT1:" FOR OUTPUT AS #2
         PRINT "Printing file on printer."
      CASE "S"
         CLS
         OPEN "SCRN:" FOR OUTPUT AS #2
   END SELECT

   ' Set the width of the chosen output device to 80 columns:
   WIDTH #2, 80

   ' As long as there are lines in the file, read a line
   ' from the file and print it on the chosen device:
   DO UNTIL EOF(1)
      LINE INPUT #1, LineBuffer$
      PRINT #2, LineBuffer$
   LOOP

   CLOSE        ' End input from the file and output to the device.
   END

 3.5.2  Communications through the Serial Port

   The OPEN "COMn:" statement (where n can be 1 or, if you have two serial
   ports, 2) allows you to open your computer's serial port(s) for serial
   (bit-by-bit) communication with other computers or with peripheral devices
   such as modems or serial printers. The following are some of the
   parameters you can specify:

   ■ Rate of data transmission, measured in "baud" (bits per second)

   ■ Whether or not to detect transmission errors and how those errors will
     be detected

   ■ How many stop bits (1, 1.5, or 2) are to be used to signal the end of a
     transmitted byte

   ■ How many bits in each byte of data transmitted or received constitute
     actual data

   When the serial port is opened for communication, an input buffer is set
   aside to hold the bytes being read from other device. This is because, at
   high baud rates, characters arrive faster than they can be processed. The
   default size for this buffer is 512 bytes, and it can be modified with the
   LEN = numbytes option of the OPEN "COMn:" statement. The values returned
   by the EOF, LOC, and LOF functions when used with a communications device
   return information about the size of this buffer, as shown in the
   following list:

   Function                 Information Returned
   ──────────────────────────────────────────────────────────────────────────
   EOF                      Whether or not any characters are waiting to be
                            read from the input buffer

   LOC                      The number of characters waiting in the input
                            buffer

   LOF                      The amount of space remaining (in bytes) in the
                            output buffer

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

   Since every character is potentially significant data, both INPUT # and
   LINE INPUT # have serious drawbacks for getting input from another device.
   This is because INPUT # stops reading data into a variable when it
   encounters a comma or new line (and, sometimes, a space or double quote),
   and LINE INPUT # stops reading data when it encounters a new line. This
   makes INPUT$ the best function to use for input from a communications
   device, since it reads all characters.

   The following line uses the LOC function to check the input buffer for the
   number of characters waiting there from the communications device opened
   as file #1; it then uses the INPUT$ function to read those characters,
   assigning them to a string variable named ModemInput$:

   ModemInput$ = INPUT$(LOC(1), #1)


 3.6  Sample Applications

   The sample applications listed in this section include a screen-handling
   program that prints a calendar for any month in any year from 1899 to
   2099, a file I/O program that builds and searches an index of record
   numbers from a random-access file, and a communications program that makes
   your PC behave like a terminal when connected to a modem.

 3.6.1  Perpetual Calendar (CAL.BAS)

   After prompting the user to input a month from 1 to 12 and a year from
   1899 to 2099, the following program prints the calendar for the given
   month and year. The IsLeapYear procedure makes appropriate adjustments to
   the calendar for months in a leap year.

   Statements and Functions Used

   This program demonstrates the following screen-handling functions and
   statements discussed in Sections 3.1-3.3:

   ■ INPUT

   ■ INPUT$

   ■ LOCATE

   ■ POS(0)

   ■ PRINT

   ■ PRINT USING

   ■ TAB

   Program Listing

   The perpetual calendar program CAL.BAS is listed below.

   DEFINT A-Z              ' Default variable type is integer.

   ' Define a data type for the names of the months and the
   ' number of days in each:
   TYPE MonthType
      Number AS INTEGER       ' Number of days in the month
      MName AS STRING * 9     ' Name of the month
   END TYPE

   ' Declare procedures used:
   DECLARE FUNCTION IsLeapYear% (N%)
   DECLARE FUNCTION GetInput% (Prompt$, Row%, LowVal%, HighVal%)

   DECLARE SUB PrintCalendar (Year%, Month%)
   DECLARE SUB ComputeMonth (Year%, Month%, StartDay%, TotalDays%)

   DIM MonthData(1 TO 12) AS MonthType

   ' Initialize month definitions from DATA statements below:
   FOR I = 1 TO 12
      READ MonthData(I).MName, MonthData(I).Number
   NEXT

   ' Main loop, repeat for as many months as desired:
   DO
      CLS

      ' Get year and month as input:
      Year = GetInput("Year (1899 to 2099): ", 1, 1899, 2099)
      Month = GetInput("Month (1 to 12): ", 2, 1, 12)

      ' Print the calendar:
      PrintCalendar Year, Month
   ' Another Date?
      LOCATE 13, 1           ' Locate in 13th row, 1st column.
      PRINT "New Date? ";    ' Keep cursor on same line.
      LOCATE , , 1, 0, 13    ' Turn cursor on and make it one
                             ' character high.
      Resp$ = INPUT$(1)      ' Wait for a key press.
      PRINT Resp$            ' Print the key pressed.

   LOOP WHILE UCASE$(Resp$) = "Y"
   END

   ' Data for the months of a year:
   DATA January, 31, February, 28, March, 31
   DATA April, 30, May, 31, June, 30, July, 31, August, 31
   DATA September, 30, October, 31, November, 30, December, 31

   ' ====================== COMPUTEMONTH =====================
   '  Computes the first day and the total days in a month
   ' =========================================================

   SUB ComputeMonth (Year, Month, StartDay, TotalDays) STATIC
      SHARED MonthData() AS MonthType

      CONST LEAP   = 366 MOD 7
      CONST NORMAL = 365 MOD 7

      ' Calculate total number of days (NumDays) since 1/1/1899:

      ' Start with whole years:
      NumDays = 0
      FOR I = 1899 TO Year - 1
         IF IsLeapYear(I) THEN         ' If leap year,
            NumDays = NumDays + LEAP   ' add 366 MOD 7.
         ELSE                          ' If normal year,
            NumDays = NumDays + NORMAL ' add 365 MOD 7.
         END IF
      NEXT

      ' Next, add in days from whole months:
      FOR I = 1 TO Month - 1
         NumDays = NumDays + MonthData(I).Number
      NEXT

      ' Set the number of days in the requested month:
      TotalDays = MonthData(Month).Number

      ' Compensate if requested year is a leap year:
      IF IsLeapYear(Year) THEN

         ' If after February, add one to total days:
         IF Month > 2 THEN
            NumDays = NumDays + 1

         ' If February, add one to the month's days:
         ELSEIF Month = 2 THEN
            TotalDays = TotalDays + 1
         END IF
      END IF

      ' 1/1/1899 was a Sunday, so calculating "NumDays MOD 7"
      ' gives the day of week (Sunday = 0, Monday = 1, Tuesday
      ' = 2, and so on) for the first day of the input month:
      StartDay = NumDays MOD 7
   END SUB

   ' ======================== GETINPUT =======================
   '    Prompts for input, then tests for a valid range
   ' =========================================================

   FUNCTION GetInput (Prompt$, Row, LowVal, HighVal) STATIC

      ' Locate prompt at specified row, turn cursor on and
      ' make it one character high:
      LOCATE Row, 1, 1, 0, 13
      PRINT Prompt$;

      ' Save column position:
      Column = POS(0)

      ' Input value until it's within range:
      DO
         LOCATE Row, Column   ' Locate cursor at end of prompt.
         PRINT SPACE$(10)     ' Erase anything already there.
         LOCATE Row, Column   ' Relocate cursor at end of prompt.
         INPUT "", Value      ' Input value with no prompt.
      LOOP WHILE (Value < LowVal OR Value > HighVal

      ' Return valid input as value of function:
      GetInput = Value

   END FUNCTION

   ' ====================== ISLEAPYEAR =======================
   '   Determines if a year is a leap year or not
   ' =========================================================

   FUNCTION IsLeapYear (N) STATIC

      ' If the year is evenly divisible by 4 and not divisible
      ' by 100, or if the year is evenly divisible by 400,
      ' then it's a leap year:
      IsLeapYear = (N MOD 4=0 AND N MOD 100<>0) OR (N MOD 400=0)
   END FUNCTION

   ' ===================== PRINTCALENDAR =====================
   '   Prints a formatted calendar given the year and month
   ' =========================================================

   SUB PrintCalendar (Year, Month) STATIC
   SHARED MonthData() AS MonthType

      ' Compute starting day (Su M Tu ...)
      ' and total days for the month:
      ComputeMonth Year, Month, StartDay, TotalDays
      CLS
      Header$ = RTRIM$(MonthData(Month).MName) + "," + STR$(Year)

      ' Calculate location for centering month and year:
      LeftMargin = (35 - LEN(Header$)) \ 2

   ' Print header:
      PRINT TAB(LeftMargin); Header$
      PRINT
      PRINT "Su   M   Tu   W   Th    F   Sa"
      PRINT

      ' Recalculate and print tab
      ' to the first day of the month (Su M Tu ...):
      LeftMargin = 5 * StartDay + 1
      PRINT TAB(LeftMargin);

      ' Print out the days of the month:
      FOR I = 1 TO TotalDays
         PRINT USING "##"; I;

         ' Advance to the next line
         ' when the cursor is past column 32:
         IF POS(0) > 32 THEN PRINT
      NEXT

   END SUB

   Output

   ┌───────────────────────────────────────────────────────────────────┐
   │                                                                   │
   │                June, 1988                                         │
   │                                                                   │
   │     Su    M    Tu    W   Th     F    Sa                           │
   │                                                                   │
   │                      1    2     3     4                           │
   │      5    6     7    8    9    10    11                           │
   │     12   13    14   15   16    17    18                           │
   │     19   20    21   22   23    24    25                           │
   │     26   27    28   29   30                                       │
   │                                                                   │
   │                                                                   │
   │     New Date?                                                     │
   │                                                                   │
   └───────────────────────────────────────────────────────────────────┘

 3.6.2  Indexing a Random-Access File (INDEX.BAS)

   The following program uses an indexing technique to store and retrieve
   records in a random-access file. Each element of the Index array has two
   parts: a string field (PartNumber) and an integer field (RecordNumber).
   This array is sorted alphabetically on the PartNumber field, which allows
   the array to be rapidly searched for a specific part number using a binary
   search.

   The Index array functions much like the index to a book. When you want to
   find the pages in a book that deal with a particular topic, you look up an
   entry for that topic in the index. The entry then points to a page number
   in the book. Similarly, this program looks up a part number in the
   alphabetically sorted Index array. Once it finds the part number, the
   associated record number in the RecordNumber field points to the record
   containing all the information for that part.

   Statements and Functions Used

   This program demonstrates the following functions and statements used in
   accessing random-access files:

   ■ TYPE...END TYPE

   ■ OPEN...FOR RANDOM

   ■ GET #

   ■ PUT #

   ■ LOF

   Program Listing

   The random-access file indexing program INDEX.BAS is listed below.

   DEFINT A-Z

   ' Define the symbolic constants used globally in the program:
   CONST FALSE = 0, TRUE = NOT FALSE

   ' Define a record structure for random-file records:
   TYPE StockItem
      PartNumber AS STRING * 6
      Description AS STRING * 20
      UnitPrice AS SINGLE
      Quantity AS INTEGER
   END TYPE

   ' Define a record structure for each element of the index:
   TYPE IndexType
      RecordNumber AS INTEGER
      PartNumber AS STRING * 6
   END TYPE

   ' Declare procedures that will be called:
   DECLARE FUNCTION Filter$ (Prompt$)
   DECLARE FUNCTION FindRecord% (PartNumber$, RecordVar AS StockItem)

   DECLARE SUB AddRecord (RecordVar AS StockItem)
   DECLARE SUB InputRecord (RecordVar AS StockItem)
   DECLARE SUB PrintRecord (RecordVar AS StockItem)
   DECLARE SUB SortIndex ()
   DECLARE SUB ShowPartNumbers ()
   ' Define a buffer (using the StockItem type)
   ' and define and dimension the index array:
   DIM StockRecord AS StockItem, Index(1 TO 100) AS IndexType

   ' Open the random-access file:
   OPEN "STOCK.DAT" FOR RANDOM AS #1 LEN = LEN(StockRecord)

   ' Calculate number of records in the file:
   NumberOfRecords = LOF(1) \ LEN(StockRecord)

   ' If there are records, read them and build the index:
   IF NumberOfRecords <> 0 THEN
      FOR RecordNumber = 1 TO NumberOfRecords

         ' Read the data from a new record in the file:
         GET #1, RecordNumber, StockRecord

         ' Place part number and record number in index:
         Index(RecordNumber).RecordNumber = RecordNumber
         Index(RecordNumber).PartNumber = StockRecord.PartNumber
      NEXT

      SortIndex            ' Sort index in part-number order.
   END IF

   DO                      ' Main-menu loop.
      CLS
      PRINT "(A)dd records."
      PRINT "(L)ook up records."
      PRINT "(Q)uit program."
      PRINT
      LOCATE , , 1
      PRINT "Type your choice (A, L, or Q) here: ";

      ' Loop until user presses, A, L, or Q:
      DO
         Choice$ = UCASE$(INPUT$(1))
      LOOP WHILE INSTR("ALQ", Choice$) = 0

      ' Branch according to choice:
      SELECT CASE Choice$
         CASE "A"
        AddRecord StockRecord
         CASE "L"
        IF NumberOfRecords = 0 THEN
           PRINT : PRINT "No records in file yet. ";
           PRINT "Press any key to continue.";
           Pause$ = INPUT$(1)
        ELSE
           InputRecord StockRecord
        END IF
         CASE "Q"          ' End program.
      END SELECT
   LOOP UNTIL Choice$ = "Q"

   CLOSE #1                ' All done, close file and end.
   END

   ' ======================== ADDRECORD ======================
   ' Adds records to the file from input typed at the keyboard
   ' =========================================================

   SUB AddRecord (RecordVar AS StockItem) STATIC
      SHARED Index() AS IndexType, NumberOfRecords
      DO
         CLS
         INPUT "Part Number: ", RecordVar.PartNumber
         INPUT "Description: ", RecordVar.Description

         ' Call the Filter$ FUNCTION to input price & quantity:
         RecordVar.UnitPrice = VAL(Filter$("Unit Price : "))
         RecordVar.Quantity = VAL(Filter$("Quantity   : "))

         NumberOfRecords = NumberOfRecords + 1

         PUT #1, NumberOfRecords, RecordVar

         Index(NumberOfRecords).RecordNumber = NumberOfRecords
         Index(NumberOfRecords).PartNumber = RecordVar.PartNumber
         PRINT : PRINT "Add another? ";
         OK$ = UCASE$(INPUT$(1))
      LOOP WHILE OK$ = "Y"

      SortIndex            ' Sort index file again.
   END SUB

   ' ========================= FILTER ========================
   '       Filters all non-numeric characters from a string
   '       and returns the filtered string
   ' =========================================================

   FUNCTION Filter$ (Prompt$) STATIC
      ValTemp2$ = ""
      PRINT Prompt$;                    ' Print the prompt passed.
      INPUT "", ValTemp1$               ' Input a number as
                                        ' a string.
      StringLength = LEN(ValTemp1$)     ' Get the string's length.
      FOR I% = 1 TO StringLength        ' Go through the string,
         Char$ = MID$(ValTemp1$, I%, 1) ' one character at a time.

         ' Is the character a valid part of a number (i.e.,
         ' a digit or a decimal point)?  If yes, add it to
         ' the end of a new string:
         IF INSTR(".0123456789", Char$) > 0 THEN
            ValTemp2$ = ValTemp2$ + Char$

         ' Otherwise, check to see if it's a lowercase "l",
         ' since typewriter users may enter a one that way:
         ELSEIF Char$ = "l" THEN
            ValTemp2$ = ValTemp2$ + "1" ' Change the "l" to a "1".
         END IF
      NEXT I%

      Filter$ = ValTemp2$               ' Return filtered string.

   END FUNCTION

   ' ======================= FINDRECORD ===================
   '  Uses a binary search to locate a record in the index
   ' ======================================================

   FUNCTION FindRecord% (Part$, RecordVar AS StockItem) STATIC
      SHARED Index() AS IndexType, NumberOfRecords

      ' Set top and bottom bounds of search:
      TopRecord = NumberOfRecords
      BottomRecord = 1

      ' Search until top of range is less than bottom:
      DO UNTIL (TopRecord < BottomRecord)

         ' Choose midpoint:
         Midpoint = (TopRecord + BottomRecord) \ 2

         ' Test to see if it's the one wanted (RTRIM$()
         ' trims trailing blanks from a fixed string):
         Test$ = RTRIM$(Index(Midpoint).PartNumber)

         ' If it is, exit loop:
         IF Test$ = Part$ THEN
        EXIT DO

         ' Otherwise, if what we're looking for is greater,
         ' move bottom up:
         ELSEIF Part$ > Test$ THEN
        BottomRecord = Midpoint + 1

         ' Otherwise, move the top down:
         ELSE
        TopRecord = Midpoint - 1
         END IF
      LOOP

      ' If part was found, input record from file using
      ' pointer in index and set FindRecord% to TRUE:
      IF Test$ = Part$ THEN
         GET #1, Index(Midpoint).RecordNumber, RecordVar
         FindRecord% = TRUE

      ' Otherwise, if part was not found, set FindRecord%
      ' to FALSE:
      ELSE
         FindRecord% = FALSE
      END IF
   END FUNCTION

   ' ======================= INPUTRECORD =====================
   '    First, INPUTRECORD calls SHOWPARTNUMBERS, which prints
   '    a menu of part numbers on the top of the screen. Next,
   '    INPUTRECORD prompts the user to enter a part number.
   '    Finally, it calls the FINDRECORD and PRINTRECORD
   '    procedures to find and print the given record.
   ' =========================================================

   SUB InputRecord (RecordVar AS StockItem) STATIC
      CLS
      ShowPartNumbers      ' Call the ShowPartNumbers SUB.

      ' Print data from specified records
      ' on the bottom part of the screen:
      DO
         PRINT "Type a part number listed above ";
         INPUT "(or Q to quit) and press <ENTER>: ", Part$
         IF UCASE$(Part$) <> "Q" THEN
            IF FindRecord(Part$, RecordVar) THEN
               PrintRecord RecordVar
            ELSE
               PRINT "Part not found."
            END IF
         END IF
         PRINT STRING$(40, "_")
      LOOP WHILE UCASE$(Part$) <> "Q"

      VIEW PRINT   ' Restore the text viewport to entire screen.
   END SUB

   ' ======================= PRINTRECORD =====================
   '                Prints a record on the screen
   ' =========================================================

   SUB PrintRecord (RecordVar AS StockItem) STATIC
      PRINT "Part Number: "; RecordVar.PartNumber
      PRINT "Description: "; RecordVar.Description
      PRINT USING "Unit Price :$$###.##"; RecordVar.UnitPrice
      PRINT "Quantity   :"; RecordVar.Quantity
   END SUB

   ' ===================== SHOWPARTNUMBERS ===================
   ' Prints an index of all the part numbers in the upper part
   ' of the screen
   ' =========================================================

   SUB ShowPartNumbers STATIC
      SHARED Index() AS IndexType, NumberOfRecords

      CONST NUMCOLS = 8, COLWIDTH = 80 \ NUMCOLS

      ' At the top of the screen, print a menu indexing all
      ' the part numbers for records in the file. This menu is
      ' printed in columns of equal length (except possibly the
      ' last column, which may be shorter than the others):
      ColumnLength = NumberOfRecords
      DO WHILE ColumnLength MOD NUMCOLS
         ColumnLength = ColumnLength + 1
      LOOP
      ColumnLength = ColumnLength \ NUMCOLS
      Column = 1
      RecordNumber = 1

   DO UNTIL RecordNumber > NumberOfRecords
         FOR Row = 1 TO ColumnLength
            LOCATE Row, Column
            PRINT Index(RecordNumber).PartNumber
            RecordNumber = RecordNumber + 1
            IF RecordNumber > NumberOfRecords THEN EXIT FOR
         NEXT Row
         Column = Column + COLWIDTH
      LOOP

      LOCATE ColumnLength + 1, 1
      PRINT STRING$(80, "_")       ' Print separator line.

      ' Scroll information about records below the part-number
      ' menu (this way, the part numbers are not erased):
      VIEW PRINT ColumnLength + 2 TO 24
   END SUB

   ' ========================= SORTINDEX =====================
   '                Sorts the index by part number
   ' =========================================================

   SUB SortIndex STATIC


      SHARED Index() AS IndexType, NumberOfRecords

      ' Set comparison offset to half the number of records
      ' in index:
      Offset = NumberOfRecords \ 2

      ' Loop until offset gets to zero:
      DO WHILE Offset > 0
         Limit = NumberOfRecords - Offset
         DO

            ' Assume no switches at this offset:
            Switch = FALSE

            ' Compare elements and switch ones out of order:
            FOR I = 1 TO Limit
               IF Index(I).PartNumber > Index(I + Offset).PartNumber THEN
                  SWAP Index(I), Index(I + Offset)
                  Switch = I
               END IF
            NEXT I

            ' Sort on next pass only to where
            ' last switch was made:
            Limit = Switch
         LOOP WHILE Switch

         ' No switches at last offset, try one half as big:
         Offset = Offset \ 2
      LOOP
   END SUB

   Output

   ┌────────────────────────────────────────────────────────────────────────┐
   │                                                                        │
   │ 0235         0417       0583        8721                               │
   │                                                                        │
   │ ────────────────────────────────────────────────────────────────────── │
   │ Type a part number listed above <or Q to quit> and press <ENTER>: 0417 │
   │ Part Number: 0417                                                      │
   │ Description: oil filter                                                │
   │ Unit Price :   $5.99                                                   │
   │ Quantity   : 12                                                        │
   │                                                                        │
   │ ────────────────────────────────────────                               │
   │ Type a part number listed above <or Q to quit> and press <ENTER>: 8721 │
   │ Part Number: 8721                                                      │
   │ Description: chamois cloth                                             │
   │ Unit Price :   $8.99                                                   │
   │ Quantity   : 23                                                        │
   │                                                                        │
   │ ────────────────────────────────────────                               │
   │ Type a part number listed above <or Q to quit> and press <ENTER>:      │
   │                                                                        │
   └────────────────────────────────────────────────────────────────────────┘

 3.6.3  Terminal Emulator (TERMINAL.BAS)

   The following simple program turns your computer into a "dumb" terminal;
   that is, it makes your computer function solely as an I/O device in tandem
   with a modem. This program uses the OPEN "COM1:" statement and associated
   device I/O functions to do the following two things:

   1. Send the characters you type to the modem

   2. Print characters returned by the modem on the screen

   Note that typed characters displayed on the screen are first sent to the
   modem and then returned to your computer through the open communications
   channel. You can verify this if you have a modem with Receive Detect (RD)
   and Send Detect (SD) lights──they will flash in sequence as you type.

   To dial a number, you would have to enter the Attention Dial Touch-Tone
   (ATDT) or Attention Dial Pulse (ATDP) commands at the keyboard (assuming
   you have a Hayes(R)-compatible modem).

   Any other commands sent to the modem would also have to be entered at the
   keyboard.

   Statements and Functions Used

   This program demonstrates the following functions and statements used in
   communicating with a modem through your computer's serial port:

   ■ OPEN "COM1:"

   ■ EOF

   ■ INPUT$

   ■ LOC

   Program Listing

   DEFINT A-Z

   DECLARE SUB Filter (InString$)

   COLOR 7, 1                    ' Set screen color.
   CLS

   Quit$ = CHR$(0) + CHR$(16)    ' Value returned by INKEY$
                                 ' when ALT+q is pressed.

   ' Set up prompt on bottom line of screen and turn cursor on:
   LOCATE 24, 1, 1
   PRINT STRING$(80, "_");
   LOCATE 25, 1
   PRINT TAB(30); "Press ALT+q to quit";

   VIEW PRINT 1 TO    23           ' Print between lines 1 & 23.

   ' Open communications (1200 baud, no parity, 8-bit data,
   ' 1 stop bit, 256-byte input buffer):
   OPEN "COM1:1200,N,8,1" FOR RANDOM AS #1    LEN = 256

   DO                              ' Main communications loop.

      KeyInput$ = INKEY$           ' Check the keyboard.

      IF KeyInput$ = Quit$ THEN    ' Exit the loop if the user
         EXIT DO                   ' pressed ALT+q.

      ELSEIF KeyInput$ <> "" THEN  ' Otherwise, if the user has
         PRINT #1, KeyInput$;      ' pressed a key, send the
      END IF                       ' character typed to modem.

      ' Check the modem. If characters are waiting (EOF(1) is
      ' true), get them and print them to the screen:
      IF NOT EOF(1) THEN

         ' LOC(1) gives the number of characters waiting:
         ModemInput$ = INPUT$(LOC(1), #1)

         Filter ModemInput$        ' Filter out line feeds and
         PRINT ModemInput$;        ' backspaces, then print.
      END IF
   LOOP

   CLOSE                           ' End communications.
   CLS
   END

   '
   ' ========================= FILTER ========================
   '               Filters characters in an input string
   ' =========================================================
   '
   SUB Filter (InString$) STATIC

      ' Look for backspace characters and recode
      ' them to CHR$(29) (the LEFT cursor key):
      DO
         BackSpace = INSTR(InString$, CHR$(8))
         IF BackSpace THEN
         MID$(InString$, BackSpace) = CHR$(29)
         END IF
      LOOP WHILE BackSpace

      ' Look for line-feed characters and
      ' remove any found:
      DO
         LnFd = INSTR(InString$, CHR$(10))
         IF LnFd THEN
      InString$=LEFT$(InString$,LnFd-1)+MID$(InString$,LnFd+1)
         END IF
      LOOP WHILE LnFd

   END SUB



 ────────────────────────────────────────────────────────────────────────────
 Chapter 4  String Processing

   This chapter shows you how to manipulate sequences of ASCII characters,
   known as strings. String manipulation is indispensable when you are
   processing text files, sorting data, or modifying string-data input.

   When you are finished with this chapter, you will know how to perform the
   following string-processing tasks:

   ■ Declare fixed-length strings

   ■ Compare strings and sort them alphabetically

   ■ Search for one string inside another

   ■ Get part of a string

   ■ Trim spaces from the beginning or end of a string

   ■ Generate a string by repeating a single character

   ■ Change uppercase letters in a string to lowercase and vice versa

   ■ Convert numeric expressions to string representations and vice versa


 4.1  Strings Defined

   A string is a sequence of contiguous characters. Examples of characters
   are the letters of the alphabet (a-z and A-Z), punctuation symbols such as
   commas (,) or question marks (?), and other symbols from the fields of
   math and finance such as plus (+) or percent (%) signs.

   In this chapter, the term "string" can refer to any of the following:

   ■ A string constant

   ■ A string variable

   ■ A string expression

   String constants are declared in one of two ways:

   1. By enclosing a sequence of characters between double quotes, as in the
      following PRINT statement:

      PRINT "Processing the file. Please wait."

      This is known as a "literal string constant."

   2. By setting a name equal to a literal string in a CONST statement, as in
      the following:

      ' Define the string constant MESSAGE:
      CONST MESSAGE = "Drive door open."

      This is known as a "symbolic string constant."

   String variables can be declared in one of three ways:

   1. By appending the string-type suffix ($) to the variable name:

      LINE INPUT "Enter your name: "; Buffer$

   2. By using the DEFSTR statement:

      ' All variables beginning with the letter "B"
      ' are strings, unless they end with one of the
      ' numeric-type suffixes (%, &, !, or #):
      DEFSTR B
      .
      .
      .
      Buffer = "Your name here"  ' Buffer is a string variable

   3. By declaring the string name in an AS STRING statement:

      DIM Buffer1 AS STRING      ' Buffer1 is a variable-
                                 ' length string.
      DIM Buffer2 AS STRING*10   ' Buffer2 is a fixed-length
                                 ' string 10 bytes long.

   A string expression is a combination of string variables, constants,
   and/or string functions.

   Of course, the character components of strings are not stored in your
   computer's memory in a form generally recognizable to humans. Instead,
   each character is translated to a number known as the ASCII code for that
   character. For example, capital "A" is stored as decimal 65 (or
   hexadecimal 41H), while lowercase "a" is stored as decimal 97 (or
   hexadecimal 61H). See Appendix D, "Keyboard Scan Codes and ASCII
   Character Codes," for a complete list of the ASCII codes for each
   character.

   You can also use the BASIC ASC function to determine the ASCII code for a
   character; for example, ASC("A") returns the value 65. The inverse of the
   ASC function is the CHR$ function. CHR$ takes an ASCII code as its
   argument and returns the character with that code; for example, the
   statement PRINT CHR$(64) displays the character @.


 4.2  Variable- and Fixed-Length Strings

   In previous versions of BASIC, strings were always variable length. BASIC
   now supports both variable-length strings and fixed-length strings.

 4.2.1  Variable-Length Strings

   Variable-length strings are "elastic"; that is, they expand and contract
   to store different numbers of characters (from none to a maximum of
   32,767). For example, the length of the variable Temp$ in the following
   example varies according to the size of what is stored in Temp$:

   Temp$ = "1234567"

   ' LEN function returns length of string
   '  (number of characters it contains):



   PRINT LEN(Temp$)

   Temp$ = "1234"
   PRINT LEN(Temp$)

   Output

    7
    4

 4.2.2  Fixed-Length Strings

   Fixed-length strings are commonly used as record elements in a TYPE...END
   TYPE user-defined data type. However, they can also be declared by
   themselves in COMMON, DIM, REDIM, SHARED, or STATIC statements, as in the
   following statement:

   DIM Buffer AS STRING * 10

   As their name implies, fixed-length strings have a constant length,
   regardless of the length of the string stored in them. This is shown by
   the output from the following example:

   DIM LastName AS STRING * 12
   DIM FirstName AS STRING * 10

   LastName = "Huntington-Ashley"
   FirstName = "Claire"

   PRINT "123456789012345678901234567890"
   PRINT FirstName; LastName
   PRINT LEN(FirstName)
   PRINT LEN(LastName)

   Output

   123456789012345678901234567890
   Claire    Huntington-A
    10
    12

   Note that the lengths of the string variables FirstName and LastName did
   not change, as demonstrated by the values returned by the LEN function (as
   well as the four spaces following the six-letter name, Claire).

   The output from the above example also illustrates how values assigned to
   fixed-length variables are left-justified and, if necessary, truncated on
   the right. It is not necessary to use the LSET function to left-justify
   values in fixed-length strings; this is done automatically. If you want to
   right-justify a string inside a fixed-length string, use RSET, as shown
   here:

   DIM NameBuffer AS STRING * 10
   RSET NameBuffer = "Claire"
   PRINT "1234567890"
   PRINT NameBuffer

   Output

   1234567890
       Claire


 4.3  Combining Strings

   Two strings can be combined with the plus (+) operator. The string
   following the plus operator is appended to the string preceding the plus
   operator, as shown in the next example:

   A$ = "first string"
   B$ = "second string"
   C$ = A$ + B$
   PRINT C$

   Output

   first stringsecond string

   The process of combining strings in this way is called "concatenation,"
   which means linking together.

   Note that in the previous example, the two strings are combined without
   any intervening spaces. If you want a space in the combined string, you
   could pad one of the strings A$ or B$, like this:

   B$ = " second string"          ' Leading blank in B$

   Because values are left-justified in fixed-length strings, you may find
   extra spaces when you concatenate them, as in this example:

   TYPE NameType
      First AS STRING * 10
      Last  AS STRING * 12
   END TYPE

   DIM NameRecord AS NameType

   ' The constant "Ed" is left-justified in the variable
   ' NameRecord.First, so there are eight trailing blanks:
   NameRecord.First = "Ed"
   NameRecord.Last  = "Feldstein"

   ' Print a line of numbers for reference:
   PRINT "123456789012345678901234567890"

   WholeName$ = NameRecord.First + NameRecord.Last
   PRINT WholeName$

   Output

   123456789012345678901234567890
   Ed        Feldstein

   The LTRIM$ function returns a string with its leading spaces stripped
   away, while the RTRIM$ function returns a string with its trailing spaces
   stripped away. The original string is unaltered. (See Section 4.6,
   "Retrieving Parts of Strings," for more information on these functions.)


 4.4  Comparing Strings

   Strings are compared with the following relational operators:

   Operator                 Meaning
   ──────────────────────────────────────────────────────────────────────────
   < >                      Not equal

   =                        Equal

   <                        Less than

   >                        Greater than

   <=                       Less than or equal to

   >=                       Greater than or equal to
   ──────────────────────────────────────────────────────────────────────────

   A single character is greater than another character if its ASCII value is
   greater. For example, the ASCII value of the letter "B" is greater than
   the ASCII value of the letter "A," so the expression "B" > "A"is true.

   When comparing two strings, BASIC looks at the ASCII values of
   corresponding characters. The first character where the two strings differ
   determines the alphabetical order of the strings. For instance, the
   strings "doorman" and "doormats" are the same up to the seventh character
   in each ("n" and "t"). Since the ASCII value of "n" is less than the ASCII
   value of "t", the expression "doorman" < "doormats"is true. Note that the
   ASCII values for letters follow alphabetical order from A to Z and from a
   to z, so you can use the relational operators listed above to alphabetize
   strings. Moreover, uppercase letters have smaller ASCII values than
   lowercase letters, so in a sorted list of strings, "ASCII" would come
   before "ascii".

   If there is no difference between corresponding characters of two strings
   and they are the same length, then the two strings are equal. If there is
   no difference between corresponding characters of two strings, but one of
   the strings is longer, then the longer string is greater than the shorter
   string. For example "abc" = "abc" and "aaaaaaa" > "aaa" are both true
   expressions.

   Leading and trailing blank spaces are significant in string comparisons.
   For example, the string " test" is less than the string "test", since a
   blank space (" ") is less than a"t"; on the other hand, the string "test "
   is greater than the string "test". Keep this in mind when comparing
   fixed-length and variable-length strings, since fixed-length strings may
   contain trailing spaces.


 4.5  Searching for Strings

   One of the most common string-processing tasks is searching for a string
   inside another string. The INSTR(string1, string2) function tells you
   whether or not string2 is contained in string1 by returning the position
   of the first character in string1 (if any) where the match begins, as
   shown in this next example:

   String1$ = "A line of text with 37 letters in it."
   String2$ = "letters"

   PRINT "         1         2         3         4"
   PRINT "1234567890123456789012345678901234567890"
   PRINT String1$
   PRINT String2$
   PRINT INSTR(String1$, String2$)

   Output

   1         2         3         4
   1234567890123456789012345678901234567890
   A line of text with 37 letters in it.
   letters
    24

   If no match is found (that is, string2 is not a substring of string1),
   INSTR returns the value 0.

   A variation of the syntax shown above, INSTR(position, string1, string2),
   allows you to specify where you want the search to start in string1. To
   illustrate, making the following modification to the preceding example
   changes the output:

   ' Start looking for a match at the 30th
   ' character of String1$:
   PRINT INSTR(30, String1$, String2$)

   Output

   1         2         3         4
   1234567890123456789012345678901234567890
   A line of text with 37 letters in it.
   letters
    0

   In other words, the string "letters" does not appear after the 30th
   character of String1$.

   The INSTR(position, string1, string2) variation is useful for finding
   every occurrence of string2 in string1 instead of just the first
   occurrence, as shown in the next example:

   String1$ = "the dog jumped over the broken saxophone."
   String2$ = "the"
   PRINT String1$

   Start      = 1
   NumMatches = 0

   DO
      Match = INSTR(Start, String1$, String2$)
      IF Match > 0 THEN
         PRINT TAB(Match); String2$
         Start      = Match + 1
         NumMatches = NumMatches + 1
      END IF
   LOOP WHILE MATCH

   PRINT "Number of matches ="; NumMatches

   Output

   the dog jumped over the broken saxophone.
   the
                                     the
   Number of matches = 2


 4.6  Retrieving Parts of Strings

   Section 4.3, "Combining Strings," shows how to put strings together
   (concatenate them) by using the + operator. Several functions are
   available in BASIC that take strings apart, returning pieces of a string,
   either from the left side, the right side, or the middle of a target
   string.

 4.6.1  Retrieving Characters from the Left Side of a String

   The LEFT$ and RTRIM$ functions return characters from the left side of a
   string. The LEFT$(string, number) function returns the specified number of
   characters from the left side of the string. For example:

   Test$ = "Overtly"

   ' Print the leftmost 4 characters from Test$:
   PRINT LEFT$(Test$, 4)

   Output

   Over

   Note that LEFT$, like the other functions described in this chapter, does
   not change the original string Test$; it merely returns a different
   string, a copy of part of Test$.

   The RTRIM$ function returns the left part of a string after removing any
   blank spaces at the end. For example, contrast the output from the two
   PRINT statements in the following example:

   PRINT "a left-justified string      "; "next"
   PRINT RTRIM$("a left-justified string      "); "next"

   Output

   a left-justified string      next
   a left-justified stringnext

   The RTRIM$ function is useful for comparing fixed-length and
   variable-length strings, as in the next example:

   DIM NameRecord AS STRING * 10
   NameRecord = "Ed"

   NameTest$ = "Ed"

   ' Use RTRIM$ to trim all the blank spaces from the right
   ' side of the fixed-length string NameRecord, then compare
   ' it with the variable-length string NameTest$:
   IF RTRIM$(NameRecord) = NameTest$ THEN
      PRINT "They're equal"
   ELSE
      PRINT "They're not equal"
   END IF

   Output

   They're equal

 4.6.2  Retrieving Characters from the Right Side of a String

   The RIGHT$ and LTRIM$ functions return characters from the right side of a
   string. The RIGHT$(string, number) function returns the specified number
   of characters from the right side of the string. For example:

   Test$ = "1234567890"

   ' Print the rightmost 5 characters from Test$:
   PRINT RIGHT$(Test$,5)

   Output

   67890

   The LTRIM$ function returns the right part of a string after removing any
   blank spaces at the beginning. For example, contrast the output from the
   next two PRINT statements:

   PRINT "first"; "      a right-justified string"
   PRINT "first"; LTRIM$("      a right-justified string")

   Output

   first      a right-justified string
   firsta right-justified string

 4.6.3  Retrieving Characters from Anywhere in a String

   Use the MID$ function to retrieve any number of characters from any point
   in a string. The MID$(string, start, number) function returns the
   specified number of characters from the string, starting at the character
   with position start. For example, the statement

   MID$("**over the hill**", 12, 4)

   starts at the twelfth character (or h) of the string

   **over the hill**

   and returns that character plus the next three characters (hill).

   The following example shows how to use the MID$ function to step through a
   line of text character by character:

   .
   .
   .
   ' Get the number of characters in the string of text:
   Length = LEN(TextString$)

   FOR I = 1 TO Length

     ' Get the first character, then the second, third,
     ' and so forth, up to the end of the string:
     Char$ = MID$(TextString$, I, 1)

     ' Evaluate that character:
     .
     .
     .
   NEXT


 4.7  Generating Strings

   The easiest way to create a string of one character repeated over and over
   is to use the intrinsic function STRING$. The STRING$(number, string)
   function produces a new string the specified number of characters long,
   each character of which is the first character of the string argument. For
   example, the statement

   Filler$ = STRING$(27, "*")

   generates a string of 27 asterisks. For characters that cannot be produced
   by typing, such as characters whose ASCII values are greater than 127, use
   the alternative form of this function, STRING$(number, code). This form
   creates a string the specified number of characters long, each character
   of which has the ASCII code specified by the code argument, as in the next
   example:

   ' Print a string of 10 "@" characters
   ' (64 is ASCII code for @):
   PRINT STRING$(10, 64)

   Output

   @@@@@@@@@@@

   The SPACE$(number) function generates a string consisting of the specified
   number of blank spaces.


 4.8  Changing the Case of Letters

   You may want to convert uppercase (capital) letters in a string to
   lowercase or vice versa. This conversion would be useful in a
   case-insensitive search for a particular string pattern in a large file
   (in other words, help, HELP, or Help would all be considered the same).
   These functions would also be handy when you are not sure whether a user
   will input text in capital or lowercase letters.

   The UCASE$ and LCASE$ functions make the following conversions to a
   string:

   ■ UCASE$ returns a copy of the string passed to it, with all the lowercase
     letters converted to uppercase.

   ■ LCASE$ returns a copy of the string passed to it, with all the uppercase
     letters converted to lowercase.

   Example

   Sample$ = "* The ASCII Appendix: a table
   of useful codes *"
   PRINT Sample$
   PRINT UCASE$(Sample$)
   PRINT LCASE$(Sample$)

   Output

   * The ASCII Appendix: a table of useful codes *
   * THE ASCII APPENDIX: A TABLE OF USEFUL CODES *
   * the ascii appendix: a table of useful codes *

   Letters that are already uppercase, as well as characters that are not
   letters, remain unchanged by UCASE$; similarly, lowercase letters and
   characters that are not letters are unaffected by LCASE$.


 4.9  Strings and Numbers

   BASIC does not allow a string to be assigned to a numeric variable, nor
   does it allow a numeric expression to be assigned to a string variable.
   For example, both of these statements result in an error message reading
   Type mismatch:

   TempBuffer$ = 45
   Counter% = "45"

   Instead, use the STR$ function to return the string representation of a
   number or the VAL function to return the numeric representation of a
   string:

   ' The following statements are both valid:
   TempBuffer$ = STR$(45)
   Counter%  = VAL("45")

   Note that STR$ includes the leading blank space that BASIC prints for
   positive numbers, as this short example shows:

   FOR I = 0 TO 9
      PRINT STR$(I);
   NEXT

   Output

   0 1 2 3 4 5 6 7 8 9

   If you want to eliminate this space, you can use the LTRIM$ function, as
   shown in the example below:

   FOR I = 0 TO 9
      PRINT LTRIM$(STR$(I));
   NEXT

   Output

   0123456789

   Another way to format numeric output is with the PRINT USING statement
   (see Section 3.1, "Printing Text on the Screen").


 4.10  Changing Strings

   The functions mentioned in each of the preceding sections all leave their
   string arguments unchanged. Changes are made to a copy of the argument.

   In contrast, the MID$ statement (unlike the MID$ function discussed in
   Section 4.6.3, "Retrieving Characters from Anywhere in a String") changes
   its argument by embedding another string in it. The embedded string
   replaces part or all of the original string, as shown in the following
   example:

   Temp$ = "In the sun."
   PRINT Temp$

   ' Replace the "I" with an "O":
   MID$(Temp$,1) = "O"

   ' Replace "sun." with "road":
   MID$(Temp$,8) = "road"
   PRINT Temp$

   Output

   In the sun.
   On the road


 4.11  Sample Application: Converting a String to a Number (STRTONUM.BAS)

   The following program takes a number that is input as a string, filters
   any numeric characters (such as commas) out of the string, then converts
   the string to a number with the VAL function.

   Statements and Functions Used

   This program demonstrates the following string-handling functions
   discussed in this chapter:

   ■ INSTR

   ■ LEN

   ■ MID$

   ■ VAL

   Program Listing

   DECLARE FUNCTION Filter$ (Txt$, FilterString$)

   ' Input a line:
   LINE INPUT "Enter a number with commas: ", A$

   ' Look only for valid numeric characters (0123456789.-)
   ' in the input string:
   CleanNum$ = Filter$(A$, "0123456789.-")

   ' Convert the string to a number:
   PRINT "The number's value = " VAL(CleanNum$)
   END

   ' ========================== FILTER =======================
   '         Takes unwanted characters out of a string by
   '         comparing them with a filter string containing
   '         only acceptable numeric characters
   ' =========================================================

   FUNCTION Filter$ (Txt$, FilterString$) STATIC
      Temp$ = ""
      TxtLength = LEN(Txt$)

      FOR I = 1 TO TxtLength     ' Isolate each character in
         C$ = MID$(Txt$, I, 1)   ' the string.

         ' If the character is in the filter string, save it:
         IF INSTR(FilterString$, C$) <> 0 THEN
            Temp$ = Temp$ + C$
         END IF
      NEXT I

      Filter$ = Temp$
   END FUNCTION



 ────────────────────────────────────────────────────────────────────────────
 Chapter 5  Graphics

   This chapter shows you how to use the graphics statements and functions of
   BASIC to create a wide variety of shapes, colors, and patterns on your
   screen. With graphics, you can add a visual dimension to almost any
   program, whether it's a game, an educational tool, a scientific
   application, or a financial package.

   When you have finished studying this chapter, you will know how to perform
   the following graphics tasks:

   ■ Use the physical-coordinate system of your personal computer's screen to
     locate individual pixels, turn those pixels on or off, and change their
     colors

   ■ Draw lines

   ■ Draw and fill simple shapes, such as circles, ovals, and boxes

   ■ Restrict the area of the screen showing graphics output by using
     viewports

   ■ Adjust the coordinates used to locate a pixel by redefining screen
     coordinates

   ■ Use color in graphics output

   ■ Create patterns and use them to fill enclosed figures

   ■ Copy images and reproduce them in another location on the screen

   ■ Animate graphics output

   Section 5.1 below contains important information on what you'll need to
   run the graphics examples shown in this chapter. Read it first.


 5.1  What You Need for Graphics Programs

   To run the graphics examples shown in this chapter, your computer must
   have graphics capability, either built in or in the form of a graphics
   card such as the Color Graphics Adapter (CGA), Enhanced Graphics Adapter
   (EGA), or Video Graphics Array (VGA). You also need a video display
   (either monochrome or color) that supports pixel-based graphics.

   Also, please keep in mind that these programs all require that your screen
   be in one of the "screen modes" supporting graphics output. (The screen
   mode controls the clarity of graphics images, the number of colors
   available, and the part of the video memory to display.) To select a
   graphics output mode, use the following statement in your program before
   using any of the graphics statements or functions described in this
   chapter:

   SCREEN mode

   Here, mode can be either 1, 2, 3, 4, 7, 8, 9, 10, 11, 12, or 13, depending
   on the monitor/adapter combination installed on your computer.

   If you are not sure whether or not the users of your programs have
   hardware that supports graphics, you can use the following simple test:

   CONST FALSE = 0, TRUE = NOT FALSE

   ' Test to make sure user has hardware
   ' with color/graphics capability:
   ON ERROR GOTO Message      ' Turn on error trapping.
   SCREEN 1                   ' Try graphics mode one.
   ON ERROR GOTO 0            ' Turn off error trapping.
   IF NoGraphics THEN END     ' End if no graphics hardware.
   .
   .
   .
   END

   ' Error-handling routine:
   Message:
      PRINT "This program requires graphics capability."
      NoGraphics = TRUE
      RESUME NEXT

   If the user has only a monochrome display with no graphics adapter, the
   SCREEN statement produces an error that in turn triggers a branch to the
   error-handling routine Message. (See Chapter 6, "Error and Event
   Trapping," for more information on error trapping.)


 5.2  Pixels and Screen Coordinates

   Shapes and figures on a video display are composed of individual dots of
   light known as picture elements or "pixels" (or sometimes as "pels") for
   short. BASIC draws and paints on the screen by turning these pixels on or
   off and by changing their colors.

   A typical screen is composed of a grid of pixels. The exact number of
   pixels in this grid depends on the hardware you have installed and the
   screen mode you have selected in the SCREEN statement. The larger the
   number of pixels, the higher the clarity of graphics output. For example,
   a SCREEN 1 statement gives a resolution of 320 pixels horizontally by 200
   pixels vertically (320 x 200 pixels), while a SCREEN 2 statement gives a
   resolution of 640 x 200 pixels. The higher horizontal density in screen
   mode 2──640 pixels per row versus 320 pixels per row──gives images a
   sharper, less ragged appearance than they have in screen mode 1.

   Depending on the graphics capability of your system, you can use other
   screen modes that support even higher resolutions (as well as adjust other
   screen characteristics). Consult the QB Advisor for more information.

   When your screen is in one of the graphics modes, you can locate each
   pixel by means of pairs of coordinates. The first number in each
   coordinate pair tells the number of pixels from the left side of the
   screen, while the second number in each pair tells the number of pixels
   from the top of the screen. For example, in screen mode 2 the point in the
   extreme upper-left corner of the screen has coordinates (0, 0), the point
   in the center of the screen has coordinates (320, 100), and the point in
   the extreme lower-right corner of the screen has coordinates (639, 199),
   as shown in Figure 5.1.

   BASIC uses these screen coordinates to determine where to display graphics
   (for example, to locate the end points of a line or the center of a
   circle), as shown in Section 5.3, "Drawing Basic Shapes."

   Graphics coordinates differ from text-mode coordinates specified in a
   LOCATE statement. First, LOCATE is not as precise: graphics coordinates
   pinpoint individual pixels on the screen, whereas coordinates used by
   LOCATE are character positions. Second, text-mode coordinates are given in
   the form "row, column," as in the following:

   ' Move to the 13th row, 15th column,
   ' then print the message shown:
   LOCATE 13, 15
   PRINT "This should appear in the middle of the screen."

   This is the reverse of graphics coordinates, which are given in the form
   "column, row." A LOCATE statement has no effect on the positioning of
   graphics output on the screen.


   ┌──────────────────────────────────────────────────────────────────┐
   │                              x positive                          │
   │              ────────────────────────────────────────────       │
   │            ┌──────────────────────────────────────────────────┐  │
   │          │ │°(0,0)                °(320,0)            (639,0)°│  │
   │          │ │                                                  │  │
   │          │ │                                                  │  │
   │          │ │                                                  │  │
   │          │ │                                                  │  │
   │   y      │ │                      °(320,100)                  │  │
   │ positive │ │                                                  │  │
   │          │ │                                                  │  │
   │          │ │                                                  │  │
   │          │ │                                                  │  │
   │          │ │                                                  │  │
   │           │°(0,199)              °(320,199)        (639,199)°│  │
   │            └──────────────────────────────────────────────────┘  │
   └──────────────────────────────────────────────────────────────────┘

   Figure 5.1  Coordinates of Selected Pixels in Screen Mode 2


 5.3  Drawing Basic Shapes: Points, Lines, Boxes, and Circles

   You can pass coordinate values to BASIC graphics statements to produce a
   variety of simple figures, as shown in Sections 5.3.1-5.3.2.

 5.3.1  Plotting Points with PSET and PRESET

   The most fundamental level of control over graphics output is simply
   turning individual pixels on and off. You do this in BASIC with the PSET
   (for pixel set) and PRESET (for pixel reset) statements. The statement
   PSET (x, y) gives the pixel at location (x, y) the current foreground
   color. The PRESET (x, y) statement gives the pixel at location (x, y) the
   current background color.

   On monochrome monitors, the foreground color is the color that is used for
   printed text and is typically white, amber, or light green; the background
   color on monochrome monitors is typically black or dark green. You can
   choose another color for PSET and PRESET to use by adding an optional
   color argument. The syntax is then:

   PSET (x, y), color

   or

   PRESET (x, y), color

   See Section 5.7 for more information on choosing colors.

   Because PSET uses the current foreground color by default and PRESET uses
   the current background color by default, PRESET without a color argument
   erases a point drawn with PSET, as shown in the next example:

   SCREEN 2          ' 640 x 200 resolution
   PRINT "Press any key to end."

   DO

      ' Draw a horizontal line from the left to the right:
      FOR X = 0 TO 640
         PSET (X, 100)
      NEXT

      ' Erase the line from the right to the left:
      FOR X = 640 TO 0 STEP -1
         PRESET (X, 100)
      NEXT

   LOOP UNTIL INKEY$ <> ""
   END

   While it is possible to draw any figure using only PSET statements to
   manipulate individual pixels, the output tends to be rather slow, since
   most pictures consist of many pixels. BASIC has several statements that
   dramatically increase the speed with which simple figures──such as lines,
   boxes, and ellipses──are drawn, as shown in Sections 5.3.2 and
   5.4.1-5.4.4.

 5.3.2  Drawing Lines and Boxes with LINE

   When using PSET or PRESET, you specify only one coordinate pair since you
   are dealing with only one point on the screen. With LINE, you specify two
   pairs, one for each end of a line segment. The simplest form of the LINE
   statement is as follows:

   LINE (x1, y1) - (x2, y2)

   where (x1, y1) are the coordinates of one end of a line segment and (x2,
   y2) are the coordinates of the other. For example, the following statement
   draws a straight line from the pixel with coordinates (10, 10) to the
   pixel with coordinates (150, 200):

   SCREEN 1
   LINE (10, 10)-(150, 200)

   Note that BASIC does not care about the order of the coordinate pairs: a
   line from (x1, y1) to (x2, y2) is the same as a line from (x2, y2) to (x1,
   y1). This means you could also write the preceding statement as:

   SCREEN 1
   LINE (150, 200)-(10, 10)

   However, reversing the order of the coordinates could have an effect on
   graphics statements that follow, as shown in the next section.

   5.3.2.1  Using the STEP Option

   Up to this point, screen coordinates have been presented as absolute
   values measuring the horizontal and vertical distances from the extreme
   upper-left corner of the screen, which has coordinates (0, 0). However, by
   using the STEP option in any of the following graphics statements, you can
   make the coordinates that follow STEP relative to the last point
   referenced on the screen:

   CIRCLE
   GET
   LINE
   PAINT
   PRESET
   PSET
   PUT

   If you picture images as being drawn on the screen by a tiny paintbrush
   exactly the size of one pixel, then the last point referenced is the
   location of this paintbrush, or "graphics cursor," when it finishes
   drawing an image. For example, the following statements leave the graphics
   cursor at the pixel with coordinates (100, 150):

   SCREEN 2
   LINE (10, 10)-(100, 150)

   If the next graphics statement in the program is

   PSET STEP(20, 20)

   then the point plotted by PSET is not in the upper-left quadrant of the
   screen. Instead, the STEP option has made the coordinates (20, 20)
   relative to the last point referenced, which has coordinates (100, 150).
   This makes the absolute coordinates of the point (100 + 20, 150 + 20) or
   (120, 170).

   In the last example, the last point referenced is determined by a
   preceding graphics statement. You can also establish a reference point
   within the same statement, as shown in the next example:

   ' Set 640 x 200 pixel resolution, and make the last
   ' point referenced the center of the screen:
   SCREEN 2

   ' Draw a line from the lower-left corner of the screen
   ' to the upper-left corner:
   LINE STEP(-310, 100) -STEP(0, -200)

   ' Draw the "stair steps" down from the upper-left corner
   ' to the right side of the screen:
   FOR I% = 1 TO 20
      LINE -STEP(30, 0)     ' Draw the horizontal line.
      LINE -STEP(0, 5)      ' Draw the vertical line.
   NEXT

   ' Draw the unconnected vertical line segments from the
   ' right side to the lower-left corner:
   FOR I% = 1 TO 20
      LINE STEP(-30, 0) -STEP(0, 5)
   NEXT

   DO: LOOP WHILE INKEY$ = ""       ' Wait for a keystroke.

   Output

   ┌──────────────────────────────────────────────────────────────────┐
   │ ┌─┐                                                              │
   │ │ └──────┐                                                       │
   │ │        └──────┐                                                │
   │ │               └──────┐                                         │
   │ │                      └──────┐                                  │
   │ │                             └──────┐                           │
   │ │                                    └──────┐                    │
   │ │                                           └──────┐             │
   │ │                                                  └──────┐      │
   │ │                                                                │
   │ │                                                  │             │
   │ │                                           │                    │
   │ │                                    │                           │
   │ │                             │                                  │
   │ │                      │                                         │
   │ │               │                                                │
   │ │        │                                                       │
   │ │ │                                                              │
   └──────────────────────────────────────────────────────────────────┘

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Note the empty DO loop at the end of the last program. If you are
     running a compiled, stand-alone BASIC program that produces graphics
     output, your program needs some mechanism like this at the end to hold
     the output on the screen. Otherwise, it vanishes from the screen before
     the user has time to notice it.
   ──────────────────────────────────────────────────────────────────────────

   5.3.2.2  Drawing Boxes

   Using the forms of the LINE statement already presented, it is quite easy
   to write a short program that connects four straight lines to form a box,
   as shown here:

   SCREEN 1        ' 320 x 200 pixel resolution

   ' Draw a box measuring 120 pixels on a side:
   LINE (50, 50)-(170, 50)
   LINE -STEP(0, 120)
   LINE -STEP(-120, 0)
   LINE -STEP(0, -120)

   However, BASIC provides an even simpler way to draw a box, using a single
   LINE statement with the B (for box) option. The B option is shown in the
   next example, which produces the same output as the four LINE statements
   in the preceding program:

   SCREEN 1        ' 320 x 200 pixel resolution

   ' Draw a box with coordinates (50, 50) for the upper-left
   ' corner, and (170, 170) for the lower-right corner:
   LINE (50, 50)-(170, 170), , B

   When you add the B option, the LINE statement no longer connects the two
   points you specify with a straight line; instead, it draws a rectangle
   whose opposite corners (upper left and lower right) are at the locations
   specified.

   Two commas precede the B in the last example. The first comma functions
   here as a placeholder for an unused option (the color argument), which
   allows you to pick the color for a line or the sides of a box. (See
   Section 5.7 for more information on the use of color.)

   As before, it does not matter what order the coordinate pairs are given
   in, so the rectangle from the last example could also be drawn with this
   statement:

   LINE (170, 170)-(50, 50), , B

   Adding the F (for fill) option after B fills the interior of the box with
   the same color used to draw the sides. With a monochrome display, this is
   the same as the foreground color used for printed text. If your hardware
   has color capabilities, you can change this color with the optional color
   argument (see Section 5.7.1, "Selecting a Color for Graphics Output").

   The syntax introduced here for drawing a box is the general syntax used in
   BASIC to define a rectangular graphics region, and it also appears in the
   GET and VIEW statements:

   {GET| LINE| VIEW} (x1, y1) - (x2, y2),...

   Here, (x1, y1) and (x2, y2) are the coordinates of diagonally opposite
   corners of the rectangle (upper left and lower right). (See Section 5.5,
   "Defining a Graphics Viewport," for a discussion of VIEW, and Section
   5.10, "Basic Animation Techniques," for information on GET and PUT.)

   5.3.2.3  Drawing Dotted Lines

   The previous sections explain how to use LINE to draw solid lines and use
   them in rectangles; that is, no pixels are skipped. Using yet another
   option with LINE, you can draw dashed or dotted lines instead. This
   process is known as "line styling." The following is the syntax for
   drawing a single dashed line from point (x1, y1) to point (x2, y2) using
   the current foreground color:

   LINE (x1,y1) - (x2,y2), ,[[B]], style

   Here style is a 16-bit decimal or hexadecimal integer. The LINE statement
   uses the binary representation of the line-style argument to create dashes
   and blank spaces, with a 1 bit meaning "turn on the pixel," and a 0 bit
   meaning "leave the pixel off." For example, the hexadecimal integer &HCCCC
   is equal to the binary integer 1100110011001100, and when used as a style
   argument it draws a line alternating two pixels on, two pixels off.

   Example

   The following example shows different dashed lines produced using
   different values for style:

   SCREEN 2        ' 640 x 200 pixel resolution

   ' Style data:
   DATA &HCCCC, &HFF00, &HF0F0
   DATA &HF000, &H7777, &H8888

   Row% = 4
   Column% = 4
   XLeft% = 60
   XRight% = 600
   Y% = 28

   FOR I% = 1 TO 6
      READ Style%
      LOCATE Row%, Column%
      PRINT HEX$(Style%)
      LINE (XLeft%, Y%)-(XRight%,Y%), , , Style%
      Row% = Row% + 3
      Y% = Y% + 24
   NEXT

   Output

   ┌───────────────────────────────────────────────────────────────────┐
   │                                                                   │
   │                                                                   │
   │ CCCC····························································· │
   │                                                                   │
   │ FF00------------------------------------------------------------- │
   │                                                                   │
   │ F0F0 │
   │                                                                   │
   │ F000- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - │
   │                                                                   │
   │ 7777───────────────────────────────────────────────────────────── │
   │                                                                   │
   │ 8888............................................................. │
   │                                                                   │
   │                                                                   │
   │                                                                   │
   └───────────────────────────────────────────────────────────────────┘


 5.4  Drawing Circles and Ellipses with CIRCLE

   The CIRCLE statement draws a variety of circular and elliptical, or oval,
   shapes. In addition, CIRCLE draws arcs (segments of circles), and
   pie-shaped wedges. In graphics mode you can produce just about any kind of
   curved line with some variation of CIRCLE.

 5.4.1  Drawing Circles

   To draw a circle, you need to know only two things: the location of its
   center and the length of its radius (the distance from the center to any
   point on the circle). With this information and a reasonably steady hand
   (or better yet, a compass), you can produce an attractive circle.

   Similarly, BASIC needs only the location of a circle's center and the
   length of its radius to draw a circle. The simplest form of the CIRCLE
   syntax is

   CIRCLE[[STEP]](x, y), radius

   where x, y are the coordinates of the center, and radius is the radius of
   the circle. The next example draws a circle with center (200, 100) and
   radius 75:

   SCREEN 2
   CIRCLE (200, 100), 75

   You could rewrite the preceding example as follows, making the same circle
   but using the STEP option to make the coordinates relative to the center
   rather than to the upper-left corner:

   SCREEN 2       ' Uses center of screen (320,100) as the
                  ' reference point for the CIRCLE statement:
   CIRCLE STEP(-120, 0), 75

 5.4.2  Drawing Ellipses

   The CIRCLE statement automatically adjusts the "aspect ratio" to make sure
   that circles appear round and not flattened on your screen. However, you
   may need to adjust the aspect ratio to make circles come out right on your
   monitor, or you may want to change the aspect ratio to draw the oval
   figure known as an ellipse. In either case, use the syntax

   CIRCLE[[STEP]] (x,y), radius, , , , aspect

   where aspect is a positive real number. (See Section 5.4.5 for more
   information on the aspect ratio and how to calculate it for different
   screen modes.)

   The extra commas between radius and aspect are placeholders for other
   options that tell CIRCLE which color to use (if you have a color
   monitor/adapter and are using one of the screen modes that support color),
   or whether to draw an arc or wedge. (See Sections 5.4.3, "Drawing Arcs,"
   and 5.7.1, "Selecting a Color for Graphics Output," for more information
   on these options.)

   Since the aspect argument specifies the ratio of the vertical to
   horizontal dimensions, large values for aspect produce ellipses stretched
   out along the vertical axis, while small values for aspect produce
   ellipses stretched out along the horizontal axis. Since an ellipse has two
   radii──one horizontal x-radius and one vertical y-radius──BASIC uses the
   single radius argument in a CIRCLE statement as follows: if aspect is less
   than one, then radius is the x-radius; if aspect is greater than or equal
   to one, then radius is the y-radius.

   Example

   The following example and its output show how different aspect values
   affect whether the CIRCLE statement uses the radius argument as the
   x-radius or the y-radius of an ellipse:

   SCREEN 1

   ' This draws the ellipse on the left:
   CIRCLE (60, 100), 80, , , , 3

   ' This draws the ellipse on the right:
   CIRCLE (180, 100), 80, , , , 3/10

   Output

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 160 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

 5.4.3  Drawing Arcs

   An arc is a segment of a ellipse, in other words a short, curved line. To
   understand how the CIRCLE statement draws arcs, you need to know how BASIC
   measures angles.

   BASIC uses the radian as its unit of angle measure, not only in the CIRCLE
   statement, but also in the intrinsic trigonometric functions such as COS,
   SIN, or TAN. (The one exception to this use of radians is the DRAW
   statement, which expects angle measurements in degrees. See Section 5.9
   for more information about DRAW.)

   The radian is closely related to the radius of a circle. In fact, the word
   "radian" is derived from the word "radius." The circumference of a circle
   equals 2 * π * radius, where π is equal to approximately 3.14159265.
   Similarly, the number of radians in one complete angle of revolution (or
   360) equals 2 * π, or a little more than 6.28. If you are more used to
   thinking of angles in terms of degrees, here are some common equivalences:

   Angle in Degrees         Angle in Radians
   ──────────────────────────────────────────────────────────────────────────
   360                      2π    (approximately 6.283)

   180                      π    (approximately 3.142)

   90                       π/2  (approximately 1.571)

   60                       π/3  (approximately 1.047)
   ──────────────────────────────────────────────────────────────────────────

   If you picture a clock face on the screen, CIRCLE measures angles by
   starting at the "3:00" position and rotating counterclockwise, as shown in
   Figure 5.2:


   ┌────────────────────────────────────┐
   │                                    │
   │   Figure 5.2 can be found on       │
   │   page 161 of the printed manual.  │
   │                                    │
   └────────────────────────────────────┘

   Figure 5.2  How Angles Are Measured for CIRCLE

   The general formula for converting from degrees to radians is to multiply
   degrees by π/180.

   To draw an arc, give angle arguments defining the arc's limits:

   CIRCLE[[STEP]] (x, y), radius,[[color]], start, end [[, aspect]]

   Example

   The CIRCLE statements in the next example draw seven arcs, with the
   innermost arc starting at the "3:00" position (0 radians) and the
   outermost arc starting at the "6:00" position (3π/2 radians), as you can
   see from the output:

   SCREEN 2
   CLS

   CONST PI = 3.141592653589#      ' Double-precision constant

   StartAngle = 0
   FOR Radius% = 100 TO 220 STEP 20
      EndAngle = StartAngle + (PI / 2.01)
      CIRCLE (320, 100), Radius%, , StartAngle, EndAngle
      StartAngle = StartAngle + (PI / 4)
   NEXT Radius%

   Output

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 162 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

 5.4.4  Drawing Pie Shapes

   By making either of CIRCLE's start or end arguments negative, you can
   connect the arc at its beginning or ending point with the center of the
   circle. By making both arguments negative, you can draw shapes ranging
   from a wedge that resembles a slice of pie to the pie itself with the
   piece missing.

   Example

   This example draws a pie shape with a piece missing:

   SCREEN 2

   CONST RADIUS = 150, PI = 3.141592653589#

   StartAngle = 2.5
   EndAngle = PI

   ' Draw the wedge:
   CIRCLE (320, 100), RADIUS, , -StartAngle, -EndAngle

   ' Swap the values for the start and end angles:
   SWAP StartAngle, EndAngle

   ' Move the center 10 pixels down and 70 pixels to the
   ' right, then draw the "pie" with the wedge missing:
   CIRCLE STEP(70, 10), RADIUS, , -StartAngle, -EndAngle

   Output

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 163 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

 5.4.5  Drawing Shapes to Proportion with the Aspect Ratio

   As discussed in Section 5.4.2, "Drawing Ellipses," BASIC's CIRCLE
   statement automatically corrects the aspect ratio, which determines how
   figures are scaled on the screen. However, with other graphics statements
   you need to scale horizontal and vertical dimensions yourself to make
   shapes appear with correct proportions. For example, although the
   following statement draws a rectangle that measures 100 pixels on all
   sides, it does not look like a square:

   SCREEN 1
   LINE (0, 0)-(100, 100), , B

   In fact, this is not an optical illusion; the rectangle really is taller
   than it is wide. This is because in screen mode 1 there is more space
   between pixels vertically than horizontally. To draw a perfect square, you
   have to change the aspect ratio.

   The aspect ratio is defined as follows: in a given screen mode consider
   two lines, one vertical and one horizontal, that appear to have the same
   length. The aspect ratio is the number of pixels in the vertical line
   divided by the number of pixels in the horizontal line. This ratio depends
   on two factors:

   1. Because of the way pixels are spaced on most screens, a horizontal row
      has more pixels than a vertical column of the exact same physical
      length in all screen modes except modes 11 and 12.

   2. The standard personal computer's video-display screen is wider than it
      is high. Typically, the ratio of screen width to screen height is 4:3.

   To see how these two factors interact to produce the aspect ratio,
   consider a screen after a SCREEN 1 statement, which gives a resolution of
   320 x 200 pixels. If you draw a rectangle from the top of the screen to
   the bottom, and from the left side of the screen three-fourths of the way
   across, you have a square, as shown in Figure 5.3.


   ┌────────────────────────────────────────────────────────────────┐
   │ ┌──────────────────────────────────────────────────────┐       │
   │ │ ┌───────────────────────────────────┬─ - - - - - -   │       │
   │ │ │                                   │               │       │
   │ │ │                                   │      │         │       │
   │ │ │                                   │      │         │       │
   │ │ │                                   │      │         │       │
   │ │ │ ────────── 240 pixels───────────│   200 pixels   │       │
   │ │ │                                   │      │         │       │
   │ │ │                                   │      │         │       │
   │ │ │                                   │      │         │       │
   │ │ │                                   │      │         │       │
   │ │ │                                   │      │         │       │
   │ │ │                                   │               │       │
   │ │ └───────────────────────────────────┴─ - - - - - - - │       │
   │ │ ──────────────────320 pixels───────────────────────│       │
   │ └──────────────────────────────────────────────────────┘       │
   │                                                                │
   └────────────────────────────────────────────────────────────────┘
   Figure 5.3  The Aspect Ratio In Screen Mode 1

   As you can see from the diagram, this square has a height of 200 pixels
   and a width of 240 pixels. The ratio of the square's height to its width
   (200 / 240, or when simplified, 5 / 6) is the aspect ratio for this screen
   resolution. In other words, to draw a square in 320 x 200 resolution, make
   its height in pixels equal to 5 / 6 times its width in pixels, as shown in
   the next example:

   SCREEN 1        ' 320 x 200 pixel resolution

   ' The height of this box is 100 pixels, and the width is
   ' 120 pixels, which makes the ratio of the height to the
   ' width equal to 100/120, or 5/6. The result is a square:
   LINE (50, 50) -STEP(120, 100), , B

   The formula for calculating the aspect ratio for a given screen mode is

   (4 / 3) * (ypixels / xpixels)

   where xpixelsby ypixels is the current screen resolution. In screen mode
   1, this formula shows the aspect ratio to be (4 / 3) * (200 / 320), or 5 /
   6; in screen mode 2, the aspect ratio is (4 / 3) * (200 / 640), or 5 / 12.

   If you have a video display with a ratio of width to height that is not
   equal to 4:3, use the more general form of the formula for computing the
   aspect ratio:

   (screenwidth / screenheight) * (ypixels / xpixels)

   The CIRCLE statement can be made to draw an ellipse by varying the value
   of the aspect argument, as shown above in Section 5.4.2.


 5.5  Defining a Graphics Viewport

   The graphics examples presented so far have all used the entire
   video-display screen as their drawing board, with absolute coordinate
   distances measured from the extreme upper-left corner of the screen.

   However, using the VIEW statement you can also define a kind of miniature
   screen (known as a "graphics viewport") inside the boundaries of the
   physical screen. Once it is defined, all graphics operations take place
   within this viewport. Any graphics output outside the viewport boundaries
   is "clipped"; that is, any attempt to plot a point outside the viewport is
   ignored. There are two main advantages to using a viewport:

   1. A viewport makes it easy to change the size and position of the screen
      area where graphics appear.

   2. Using CLS 1, you can clear the screen inside a viewport without
      disturbing the screen outside the viewport.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Refer to Section 3.1.6 to learn how to create a "text viewport" for
     output printed on the screen.
   ──────────────────────────────────────────────────────────────────────────

   The general syntax for VIEW (note that the STEP option is not allowed with
   VIEW) is

   VIEW[[[[SCREEN]] (x1, y1) - (x2, y2)[[,[[color]], [[border]]]]]]

   where (x1, y1) and (x2, y2) define the corners of the viewport, using the
   standard BASIC syntax for rectangles (see Section 5.3.2.2, "Drawing
   Boxes"). The optional color and border arguments allow you to choose a
   color for the interior and edges, respectively, of the viewport rectangle.
   See Section 5.7 below for more information on setting and changing
   colors.

   The VIEW statement without arguments makes the entire screen the viewport.
   Without the SCREEN option, the VIEW statement makes all pixel coordinates
   relative to the viewport, rather than the full screen. In other words,
   after the statement

   VIEW (50, 60)-(150, 175)

   the pixel plotted with

   PSET (10, 10)

   is visible, since it is 10 pixels below and 10 pixels to the right of the
   upper-left corner of the viewport. Note that this makes the pixel's
   absolute screen coordinates (50 + 10, 60 + 10) or (60, 70).

   In contrast, the VIEW statement with the SCREEN option keeps all
   coordinates absolute; that is, coordinates measure distances from the side
   of the screen, not from the sides of the viewport. Therefore, after the
   statement

   VIEW SCREEN (50, 60)-(150, 175)

   the pixel plotted with

   PSET (10, 10)

   is not visible, since it is 10 pixels below and 10 pixels to the right of
   the upper-left corner of the screen──outside the viewport.

   Examples

   The output from the next two examples should further clarify the
   distinction between VIEW and VIEW SCREEN:

   SCREEN 2

   VIEW (100, 50)-(450, 150), , 1

   ' This circle's center point has absolute coordinates
   ' (100 + 100, 50 + 50), or (200, 100):
   CIRCLE (100, 50), 50

   Output using VIEW

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 167 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

   SCREEN 2

   ' This circle's center point has absolute coordinates
   ' (100, 50), so only part of the circle appears
   '  within the view port:
   VIEW SCREEN (100, 50)-(450, 150), , 1
   CIRCLE (100, 50), 50

   Output using VIEW SCREEN

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 167 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

   Note that graphics output located outside the current viewport is clipped
   by the viewport's edges and does not appear on the screen.


 5.6  Redefining Viewport Coordinates with WINDOW

   This section shows you how to use the WINDOW statement and your own
   coordinate system to redefine pixel coordinates.

   In Sections 5.2-5.5, the coordinates used to locate pixels on the screen
   represent actual physical distances from the upper-left corner of the
   screen (or the upper-left corner of the current viewport, if it has been
   defined with a VIEW statement). These are known as "physical coordinates."
   The "origin," or reference point, for physical coordinates is always the
   upper-left corner of the screen or viewport, which has coordinates (0, 0).

   As you move down the screen and to the right, x values (horizontal
   coordinates) and y values (vertical coordinates) get bigger, as shown in
   the upper diagram of Figure 5.4. While this scheme is standard for video
   displays, it may seem counterintuitive if you have used other coordinate
   systems to draw graphs. For example, on the Cartesian grid used in
   mathematics, y values get bigger toward the top of a graph and smaller
   toward the bottom.

   With BASIC's WINDOW statement, you can change the way pixels are addressed
   to use any coordinate system you choose, thus freeing you from the
   limitations of using physical coordinates.

   The general syntax for WINDOW is

   WINDOW [[[[SCREEN]] (x1, y1) - (x2, y2)]]

   where y1, y2, x1, and x2 are real numbers specifying the top, bottom,
   left, and right sides of the window, respectively. These numbers are known
   as "view coordinates." For example, the following statement remaps your
   screen so that it is bounded on the top and bottom by the lines y = 10 and
   y = -15 and on the left and right by the lines x = -25 and x = 5 :

   WINDOW (-25, -15)-(5, 10)

   After a WINDOW statement, y values get bigger toward the top of the
   screen. In contrast, after a WINDOW SCREEN statement, y values get bigger
   toward the bottom of the screen. The bottom half of Figure 5.4 shows the
   effects of both a WINDOW statement and a WINDOW SCREEN statement on a line
   drawn in screen mode 2. Note also how both of these statements change the
   coordinates of the screen corners. A WINDOW statement with no arguments
   restores the regular physical-coordinate system.

   Example


   ┌──────────────────────────────────────────────────────────────────────────
   │                               Increasing X
   │                     ─────────────────────────────
   │                     ┌────────────────────────────┐
   │                   │ │°(0,0)              (639,0)°│
   │                   │ │                            │
   │        Increasing │ │                            │
   │             Y     │ │                            │
   │                   │ │                            │
   │                   │ │                            │
   │                   │ │°(0,199)          (639,199)°│
   │                    └────────────────────────────┘
   │                                   ^
   │                                 /   \
   │                                /      \
   │       WINDOW (-25, -15) - (5, 10)   WINDOW SCREEN (-25, -15) - (5, 10)
   │       LINE (-15, -10  - (-5, -5)    LINE (-15, -10) - (-5, -5)
   │                            /              \
   │                          /                  \
   │                        /                      \
   │                                                       Increasing X
   │                                                ─────────────────────────
   │            ┌─────────────────────┐             ┌────────────────────────┐
   │           │°(-25,10)     (5,10)°│            ││°(-25,-15)    (5,-15)°  │
   │           ││                     │            ││        °(-15,-10)      │
   │           ││           (0,0)°    │            ││             \          │
   │ Increasing││                     │  Increasing││              °(-5,-5)  │
   │      Y    ││       (-5,-5)°      │       Y    ││                        │
   │           ││(-15,-10)  /         │            ││                   °    │
   │           ││         °           │            ││               (0,0)    │
   │           ││°(-25,-15)   (5,-15)°│            ││°(-25,10)        (5,10)°│
   │            └─────────────────────┘            └────────────────────────┘
   │            ──────────────────────
   │                 Increasing X
   └──────────────────────────────────────────────────────────────────────────

   Figure 5.4  WINDOW Contrasted with WINDOW SCREEN

   The following example uses both VIEW and WINDOW to simplify writing a
   program to graph the sine-wave function for angle values from 0 radians to
   p radians (or 0° to 180°). This program is in the file named SINEWAVE.BAS
   on the QuickBASIC distribution disks.

   SCREEN 2

   ' Viewport sized to proper scale for graph:
   VIEW (20, 2)-(620, 172), , 1
   CONST PI = 3.141592653589#

   ' Make window large enough to graph sine wave from
   ' 0 radians to pi radians:
   WINDOW (0, -1.1)-(PI, 1.1)
   Style% = &HFF00                 ' Use to make dashed line.
   VIEW PRINT 23 TO 24  ' Scroll printed output in rows 23, 24.
   DO
      PRINT TAB(20);
      INPUT "Number of cycles (0 to end): ", Cycles
      CLS
      LINE (PI, 0)-(0, 0), , , Style%  ' Draw the x axis.
      IF Cycles > 0 THEN

         ' Start at (0,0) and plot the graph:
         FOR X = 0 TO PI STEP .01
            Y = SIN(Cycles * X)    ' Calculate the y coordinate.
            LINE -(X, Y)           ' Draw a line to new point.
         NEXT X
      END IF
   LOOP WHILE Cycles > 0

   Output

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 170 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

 5.6.1  The Order of Coordinate Pairs

   As with the other BASIC graphics statements that define rectangular areas
   (GET, LINE, and VIEW), the order of coordinate pairs in a WINDOW statement
   is unimportant. The first pair of statements below has the same effect as
   the second pair of statements:

   VIEW (100, 20)-(300, 120)
   WINDOW (-4, -3)-(0, 0)

   VIEW (300, 120)-(100, 20)
   WINDOW (0, 0)-(-4, -3)

 5.6.2  Keeping Track of View and Physical Coordinates

   The PMAP and POINT functions are useful for keeping track of physical and
   view coordinates. POINT(number) tells you the current location of the
   graphics cursor by returning either the physical or view coordinates
   (depending on the value for number) of the last point referenced in a
   graphics statement. PMAP allows you to translate physical coordinates to
   view coordinates and vice versa. The physical-coordinate values returned
   by PMAP are always relative to the current viewport.

   Examples

   The following example shows the different values that are returned by
   POINT (number) for number values of 0, 1, 2, or 3:

   SCREEN 2
   ' Define the view-coordinate window:
   WINDOW (-10, -30)-(-5, -10)
   ' Draw a line from the point with view coordinates (-9,-28)
   ' to the point with view coordinates (-6,-24):
   LINE (-9, -28)-(-6, -24)

   PRINT "Physical x-coordinate of the last point = " POINT(0)
   PRINT "Physical y-coordinate of the last point = " POINT(1)
   PRINT
   PRINT "View x-coordinate of the last point  = " POINT(2)
   PRINT "View y-coordinate of the last point  = " POINT(3)

   END

   Output

   Physical x-coordinate of the last point = 511
   Physical y-coordinate of the last point = 139

   View x-coordinate of the last point  = -6
   View y-coordinate of the last point  = -24

   Given the WINDOW statement in the preceding example, the next four PMAP
   statements would print the output that follows:

   ' Map the view x-coordinate -6 to physical x and print:
   PhysX% = PMAP(-6, 0)
   PRINT PhysX%

   ' Map the view y-coordinate -24 to physical y and print:
   PhysY% = PMAP(-24, 1)
   PRINT PhysY%

   ' Map physical x back to view x and print:
   ViewX% = PMAP(PhysX%, 2)
   PRINT ViewX%

   ' Map physical y back to view y and print:
   ViewY% = PMAP(PhysY%, 3)
   PRINT ViewY%

   Output

    511
    139
   -6
   -24


 5.7  Using Colors

   If you have a Color Graphics Adapter (CGA), you can choose between the
   following two graphics modes only:

   1. Screen mode 2 has 640 x 200 high resolution, with only one foreground
      and one background color. This is known as "monochrome," since all
      graphics output has the same color.

   2. Screen mode 1 has 320 x 200 medium resolution with 4 foreground colors
      and 16 background colors.

   There is thus a tradeoff between color and clarity in the two screen modes
   supported by most color-graphics display adapter hardware. Depending on
   the graphics capability of your system, you may not have to sacrifice
   clarity to get a full range of color. However, this section focuses on
   screen modes 1 and 2.

 5.7.1  Selecting a Color for Graphics Output

   The following list shows where to put the color argument in the graphics
   statements discussed in previous sections of this chapter. This list also
   shows other options (such as BF with the LINE statement or border with the
   VIEW statement) that can have a different colors. (Please note that these
   do not give the complete syntax for some of these statements. This summary
   is intended to show how to use the color option in those statements that
   accept it.)

   PSET (x, y), color
   PRESET (x, y), color
   LINE (x1, y1) - (x2, y2), color [[, B[[F]]]]
   CIRCLE (x, y), radius, color
   VIEW (x1, y1) - (x2, y2), color, border

   In screen mode 1, the color argument is a numeric expression with the
   value 0, 1, 2, or 3. Each of these values, known as an "attribute,"
   represents a different color, as demonstrated by the following program:

   ' Draw an "invisible" line (same color as background):
   LINE (10, 10)-(310, 10), 0

   ' Draw a light blue (cyan) line:
   LINE (10, 30)-(310, 30), 1

   ' Draw a purple (magenta) line:
   LINE (10, 50)-(310, 50), 2

   ' Draw a white line:
   LINE (10, 70)-(310, 70), 3
   END

   As noted in the comments for the preceding example, a color value of 0
   produces no visible output, since it is always equal to the current
   background color. At first glance, this may not seem like such a useful
   color value, but in fact it is useful for erasing a figure without having
   to clear the entire screen or viewport, as shown in the next example:

   SCREEN 1

   CIRCLE (100, 100), 80, 2, , , 3   ' Draw an ellipse.
   Pause$ = INPUT$(1)                ' Wait for a key press.
   CIRCLE (100, 100), 80, 0, , , 3   ' Erase the ellipse.

 5.7.2  Changing the Foreground or Background Color

   Section 5.7.1 above describes how to use 4 different foreground colors
   for graphics output. You have a wider variety of colors in screen mode 1
   for the screen's background: 16 in all.

   In addition, you can change the foreground color by using a different
   "palette." In screen mode 1, there are two palettes, or groups of four
   colors. Each palette assigns a different color to the same attribute; so,
   for instance, in palette 1 (the default) the color associated with
   attribute 2 is magenta, while in palette 0 the color associated with
   attribute 2 is red. If you have a CGA, these colors are predetermined for
   each palette; that is, the color assigned to number 2 in palette 1 is
   always magenta, while the color assigned to number 2 in palette 0 is
   always red.

   If you have an Enhanced Graphics Adapter (EGA) or Video Graphics Adapter
   (VGA), you can use the PALETTE statement to choose the color displayed by
   any attribute. For example, by changing arguments in a PALETTE statement,
   you could make the color displayed by attribute 1 green one time and brown
   the next. (See Section 5.7.3, "Changing Colors with PALETTE and PALETTE
   USING," in this manual for more information on reassigning colors.)

   In screen mode 1, the COLOR statement allows you to control both the
   background color and the palette for the foreground colors. Here is the
   syntax for COLOR in screen mode 1:

   COLOR[[background]] [[, palette]]

   The background argument is a numeric expression from 0 to 15, and palette
   is a numeric expression equal to either 0 or 1.

   Table 5.1 shows the colors produced with the 4 different foreground
   numbers in each of the two palettes, while Table 5.2 shows the colors
   produced with the 16 different background numbers.

   Table 5.1  Color Palettes in Screen Mode 1
   Foreground Color Number  Color in Palette 0      Color in Palette 1
   ──────────────────────────────────────────────────────────────────────────
   0                        Current background      Current background color
                            color

   1                        Green                   Cyan (bluish green)

   2                        Red                     Magenta (light purple)

   3                        Brown                   White (light grey on some
                                                    monitors)
   ──────────────────────────────────────────────────────────────────────────

   Table 5.2  Background Colors in Screen Mode 1
╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
   Background Color Number  Color
   ──────────────────────────────────────────────────────────────────────────
   0                        Black

   1                        Blue

   Background Color Number  Color
   ──────────────────────────────────────────────────────────────────────────

   2                        Green

   3                        Cyan

   4                        Red

   5                        Magenta

   6                        Brown (dark yellow on some monitors)

   7                        White (light grey on some monitors)

   8                        Dark grey (black on some monitors)

   9                        Light blue

   10                       Light green

   Background Color Number  Color
   ──────────────────────────────────────────────────────────────────────────

   11                       Light cyan

   12                       Light red

   13                       Light magenta

   14                       Light yellow (may have greenish tinge on some
                            monitors)

   15                       Bright white or very light grey
   ──────────────────────────────────────────────────────────────────────────


   Example

   The following program shows all combinations of the two color palettes
   with the 16 different background screen colors. This program is in the
   file named COLORS.BAS on the QuickBASIC distribution disks.

   SCREEN 1

   Esc$ = CHR$(27)
   ' Draw three boxes and paint the interior
   ' of each box with a different color:
   FOR ColorVal = 1 TO 3
      LINE (X, Y) -STEP(60, 50), ColorVal, BF
      X = X + 61
      Y = Y + 51
   NEXT ColorVal

   LOCATE 21, 1
   PRINT "Press ESC to end."
   PRINT "Press any other key to continue."

   ' Restrict additional printed output to the 23rd line:
   VIEW PRINT 23 TO 23
   DO
      PaletteVal = 1
      DO

         ' PaletteVal is either 1 or 0:
         PaletteVal = 1 - PaletteVal

         ' Set the background color and choose the palette:
         COLOR BackGroundVal, PaletteVal
         PRINT "Background ="; BackGroundVal;
         PRINT "Palette ="; PaletteVal;

         Pause$ = INPUT$(1)        ' Wait for a keystroke.
         PRINT

      ' Exit the loop if both palettes have been shown,
      ' or if the user pressed the ESC key:
      LOOP UNTIL PaletteVal = 1 OR Pause$ = Esc$

      BackGroundVal = BackGroundVal + 1

   ' Exit this loop if all 16 background colors have
   ' been shown, or if the user pressed the ESC key:
   LOOP UNTIL BackGroundVal > 15 OR Pause$ = Esc$

   SCREEN 0                     ' Restore text mode and
   WIDTH 80                     ' 80-column screen width.

 5.7.3  Changing Colors with PALETTE and PALETTE USING

   The preceding section showed how you can change the color displayed by an
   attribute simply by specifying a different palette in the COLOR statement.
   However, this restricts you to two fixed color palettes, with just 4
   colors in each. Furthermore, each attribute can stand for only one of two
   possible colors; for example, attribute 1 can signify only green or cyan.

   With an EGA or VGA, your choices are potentially much broader. (If you
   don't have an EGA or VGA, you may want to skip this section.) For
   instance, depending on the amount of video memory available to your
   computer, with a VGA you can choose from a palette with as many as 256K
   (that's right, over 256,000) colors and assign those colors to 256
   different attributes. Even an EGA allows you to display up to 16 different
   colors from a palette of 64 colors.

   In contrast to the COLOR statement, the PALETTE and PALETTE USING
   statements give you a lot more flexibility in manipulating the available
   color palette. Using these statements, you can assign any color from the
   palette to any attribute. For example, after the following statement, the
   output of all graphics statements using attribute 4 appears in light
   magenta (color 13):

   PALETTE 4, 13

   This color change is instantaneous and affects not only subsequent
   graphics statements but any output already on the screen. In other words,
   you can draw and paint your screen, then switch the palette to achieve an
   immediate change of color, as shown by the following example:

   SCREEN 8
   LINE (50, 50)-(150, 150), 4  ' Draws a line in red.
   SLEEP 1                      ' Pauses program.
   PALETTE 4, 13                ' Attribute 4 now means color
                                ' 13, so the line drawn in the
                                ' last statement is now light
                                ' magenta.

   With the PALETTE statement's USING option, you can change the colors
   assigned to every attribute all at once.

   Example

   The following example uses the PALETTE USING statement to give the
   illusion of movement on the screen by constantly rotating the colors
   displayed by attributes 1 through 15. This program is in the file named
   PALETTE.BAS on the QuickBASIC distribution disks.

   DECLARE SUB InitPalette ()
   DECLARE SUB ChangePalette ()
   DECLARE SUB DrawEllipses ()

   DEFINT A-Z
   DIM SHARED PaletteArray(15)

   SCREEN 8                 ' 640 x 200 resolution; 16 colors

   InitPalette              ' Initialize PaletteArray.
   DrawEllipses             ' Draw and paint concentric ellipses.

   DO                       ' Shift the palette until a key
      ChangePalette         ' is pressed.
   LOOP WHILE INKEY$ = ""

   END


   ' ====================== InitPalette ======================
   '    This procedure initializes the integer array used to
   '    change the palette.
   ' =========================================================

   SUB InitPalette STATIC
      FOR I = 0 TO 15
         PaletteArray(I) = I
      NEXT I
   END SUB
   ' ===================== DrawEllipses ======================
   '    This procedure draws 15 concentric ellipses and
   '    paints the interior of each with a different color.
   ' =========================================================

   SUB DrawEllipses STATIC
      CONST ASPECT = 1 / 3
      FOR ColorVal = 15 TO 1 STEP -1
         Radius = 20 * ColorVal
         CIRCLE (320, 100), Radius, ColorVal, , , ASPECT
         PAINT (320, 100), ColorVal
      NEXT
   END SUB


   ' ===================== ChangePalette =====================
   '  This procedure rotates the palette by one each time it
   '  is called. For example, after the first call to
   '  ChangePalette, PaletteArray(1) = 2, PaletteArray(2) = 3,
   '  . . . , PaletteArray(14) = 15, and PaletteArray(15) = 1
   ' =========================================================

   SUB ChangePalette STATIC
      FOR I = 1 TO 15
         PaletteArray(I) = (PaletteArray(I) MOD 15) + 1
      NEXT I
      PALETTE USING PaletteArray(0) ' Shift the color displayed
                                    ' by each of the attributes.
   END SUB


 5.8  Painting Shapes

   Section 5.3.2.2 above shows how to draw a box with the LINE statement's B
   option, then paint the box by appending the F (for fill) option:

   SCREEN 1

   ' Draw a square, then paint the interior with color 1
   ' (cyan in the default palette):
   LINE (50, 50)-(110, 100), 1, BF

   With BASIC's PAINT statement, you can fill any enclosed figure with any
   color you choose. PAINT also allows you to fill enclosed figures with your
   own custom patterns, such as stripes or checks, as shown in Section
   5.8.2, "Painting with Patterns."

 5.8.1  Painting with Colors

   To paint an enclosed shape with a solid color, use this form of the PAINT
   statement:

   PAINT[[STEP]](x, y) [[,[[interior]],[[border]]]]

   Here, x, y are the coordinates of a point in the interior of the figure
   you want to paint, interior is the number for the color you want to paint
   with, and border is the color number for the outline of the figure.

   For example, the following program lines draw a circle in cyan, then paint
   the inside of the circle magenta:

   SCREEN 1
   CIRCLE (160, 100), 50, 1
   PAINT (160, 100), 2, 1

   The following three rules apply when painting figures:

   1. The coordinates given in the PAINT statement must refer to a point
      inside the figure.

      For example, any one of the following statements would have the same
      effect as the PAINT statements shown in the two preceding examples,
      since all of the coordinates identify points in the interior of the
      circle:

      PAINT (150, 90), 2, 1
      PAINT (170, 110), 2, 1
      PAINT (180, 80), 2, 1

      In contrast, since (5, 5) identifies a point outside the circle, the
      next statement would paint all of the screen except the inside of the
      circle, leaving it colored with the current background color:

      PAINT (5, 5), 2, 1

      If the coordinates in a PAINT statement specify a point right on the
      border of the figure, then no painting occurs:

      LINE (50, 50)-(150, 150), , B  ' Draw a box.
      PAINT (50, 100)  ' The point with coordinates
                       ' (50, 100) is on the top edge of the
                       ' box, so no painting occurs.

   2. The figure must be completely enclosed; otherwise, the paint color will
      "leak out," filling the entire screen or viewport (or any larger figure
      completely enclosing the first one).

      For example, in the following program, the CIRCLE statement draws an
      ellipse that is not quite complete (there is a small gap on the right
      side); the LINE statement then encloses the partial ellipse inside a
      box. Even though painting starts in the interior of the ellipse, the
      paint color flows through the gap and fills the entire box.

      SCREEN 2
      CONST PI = 3.141592653589#
      CIRCLE (300, 100), 80, , 0, 1.9 * PI, 3
      LINE (200, 10)-(400, 190), , B
      PAINT (300, 100)

   3. If you are painting an object a different color from the one used to
      outline the object, you must use the border option to tell PAINT where
      to stop painting.

      For example, the following program draws a triangle outlined in green
      (attribute 1 in palette 0) and then tries to paint the interior of the
      triangle red (attribute 2). However, since the PAINT statement doesn't
      indicate where to stop painting, it paints the entire screen red.

      SCREEN 1
      COLOR , 0

      LINE (10, 25)-(310, 25), 1
      LINE -(160, 175), 1
      LINE -(10, 25), 1

      PAINT (160, 100), 2

      Making the following change to the PAINT statement (choose red for the
      interior and stop when a border colored green is reached) produces the
      desired effect:

      PAINT (160, 100), 2, 1

      Note that you don't have to specify a border color in the PAINT
      statement if the paint color is the same as the border color.

      LINE (10, 25)-(310, 25), 1
      LINE -(160, 175), 1
      LINE -(10, 25), 1

      PAINT (160, 100), 1

 5.8.2  Painting with Patterns: Tiling

   You can use the PAINT statement to fill any enclosed figure with a
   pattern; this process is known as "tiling." A "tile" is the pattern's
   basic building block. The process is identical to laying down tiles on a
   floor. When you use tiling, the argument interior in the syntax for PAINT
   is a string expression, rather than a number. While interior can be any
   string expression, a convenient way to define tile patterns uses the
   following form for interior:

   CHR$(arg1) + CHR$(arg2) + CHR$(arg3) + ... + CHR$(argn)

   Here, arg1, arg2, and so forth are eight-bit integers. See Sections
   5.8.2.2-5.8.2.4 below for an explanation of how these eight-bit integers
   are derived.

   5.8.2.1  Pattern-Tile Size in Different Screen Modes

   Each tile for a pattern is composed of a rectangular grid of pixels. This
   tile grid can have up to 64 rows in all screen modes. However, the number
   of pixels in each row depends on the screen mode.

   Here is why the length of each tile row varies according to the screen
   mode: although the number of bits in each row is fixed at eight (the
   length of an integer), the number of pixels these eight bits can represent
   decreases as the number of color attributes in a given screen mode
   increases. For example, in screen mode 2, which has only 1 color
   attribute, the number of bits per pixel is 1; in screen mode 1, which has
   4 different attributes, the number of bits per pixel is 2; and in the EGA
   screen mode 7, which has 16 attributes, the number of bits per pixel is 4.
   The following formula allows you to compute the bits per pixel in any
   given screen mode:

   bits-per-pixel = log2(numattributes)

   Here, numattributes is the number of color attributes in that screen mode.
   (The on-line QB Advisor has this information.)

   Thus, the length of a tile row is eight pixels in screen mode 2 (eight
   bits divided by one bit per pixel), but only four pixels in screen mode 1
   (eight bits divided by two bits per pixel).

   The next three sections show the step-by-step process involved in creating
   a pattern tile. Section 5.8.2.2 shows how to make a monochrome pattern in
   screen mode 2. Next, Section 5.8.2.3 shows how to make a multicolored
   pattern in screen mode 1. Finally, if you have an EGA, read Section
   5.8.2.4 to see how to make a multicolored pattern in screen mode 8.

   5.8.2.2  Creating a Single-Color Pattern in Screen Mode 2

   The following steps show how to define and use a pattern tile that
   resembles the letter "M":

   1. Draw the pattern for a tile in a grid with 8 columns and however many
      rows you need (up to 64). In this example, the tile has 6 rows; an
      asterisk (*) in a box means the pixel is on:

      ┌──────────────────────────────────────────────────────────────────┐
      │            1 pixel                                               │
      │            ┌──┴───┐                                              │
      │          ┌ ┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐     │
      │ 1 pixel ─┤ │  *  │     │     │     │     │  *  │     │     │     │
      │          └ ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤     │
      │            │  *  │  *  │     │     │  *  │  *  │     │     │     │
      │            ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤     │
      │            │  *  │     │  *  │  *  │     │  *  │     │     │     │
      │            ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤     │
      │            │  *  │     │     │     │     │  *  │     │     │     │
      │            ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤     │
      │            │  *  │     │     │     │     │  *  │     │     │     │
      │            ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤     │
      │            │  *  │     │     │     │     │  *  │     │     │     │
      │            ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤     │
      │            │     │     │     │     │     │     │     │     │     │
      │            └─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘     │
      │                                                                  │
      └──────────────────────────────────────────────────────────────────┘

   2. Next, translate each row of pixels to an eight-bit number, with a 1
      meaning the pixel is on, and a 0 meaning the pixel is off:

      ┌─────────────────────────────────────────────────────────────────┐
      │                                                                 │
      │        ┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐        │
      │        │  1  │  0  │  0  │  0  │  0  │  1  │  0  │  0  │        │
      │        ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤        │
      │        │  1  │  1  │  0  │  0  │  0  │  1  │  0  │  0  │        │
      │        ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤        │
      │        │  1  │  0  │  1  │  1  │  0  │  1  │  0  │  0  │        │
      │        ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤        │
      │        │  1  │  0  │  0  │  0  │  0  │  1  │  0  │  0  │        │
      │        ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤        │
      │        │  1  │  0  │  0  │  0  │  0  │  1  │  0  │  0  │        │
      │        ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤        │
      │        │  1  │  0  │  0  │  0  │  0  │  1  │  0  │  0  │        │
      │        ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤        │
      │        │  0  │  0  │  0  │  0  │  0  │  0  │  0  │  0  │        │
      │        └─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘        │
      │                                                                 │
      │                                                                 │
      └─────────────────────────────────────────────────────────────────┘

   3. Convert the binary numbers given in step 2 to hexadecimal integers:

      10000100 = &H84
      11001100 = &HCC
      10110100 = &HB4
      10000100 = &H84
      10000100 = &H84
      00000000 = &H00

      These integers do not have to be hexadecimal; they could be decimal or
      octal. However, binary to hexadecimal conversion easier. To convert
      from binary to hexadecimal, read the binary number from right to left.
      Each group of four digits is then converted to its hexadecimal
      equivalent, as shown here:

      ┌───────────────────────────────────────────────────────────┐
      │                                                           │
      │                Binary         1010    1001    1111        │
      │                              └─┬──┘  └─┬──┘  └─┬──┘       │
      │                                │       │       │          │
      │                Hexadecimal     A       9       F          │
      │                                                           │
      └───────────────────────────────────────────────────────────┘

      Table 5.3 lists four-bit binary sequences and their hexadecimal
      equivalents.

   4. Create a string by concatenating the characters with the ASCII values
      from step 3 (use the CHR$ function to get these characters):

      Tile$ = CHR$(&H84) + CHR$(&HCC) + CHR$(&HB4)
      Tile$ = Tile$ + CHR$(&H84) + CHR$(&H84) + CHR$(&H00)

   5. Draw a figure and paint its interior, using PAINT and the string
      argument from step 4:

      PAINT (X, Y), Tile$

   Table 5.3  Binary to Hexadecimal Conversion
╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
   Binary Number            Hexadecimal Number
   ──────────────────────────────────────────────────────────────────────────
   0000                     0

   0001                     1

   0010                     2

   0011                     3

   0100                     4

   0101                     5
   Binary Number            Hexadecimal Number
   ──────────────────────────────────────────────────────────────────────────
  0101                     5

   0110                     6

   0111                     7

   1000                     8

   1001                     9

   1010                     A

   1011                     B

   1100                     C

   1101                     D

   1110                     E
   Binary Number            Hexadecimal Number
   ──────────────────────────────────────────────────────────────────────────
  1110                     E

   1111                     F
   ──────────────────────────────────────────────────────────────────────────


   Example

   The following example draws a circle and then paints the circle's interior
   with the pattern created in the preceding steps:

   SCREEN 2
   CLS
   Tile$ = CHR$(&H84) + CHR$(&HCC) + CHR$(&HB4)
   Tile$ = Tile$ + CHR$(&H84) + CHR$(&H84) + CHR$(&H00)
   CIRCLE STEP(0, 0), 150
   PAINT STEP(0, 0), Tile$

   Output


   ┌────────────────────────────────────┐
   │                                    │
   │   Figure 5.5 can be found on       │
   │   page 184 of the printed manual.  │
   │                                    │
   └────────────────────────────────────┘

   Figure 5.5  Patterned Circle

   5.8.2.3  Creating a Multicolor Pattern in Screen Mode 1

   The following steps show how to create a multicolor pattern consisting of
   alternating diagonal stripes of cyan and magenta (or green and red in
   palette 0):

   1. Draw the pattern for a tile in a grid with four columns (four columns
      because each row of pixels is stored in an eight-bit integer and each
      pixel in screen mode 1 requires two bits) and however many rows you
      need (up to 64). In this example, the tile has four rows, as shown in
      the next diagram:

      ┌──────────────────────────────────────────────────────────────────┐
      │                                                                  │
      │              1 pixel                                             │
      │             ┌────┴───┐                                           │
      │           ┌─┌────────┬────────┬────────┬────────┐                │
      │   1 pixel ┤ │  cyan  │magenta │magenta │magenta │                │
      │           │ │        │        │        │        │                │
      │           └─├────────┼────────┼────────┼────────┤                │
      │             │ magenta│ cyan   │magenta │magenta │                │
      │             │        │        │        │        │                │
      │             ├────────┼────────┼────────┼────────┤                │
      │             │ magenta│ magenta│ cyan   │magenta │                │
      │             │        │        │        │        │                │
      │             ├────────┼────────┼────────┼────────┤                │
      │             │ magenta│ magenta│ magenta│ cyan   │                │
      │             │        │        │        │        │                │
      │             └────────┴────────┴────────┴────────┘                │
      │                                                                  │
      └──────────────────────────────────────────────────────────────────┘

   2. Convert the colors to their respective color numbers in binary
      notation, as shown below (be sure to use two-bit values, so 1 that =
      binary 01 and 2 = binary 10):

      ┌──────────────────────────────────────────────────────────────────┐
      │                                                                  │
      │              2 bits                                              │
      │             ┌───┴────┐                                           │
      │             ┌────────┬────────┬────────┬────────┐                │
      │             │  01    │  10    │  10    │  10    │                │
      │             │        │        │        │        │                │
      │             ├────────┼────────┼────────┼────────┤                │
      │             │  10    │  01    │  10    │  10    │                │
      │             │        │        │        │        │                │
      │             ├────────┼────────┼────────┼────────┤                │
      │             │  10    │  10    │  01    │  10    │                │
      │             │        │        │        │        │                │
      │             ├────────┼────────┼────────┼────────┤                │
      │             │  10    │  10    │  10    │  01    │                │
      │             │        │        │        │        │                │
      │             └────────┴────────┴────────┴────────┘                │
      │                                                                  │
      └──────────────────────────────────────────────────────────────────┘

   3. Convert the binary numbers from step 2 to hexadecimal integers:

      01101010 = &H6A
      10011010 = &H9A
      10100110 = &HA6
      10101001 = &HA9

   4. Create a string by concatenating the characters with the ASCII values
      from step 3 (use the CHR$ function to get these characters):

      Tile$ = CHR$(&H6A) + CHR$(&H9A) + CHR$(&HA6) + CHR$(&HA9)

   5. Draw a figure and paint its interior using PAINT and the string
      argument from step 4:

      PAINT (X, Y), Tile$

   The following program draws a triangle and then paints its interior with
   the pattern created in the preceding steps:

   SCREEN 1

   ' Define a pattern:
   Tile$ = CHR$(&H6A) + CHR$(&H9A) + CHR$(&HA6) + CHR$(&HA9)

   ' Draw a triangle in white (color 3):
   LINE (10, 25)-(310, 25)
   LINE -(160, 175)
   LINE -(10, 25)

   ' Paint the interior of the triangle with the pattern:
   PAINT (160, 100), Tile$

   Note that if the figure you want to paint is outlined in a color that is
   also contained in the pattern, then you must give the border argument with
   PAINT as shown below; otherwise, the pattern spills over the edges of the
   figure:

   SCREEN 1

   ' Define a pattern:
   Tile$ = CHR$(&H6A) + CHR$(&H9A) + CHR$(&HA6) + CHR$(&HA9)

   ' Draw a triangle in magenta (color 2):
   LINE (10, 25)-(310, 25), 2
   LINE -(160, 175), 2
   LINE -(10, 25), 2

   ' Paint the interior of the triangle with the pattern,
   ' adding the border argument (, 2) to tell PAINT
   ' where to stop:
   PAINT (160, 100), Tile$, 2

   Sometimes, after painting a figure with a solid color or pattern, you may
   want to repaint that figure, or some part of it, with a new pattern. If
   the new pattern contains two or more adjacent rows that are the same as
   the figure's current background, you will find that tiling does not work.
   Instead, the pattern starts to spread, finds itself surrounded by pixels
   that are the same as two or more of its rows, then stops.

   You can alleviate this problem by using the background argument with PAINT
   if there are at most two adjacent rows in your new pattern that are the
   same as the old background. PAINT with background has the following
   syntax:

   PAINT[[ STEP]] (x, y) [[,[[ interior]][[,[[ border]][[,background]] ]]]]

   The background argument is a string character of the form CHR$(n) that
   specifies the rows in the pattern tile that are the same as the figure's
   current background. In essence, background tells PAINT to skip over these
   rows when repainting the figure. The next example clarifies how this
   works:

   SCREEN 1

   ' Define a pattern (two rows each of cyan, magenta, white):
   Tile$ = CHR$(&H55) + CHR$(&H55) + CHR$(&HAA)
   Tile$ = Tile$ + CHR$(&HAA) + CHR$(&HFF) + CHR$(&HFF)

   ' Draw a triangle in white (color number 3):
   LINE (10, 25)-(310, 25)
   LINE -(160, 175)
   LINE -(10, 25)

   ' Paint the interior magenta:
   PAINT (160, 100), 2, 3

   ' Wait for a keystroke:
   Pause$ = INPUT$(1)

   ' Since the background is already magenta, CHR$(&HAA) tells
   ' PAINT to skip over the magenta rows in the pattern tile:
   PAINT (160, 100), Tile$, , CHR$(&HAA)

   5.8.2.4  Creating a Multicolor Pattern in Screen Mode 8

   In the EGA and VGA screen modes, it takes more than one eight-bit integer
   to define one row in a pattern tile. In these screen modes, a row is
   composed of several layers of eight-bit integers. This is because a pixel
   is represented three dimensionally in a stack of "bit planes" rather than
   sequentially in a single plane, as is the case with screen modes 1 and 2.
   For example, screen mode 8 has four of these bit planes. Each of the four
   bits per pixel in this screen mode is on a different plane.

   The following steps diagram the process for creating a multicolor pattern
   consisting of rows of alternating yellow and magenta. Note how each row in
   the pattern tile is represented by four parallel bytes:

   1. Define one row of pixels in the pattern tile. Each pixel in the row
      takes four bits, and each bit is in a different plane, as shown below:

      ┌───────────────────────────────────────────────────────────────────────
      │
      │                  Read bits for each
      │                 plane in this order.
      │                ────────────────────────────────
      │                 ─────────────────────────────────
      │              / / 1 / 1 / 0 / 0 / 0 / 0 / 1 / 1  /──── CHR$ (&HC3) + /
      │Read bits for/ / 0 / 0 / 1 / 1 / 1 / 1 / 0 / 0  /──── CHR$ (&H3C) + /
      │each pixel  / / 1 / 1 / 1 / 1 / 1 / 1 / 1 / 1  /──── CHR$ (&HFF) + /AD
      │in this    / / 0 / 0 / 1 / 1 / 1 / 1 / 0 / 0  /──── CHR$ (&H3C)  /CHR$
      │order.    / /────────────────────────────────/                    valu
      │     Magenta ─┘   │   │   │   │   │    │   │                       in t
      │         Magenta ─┘   │   │   │   │    │   │                       orde
      │              Yellow ─┘   │   │   │    │   │
      │                  Yellow ─┘   │   │    │   │   ┌───────────────────────
      │                      Yellow ─┘   │    │   │   │Color   Decimal    Bina
      │                          Yellow ─┘    │   │   │Yellow  14         1110
      │                              Magenta ─┘   │   │Magenta  5         0101
      │                                  Magenta ─┘   └───────────────────────
      │
      └───────────────────────────────────────────────────────────────────────

      Add the CHR$ values for all four bit planes to get one tile byte. This
      row is repeated in the pattern tile, so

      Row$(1) = Row$(2) =
            CHR$(&HC3) + CHR$(&H3C) + CHR$(&HFF) + CHR$(&H3C)

   2. Define another row of pixels in the pattern tile, as follows:

      ┌───────────────────────────────────────────────────────────────────────
      │
      │                  Read bits for each
      │                 plane in this order.
      │                ────────────────────────────────
      │                 ─────────────────────────────────
      │              / / 0 / 0 / 1 / 1 / 1 / 1 / 0 / 0  /──── CHR$ (&HC3) + /
      │Read bits for/ / 1 / 1 / 0 / 0 / 0 / 0 / 1 / 1  /──── CHR$ (&H3C) + /
      │each pixel  / / 1 / 1 / 1 / 1 / 1 / 1 / 1 / 1  /──── CHR$ (&HFF) + /AD
      │in this    / / 1 / 1 / 0 / 0 / 0 / 0 / 1 / 1  /──── CHR$ (&H3C)  /CHR$
      │order.    / /────────────────────────────────/                    valu
      │      Yellow ─┘   │   │   │   │   │    │   │                       in t
      │          Yellow ─┘   │   │   │   │    │   │                       orde
      │             Magenta ─┘   │   │   │    │   │
      │                 Magenta ─┘   │   │    │   │   ┌───────────────────────
      │                     Magenta ─┘   │    │   │   │Color   Decimal    Bina
      │                         Magenta ─┘    │   │   │Yellow  14         1110
      │                               Yellow ─┘   │   │Magenta  5         0101
      │                                   Yellow ─┘   └───────────────────────
      │
      └───────────────────────────────────────────────────────────────────────

      This row is also repeated in the pattern tile, so

      Row$(3) = Row$(4) =
            CHR$(&H3C) + CHR$(&HC3) + CHR$(&HFF) + CHR$(&HC3)

   Example

   The following example draws a box, then paints its interior with the
   pattern created in the preceding steps:

   SCREEN 8
   DIM Row$(1 TO 4)

   ' Two rows of alternating magenta and yellow:
   Row$(1) = CHR$(&HC3) + CHR$(&H3C) + CHR$(&HFF) + CHR$(&H3C)
   Row$(2) = Row$(1)

   ' Invert the pattern (two rows of alternating yellow
   ' and magenta):
   Row$(3) = CHR$(&H3C) + CHR$(&HC3) + CHR$(&HFF) + CHR$(&HC3)
   Row$(4) = Row$(3)

   ' Create a pattern tile from the rows defined above:
   FOR I% = 1 TO 4
      Tile$ = Tile$ + Row$(I%)
   NEXT I%

   ' Draw box and fill it with the pattern:
   LINE (50, 50)-(570, 150), , B
   PAINT (320, 100), Tile$


 5.9  DRAW: a Graphics Macro Language

   The DRAW statement is a miniature language by itself. It draws and paints
   images on the screen using a set of one- or two-letter commands, known as
   "macros," embedded in a string expression.

   DRAW offers the following advantages over the other graphics statements
   discussed so far:

   ■ The macro string argument to DRAW is compact: a single, short string can
     produce the same output as several LINE statements.

   ■ Images created with DRAW can easily be scaled──that is, enlarged or
     reduced in size──by using the S macro in the macro string.

   ■ Images created with DRAW can be rotated any number of degrees by using
     the TA macro in the macro string.

   Consult the QB Advisor for more information.

   Example

   The following program gives a brief introduction to the movement macros U,
   D, L, R, E, F, G, and H; the "plot/don't plot" macro B; and the color
   macro C. This program draws horizontal, vertical, and diagonal lines in
   different colors, depending on which DIRECTION key on the numeric keypad
   (UP, DOWN, LEFT, PGUP, PGDN, and so on) is pressed.

   This program is in the file named PLOTTER.BAS on the QuickBASIC
   distribution disks.

   ' Values for keys on the numeric keypad and the spacebar:
   CONST UP = 72, DOWN = 80, LFT = 75, RGHT = 77
   CONST UPLFT = 71, UPRGHT = 73, DOWNLFT = 79, DOWNRGHT = 81
   CONST SPACEBAR = " "

   ' Null$ is the first character of the two-character INKEY$
   ' value returned for direction keys such as UP and DOWN:
   Null$ = CHR$(0)

   ' Plot$ = "" means draw lines; Plot$ = "B" means
   ' move graphics cursor, but don't draw lines:
   Plot$ = ""

   PRINT "Use the cursor movement keys to draw lines."
   PRINT "Press spacebar to toggle line drawing on and off."
   PRINT "Press <ENTER> to begin. Press q to end the program."
   DO : LOOP WHILE INKEY$ = ""

   SCREEN 1

   DO
      SELECT CASE KeyVal$
         CASE Null$ + CHR$(UP)
            DRAW Plot$ + "C1 U2"
         CASE Null$ + CHR$(DOWN)
            DRAW Plot$ + "C1 D2"
         CASE Null$ + CHR$(LFT)
            DRAW Plot$ + "C2 L2"
         CASE Null$ + CHR$(RGHT)
            DRAW Plot$ + "C2 R2"
         CASE Null$ + CHR$(UPLFT)
            DRAW Plot$ + "C3 H2"
         CASE Null$ + CHR$(UPRGHT)
            DRAW Plot$ + "C3 E2"
         CASE Null$ + CHR$(DOWNLFT)
            DRAW Plot$ + "C3 G2"
         CASE Null$ + CHR$(DOWNRGHT)
            DRAW Plot$ + "C3 F2"
         CASE SPACEBAR
            IF Plot$ = "" THEN Plot$ = "B " ELSE Plot$ = ""
         CASE ELSE
            ' The user pressed some key other than one of the
            ' direction keys, the spacebar, or "q," so
            ' don't do anything.
      END SELECT

      KeyVal$ = INKEY$

   LOOP UNTIL KeyVal$ = "q"

   SCREEN 0, 0             ' Restore the screen to 80-column
   WIDTH 80                ' text mode and end.
   END

   Output

   Here's a sample sketch created with this program.

   ┌──────────────────────────────────────────────────────────────────┐
   │                                                                  │
   │                                                                  │
   │        / ────\ │     │ │ ┌────\  │   /        │                  │
   │        │     │ │     │ │ │       │ /          │                  │
   │        │     │ │     │ │ │       /\           │                  │
   │        │     │ │     │ │ │       │  \         │                  │
   │        \────\/ \─────/ │ \─────/ │    \                         │
   │              \                                                   │
   │        ─────────────────────────────────                         │
   │                                                                  │
   │          ───────────────────────────────                         │
   │                                                                  │
   │             ────────────────────────────                         │
   │                                                                  │
   └──────────────────────────────────────────────────────────────────┘


 5.10  Basic Animation Techniques

   Using only the graphics statements covered in earlier sections, you can do
   simple animation of objects on the screen. For instance, you can first
   draw a circle with CIRCLE, then redraw it with the background color to
   erase it, and finally recalculate the circle's center point and draw it in
   a new location.

   This technique works well enough for simple figures, but its disadvantages
   become apparent when animating more complex images. Even though the
   graphics statements are very fast, you can still notice the lag. Moreover,
   it is not possible to preserve the background with this method: when you
   erase the object, you also erase whatever was already on the screen.

   Two statements allow you to do high-speed animation: GET and PUT. You can
   create an image using output from statements such as PSET, LINE, CIRCLE,
   or PAINT, then take a "snapshot" of that image with GET, copying the image
   to memory. With PUT, you can then reproduce the image stored with GET
   anywhere on the screen or viewport.

 5.10.1  Saving Images with GET

   After you have created the original image on the screen, you need to
   calculate the x- and y-coordinates of a rectangle large enough to hold the
   entire image. You then use GET to copy the entire rectangle to memory. The
   syntax for the graphics GET statement is

   GET[[STEP]](x1, y1) -[[STEP]](x2, y2), array-name

   where (x1, y1) and (x2, y2) give the coordinates of a rectangle's
   upper-left and lower-right corners. The argument array-name refers to any
   numeric array. The size specified in a DIM statement for array-name
   depends on the following three factors:

   1. The height and width of the rectangle enclosing the image

   2. The screen mode chosen for graphics output

   3. The type of the array (integer, long integer, single precision, or
      double precision)

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Although the array used to store images can have any numeric type, it is
     strongly recommended that you use only integer arrays. All possible
     graphics patterns on the screen can be represented by integers. This is
     not the case, however, with single-precision or double-precision real
     numbers: some graphics patterns are not valid real numbers, and it could
     lead to unforeseen results if these patterns were stored in a
     real-number array.
   ──────────────────────────────────────────────────────────────────────────

   The formula for calculating the size in bytes of arrayname is

   size-in-bytes = 4 + height * planes * INT((width * bits-per-pixel/planes +
   7)/8)

   where height and width are the dimensions, in number of pixels, of the
   rectangle to get, and the value for bits-per-pixel depends on the number
   of colors available in the given screen mode. More colors mean more bits
   are required to define each pixel. In screen mode 1, two bits define a
   pixel, while in screen mode 2, one bit is enough. (See Section 5.8.2.1
   above, "Pattern-Tile Size in Different Screen Modes," for the general
   formula for bits-per-pixel.) The following list shows the value for planes
   for each of the screen modes:

   Screen Mode                                             Number of Bit
                                                           Planes
   ──────────────────────────────────────────────────────────────────────────
   1, 2, 11, and 13                                        1

   9 (64K of video memory) and 10                          2

   7, 8, 9 (more than 64K of video memory), and 12         4
   ──────────────────────────────────────────────────────────────────────────

   To get the number of elements that should be in the array, divide the
   size-in-bytes by the number of bytes for one element in the array. This is
   where the type of the array comes into play. If it is an integer array,
   each element takes two bytes of memory (the size of an integer), so
   size-in-bytes should be divided by two to get the actual size of the
   array. Similarly, if it is a long integer array, size-in-bytes should be
   divided by four (since one long integer requires four bytes of memory),
   and so on. If it is single precision, divide by four; if it is double
   precision, divide by eight.

   The following steps show how to calculate the size of an integer array
   large enough to hold a rectangle in screen mode 1 with coordinates (10,
   40) for the upper-left corner and (90, 80) for the lower-right corner:

   1. Calculate the height and width of the rectangle:

      RectHeight = ABS(y2 - y1) + 1 = 80 - 40 + 1 = 41
      RectWidth = ABS(x2 - x1) + 1 = 90 - 10 + 1 = 81

      Remember to add one after subtracting y1 from y2 or x1 from x2. For
      example, if x1 = 10 and x2 = 20, then the width of the rectangle is 20
      - 10 + 1, or 11.

   2. Calculate the size in bytes of the integer array:

      ByteSize = 4 + RectHeight * INT((RectWidth * BitsPerPixel + 7) / 8)
               = 4 + 41 * INT((81 * 2 + 7) / 8)
               = 4 + 41 * INT(169 / 8)
               = 4 + 41 * 21
               = 865

   3. Divide the size in bytes by the bytes per element (two for integers)
      and round the result up to the nearest whole number:

      865 / 2 = 433

   Therefore, if the name of the array is Image, the following DIM statement
   ensures that Image is big enough to copy the pixel information in the
   rectangle:

   DIM Image (1 TO 433) AS INTEGER

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Although the GET statement uses view coordinates after a WINDOW
     statement, you must use physical coordinates to calculate the size of
     the array used in GET. (See Section 5.6 above, "Redefining Viewport
     Coordinates with WINDOW," for more information on WINDOW and how to
     convert view coordinates to physical coordinates.)
   ──────────────────────────────────────────────────────────────────────────

   Note that the steps outlined above give the minimum size required for the
   array; however, any larger size will do. For example, the following
   statement also works:

   DIM Image (1 TO 500) AS INTEGER

   Example

   The following program draws an ellipse and paints its interior. A GET
   statement copies the rectangular area containing the ellipse into memory.
   (Section 5.10.2 below, "Moving Images with PUT," shows how to use the PUT
   statement to reproduce the ellipse in a different location.)

   SCREEN 1

   ' Dimension an integer array large enough
   ' to hold the rectangle:
   DIM Image (1 TO 433) AS INTEGER

   ' Draw an ellipse inside the rectangle, using magenta for
   ' the outline and painting the interior white:
   CIRCLE (50, 60), 40, 2, , , .5
   PAINT (50, 60), 3, 2

   ' Store the image of the rectangle in the array:
   GET (10, 40)-(90, 80), Image

 5.10.2  Moving Images with PUT

   While the GET statement allows you to take a snapshot of an image, PUT
   allows you to paste that image anywhere you want on the screen. A
   statement of the form

   PUT (x, y), array-name [[, actionverb]]

   copies the rectangular image stored in array-name back to the screen and
   places its upper-left corner at the point with coordinates (x, y). Note
   that only one coordinate pair appears in PUT.

   If a WINDOW statement appears in the program before PUT, the coordinates x
   and y refer to the lower-left corner of the rectangle. WINDOW SCREEN,
   however, does not have this effect; that is, after WINDOW SCREEN, x and y
   still refer to the upper-left corner of the rectangle.

   For example, adding the next line to the last example in Section 5.10.1
   above causes an exact duplicate of the painted ellipse to appear on the
   right side of the screen much more quickly than redrawing and repainting
   the same figure with CIRCLE and PAINT:

   PUT (200, 40), Image

   Take care not to specify coordinates that would put any part of the image
   outside the screen or active viewport, as in the following statements:

   SCREEN 2
   .
   .
   .
   ' Rectangle measures 141 pixels x 91 pixels:
   GET (10, 10)-(150, 100), Image
   PUT (510, 120), Image

   Unlike other graphics statements such as LINE or CIRCLE, PUT does not clip
   images lying outside the viewport. Instead, it produces an error message
   reading Illegal function call.

   One of the other advantages of the PUT statement is that you can control
   how the stored image interacts with what is already on the screen by using
   the argument actionverb. The actionverb argument can be one of the
   following options: PSET, PRESET, AND, OR, or XOR.

   If you do not care what happens to the existing screen background, use the
   PSET option, since it transfers an exact duplicate of the stored image to
   the screen and overwrites anything that was already there.

   Table 5.4 shows how other options affect the way the PUT statement causes
   pixels in a stored image to interact with pixels on the screen. In this
   table, a 1 means a pixel is on and a 0 means a pixel is off.

   Table 5.4  The Effect of Different Action Options in Screen Mode 2
╓┌─┌──────────────────┌─────────────────┌──────────────────┌─────────────────╖
                                        Pixel on Screen    Pixel on Screen
                      Pixel in          before PUT         after PUT
   Action Option      Stored Image      Statement          Statement
   ──────────────────────────────────────────────────────────────────────────
   PSET               0                 0                  0

                      0                 1                  0

                      1                 0                  1

                      1                 1                  1
                                        Pixel on Screen    Pixel on Screen
                      Pixel in          before PUT         after PUT
   Action Option      Stored Image      Statement          Statement
   ──────────────────────────────────────────────────────────────────────────
                     1                 1                  1

   PRESET             0                 0                  1

                      0                 1                  1

                      1                 0                  0

                      1                 1                  0

   AND                0                 0                  0

                      0                 1                  0

                      1                 0                  0

                      1                 1                  1
                                        Pixel on Screen    Pixel on Screen
                      Pixel in          before PUT         after PUT
   Action Option      Stored Image      Statement          Statement
   ──────────────────────────────────────────────────────────────────────────
                     1                 1                  1

   OR                 0                 0                  0

                      0                 1                  1

                      1                 0                  1

                      1                 1                  1

   XOR                0                 0                  0

                      0                 1                  1

                      1                 0                  1

                      1                 1                  0
                                        Pixel on Screen    Pixel on Screen
                      Pixel in          before PUT         after PUT
   Action Option      Stored Image      Statement          Statement
   ──────────────────────────────────────────────────────────────────────────
                     1                 1                  0
   ──────────────────────────────────────────────────────────────────────────


   As you can see, these options cause a PUT statement to treat pixels the
   same way logical operators treat numbers. The PRESET option is like the
   logical operator NOT in that it inverts the pixels in the stored image,
   regardless of what was on the screen. The options AND, OR, and XOR are
   identical to the logical operators with the same names; for example, the
   logical operation

   1 XOR 1

   gives 0 as its result, just as using the XOR option turns a pixel off when
   both the pixel in the image and the pixel in the background are on.

   The output from the following program shows the same image superimposed
   over a filled rectangle using each of the five options discussed above:

   SCREEN 2

   DIM CircImage (1 TO 485) AS INTEGER

   ' Draw and paint an ellipse then store its image with GET:
   CIRCLE (22, 100), 80, , , , 4
   PAINT (22, 100)
   GET (0, 20)-(44, 180), CircImage
   CLS

   ' Draw a box and fill it with a pattern:
   LINE (40, 40)-(600, 160), , B
   Pattern$ = CHR$(126) + CHR$(0) + CHR$(126) + CHR$(126)
   PAINT (50, 50), Pattern$

   ' Put the images of the ellipse over the box
   ' using the different action options:
   PUT (100, 20), CircImage, PSET
   PUT (200, 20), CircImage, PRESET
   PUT (300, 20), CircImage, AND
   PUT (400, 20), CircImage, OR
   PUT (500, 20), CircImage, XOR

   Output

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 199 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

   In screen modes supporting color, the options PRESET, AND, OR, and XOR
   produce a more complicated interaction, since color involves more than
   simply turning a pixel on or off. However, the analogy made above between
   these options and logical operators still holds in these modes. For
   example, if the current pixel on the screen is color 1 (cyan in palette 1)
   and the pixel in the overlaid image is color 2 (magenta in palette 1),
   then the color of the resulting pixel after a PUT statement depends on the
   option, as shown for just 2 of the 16 different combinations of image
   color and background color in Table 5.5.

   Table 5.5  The Effect of Different Action Options on Color in Screen Mode
   1 (Palette 1)
                                        Pixel Color on     Pixel Color on
                      Pixel Color in    Screen before      Screen after PUT
   Action Option      Stored Image      PUT Statement      Statement
   ──────────────────────────────────────────────────────────────────────────
   PSET               10 (magenta)      01 (cyan)          10 (magenta)

   PRESET             10 (magenta)      01 (cyan)          01 (cyan)

   AND                10 (magenta)      01 (cyan)          00 (black)

   OR                 10 (magenta)      01 (cyan)          11 (white)

   XOR                10 (magenta)      01 (cyan)          11 (white)
   ──────────────────────────────────────────────────────────────────────────

   In palette 1, cyan is assigned to attribute 1 (01 binary), magenta is
   assigned to attribute 2 (10 binary), and white is assigned to attribute 3
   (11 binary). If you have an EGA, you can use the PALETTE statement to
   assign different colors to the attributes 1, 2, and 3.

 5.10.3  Animation with GET and PUT

   One of the most useful things that can be done with the GET and PUT
   statements is animation. The two options best suited for animation are XOR
   and PSET. Animation done with PSET is faster; but as shown by the output
   from the last program, PSET erases the screen background. In contrast, XOR
   is slower but restores the screen background after the image is moved.
   Animation with XOR is done with the following four steps:

   1. Put the object on the screen with XOR.

   2. Recalculate the new position of the object.

   3. Put the object on the screen a second time at the old location, using
      XOR again, this time to remove the old image.

   4. Go to step 1, but this time put the object at the new location.

   Movement done with these four steps leaves the background unchanged after
   step 3. Flicker can be reduced by minimizing the time between steps 4 and
   1 and by making sure that there is enough time delay between steps 1 and
   3. If more than one object is being animated, every object should be
   processed at once, one step at a time.

   If it is not important to preserve the background, use the PSET option for
   animation. The idea is to leave a border around the image when you copy it
   with the GET statement. If this border is as large or larger than the
   maximum distance the object will move, then each time the image is put in
   a new location, the border erases all traces of the image in the old
   location. This method can be somewhat faster than the method using XOR
   described above, since only one PUT statement is required to move an
   object (although you must move a larger image).

   Examples

   The following example shows how to use PUT with the PSET option to produce
   the effect of a ball bouncing off the bottom and sides of a box. Note in
   the output that follows how the rectangle containing the ball, specified
   in the GET statement, erases the filled box and the printed message.

   This program is in the file named BALLPSET.BAS on the QuickBASIC
   distribution disks.

   DECLARE FUNCTION GetArraySize (WLeft, WRight, WTop,
   WBottom)

   SCREEN 2

   ' Define a viewport and draw a border around it:
   VIEW (20, 10)-(620, 190),,1

   CONST PI = 3.141592653589#

   ' Redefine the coordinates of the viewport with view
   ' coordinates:
   WINDOW (-3.15, -.14)-(3.56, 1.01)

   ' Arrays in program are now dynamic:
   ' $DYNAMIC

   ' Calculate the view coordinates for the top and bottom of a
   ' rectangle large enough to hold the image that will be
   ' drawn with CIRCLE and PAINT:
   WLeft = -.21
   WRight = .21
   WTop = .07
   WBottom = -.07

   ' Call the GetArraySize function,
   ' passing it the rectangle's view coordinates:
   ArraySize% = GetArraySize(WLeft, WRight, WTop, WBottom)

   DIM Array (1 TO ArraySize%) AS INTEGER

   ' Draw and paint the circle:
   CIRCLE (0, 0), .18
   PAINT (0, 0)

   ' Store the rectangle in Array:
   GET (WLeft, WTop)-(WRight, WBottom), Array
   CLS
   ' Draw a box and fill it with a pattern:
   LINE (-3, .8)-(3.4, .2), , B
   Pattern$ = CHR$(126) + CHR$(0) + CHR$(126) + CHR$(126)
   PAINT (0, .5), Pattern$

   LOCATE 21, 29
   PRINT "Press any key to end."

   ' Initialize loop variables:
   StepSize = .02
   StartLoop = -PI
   Decay = 1

   DO
      EndLoop = -StartLoop
      FOR X = StartLoop TO EndLoop STEP StepSize

         ' Each time the ball "bounces" (hits the bottom of the
         ' viewport), the Decay variable gets smaller, making
         ' the height of the next bounce smaller:
         Y = ABS(COS(X)) * Decay - .14
         IF Y < -.13 THEN Decay = Decay * .9

         ' Stop if key pressed or Decay less than .01:
         Esc$ = INKEY$
         IF Esc$ <> "" OR Decay < .01 THEN EXIT FOR

         ' Put the image on the screen. The StepSize offset is
         ' smaller than the border around the circle. Thus,
         ' each time the image moves, it erases any traces
         ' left from the previous PUT (and also erases anything
         ' else on the screen):
         PUT (X, Y), Array, PSET
      NEXT X

      ' Reverse direction:
      StepSize = -StepSize
      StartLoop = -StartLoop
   LOOP UNTIL Esc$ <> "" OR Decay < .01

   END

   FUNCTION GetArraySize (WLeft, WRight, WTop, WBottom) STATIC

      ' Map the view coordinates passed to this function to
      ' their physical-coordinate equivalents:
      VLeft = PMAP(WLeft, 0)
      VRight = PMAP(WRight, 0)
      VTop = PMAP(WTop, 1)
      VBottom = PMAP(WBottom, 1)

   ' Calculate the height and width in pixels
      ' of the enclosing rectangle:
      RectHeight = ABS(VBottom - VTop) + 1
      RectWidth = ABS(VRight - VLeft) + 1

      ' Calculate size in bytes of array:
      ByteSize = 4 + RectHeight * INT((RectWidth + 7) \ 8)

      ' Array is integer, so divide bytes by two:
      GetArraySize = ByteSize \ 2 + 1
   END FUNCTION

   Output

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 203 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

   Contrast the preceding program with the next program, which uses PUT with
   XOR to preserve the screen's background, according to the four steps
   outlined above. Note how the rectangle containing the ball is smaller than
   in the preceding program, since it is not necessary to leave a border.
   Also note that two PUT statements are required, one to make the image
   visible and another to make it disappear. Finally, observe the empty
   FOR...NEXT delay loop between the PUT statements; this loop reduces the
   flicker that results from the image appearing and disappearing too
   rapidly.

   This program is in the file named BALLXOR.BAS on the QuickBASIC
   distribution disks.

   .
   .
   .
   ' The rectangle is smaller than the one in the previous
   ' program, which means Array is also smaller:
   WLeft = -.18
   WRight = .18
   WTop = .05
   WBottom = -.05
   .
   .
   .
   DO
      EndLoop = -StartLoop
      FOR X = StartLoop TO EndLoop STEP StepSize
         Y = ABS(COS(X)) * Decay - .14

         ' The first PUT statement places the image
         ' on the screen:
         PUT (X,Y), Array, XOR

         ' Use an empty FOR...NEXT loop to delay
         ' the program and reduce image flicker:
         FOR I = 1 TO 5: NEXT I

         IF Y < -.13 THEN Decay = Decay * .9
         Esc$ = INKEY$
         IF Esc$ <> "" OR Decay < .01 THEN EXIT FOR

         ' The second PUT statement erases the image and
         ' restores the background:
         PUT (X, Y), Array, XOR
      NEXT X

      StepSize = -StepSize
      StartLoop = -StartLoop
   LOOP UNTIL Esc$ <> "" OR Decay < .01

   END
   .
   .
   .

   Output

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 205 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

 5.10.4  Animating with Screen Pages

   This section describes an animation technique that utilizes multiple pages
   of your computer's video memory.

   Pages in video memory are analogous to pages in a book. Depending on the
   graphics capability of your computer, what you see displayed on the screen
   may only be part of the video memory available──just as what you see when
   you open a book is only part of the book. However, unlike a book, the
   unseen pages of your computer's video memory can be active; that is, while
   you are looking at one page on the screen, graphics output can be taking
   place on the others. It's as if the author of a book were still writing
   new pages even as you were reading the book.

   The area of video memory visible on the screen is called the "visual
   page," while the area of video memory where graphics statements put their
   output is called the "active page." The SCREEN statement allows you to
   select visual and active screen pages with the following syntax:

   SCREEN[[mode]],[[,[[apage]][[, vpage]]]]

   In this syntax, apage is the number of the active page, and vpage is the
   number of the visual page. The active page and the visual page can be one
   and the same (and are by default when the apage or vpage arguments are not
   used with SCREEN, in which case the value of both arguments is 0).

   You can animate objects on the screen by selecting a screen mode with more
   than one video memory page, then alternating the pages, sending output to
   one or more active pages while displaying finished output on the visual
   page. This technique makes an active page visible only when output to that
   page is complete. Since the viewer sees only a finished image, the display
   is instantaneous.

   Example

   The following program demonstrates the technique discussed above. It
   selects screen mode 7, which has two pages, then draws a cube with the
   DRAW statement. This cube is then rotated through successive 15° angles by
   changing the value of the TA macro in the string used by DRAW. By swapping
   the active and visual pages back and forth, this program always shows a
   completed cube while a new one is being drawn.

   This program is in the file named CUBE.BAS on the QuickBASIC distribution
   disks.

   ' Define the macro string used to draw the cube
   ' and paint its sides:
   One$ =  "BR30 BU25 C1 R54 U45 L54 D45 BE20 P1,1 G20 C2 G20"
   Two$ =  "R54 E20 L54 BD5 P2,2 U5 C4 G20 U45 E20 D45 BL5 P4,4"
   Plot$ = One$ + Two$

   APage% = 1      ' Initialize values for the active and visual
   VPage% = 0      ' pages as well as the angle of rotation.
   Angle% = 0

   DO
      SCREEN 7, , APage%, VPage% ' Draw to the active page
                                 ' while showing the visual page.

      CLS 1                      ' Clear the active page.

      ' Rotate the cube "Angle%" degrees:
      DRAW "TA" + STR$(Angle%) + Plot$

      ' Angle% is some multiple of 15 degrees:
      Angle% = (Angle% + 15) MOD 360

      ' Drawing is complete, so make the cube visible in its
      ' new position by switching the active and visual pages:
      SWAP APage%, VPage%

   LOOP WHILE INKEY$ = ""        ' A keystroke ends the program.

   END


 5.11  Sample Applications

   The sample applications in this chapter are a bar-graph generator, a
   program that plots points in the Mandelbrot Set using different colors,
   and a pattern editor.

 5.11.1  Bar-Graph Generator (BAR.BAS)

   This program uses all the forms of the LINE statement presented above in
   Sections 5.3.2.1-5.3.2.3 to draw a filled bar chart. Each bar is filled
   with a pattern specified in a PAINT statement. The input for the program
   consists of titles for the graph, labels for the x- and y-axes, and a set
   of up to five labels (with associated values) for the bars.

   Statements and Functions Used

   This program demonstrates the use of the following graphics statements:

   ■ LINE

   ■ PAINT (with a pattern)

   ■ SCREEN

   Program Listing

   The bar-graph generator program BAR.BAS is listed below.

   ' Define type for the titles:
   TYPE TitleType
      MainTitle AS STRING * 40
      XTitle AS STRING * 40
      YTitle AS STRING * 18
   END TYPE

   DECLARE SUB InputTitles (T AS TitleType)
   DECLARE FUNCTION DrawGraph$ (T AS TitleType, Label$(), Value!(), N%)
   DECLARE FUNCTION InputData% (Label$(), Value!())

   ' Variable declarations for titles and bar data:
   DIM Titles AS TitleType, Label$(1 TO 5), Value(1 TO 5)

   CONST FALSE = 0, TRUE = NOT FALSE

   DO
      InputTitles Titles
      N% = InputData%(Label$(), Value())
      IF N% <> FALSE THEN
         NewGraph$ = DrawGraph$(Titles, Label$(), Value(), N%)
      END IF
   LOOP WHILE NewGraph$ = "Y"

   END

   ' ======================== DRAWGRAPH ======================
   '   Draws a bar graph from the data entered in the
   '   INPUTTITLES and INPUTDATA procedures.
   ' =========================================================

   FUNCTION DrawGraph$ (T AS TitleType, Label$(), Value(), N%) STATIC

      ' Set size of graph:
      CONST GRAPHTOP = 24, GRAPHBOTTOM = 171
      CONST GRAPHLEFT = 48, GRAPHRIGHT = 624
      CONST YLENGTH = GRAPHBOTTOM - GRAPHTOP

      ' Calculate maximum and minimum values:
      YMax = 0
      YMin = 0
      FOR I% = 1 TO N%
         IF Value(I%) < YMin THEN YMin = Value(I%)
         IF Value(I%) > YMax THEN YMax = Value(I%)
      NEXT I%

      ' Calculate width of bars and space between them:
      BarWidth = (GRAPHRIGHT - GRAPHLEFT) / N%
      BarSpace = .2 * BarWidth
      BarWidth = BarWidth - BarSpace

      SCREEN 2
      CLS

      ' Draw y-axis:
      LINE (GRAPHLEFT, GRAPHTOP)-(GRAPHLEFT, GRAPHBOTTOM), 1

      ' Draw main graph title:
      Start% = 44 - (LEN(RTRIM$(T.MainTitle)) / 2)
      LOCATE 2, Start%
      PRINT RTRIM$(T.MainTitle);

      ' Annotate y-axis:
      Start% = CINT(13 - LEN(RTRIM$(T.YTitle)) / 2)
      FOR I% = 1 TO LEN(RTRIM$(T.YTitle))
         LOCATE Start% + I% - 1, 1
         PRINT MID$(T.YTitle, I%, 1);
      NEXT I%

      ' Calculate scale factor so labels aren't bigger than four digits:
      IF ABS(YMax) > ABS(YMin) THEN
         Power = YMax
      ELSE
         Power = YMin
      END IF
      Power = CINT(LOG(ABS(Power) / 100) / LOG(10))
      IF Power < 0 THEN Power = 0

      ' Scale minimum and maximum values down:
      ScaleFactor = 10 ^ Power
      YMax = CINT(YMax / ScaleFactor)
      YMin = CINT(YMin / ScaleFactor)


      ' If power isn't zero then put scale factor on chart:
      IF Power <> 0 THEN
         LOCATE 3, 2
         PRINT "x 10^"; LTRIM$(STR$(Power))
      END IF

      ' Put tic mark and number for Max point on y-axis:
      LINE (GRAPHLEFT - 3, GRAPHTOP) -STEP(3, 0)
      LOCATE 4, 2
      PRINT USING "####"; YMax

      ' Put tic mark and number for Min point on y-axis:
      LINE (GRAPHLEFT - 3, GRAPHBOTTOM) -STEP(3, 0)
      LOCATE 22, 2
      PRINT USING "####"; YMin

      YMax = YMax * ScaleFactor ' Scale minimum and maximum back
      YMin = YMin * ScaleFactor ' up for charting calculations.

      ' Annotate x-axis:
      Start% = 44 - (LEN(RTRIM$(T.XTitle)) / 2)
      LOCATE 25, Start%
      PRINT RTRIM$(T.XTitle);

      ' Calculate the pixel range for the y-axis:
      YRange = YMax - YMin

      ' Define a diagonally striped pattern:
      Tile$ = CHR$(1)+CHR$(2)+CHR$(4)+CHR$(8)+CHR$(16)+CHR$(32)+CHR$(64)+CHR$
   (128)

      ' Draw a zero line if appropriate:
      IF YMin < 0 THEN
         Bottom = GRAPHBOTTOM - ((-YMin) / YRange * YLENGTH)
         LOCATE INT((Bottom - 1) / 8) + 1, 5
         PRINT "0";
      ELSE
         Bottom = GRAPHBOTTOM
      END IF

      ' Draw x-axis:
      LINE (GRAPHLEFT - 3, Bottom)-(GRAPHRIGHT, Bottom)
      ' Draw bars and labels:
      Start% = GRAPHLEFT + (BarSpace / 2)
      FOR I% = 1 TO N%

         ' Draw a bar label:
         BarMid = Start% + (BarWidth / 2)
         CharMid = INT((BarMid - 1) / 8) + 1
         LOCATE 23, CharMid - INT(LEN(RTRIM$(Label$(I%))) / 2)
         PRINT Label$(I%);

         ' Draw the bar and fill it with the striped pattern:
         BarHeight = (Value(I%) / YRange) * YLENGTH
         LINE (Start%, Bottom) -STEP(BarWidth, -BarHeight), , B
         PAINT (BarMid, Bottom - (BarHeight / 2)), Tile$, 1

         Start% = Start% + BarWidth + BarSpace
      NEXT I%
      LOCATE 1, 1
      PRINT "New graph? ";
      DrawGraph$ = UCASE$(INPUT$(1))

   END FUNCTION

   ' ======================== INPUTDATA ======================
   '     Gets input for the bar labels and their values
   ' =========================================================

   FUNCTION InputData% (Label$(), Value()) STATIC

      ' Initialize the number of data values:
      NumData% = 0

      ' Print data-entry instructions:
      CLS
      PRINT "Enter data for up to 5 bars:"
      PRINT "   * Enter the label and value for each bar."
      PRINT "   * Values can be negative."
      PRINT "   * Enter a blank label to stop."
      PRINT
      PRINT "After viewing the graph, press any key ";
      PRINT "to end the program."

      ' Accept data until blank label or 5 entries:
      Done% = FALSE
      DO
         NumData% = NumData% + 1
         PRINT
         PRINT "Bar("; LTRIM$(STR$(NumData%)); "):"
         INPUT ; "        Label? ", Label$(NumData%)

         ' Only input value if label isn't blank:
         IF Label$(NumData%) <> "" THEN
            LOCATE , 35
            INPUT "Value? ", Value(NumData%)

         ' If label is blank, decrement data counter
         ' and set Done flag equal to TRUE:
         ELSE
            NumData% = NumData% - 1
            Done% = TRUE
         END IF
      LOOP UNTIL (NumData% = 5) OR Done%

      ' Return the number of data values input:
      InputData% = NumData%

   END FUNCTION

   ' ====================== INPUTTITLES ======================
   '     Accepts input for the three different graph titles
   ' =========================================================

   SUB InputTitles (T AS TitleType) STATIC
      SCREEN 0, 0          ' Set text screen.
      DO                   ' Input titles.
         CLS
         INPUT "Enter main graph title: ", T.MainTitle
         INPUT "Enter x-axis title    : ", T.XTitle
         INPUT "Enter y-axis title    : ", T.YTitle

         ' Check to see if titles are OK:
         LOCATE 7, 1
         PRINT "OK (Y to continue, N to change)? ";
         LOCATE , , 1
         OK$ = UCASE$(INPUT$(1))
      LOOP UNTIL OK$ = "Y"
   END SUB

   Output

   ┌─────────────────────────────────────────────────────────────────┐
   │    New graph?                                                   │
   │                    LOW TEMPERATURE BY MONTH                     │
   │     15 ┐                                        ┌───────┐       │
   │ C      │                                        │░░░░░░░│       │
   │ e      │                                        │░░░░░░░│       │
   │ l      │                                        │░░░░░░░│       │
   │ s      │                                        │░░░░░░░│       │
   │ i      │                                        │░░░░░░░│       │
   │ u      │                                        │░░░░░░░│       │
   │ s      │                              ┌───────┐ │░░░░░░░│       │
   │        │                              │░░░░░░░│ │░░░░░░░│       │
   │ D      │                              │░░░░░░░│ │░░░░░░░│       │
   │ e    0 ┼┬───────┬─┬───────┬─┬───────┬─┴───────┴─┴───────┴─      │
   │ g      ││░░░░░░░│ │░░░░░░░│ │░░░░░░░│                           │
   │ r      ││░░░░░░░│ │░░░░░░░│ └───────┘                           │
   │ e      ││░░░░░░░│ │░░░░░░░│                                     │
   │ e      ││░░░░░░░│ │░░░░░░░│                                     │
   │ s      │└───────┘ │░░░░░░░│                                     │
   │      -9┘          └───────┘                                     │
   │          January   February    March    April     May           │
   │                              Month                              │
   └─────────────────────────────────────────────────────────────────┘

 5.11.2  Color in a Figure Generated Mathematically (MANDEL.BAS)

   This program uses BASIC graphics statements to generate a figure known as
   a "fractal." A fractal is a graphic representation of what happens to
   numbers when they are subjected to a repeated sequence of mathematical
   operations. The fractal generated by this program shows a subset of the
   class of numbers known as complex numbers; this subset is called the
   "Mandelbrot Set," named after Benoit B. Mandelbrot of the IBM Thomas J.
   Watson Research Center.

   Briefly, complex numbers have two parts, a real part and a so-called
   imaginary part, some multiple of the √-1. Squaring a complex number, then
   plugging the real and imaginary parts back into a second complex number,
   squaring the new complex number, and repeating the process causes some
   complex numbers to get very large fairly fast. However, others hover
   around some stable value. The stable values are in the Mandelbrot Set and
   are represented in this program by the color black. The unstable values──
   that is, the ones that are moving away from the Mandelbrot Set──are
   represented by the other colors in the palette. The smaller the color
   attribute, the more unstable the point.

   See A.K. Dewdney's column, "Computer Recreations," in Scientific American,
   August 1985, for more background on the Mandelbrot Set.

   This program also tests for the presence of an EGA card, and if one is
   present, it draws the Mandelbrot Set in screen mode 8. After drawing each
   line, the program rotates the 16 colors in the palette with a PALETTE
   USING statement. If there is no EGA card, the program draws a four-color
   (white, magenta, cyan, and black) Mandelbrot Set in screen mode 1.

   Statements and Functions Used

   This program demonstrates the use of the following graphics statements:

   ■ LINE

   ■ PALETTE USING

   ■ PMAP

   ■ PSET

   ■ SCREEN

   ■ VIEW

   ■ WINDOW

   Program Listing

   DEFINT A-Z           ' Default variable type is integer.

   DECLARE SUB ShiftPalette ()
   DECLARE SUB WindowVals (WL%, WR%, WT%, WB%)
   DECLARE SUB ScreenTest (EM%, CR%, VL%, VR%, VT%, VB%)

   CONST FALSE = 0, TRUE = NOT FALSE ' Boolean constants

   ' Set maximum number of iterations per point:
   CONST MAXLOOP = 30, MAXSIZE = 1000000

   DIM PaletteArray(15)
   FOR I = 0 TO 15: PaletteArray(I) = I: NEXT I

   ' Call WindowVals to get coordinates of window corners:
   WindowVals WLeft, WRight, WTop, WBottom

   ' Call ScreenTest to find out if this is an EGA machine
   ' and get coordinates of viewport corners:
   ScreenTest EgaMode, ColorRange, VLeft, VRight, VTop, VBottom

   ' Define viewport and corresponding window:
   VIEW (VLeft, VTop)-(VRight, VBottom), 0, ColorRange
   WINDOW (WLeft, WTop)-(WRight, WBottom)

   LOCATE 24, 10 : PRINT "Press any key to quit.";

   XLength = VRight - VLeft
   YLength = VBottom - VTop
   ColorWidth = MAXLOOP \ ColorRange

   ' Loop through each pixel in viewport and calculate
   ' whether or not it is in the Mandelbrot Set:
   FOR Y = 0 TO YLength       ' Loop through every line
                              ' in the viewport.
      LogicY = PMAP(Y, 3)     ' Get the pixel's view
                              ' y-coordinate.
      PSET (WLeft, LogicY)    ' Plot leftmost pixel in the line.
      OldColor = 0            ' Start with background color.

      FOR X = 0 TO XLength    ' Loop through every pixel
                              ' in the line.
         LogicX = PMAP(X, 2)  ' Get the pixel's view
                              ' x-coordinate.
         MandelX& = LogicX
         MandelY& = LogicY


         ' Do the calculations to see if this point
         ' is in the Mandelbrot Set:
         FOR I = 1 TO MAXLOOP
            RealNum& = MandelX& * MandelX&
            ImagNum& = MandelY& * MandelY&
            IF (RealNum& + ImagNum&) >= MAXSIZE THEN EXIT FOR
            MandelY& = (MandelX& * MandelY&) \ 250 + LogicY
            MandelX& = (RealNum& - ImagNum&) \ 500 + LogicX
         NEXT I

         ' Assign a color to the point:
         PColor = I \ ColorWidth

         ' If color has changed, draw a line from
         ' the last point referenced to the new point,
         ' using the old color:
         IF PColor <> OldColor THEN
            LINE -(LogicX, LogicY), (ColorRange - OldColor)
            OldColor = PColor
         END IF

         IF INKEY$ <> "" THEN END
      NEXT X

      ' Draw the last line segment to the right edge
      ' of the viewport:
      LINE -(LogicX, LogicY), (ColorRange - OldColor)

      ' If this is an EGA machine, shift the palette after
      ' drawing each line:
      IF EgaMode THEN ShiftPalette
   NEXT Y

   DO
      ' Continue shifting the palette
      ' until the user presses a key:
      IF EgaMode THEN ShiftPalette
   LOOP WHILE INKEY$ = ""

   SCREEN 0, 0             ' Restore the screen to text mode,
   WIDTH 80                ' 80 columns.
   END

   BadScreen:              ' Error handler that is invoked if
      EgaMode = FALSE      ' there is no EGA graphics card
      RESUME NEXT

   ' ====================== ShiftPalette =====================
   '    Rotates the palette by one each time it is called
   ' =========================================================

   SUB ShiftPalette STATIC
      SHARED PaletteArray(), ColorRange

      FOR I = 1 TO ColorRange
         PaletteArray(I) = (PaletteArray(I) MOD ColorRange) + 1
      NEXT I
      PALETTE USING PaletteArray(0)

   END SUB

   ' ======================= ScreenTest ======================
   '    Uses a SCREEN 8 statement as a test to see if user has
   '    EGA hardware. If this causes an error, the EM flag is
   '    set to FALSE, and the screen is set with SCREEN 1.

   '    Also sets values for corners of viewport (VL = left,
   '    VR = right, VT = top, VB = bottom), scaled with the
   '    correct aspect ratio so viewport is a perfect square.
   ' =========================================================

   SUB ScreenTest (EM, CR, VL, VR, VT, VB) STATIC
      EM = TRUE
      ON ERROR GOTO BadScreen
      SCREEN 8, 1
      ON ERROR GOTO 0

      IF EM THEN                   ' No error, SCREEN 8 is OK.
         VL = 110: VR = 529
         VT = 5: VB = 179
         CR = 15                   ' 16 colors (0 - 15)

      ELSE                         ' Error, so use SCREEN 1.
         SCREEN 1, 1
         VL = 55: VR = 264
         VT = 5: VB = 179
         CR = 3                    ' 4 colors (0 - 3)
      END IF

   END SUB

   ' ======================= WindowVals ======================
   '     Gets window corners as input from the user, or sets
   '     values for the corners if there is no input
   ' =========================================================

   SUB WindowVals (WL, WR, WT, WB) STATIC
      CLS
      PRINT "This program prints the graphic representation of"
      PRINT "the complete Mandelbrot Set. The default window"
      PRINT "is from (-1000,625) to (250,-625). To zoom in on"
      PRINT "part of the figure, input coordinates inside"
      PRINT "this window."
      PRINT "Press <ENTER> to see the default window or"
      PRINT "any other key to input window coordinates: ";
      LOCATE , , 1
      Resp$ = INPUT$(1)

      ' User didn't press ENTER, so input window corners:
      IF Resp$ <> CHR$(13) THEN
         PRINT
         INPUT "x-coordinate of upper-left corner: ", WL
         DO
            INPUT "x-coordinate of lower-right corner: ", WR
            IF WR <= WL THEN
            PRINT "Right corner must be greater than left corner."
            END IF
         LOOP WHILE WR <= WL
         INPUT "y-coordinate of upper-left corner: ", WT
         DO
            INPUT "y-coordinate of lower-right corner: ", WB
            IF WB >= WT THEN
            PRINT "Bottom corner must be less than top corner."
            END IF
         LOOP WHILE WB >= WT

      ' User pressed ENTER, so set default values:
      ELSE
         WL = -1000
         WR = 250
         WT = 625
         WB = -625
      END IF
   END SUB

   Output

   The following figure shows the Mandelbrot Set in screen mode 1. This is
   the output you see if you have a CGA and you choose the default window
   coordinates.

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 217 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

   The next figure shows the Mandelbrot Set with (x, y) coordinates of (-500,
   250) for the upper-left corner and (-300, 50) for the lower-right corner.
   This figure is drawn in screen mode 8, the default for an EGA or VGA.

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 217 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘

 5.11.3  Pattern Editor (EDPAT.BAS)

   This program allows you to edit a pattern tile for use with PAINT. While
   you are editing the tile on the left side of the screen, you can check the
   appearance of the finished pattern on the right side of the screen. When
   you have finished editing the pattern tile, the program prints the integer
   arguments used by the CHR$ statement to draw each row of the tile.

   Statements and Functions Used

   This program demonstrates the use of the following graphics statements:

   ■ LINE

   ■ PAINT (with pattern)

   ■ VIEW

   Program Listing

   DECLARE SUB DrawPattern ()
   DECLARE SUB EditPattern ()
   DECLARE SUB Initialize ()
   DECLARE SUB ShowPattern (OK$)

   DIM Bit%(0 TO 7), Pattern$, Esc$, PatternSize%

   DO
      Initialize
      EditPattern
      ShowPattern OK$
   LOOP WHILE OK$ = "Y"

   END

   ' ======================= DRAWPATTERN ====================
   '  Draws a patterned rectangle on the right side of screen
   ' ========================================================

   SUB DrawPattern STATIC
   SHARED Pattern$

      VIEW (320, 24)-(622, 160), 0, 1  ' Set view to rectangle.
      PAINT (1, 1), Pattern$           ' Use PAINT to fill it.
      VIEW                             ' Set view to full screen.

   END SUB

   ' ======================= EDITPATTERN =====================
   '                  Edits a tile-byte pattern
   ' =========================================================

   SUB EditPattern STATIC
   SHARED Pattern$, Esc$, Bit%(), PatternSize%

      ByteNum% = 1         ' Starting position.
      BitNum% = 7
      Null$ = CHR$(0)      ' CHR$(0) is the first byte of the
                           ' two-byte string returned when a
                           ' direction key such as UP or DOWN is
                           ' pressed.
      DO

         ' Calculate starting location on screen of this bit:
         X% = ((7 - BitNum%) * 16) + 80
         Y% = (ByteNum% + 2) * 8

         ' Wait for a key press (flash cursor each 3/10 second):
         State% = 0
         RefTime = 0
         DO

            ' Check timer and switch cursor state if 3/10 second:
            IF ABS(TIMER - RefTime) > .3 THEN
               RefTime = TIMER
               State% = 1 - State%

            ' Turn the border of bit on and off:
              LINE (X%-1, Y%-1) -STEP(15, 8), State%, B
            END IF

            Check$ = INKEY$ ' Check for keystroke.

         LOOP WHILE Check$ = "" ' Loop until a key is pressed.

         ' Erase cursor:
         LINE (X%-1, Y%-1) -STEP(15, 8), 0, B

         SELECT CASE Check$ ' Respond to keystroke.

         CASE CHR$(27)      ' ESC key pressed:
            EXIT SUB        ' exit this subprogram.

   CASE CHR$(32)      ' SPACEBAR pressed:
                            ' reset state of bit.

            ' Invert bit in pattern string:
            CurrentByte% = ASC(MID$(Pattern$, ByteNum%, 1))
            CurrentByte% = CurrentByte% XOR Bit%(BitNum%)
            MID$ (Pattern$, ByteNum%) = CHR$(CurrentByte%)

            ' Redraw bit on screen:
            IF (CurrentByte% AND Bit%(BitNum%)) <> 0 THEN
                CurrentColor% = 1
            ELSE
                CurrentColor% = 0
            END IF
            LINE (X%+1, Y%+1) -STEP(11, 4), CurrentColor%, BF

         CASE CHR$(13)              ' ENTER key pressed: draw
            DrawPattern             ' pattern in box on right.

         CASE Null$ + CHR$(75)      ' LEFT key: move cursor left.

            BitNum% = BitNum% + 1
            IF BitNum% > 7 THEN BitNum% = 0

         CASE Null$ + CHR$(77)      ' RIGHT key: move cursor right.

            BitNum% = BitNum% - 1
            IF BitNum% < 0 THEN BitNum% = 7

         CASE Null$ + CHR$(72)      ' UP key: move cursor up.

            ByteNum% = ByteNum% - 1
            IF ByteNum% < 1 THEN ByteNum% = PatternSize%

         CASE Null$ + CHR$(80)      ' DOWN key: move cursor down.

            ByteNum% = ByteNum% + 1
            IF ByteNum% > PatternSize% THEN ByteNum% = 1

         CASE ELSE
            ' User pressed a key other than ESC, SPACEBAR,
            ' ENTER, UP, DOWN, LEFT, or RIGHT, so don't
            ' do anything.
         END SELECT
      LOOP
   END SUB

   ' ======================= INITIALIZE ======================
   '             Sets up starting pattern and screen
   ' =========================================================

   SUB Initialize STATIC
   SHARED Pattern$, Esc$, Bit%(), PatternSize%

      Esc$ = CHR$(27)              ' ESC character is ASCII 27.

      ' Set up an array holding bits in positions 0 to 7:
      FOR I% = 0 TO 7
         Bit%(I%) = 2 ^ I%
      NEXT I%

      CLS

      ' Input the pattern size (in number of bytes):
      LOCATE 5, 5
      PRINT "Enter pattern size (1-16 rows):";
      DO
         LOCATE 5, 38
         PRINT "  ";
         LOCATE 5, 38
         INPUT "", PatternSize%
      LOOP WHILE PatternSize% < 1 OR PatternSize% > 16

      ' Set initial pattern to all bits set:
      Pattern$ = STRING$(PatternSize%, 255)

      SCREEN 2             ' 640 x 200 monochrome graphics mode

      ' Draw dividing lines:
      LINE (0, 10)-(635, 10), 1
      LINE (300, 0)-(300, 199)
      LINE (302, 0)-(302, 199)

      ' Print titles:
      LOCATE 1, 13: PRINT "Pattern Bytes"
      LOCATE 1, 53: PRINT "Pattern View"

   ' Draw editing screen for pattern:
      FOR I% = 1 TO PatternSize%

         ' Print label on left of each line:
         LOCATE I% + 3, 8
         PRINT USING "##:"; I%

         ' Draw "bit" boxes:
         X% = 80
         Y% = (I% + 2) * 8
         FOR J% = 1 TO 8
            LINE (X%, Y%) -STEP(13, 6), 1, BF
            X% = X% + 16
         NEXT J%
      NEXT I%

      DrawPattern          ' Draw   "Pattern View" box.

      LOCATE 21, 1
      PRINT "DIRECTION keys........Move cursor"
      PRINT "SPACEBAR............Changes point"
      PRINT "ENTER............Displays pattern"
      PRINT "ESC.........................Quits";

   END SUB

   ' ======================== SHOWPATTERN ====================
   '   Prints the CHR$ values used by PAINT to make pattern
   ' =========================================================

   SUB ShowPattern (OK$) STATIC
   SHARED Pattern$, PatternSize%

      ' Return screen to 80-column text mode:
      SCREEN 0, 0
      WIDTH 80

      PRINT "The following characters make up your pattern:"
      PRINT

      ' Print out the value for each pattern byte:
      FOR I% = 1 TO PatternSize%
         PatternByte% = ASC(MID$(Pattern$, I%, 1))
         PRINT "CHR$("; LTRIM$(STR$(PatternByte%)); ")"
      NEXT I%
      PRINT
      LOCATE , , 1
      PRINT "New pattern? ";
      OK$ = UCASE$(INPUT$(1))
   END SUB

   Output

   This is a sample pattern generated by the pattern editor.

   ┌────────────────────────────────────┐
   │                                    │
   │     The output for this example    │
   │     can be found on page 223 of    │
   │     the printed manual.            │
   │                                    │
   └────────────────────────────────────┘



 ────────────────────────────────────────────────────────────────────────────
 Chapter 6  Error and Event Trapping

   This chapter shows how to trap errors and events that occur while a
   program is running. With error trapping, you can protect your program from
   such user errors as entering a string when a numeric value is expected or
   trying to open a file in a nonexistent directory. With event trapping,
   your program can detect and respond to real-time events such as keystrokes
   or data arriving at a COM port.

   When you have completed this chapter, you will know how to perform these
   tasks:

   ■ Activate error trapping or event trapping

   ■ Write a routine to process trapped errors or events

   ■ Return control from an error-handling routine or an event-handling
     routine

   ■ Write a program that traps any keystroke or combination of keystrokes

   ■ Trap errors or events within SUB or FUNCTION procedures

   ■ Trap errors or events in programs composed of more than one module


 6.1  Error Trapping

   Error trapping lets your program intercept run-time errors before they
   force the program to halt. Without error trapping, errors during program
   execution (such as trying to open a nonexistent data file) cause BASIC to
   display the appropriate error message, then stop the program. If someone
   is running the stand-alone version of your program, they will have to
   restart the program, losing data entered or calculations performed before
   the error occurred.

   When error trapping is active, the trapped error makes the program branch
   to a user-written "error-handling routine," which corrects the error. If
   you can anticipate errors that might occur when someone else uses your
   program, error trapping will let you handle those errors in a
   "user-friendly" way.

   Sections 6.1.1 and 6.1.2 below show how to activate error trapping, how
   to write a routine to handle errors when they are trapped, and how to
   return control from the error-handling routine after it has dealt with the
   error.

 6.1.1  Activating Error Trapping

   You activate error trapping with the statement ON ERROR GOTO line, where
   line is a line number or line label identifying the first line of an
   error-handling routine. Once BASIC has encountered an ON ERROR GOTO line
   statement, any run-time error within the module containing that statement
   causes a branch to the specified line. (If the number or label does not
   exist within the module, a run-time error message reading Label not
   defined appears.)

   An ON ERROR GOTO statement must be executed before error trapping takes
   effect. Therefore, you must position the ON ERROR GOTO statement so that
   program execution reaches it before it is needed. This statement would
   usually be one of the first executable statements in the main module or a
   procedure.

   You cannot use an ON ERROR GOTO 0 statement to branch to an error handler,
   because this statement has a special meaning in error trapping. The ON
   ERROR GOTO 0 statement has two effects, depending on where it appears. If
   it appears outside an error-handling routine, it turns off error trapping.
   If it appears inside an error-handling routine (as it does in the Handler
   routine in the next example), it causes BASIC to print its standard
   message for the given error and stops the program.

   Therefore, even if your program has a line with line-number 0, an ON ERROR
   GOTO 0 statement tells BASIC either to turn off error detection or to
   terminate execution.

 6.1.2  Writing an Error-Handling Routine

   An error-handling routine consists of the following three parts:

   1. The line label or line number that is specified in the statement ON
      ERROR GOTO line, which is the first statement the program branches to
      after an error

   2. The body of the routine, which determines the error that caused the
      branch and takes appropriate action for each anticipated error

   3. At least one RESUME or RESUME NEXT statement to return control from the
      routine

   An error handler must be placed where it cannot be executed during the
   normal flow of program execution. For example, an error-handling routine
   in the program's main module might be placed after an END statement.
   Otherwise, a GOTO statement might be needed to skip over it during normal
   execution.

   6.1.2.1  Using ERR to Identify Errors

   Once the program has branched to an error-handling routine, it must
   determine which error caused the branch. To identify the culprit, use the
   ERR function. This function returns a numeric code for the program's most
   recent run-time error. (See Table I.1, "Run-Time Error Codes," for a
   complete list of the error codes associated with run-time errors.)

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Errors cannot be trapped within an error-handling routine. If an error
     occurs while the error-handling routine is processing another error, the
     program displays the message for the new error and then terminates.
     Event handling is also suspended, but resumes when QuickBASIC returns
     from the error handler. The first event that occurred after event
     handling was suspended is saved.
   ──────────────────────────────────────────────────────────────────────────

   Example

   The following program includes the error-handling routine Handler,
   designed to deal specifically with three different error situations. The
   ERR function, used in a SELECT CASE statement, allows this routine to take
   actions appropriate for each error.

   DATA BASIC, Pascal, FORTRAN, C, Modula, Forth
   DATA LISP, Ada, COBOL

   CONST FALSE = 0, TRUE = NOT FALSE

   EndOfData = FALSE                     ' Set end of data flag.

   ON ERROR GOTO Handler                 ' Activate error trapping.

   OPEN "LPT1:" FOR OUTPUT AS #1 ' Open the printer for output.

   DO
      ' Continue reading items from the DATA statements above,
      ' then printing them on the line printer, until there is
      ' an "Out of DATA" error message signifying no more data:
      READ Buffer$
      IF NOT EndOfData THEN
         PRINT #1, Buffer$
      ELSE
         EXIT DO
      END IF
   LOOP

   CLOSE #1
   END

   Handler:                        ' Error-handling routine

      ' Use ERR to determine which error
      ' caused the branch to "Handler":
      SELECT CASE ERR
         CASE 4

            ' 4 is the code for "Out of DATA" in DATA
            ' statements:
            EndOfData = TRUE
            RESUME NEXT
         CASE 25

            ' 25 is the code for "Device fault" error,
            ' which can be caused by trying to output
            ' to the printer when it's not on:
            PRINT "Turn printer on, then";
            PRINT "press any key to continue"
            Pause$ = INPUT$(1)
            RESUME
         CASE 27

            ' 27 is the code for "Out of paper":
            PRINT "Printer is out of paper. Insert"
            PRINT "paper, then press any key to continue."
            Pause$ = INPUT$(1)

            ' Start reading data from the beginning of first
            ' DATA statement after the paper is inserted:
            RESTORE
            RESUME
         CASE ELSE

            ' An unanticipated error has occurred; display the
            ' message for that error and stop the program:
            ON ERROR GOTO 0
      END SELECT

   6.1.2.2  Returning from an Error-Handling Routine

   The RESUME statement returns control from an error-handling routine. The
   preceding example used the following two variations of RESUME to return
   from Handler:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
   Statement                Action
   ──────────────────────────────────────────────────────────────────────────
   RESUME                   Causes the program to branch back to the exact
                            statement that caused the error.

                            If the program had to go to another module to
                            find an active error handler, control returns to
                            the last statement executed in that module.

                            The preceding program used RESUME to return to
                            the PRINT statement that attempted to send output
                            to the printer, giving it another chance to print
                            the value in Buffer$ after the printer has
                            (presumably) been turned on.

   RESUME NEXT              Causes the program to branch back to the
                            statement following the one that caused the
   Statement                Action
   ──────────────────────────────────────────────────────────────────────────
                           statement following the one that caused the
                            error.If the program had to go to another module
                            to find an active error handler, control returns
                            to the statement following the last statement
                            executed in that module.

                            The preceding program used the statement RESUME
                            NEXT when recovering from the Out of DATA error.
                            In this case, a simple RESUME would have sent the
                            program into an endless loop, since each time
                            control returned to the READ statement in the
                            main program, another Out of DATA error would
                            result, invoking the error routine over and over
                            again.

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


   Figure 6.1 outlines the flow of a program's control during error handling
   with RESUME.


   ┌──────────────────────────────────────────────────────────────────┐
   │          ┌─────────┐                                             │
   │          │  Start  │                                             │
   │          └────┬────┘                                             │
   │               │                                                  │
   │               │                                                  │
   │    ┌─────────────────────┐        ┌──────────────────────┐      │
   │ ┌─│ Statement with error ├───────│    Error handler     │      │
   │ │  └──────────┬───────────┘        └───────────┬──────────┘      │
   │ │             │                                │                 │
   │ │            ┌┼┐                   ┌─────────────────────┐      │
   │ └────────────┘│└───────────────────┤        RESUME        │      │
   │               │                    └──────────────────────┘      │
   │               │                                                  │
   │          ┌────────┐                                             │
   │          │   End   │                                             │
   │          └─────────┘                                             │
   └──────────────────────────────────────────────────────────────────┘

   Figure 6.1  Program Flow of Control with RESUME

   Contrast the preceding figure with Figure 6.2, which shows what happens
   in a program using RESUME NEXT.


   ┌──────────────────────────────────────────────────────────────────┐
   │        ┌─────────┐                                               │
   │        │  Start  │                                               │
   │        └────┬────┘                                               │
   │             │                                                    │
   │  ┌─────────────────────┐        ┌──────────────────────┐        │
   │  │ Statement with error ├───────│    Error handler     │        │
   │  └──────────────────────┘        └───────────┬──────────┘        │
   │                                              │                   │
   │  ┌──────────────────────┐        ┌─────────────────────┐        │
   │  │ Statement following  │───────┤        RESUME        │        │
   │  │the one with the error│        └──────────────────────┘        │
   │  └──────────┬───────────┘                                        │
   │             │                                                    │
   │        ┌────────┐                                               │
   │        │   End   │                                               │
   │        └─────────┘                                               │
   └──────────────────────────────────────────────────────────────────┘

   Figure 6.2  Program Flow of Control with RESUME NEXT

   Another variant of RESUME is RESUME line, where line is a line number or
   line label outside any SUB...END SUB, FUNCTION...END FUNCTION, or DEF
   FN...END DEF block. Because line must be outside these blocks, a RESUME
   line statement can produce unexpected effects if it appears in an
   error-handling routine inside a SUB or FUNCTION procedure or a DEF FN
   function. It should generally be avoided in favor of RESUME or RESUME
   NEXT.


 6.2  Event Trapping

   Section 6.2.1 below compares two methods your BASIC programs can use to
   detect events: polling and trapping. Sections 6.2.2-6.2.4 then discuss
   the different events BASIC can trap, how to set and activate a trap, and
   how to suspend or deactivate the trap. Sections 6.2.5-6.2.7 provide more
   detailed information on trapping keystrokes and music events.

 6.2.1  Detecting Events by Polling

   One way to detect an event and reroute program control to the appropriate
   routine is to use "event polling." In polling, your program stops whatever
   it is currently doing and explicitly checks for an event. For example, the
   following loop keeps checking the keyboard until the user presses either
   the Q or N keys:

   DO
      Test$ = UCASE$(INKEY$)
   LOOP UNTIL Test$ = "N" OR Test$ = "Q"

   Polling works well when you know ahead of time exactly where in the flow
   of the program you want to check for an event.

 6.2.2  Detecting Events by Trapping

   But suppose you don't want your program to pause, or you would like it to
   check between every statement (that is, check continuously). In these
   cases, polling is unwieldy or impossible, and trapping becomes the better
   alternative.

   Example

   The following example shows how to use event trapping:

   ' Alert the program that it should branch to "KeySub"
   ' whenever the user presses the F1 function key:
   ON KEY(1) GOSUB KeySub

   ' Turn on trapping for the F1 key. BASIC now checks in the
   ' background for this event until the end of the program,
   ' or until trapping is disabled with KEY(1) OFF
   ' or suspended with KEY(1) STOP:
   KEY(1) ON
   OPEN "Data" FOR INPUT AS #1
   OPEN "Data.Out" FOR OUTPUT AS #2

   DO UNTIL EOF(1)
      LINE INPUT #1, LineBuffer$
      PRINT #2, LineBuffer$
   LOOP

   KeySub:         ' When the user presses F1, the program
      .            ' branches to this procedure.
      .
      .
   RETURN

 6.2.3  Specifying the Event to Trap and Activating Event Trapping

   As you can see from the preceding example, three steps are necessary for
   event trapping:

   1. Define a target subroutine that is known as an "event-handling
      subroutine."

   2. Tell the program to branch to the event-handling subroutine when the
      event takes place with an ON event GOSUB statement.

   3. Activate trapping of that event with an ON event GOSUB statement.

   Your program cannot trap a given event until it encounters both an event
   ON and an ON event GOSUB statement.

   An event-handling routine is an ordinary BASIC GOSUB routine: control
   passes to the first line of the routine whenever the event is detected and
   returns to the main level of the module containing the routine with a
   RETURN statement.

   Note the following important differences between the syntax of error
   trapping and the syntax of event trapping:

   Error Trapping                       Event Trapping
   ──────────────────────────────────────────────────────────────────────────
   Activated with the statement ON      Activated with an event ON statement;
   ERROR GOTO, which also specifies     a separate statement, ON event GOSUB,
   the first line of the error-         specifies the first line of the
   handling routine                     event-handling subroutine

   Returns control from the error       Returns control from the event
   routine with one or more RESUME,     subroutine with one or more RETURN
   RESUME NEXT, or RESUME line          statements
   statements
   ──────────────────────────────────────────────────────────────────────────

 6.2.4  Events That BASIC Can Trap

   You can trap the following events within a BASIC program:

   BASIC Statement          Event Trapped
   ──────────────────────────────────────────────────────────────────────────
   COM(portnumber)          Data from one of the serial ports (1 or 2)
                            appearing in the communications buffer (the
                            intermediate storage area for data sent to or
                            received from the serial port)

   KEY(keynumber)           The user pressing the given key

   PEN                      The user activating the light pen

   PLAY(queuelimit)         The number of notes remaining to be played in the
                            background dropping below queuelimit

   STRIG(triggernumber)     The user squeezing the trigger of the joystick

   TIMER(interval)          The passage of interval seconds
   ──────────────────────────────────────────────────────────────────────────

 6.2.5  Suspending or Disabling Event Trapping

   You can turn off detection and trapping of any event with the event OFF
   statement. Events occurring after an event OFF statement has been executed
   are ignored. If you want to suspend trapping a given event but continue
   detecting it, use the event STOP statement.

   After event STOP, if the event occurs, there is no branch to the
   event-handling routine. However, your program remembers that the event
   occurred, and as soon as trapping is turned back on with event ON,
   branching to the event routine occurs immediately.

   Event-handling routines execute an implicit event STOP statement for a
   given event whenever program control is in the routine; this is followed
   by an implicit event ON for that event when program control returns from
   the routine. For example, if a key-handling routine is processing a
   keystroke, trapping the same key is suspended until the previous keystroke
   is completely processed by the routine. If the user presses the same key
   during this time, this new keystroke is remembered and trapped after
   control returns from the key-handling routine.

   Example

   An event trap interrupts whatever is happening in the program at the
   moment the event occurs. Therefore, if you have a block of statements that
   you do not want interrupted, precede them with event STOP and follow them
   with event ON, as in this example:

   ' Once every minute (60 seconds),
   ' branch to the ShowTime subroutine:
   ON TIMER(60) GOSUB ShowTime

   ' Activate trapping of the 60-second event:
   TIMER ON
   .
   .
   .
   TIMER STOP      ' Suspend trapping.
   .       ' A sequence of lines you don't want interrupted,
   .       ' even if 60 or more seconds elapse
   .

   TIMER ON        ' Reactivate trapping.
   .
   .
   .
   END

   ShowTime:

      ' Get the current row and column position of the cursor,
      ' and store them in the variables Row and Column:
      Row    = CSRLIN
      Column = POS(0)

      ' Go to the 24th row, 20th column, and print the time:
      LOCATE 24, 20
      PRINT TIME$

      ' Restore the cursor to its former position
      ' and return to the main program:
      LOCATE Row, Column
   RETURN

 6.2.6  Trapping Keystrokes

   To detect a keystroke and route program control to a key-press routine,
   you need both of the following statements in your program:

   ON KEY(keynumber) GOSUB line
   KEY(keynumber) ON

   Here, the keynumber value corresponds to the following keys:

   Value                    Key
   ──────────────────────────────────────────────────────────────────────────
   1-10                     Function keys F1-F10 (sometimes called "soft
                            keys")

   11                       The UP direction key

   12                       The LEFT direction key

   13                       The RIGHT direction key

   14                       The DOWN direction key

   15-25                    User-defined keys (see Sections 6.2.6.1-6.2.6.2)

   30                       The F11 function key (101-key keyboard only)

   31                       The F12 function key (101-key keyboard only)
   ──────────────────────────────────────────────────────────────────────────

   Examples

   The following two lines cause the program to branch to the KeySub routine
   each time the F2 function key is pressed:

   ON KEY(2) GOSUB KeySub
   KEY(2) ON
   .
   .
   .

   The following four lines cause the program to branch to the DownKey
   routine when the DOWN direction key is pressed and to the UpKey routine
   when the UP direction key is pressed:

   ON KEY(11) GOSUB UpKey
   ON KEY(14) GOSUB DownKey
   KEY(11) ON
   KEY(14) ON
   .
   .
   .

   6.2.6.1  Trapping User-Defined Keys

   In addition to providing the preassigned key numbers 1-14 (plus 30 and 31
   with the 101-key keyboard), BASIC allows you to assign the numbers 15-25
   to any of the remaining keys on the keyboard. To define your own key to
   trap, use these three statements:

   KEY keynumber, CHR$(0) + CHR$(scancode)
   ON KEY(keynumber) GOSUB line
   KEY(keynumber) ON

   Here, keynumber is a value from 15 to 25, and scancode is the scan code
   for that key. (See the first column of the "Keyboard Scan Codes" table in
   Appendix D for these codes.) For example, the following lines cause the
   program to branch to the TKey routine each time the user presses T:

   ' Define key 15 (the scan code for "t" is decimal 20):
   KEY 15, CHR$(0) + CHR$(20)

   ' Define the trap (where to go when "t" is pressed):
   ON KEY(15) GOSUB TKey

   KEY(15) ON                 ' Turn on detection of key 15.

   PRINT "Press q to end."

   DO                         ' Idle loop: wait for user to
   LOOP UNTIL INKEY$ = "q"    ' press "q".

   END

   TKey:                      ' Key-handling subroutine
      PRINT "Pressed t."
   RETURN

   6.2.6.2  Trapping User-Defined Shifted Keys

   You can also set a trap for "shifted" keys. A key is said to be shifted
   when you press it simultaneously with one or more of the special keys
   SHIFT, CTRL, or ALTor if you press it after toggling on the keys NUM LOCK
   or CAPS LOCK.

   This is how to trap the following key combinations:

   KEY keynumber, CHR$(keyboardflag) + CHR$(scancode)
   ON KEY(keynumber) GOSUB line
   KEY(keynumber) ON

   Here, keynumber is a value from 15 to 25; scancode is the scan code for
   the primary key; and keyboardflag is the sum of the individual codes for
   the special keys pressed, as shown in the following list:

   Key                                  Code for keyboardflag
   ──────────────────────────────────────────────────────────────────────────
   SHIFT                                1, 2, or 3
                                        Key trapping assumes the left and
                                        right shift keys are the same, so you
                                        can trap the SHIFT key with 1 (left),
                                        2 (right), or 3 (left + right).

   CTRL                                 4

   ALT                                  8

   NUM LOCK                             32

   CAPS LOCK                            64

   Any extended key on the 101-key      128
   keyboard (in other words, a key
   such as LEFT or DELETE that is not
   on the numeric keypad)
   ──────────────────────────────────────────────────────────────────────────

   For example, the following statements turn on trapping of CTRL+S. Note
   these statements are designed to trap both the CTRL+S (lowercase) and
   CTRL+SHIFT+S (uppercase) key combinations. To trap the uppercase S, your
   program must recognize capital letters produced by holding down the SHIFT
   key, as well as those produced when the CAPS LOCK key is active, as shown
   here:

   ' 31 = scan code for S key
   '  4 = code for CTRL key
   KEY 15, CHR$(4) + CHR$(31)     ' Trap CTRL+S.

   '  5 = code for CTRL key + code for SHIFT key
   KEY 16, CHR$(5) + CHR$(31)     ' Trap CTRL+SHIFT+S.

   ' 68 = code for CTRL key + code for CAPSLOCK
   KEY 17, CHR$(68) + CHR$(31)    ' Trap CTRL+CAPSLOCK+S.

   ON KEY (15) GOSUB CtrlSTrap    ' Tell program where to
   ON KEY (16) GOSUB CtrlSTrap    ' branch (note: same
   ON KEY (17) GOSUB CtrlSTrap    ' subroutine for each key).

   KEY (15) ON                    ' Activate key detection for
   KEY (16) ON                    ' all three combinations.
   KEY (17) ON
   .
   .
   .

   The following statements turn on trapping of CTRL+ALT+DEL:

   ' 12 = 4 + 8 = (code for CTRL key) + (code for ALT key)
   ' 83 = scan code for DEL key
   KEY 20, CHR$(12) + CHR$(83)
   ON KEY(20) GOSUB KeyHandler
   KEY(20) ON
   .
   .
   .

   Note in the preceding example that the BASIC event trap overrides the
   normal effect of CTRL+ALT+DEL (system reset). Using this trap in your
   program is a handy way to prevent the user from accidentally rebooting
   while a program is running.

   If you use a 101-key keyboard, you can trap any of the keys on the
   dedicated keypad by assigning the string

   CHR$(128) + CHR$(scancode)

   to any of the keynumber values from 15 to 25.

   The next example shows how to trap the LEFT direction keys on both the
   dedicated cursor keypad and the numeric keypad.

   ' 128 = keyboard flag for keys on the
   '       dedicated cursor keypad
   '  75 = scan code for LEFT arrow key

   KEY 15, CHR$(128) + CHR$(75)    ' Trap LEFT key on
   ON KEY(15) GOSUB CursorPad      ' the dedicated
   KEY(15) ON                      ' cursor keypad.

   ON KEY(12) GOSUB NumericPad     ' Trap LEFT key on
   KEY(12) ON                      ' the numeric keypad.

   DO: LOOP UNTIL INKEY$ = "q"     ' Start idle loop.
   END

   CursorPad:
      PRINT "Pressed LEFT key on cursor keypad."
   RETURN

   NumericPad:
      PRINT "Pressed LEFT key on numeric keypad."
   RETURN

   ──────────────────────────────────────────────────────────────────────────
   IMPORTANT
     For compatibility, QuickBASIC adopts many conventions of BASICA. One of
     these has to do with the way FUNCTION keys are trapped.
     If you initiate FUNCTION key trapping with an ON KEY (n) GOSUB
     statement, both BASICA and QuickBASIC trap Fn regardless of whether a
     shift key (CTRL, ALT, SHIFT) is also pressed. This means that
     user-defined traps for shifted versions of that FUNCTION key are
     ignored.
     Therefore, if you wish to trap a FUNCTION key in both its shifted and
     unshifted states, you should create a user definition for each state.
     Keys that are only used unshifted can continue to use the ON KEY (n)
     GOSUB statement.
   ──────────────────────────────────────────────────────────────────────────

 6.2.7  Trapping Music Events

   When you use the PLAY statement to play music, you can choose whether the
   music plays in the foreground or in the background. If you choose
   foreground music (which is the default) nothing else can happen until the
   music finishes playing. However, if you use the MB (Music Background)
   option in a PLAY music string, the tune plays in the background while
   subsequent statements in your program continue executing.

   The PLAY statement plays music in the background by feeding up to 32 notes
   at a time into a buffer, then playing the notes in the buffer while the
   program does other things. A "music trap" works by checking the number of
   notes currently left to be played in the buffer. As soon as this number
   drops below the limit you set in the trap, the program branches to the
   first line of the specified routine.

   To set a music trap in your program, you need the following statements:

   ON PLAY(limit) GOSUB line
   PLAY ON
   PLAY "MB"
   .
   .
   .
   PLAY musicstring
   [[PLAY musicstring]]
   .
   .
   .

   Here, limit is a number between 1 and 32. For example, this fragment
   causes the program to branch to the MusicTrap subroutine whenever the
   number of notes remaining to be played in the music buffer goes from eight
   to seven:

   ON PLAY(8) GOSUB MusicTrap
   PLAY ON
   .
   .
   .
   PLAY "MB"       ' Play subsequent notes in the background.
   PLAY "o1 A# B# C-"
   .
   .
   .
   MusicTrap:
      ' Music-trap subroutine
      .
      .
      .
   RETURN

   ──────────────────────────────────────────────────────────────────────────
   IMPORTANT
     A music trap is triggered only when the number of notes goes from limit
     to limit-1. For example, if the music buffer in the preceding example
     never contained more than seven notes, the trap would never occur. In
     the example, the trap happens only when the number of notes drops from
     eight to seven.
   ──────────────────────────────────────────────────────────────────────────

   You can use a music-trap subroutine to play the same piece of music
   repeatedly while your program executes, as shown in the next example:

   ' Turn on trapping of background music events:
   PLAY ON

   ' Branch to the Refresh subroutine when there are fewer than
   ' two notes in the background music buffer:
   ON PLAY(2) GOSUB Refresh

   PRINT "Press any key to start, q to end."
   Pause$ = INPUT$(1)

   ' Select the background music option for PLAY:
   PLAY "MB"

   ' Start playing the music, so notes will be put in the
   ' background music buffer:
   GOSUB Refresh

   I = 0

   DO

      ' Print the numbers from 0 to 10,000 over and over until
      ' the user presses the "q" key. While this is happening,
      ' the music will repeat in the background:
      PRINT I
      I = (I + 1) MOD 10001
   LOOP UNTIL INKEY$ = "q"

   END

   Refresh:

      ' Plays the opening motive of
      ' Beethoven's Fifth Symphony:
      Listen$ = "t180 o2 p2 p8 L8 GGG L2 E-"
      Fate$   = "p24 p8 L8 FFF L2 D"
      PLAY Listen$ + Fate$
   RETURN


 6.3  Error and Event Trapping in SUB or FUNCTION Procedures

   The most important thing to remember when using error or event trapping
   with BASIC procedures is that either of the following statements can
   appear within a SUB...END SUB or FUNCTION...END FUNCTION block:

   ON ERROR GOTO line ON event GOSUB line

   However, the line referred to in each case must identify a line in the
   module-level code, not another line within the SUB or FUNCTION.

   Example

   The following example shows where to put an error-handling routine that
   processes errors trapped within a SUB procedure:

   CALL ShortSub
   END

   CatchError:
      ' Put the CatchError routine at the module level,
      ' outside the subprogram:
      PRINT "Error" ERR "caught by error handler."
   RESUME NEXT

   SUB ShortSub STATIC
      ON ERROR GOTO CatchError
      ERROR 62
   END SUB

   Output

   Error 62 caught by error handler.


 6.4  Trapping across Multiple Modules

   Prior to QuickBASIC 4.5, only events could be trapped across modules. Once
   an event-handling routine was defined and an event trap was activated in
   one module, an occurrence of that event during program execution in any
   other module triggered a branch to the routine.

   Errors could not be trapped across modules. If an error occurred in a
   module lacking an active error handler, program execution would halt, even
   if there were a handler in another module that could have taken care of
   the problem.

   QuickBASIC 4.5 expands the scope of error trapping. Errors, as well as
   events, can be trapped across modules. The next two sections explain how
   this works and the slight remaining differences between event and error
   trapping.

 6.4.1  Event Trapping across Modules

   The output from the following program shows that a trap set for the F1
   function key in the main module is triggered even when program control is
   in another module:

   ' =========================================================
   '                      MODULE
   ' =========================================================
   ON KEY (1) GOSUB GotF1Key
   KEY (1) ON
   PRINT "In main module. Press c to continue."

   DO: LOOP UNTIL INKEY$ = "c"

   CALL SubKey

   PRINT "Back in main module. Press q to end."
   DO : LOOP UNTIL INKEY$ = "q"
   END

   GotF1Key:
      PRINT "Handled F1 keystroke in main module."
   RETURN

   ' =========================================================
   '                      SUBKEY MODULE
   ' =========================================================
   SUB SubKey STATIC
      PRINT "In module with SUBKEY. Press r to return."

      ' Pressing F1 here still invokes the GotF1Key
      ' subroutine in the MAIN module:
      DO: LOOP UNTIL INKEY$ = "r"
   END SUB

   Output

   In main module. Press c to continue.
   Handled F1 keystroke in main module.
   In module with SUBKEY. Press r to return.
   Handled F1 keystroke in main module.
   Back in main module. Press q to end.
   Handled F1 keystroke in main module.

 6.4.2  Error Trapping across Modules

   Errors can be trapped across multiple modules. If there is no active error
   handler in the module where the error occurred, BASIC looks for one in the
   module from which the active module was invoked, continuing back through
   the sequence of modules called until it finds a module with an active
   error handler. If it cannot find one, an error message is displayed and
   program execution halts.

   Note that BASIC does not search through all modules──only the ones that
   were in the path of invocation leading to the code that produced the
   error.

   An ON ERROR statement must be executed before an error occurs in order for
   BASIC to look for a handler. Therefore, you must put the ON ERROR GOTO
   statement where the flow of a program's control can reach it; for example,
   place it inside a procedure called from the main module (see the examples
   that follow).

   Examples

   The following example shows how to trap errors for a procedure in a Quick
   library. The AdapterType procedure in this library tries all possible
   SCREEN statements to see which graphics screen modes your computer's
   hardware supports. (See Appendix H, "Creating and Using Quick Libraries,"
   for more information on Quick libraries.)

   ' =========== MODULE-LEVEL CODE IN QUICK LIBRARY ==========
   ' The error-handling routines for procedures in this
   ' library must be defined at this level. This level is
   ' executed only when there is an error in the procedures.
   ' =========================================================

   DEFINT A-Z

   CONST FALSE = 0, TRUE = NOT FALSE

   .
   .
   .
   CALL AdapterType
   .
   .
   .
   END

   DitchMe:                        ' Error-handling routine
      DisplayError = TRUE
      RESUME NEXT

   ' ========== PROCEDURE-LEVEL CODE IN QUICK LIBRARY ========
   '          Error trapping is activated at this level.
   ' =========================================================

   SUB AdapterType STATIC

      SHARED DisplayError          ' DisplayError variable is
                                   ' shared with DitchMe error
                                   ' handler in code above.
      DIM DisplayType(1 TO 13)     ' Dimension DisplayType
                                   ' array.

      J = 1                        ' Initialize subscript
                                   ' counter for DisplayType
                                   ' array.

   ON ERROR GOTO DitchMe   ' Set up the error trap.

   FOR Test = 13 TO 1 STEP -1
         SCREEN Test               ' Try a SCREEN statement to
                                   ' see if it causes error.
         IF NOT DisplayError THEN  ' No error, so this is a
                                   ' valid screen mode.
             DisplayType(J) = Test ' Store mode in array.
             J = J + 1             ' Increment the subscript
                                   ' counter.
         ELSE
             DisplayError = FALSE  ' Error; reset DisplayError.
         END IF
      NEXT Test

      SCREEN 0, 0                  ' Set 80-column text mode.
      WIDTH 80
      LOCATE 5, 10
      PRINT "Your computer supports these screen modes:"
      PRINT

      FOR I = 1 TO J               ' Print modes not causing
                                   ' errors.
         PRINT TAB(20); "SCREEN"; DisplayType(I)
      NEXT I

      LOCATE 20, 10
      PRINT "Press any key to continue..."

      DO: LOOP WHILE INKEY$ = ""

   END SUB

   If you want the error-handling routine in each module to do the exactly
   the same thing, you can have each routine invoke a common error-processing
   SUB procedure, as shown in the next example:

   ' =========================================================
   '                       MAIN MODULE
   ' =========================================================

   DECLARE SUB GlobalHandler (ModuleName$)
   DECLARE SUB ShortSub ()

   ON ERROR GOTO LocalHandler
   ERROR 57                ' Simulate occurrence of error 57
                           ' ("Device I/O error").
   ShortSub                ' Call the ShortSub SUB.
   END

   LocalHandler:
      ModuleName$ = "MAIN"
      CALL GlobalHandler(ModuleName$)  ' Call the
                                       ' GlobalHandler SUB.
   RESUME NEXT

   ' =========================================================
   '                     SHORTSUB MODULE
   ' =========================================================

   DECLARE SUB GlobalHandler (ModuleName$)

   LocalHandler:
      ModuleName$ = "SHORTSUB"
      GlobalHandler ModuleName$    ' Call GlobalHandler.
   RESUME NEXT

   SUB ShortSub STATIC
      ON ERROR GOTO LocalHandler
      ERROR 13                     ' Simulate a "Type mismatch" error.
   END SUB


   ' =========================================================
   '                    GLOBALHANDLER MODULE
   ' =========================================================

   SUB GlobalHandler (ModuleName$) STATIC
      PRINT "Trapped error";ERR;"in";ModuleName$;"module"
   END SUB

   Output

   Trapped error 57 in MAIN module.
   Trapped error 13 in SHORTSUB module.


 6.5  Trapping Errors and Events in Programs Compiled with BC

   If both of the following statements apply to your program, then you must
   use the appropriate BC command-line option listed below when compiling
   your program:

   ■ You are developing the program outside the QuickBASIC environment──that
     is, you are using another text editor to enter your BASIC source code,
     then creating a stand-alone executable program from this source code
     with the commands BC and LINK.

   ■ Your program contains any of the statements listed in the second column
     below.

   Table 6.1  BC Command-Line Options for Error and Event Trapping
╓┌─┌──────────────┌────────────────────────────┌─────────────────────────────╖
   Command-Line   Statements                   Explanation
   Option
   ──────────────────────────────────────────────────────────────────────────
   /E             ON ERROR GOTO                The /E option tells the
                  RESUME line                  compiler your program does its
                                               own error trapping with ON
                                               ERROR GOTO and RESUME
                                               statements.

   /V             ON event GOSUB               The /V option tells the
                  event ON                     program to check between each
                                               statement to see if the given
                                               event has taken place
   Command-Line   Statements                   Explanation
   Option
   ──────────────────────────────────────────────────────────────────────────
                                              event has taken place
                                               (contrast this with the effect
                                               of /W).

   /W             ON event GOSUB               The /W option tells the
                  event ON                     program to check between each
                                               line to see if the given event
                                               has taken place (contrast this
                                               with the effect of /V).
                                               Since BASIC allows multiple
                                               statements on a single line,
                                               programs compiled with /W may
                                               check less frequently than
                                               those compiled with /V.

   /X             RESUME                       The /X option tells the
                  RESUME NEXT                  compiler you have used one of
                  RESUME 0                     the preceding forms of RESUME
   Command-Line   Statements                   Explanation
   Option
   ──────────────────────────────────────────────────────────────────────────
                 RESUME 0                     the preceding forms of RESUME
                                               in your program to return
                                               control from an error-handling
                                               routine.
   ──────────────────────────────────────────────────────────────────────────


   Example

   The following DOS command lines compile and link a BASIC module named
   RMTAB.BAS, creating a stand-alone program RMTAB.EXE. (As this program is
   compiled without the /O option, it requires the BRUN45.LIB run-time
   library in order to run. See Appendix G, "Compiling and Linking from
   DOS," for more information on compiling and linking.) Since this module
   contains ON ERROR GOTO and RESUME NEXT statements, the /E and /X options
   are required when compiling.

   BC RMTAB , , /E /X;
   LINK RMTAB;


 6.6  Sample Application: Trapping File-Access Errors (FILERR.BAS)

   The following program gets as input both a file name and a string to
   search for in the file. It then lists all lines in the given file
   containing the specified string. If a file-access error occurs, it is
   trapped and dealt with in the ErrorProc routine.

   Statements and Functions Used

   This program demonstrates the use of the following error-handling
   statements and functions:

   ■ ERR

   ■ ON ERROR GOTO

   ■ RESUME

   ■ RESUME NEXT

   Program Listing

   ' Declare symbolic constants:
   CONST FALSE = 0, TRUE = NOT FALSE

   DECLARE FUNCTION GetFileName$ ()

   ' Set up the ERROR trap and specify
   ' the name of the error-handling routine:
   ON ERROR GOTO ErrorProc

   DO
      Restart = FALSE
      CLS

      FileName$ = GetFileName$     ' Input file name.

      IF FileName$ = "" THEN
         END                       ' End if <ENTER> pressed.
      ELSE

         ' Otherwise, open the file, assigning it
         ' the next available file number:
         FileNum = FREEFILE
         OPEN FileName$ FOR INPUT AS FileNum
      END IF

   IF NOT Restart THEN

         ' Input search string:
         LINE INPUT "Enter string to locate:", LocString$
         LocString$ = UCASE$(LocString$)

         ' Loop through the lines in the file,
         ' printing them if they contain the search string:
         LineNum = 1
         DO WHILE NOT EOF(FileNum)

            ' Input line from file:
            LINE INPUT #FileNum, LineBuffer$

            ' Check for string, printing the line
            ' and its number if found:
            IF INSTR(UCASE$(LineBuffer$), LocString$) <> 0 THEN
               PRINT USING "#### &"; LineNum, LineBuffer$
            END IF

            LineNum = LineNum + 1
         LOOP

         CLOSE FileNum             ' Close the file.

      END IF
   LOOP WHILE Restart = TRUE

   END

   ErrorProc:

      SELECT CASE ERR

         CASE 64:                  ' Bad file name
            PRINT "** ERROR - Invalid file name"

            ' Get a new file name and try again:
            FileName$ = GetFileName$

            ' Resume at the statement that caused the error:
            RESUME

   CASE 71:                  ' Disk not ready.
            PRINT "** ERROR - Disk drive not ready"
            PRINT "Press C to continue, R to restart, Q to quit: "
            DO
              Char$ = UCASE$(INPUT$(1))
              IF Char$ = "C" THEN
                 RESUME           ' Resume where you left off.

              ELSEIF Char$ = "R" THEN
                 Restart = TRUE   ' Resume at beginning.
                 RESUME NEXT

              ELSEIF Char$ = "Q" THEN
                  END              ' Don't resume at all.
                  END IF
            LOOP

         CASE 53, 76:              ' File or path not found.
            PRINT "** ERROR - File or path not found"
            FileName$ = GetFileName$
            RESUME

         CASE ELSE:                ' Unforeseen error.

            ' Disable error trapping and
            ' print standard system message:
            ON ERROR GOTO 0
      END SELECT

   ' ===================== GETFILENAME$ =======================
   '           Returns a file name from user input
   ' ==========================================================

   FUNCTION GetFileName$ STATIC
      INPUT "Enter file to search (or ENTER to quit):", FTemp$
      GetFileName$ = FTemp$
   END FUNCTION



 ────────────────────────────────────────────────────────────────────────────
 Chapter 7  Programming with Modules

   This chapter shows how you can gain more control over your programming
   projects by dividing them into "modules." Modules provide a powerful
   organizing function by letting you divide a program into logically related
   parts (rather than keeping all the code in one file).

   This chapter will show you how to use modules to:

   ■ Write and test new procedures separately from the rest of the program

   ■ Create libraries of your own SUB and FUNCTION procedures that can be
     added to any new program

   ■ Combine routines from other languages (such as C or MASM) with your
     BASIC programs


 7.1  Why Use Modules?

   A module is a file that contains an executable part of your program. A
   complete program can be contained in a single module, or it can be divided
   among two or more modules.

   In dividing up a program into modules, logically related sections are
   placed in separate files. This organization can speed and simplify the
   process of writing, testing, and debugging.

   Dividing your program into modules has these advantages:

   ■ Modules allow procedures to be written separately from the rest of the
     program, then combined with it. This arrangement is especially useful
     for testing the procedures, since they can then be checked outside the
     environment of the program.

   ■ Two or more programmers can work on different parts of the same program
     without interference. This is especially helpful in managing complex
     programming projects.

   ■ As you create procedures that meet your own specific programming needs,
     you can add these procedures to their own module. They can then be
     reused in new programs simply by loading that module.

   ■ Multiple modules simplify software maintenance. A procedure used by many
     programs can be in one library module; if changes are needed, it only
     has to be modified once.


 7.2  Main Modules

   The module containing the first executable statement of a program is
   called the "main module." This statement is never part of a procedure,
   because execution cannot begin within a procedure.

   Everything in a module except SUB and FUNCTION procedures is said to be
   "module-level code." In QuickBASIC, the module-level code is every
   statement that can be accessed without switching to a procedure-editing
   window. Figure 7.1 illustrates the relationship between these elements.


 7.3  Modules Containing Only Procedures

   A module need not contain module-level code; a module can consist of
   nothing but SUB and FUNCTION procedures. Indeed, this is the most
   important use of modules.

   Modules are often used to "split off" the procedures from the body of the
   program. This makes it easy to divide a project among programmers, for
   example. Also, as you create general-purpose procedures that are useful in
   a variety of programs (such as procedures that evaluate matrices, send
   binary data to a COM port, alter strings, or handle errors), these can be
   stored in modules, then used in new programs simply by loading the
   appropriate module into QuickBASIC.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     If a procedure in a procedures-only module needs an error- or
     event-handling routine or a COMMON SHARED statement, these are inserted
     at module level.
   ──────────────────────────────────────────────────────────────────────────


   ┌───────────────────────────────────────────────────────────────────────┐
   │             Program execution begins here                             │
   │       ┌─ ┌────────────────────────────────────────────┐ ─┐            │
   │       │  │  declarations and definitions              │  │            │
   │       │  │  executable program statement 1            │  │            │
   │       │  │  executable program statement 2            │  │            │
   │       │  │  .                                         │  ├─ Module-   │
   │       │  │  .                                         │  │ level code │
   │       │  │  .                                         │  │            │
   │       │  │  END                                       │  │            │
   │       │  │  error-handling routines                   │  │            │
   │       │  └────────────────────────────────────────────┘ ─┘            │
   │       │  ┌────────────────────────────────────────────┐ ─┐            │
   │       │  │  SUB                                       │  │            │
   │       │  │   statements in first SUB procedure        │  │            │
   │       │  │  ENDSUB                                    │  │            │
   │       │  └────────────────────────────────────────────┘  │            │
   │       │  ┌────────────────────────────────────────────┐  │            │
   │ Main ─┤  │  SUB                                       │  │            │
   │module │  │   statements in second SUB procedure       │  │            │
   │       │  │  ENDSUB                                    │  │            │
   │       │  └────────────────────────────────────────────┘  │            │
   │       │     .                                            │            │
   │       │     .                                            ├─Procedures │
   │       │     .                                            │            │
   │       │  ┌────────────────────────────────────────────┐  │            │
   │       │  │  FUNCTION                                  │  │            │
   │       │  │   statements in first FUNCTION procedure   │  │            │
   │       │  │  ENDFUNCTION                               │  │            │
   │       │  └────────────────────────────────────────────┘  │            │
   │       │  ┌────────────────────────────────────────────┐  │            │
   │       │  │  FUNCTION                                  │  │            │
   │       │  │   statements in second FUNCTION procedure  │  │            │
   │       │  │  ENDFUNCTION                               │  │            │
   │       │  └────────────────────────────────────────────┘  │            │
   │       │     .                                            │            │
   │       │     .                                            │            │
   │       │     .                                            │            │
   │       └─                                                ─┘            │
   │                                                                       │
   └───────────────────────────────────────────────────────────────────────┘

   Figure 7.1  Main Module Showing Module-Level Code and Procedures


 7.4  Creating a Procedures-Only Module

   It's easy to create a module that contains only procedures. You can enter
   new procedures in a separate file, or you can move procedures from one
   file to another.

   To create a new module:

   1. Invoke QuickBASIC without opening or loading any files.

   2. Write all the SUB and FUNCTION procedures you wish, but don't enter any
      module-level code. (Any error- or event-trapping routines and BASIC
      declarations needed are exceptions.)

   3. Use the Save As command to name and save this module.

   To move procedures from one module to another:

   1. Load the files containing the procedures you want to move.

   2. If the destination file already exists, use the Load File command from
      the File menu to load it, too. If it doesn't exist, use the Create File
      option from the File menu to make the new file.

   3. Choose the SUBs command from the View menu and use its Move feature to
      transfer the procedures from the old to the new file. This transfer is
      made final when you quit QuickBASIC and respond Yes to the dialog box
      that asks whether you want to save the modified files; otherwise, the
      procedures remain where they were when you started.


 7.5  Loading Modules

   In QuickBASIC, you can load as many modules as you wish (limited only by
   the available memory) using the Load File command from the File menu. All
   the procedures in all the loaded modules can be called from any other
   procedure or from module-level code. If a module happens to contain a
   procedure that is never called, no harm occurs.

   Any or all of the loaded modules can contain module-level code. QuickBASIC
   normally begins execution with the module-level code of the first module
   loaded. If you want execution to begin in a different module, use the Set
   Main Module command from the Run menu. Execution normally halts at the end
   of the designated main module; by design, QuickBASIC does not continue
   execution with the module-level code from other modules.

   The ability to choose which module-level code gets executed is useful when
   comparing two versions of the same program. For example, you might want to
   test different user interfaces by putting each in a separate module. You
   can also place test code in a module containing only procedures, then use
   the Set Main Module command to switch between the program and the tests.

   You do not have to keep track of which modules your program uses. Whenever
   you use the Save All command, QuickBASIC creates (or updates) a .MAK file,
   which lists all the modules currently loaded. The next time the main
   module is loaded with the Open Program command, QuickBASIC consults this
   .MAK file and automatically loads the modules listed in it.


 7.6  Using the DECLARE Statement with Multiple Modules

   The DECLARE statement has several important functions in QuickBASIC. Using
   a DECLARE statement will

   1. Specify the sequence and data types of a procedure's parameters

   2. Enable type-checking, which confirms, each time a procedure is called,
      that the arguments agree with the parameters in both number and data
      type

   3. Identify a FUNCTION procedure's name as a procedure name, not a
      variable name

   4. Most important of all, enable the main module to call procedures
      located in other modules (or Quick libraries)

   QuickBASIC has its own system for automatically inserting the required
   DECLARE statements into your modules. Section 2.5.4, "Checking Arguments
   with the DECLARE Statement," explains the features and limitations of this
   system.

   Despite QuickBASIC's automatic insertion of the DECLARE statement, you may
   wish to create a separate include file that contains all the DECLARE
   statements required for a program. You can update this file manually as
   you add and delete procedures or modify your argument lists.

   If you write your programs with a text editor (rather than the QuickBASIC
   programming environment) and compile with BC, you must insert DECLARE
   statements manually.


 7.7  Accessing Variables from Two or More Modules

   You can use the SHARED attribute to make variables accessible both at
   module level and within that module's procedures. If these procedures are
   moved to another module, however, these variables are no longer shared.

   You could pass these variables to each procedure through its argument
   list. This may be inconvenient, though, if you need to pass a large number
   of variables.

   One solution is to use COMMON statements, which enable two or more modules
   to access the same group of variables. Section 2.6, "Sharing Variables
   with SHARED," explains how to do this.

   Another solution is to use a TYPE...END TYPE statement to combine all the
   variables you wish to pass into a single structure. The argument and
   parameter lists then have to include only one variable name, no matter how
   many variables are passed.

   If you are simply splitting up a program and its procedures into separate
   modules, either of these approaches works well. If, on the other hand, you
   are adding a procedure to a module (for use in other programs), you should
   avoid using a COMMON statement. Modules are supposed to make it easy to
   add existing procedures to new programs; COMMON statements complicate the
   process. If a procedure needs a large group of variables, it may not
   belong in a separate module.


 7.8  Using Modules During Program Development

   When you start a new programming project, you should first look through
   existing modules to see if there are procedures that can be reused in your
   new software. If any of these procedures aren't already in a separate
   module, you should consider moving them to one.

   As your program takes shape, newly written procedures automatically become
   part of the program file (that is, the main module). You can move them to
   a separate module for testing or perhaps add them to one of your own
   modules along with other general-purpose procedures that are used in other
   programs.

   Your program may need procedures written in other languages. (For example,
   MASM is ideal for direct interface with the hardware, FORTRAN has almost
   any math function you could want, Pascal allows the creation of
   sophisticated data structures, and C provides both structured code and
   direct memory access.) These procedures are compiled and linked into a
   Quick library for use in your program. You can also write a separate
   module to test Quick library procedures the same way you would test other
   procedures.


 7.9  Compiling and Linking Modules

   The end product of your programming efforts is usually a stand-alone .EXE
   file. You can create one in QuickBASIC by loading all of a program's
   modules, then selecting the Make EXE File command from the Run menu.

   You can also compile modules with the BC command-line compiler, then use
   LINK to combine the object code. Object files from code written in other
   languages can be linked at the same time.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     When you use the Make EXE File command, all the module-level code and
     every procedure currently loaded is included in the .EXE file, whether
     or not the program uses this code. If you want your program to be as
     compact as possible, you must unload all unneeded module-level code and
     all unneeded procedures before compiling. The same rule applies when
     using BC to compile from the command line; all unused code should be
     removed from the files.
   ──────────────────────────────────────────────────────────────────────────


 7.10  Quick Libraries

   Although Microsoft Quick libraries are not modules, it is important that
   you understand their relationship with modules.

   A Quick library contains nothing but procedures. These procedures can be
   written not only in QuickBASIC, but also in other Microsoft languages as
   well (C, Pascal, FORTRAN, and MASM).

   A Quick library contains only compiled code. (Modules contain QuickBASIC
   source code.) A Quick library is created by linking compiled object code
   (.OBJ files). The code in a Quick library can come from any combination of
   Microsoft languages. Appendix H, "Creating and Using Quick Libraries,"
   explains how to create Quick libraries from object code and how to add new
   object code to existing Quick libraries.

   Quick libraries have several uses:

   ■ They provide an interface between QuickBASIC and other languages.

   ■ They allow designers to hide proprietary software. Updates and utilities
     can be distributed as Quick libraries without revealing the source code.

   ■ They load faster and are usually smaller than modules. If a large
     program with many modules loads slowly, converting the nonmain modules
     into a Quick library will improve loading performance.

   Note, however, that modules are the easiest way to work on procedures
   during development because modules are immediately ready to run after each
   edit; you don't have to recreate the Quick library. If you want to put
   your QuickBASIC procedures in a Quick library, wait until the procedures
   are complete and thoroughly debugged.

   When a Quick library is created, any module-level code in the file it was
   created from is automatically included. However, other modules cannot
   access this code, so it just wastes space. Before converting a module to a
   Quick library, be sure that all module-level statements (except any error
   or event handlers and declarations that are used by the procedures) have
   been removed.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Quick libraries are not included in .MAK files and must be loaded with
     the / L option when you run QuickBASIC. A Quick library has the file
     extension .QLB. During the process of creating the Quick library,
     another library file with the extension .LIB is created. This file
     contains the same code as the Quick library but in a form that allows it
     to be linked with the rest of the program to create a stand-alone
     application.

     If you use Quick libraries to distribute proprietary code
     (data-manipulation procedures, for example), be sure to include the .LIB
     files so that your customers can create stand-alone applications that
     use these procedures. Otherwise, they will be limited to running
     applications within the QuickBASIC environment.
   ──────────────────────────────────────────────────────────────────────────

 7.10.1  Creating Quick Libraries

   You can create a Quick library of QuickBASIC procedures with the Make
   Library command from the Run menu. The Quick library created contains
   every procedure currently loaded, whether or not your program calls it.
   (It also contains all the module-level code.) If you want the Quick
   library to be compact, be sure to remove all unused procedures and all
   unnecessary module-level code first.

   You can create as many Quick libraries as you like, containing whatever
   combination of procedures you wish. However, only one Quick library can be
   loaded into QuickBASIC at a time. (You would generally create
   application-specific Quick libraries, containing only the procedures a
   particular program needs.) Large Quick libraries can be created by loading
   many modules, then using the Make Library command.

   You can also compile one or more modules with the BC command, then link
   the object code files to create a Quick library. Quick libraries of
   procedures written

   in other languages are created the same way. In linking, you are not
   limited to one language; the object-code files from any number of
   Microsoft languages can be combined in one Quick library. Appendix H,
   "Creating and Using Quick Libraries," explains how to convert object-code
   (.OBJ) files into Quick libraries.


 7.11  Tips for Good Programming with Modules

   You can use modules in any way you think will improve your program or help
   organize your work. The following suggestions are offered as a guide.

   1. Think and organize first.

      When you start on a new project, make a list of the operations you want
      to be performed by procedures. Then look through your own procedure
      library to see if there are any you can use, either as-is or with
      slight modifications. Don't waste time "reinventing the wheel."

   2. Write generalized procedures with broad application.

      Try to write procedures that are useful in a wide variety of programs.
      Don't, however, make the procedure needlessly complex. A good procedure
      is a simple, finely honed tool, not a Swiss army knife.

      It is sometimes useful to alter an existing procedure to work in a new
      program. This might require modifying programs you've already written,
      but it's worth the trouble if the revised procedure is more powerful or
      has broader application.

   3. When creating your own procedure modules, keep logically separate
      procedures in separate modules.

      It makes sense to put string-manipulation procedures in one module,
      matrix-handling procedures in another, and data-communication
      procedures in a third. This arrangement avoids confusion and makes it
      easy to find the procedure you need.



 ────────────────────────────────────────────────────────────────────────────
 PART 2  HEART OF BASIC
 ────────────────────────────────────────────────────────────────────────────

   Part 2 provides a quick-reference guide to all statements and functions
   used in this version of BASIC.

   Chapter 8 gives a brief summary of the action of each statement or
   function──organized alphabetically by keyword──and includes syntax lines
   that identify the statement's correct form. Use it when programming to
   remind yourself how each one works.

   Chapter 9 is made up of reference tables that organize commonly used
   statements and functions by programming topic. These tables follow the
   same organization as the first six chapters of this book. Use these tables
   to identify alternative ways to approach particular programming
   objectives.



 ────────────────────────────────────────────────────────────────────────────
 Chapter 8  Statement and Function Summary

   This chapter summarizes QuickBASIC statements and functions. Each
   statement or function name is followed by an action description and a
   syntax line. The syntax line shows exactly what you must enter to use the
   statement.

   Complete details of the typographic conventions used in syntax lines are
   given in the introduction to this manual. In general, items you must type
   exactly as shown are in boldface type; placeholders for items of
   information you must supply are in Italic type. Square brackets indicate
   optional items.

   The QB Advisor (QuickBASIC's on-line language help) provides for each
   statement or function:

   ■ A summary of the statement's action and syntax (the QuickSCREEN)

   ■ Complete details of how to use the statement, including explanations of
     the placeholders

   ■ One of more program examples illustrating statement use

   You can access this information by putting the cursor on any BASIC keyword
   displayed in the QuickBASIC View window and pressing F1.

   The statements and functions in this chapter are grouped by topic in
   Chapter 9, "Quick-Reference Tables." Use Chapter 9 to find out what
   statements are available for a particular programming task.


 ABS Function

   Returns the absolute value of a numeric expression

   SYNTAX  ABS(numeric-expression)


 ASC Function

   Returns a numeric value that is the ASCII code for the first character in
   a string expression

   SYNTAX  ASC(stringexpression)


 ATN Function

   Returns the arctangent of a numeric expression (the angle whose tangent is
   equal to the numeric expression)

   SYNTAX  ATN(numeric-expression)


 BEEP Statement

   Sounds the speaker

   SYNTAX  BEEP


 BLOAD Statement

   Loads a memory-image file, created by BSAVE, into memory from an input
   file or device

   SYNTAX  BLOAD filespec [[,offset]]


 BSAVE Statement

   Transfers the contents of an area of memory to an output file or device

   SYNTAX  BSAVE filespec,offset,length


 CALL Statement (BASIC Procedures)

   Transfers control to a BASIC SUB

   SYNTAX 1  CALL name[[(argumentlist )]]

   SYNTAX 2  name[[argumentlist]]


 CALL, CALLS Statement (Non-BASIC Procedures)

   Transfers control to a procedure written in another language

   SYNTAX 1  CALL name [[(call-argumentlist )]]

   SYNTAX 2  name [[call-argumentlist]]

   SYNTAX 3  CALLS name [[(calls-argumentlist )]]


 CALL INT86OLD Statements

   Allows programs to perform DOS system calls

   SYNTAX  CALL INT86OLD (int_no,in_array(),out_array())
           CALL INT86XOLD (int_no,in_array(),out_array())


 CALL ABSOLUTE Statement

   Transfers control to a machine-language procedure

   SYNTAX  CALL ABSOLUTE ([[argumentlist,]]integervariable)


 CALL INTERRUPT Statements

   Allows BASIC programs to perform DOS system calls

   SYNTAX  CALL INTERRUPT (interruptnum, inregs, outregs)
           CALL INTERRUPTX (interruptnum, inregs, outregs)


 CDBL Function

   Converts a numeric expression to a double-precision number

   SYNTAX  CDBL(numeric-expression)


 CHAIN Statement

   Transfers control from the current program to another program

   SYNTAX  CHAIN filespec


 CHDIR Statement

   Changes the current default directory for the specified drive

   SYNTAX  CHDIR pathspec


 CHR$ Function

   Returns a one-character string whose ASCII code is the argument

   SYNTAX  CHR$(code)


 CINT Function

   Converts a numeric expression to an integer by rounding the fractional
   part of the expression

   SYNTAX  CINT(numeric-expression)


 CIRCLE Statement

   Draws an ellipse or circle with a specified center and radius

   SYNTAX  CIRCLE[[STEP]]
           (x,y),radius[[,[[color]][[,[[start]][[,[[end]][[,aspect]]]]]]]]


 CLEAR Statement

   Reinitializes all program variables, closes files, and sets the stack size

   SYNTAX  CLEAR[[,,stack]]


 CLNG Function

   Converts a numeric expression to a long (4-byte) integer by rounding the
   fractional part of the expression

   SYNTAX  CLNG(numeric-expression)


 CLOSE Statement

   Concludes I/O to a file or device

   SYNTAX  CLOSE[[[[#]] filenumber [[,[[#]] filenumber]]... ]]


 CLS Statement

   Clears the screen

   SYNTAX  CLS[[{0| 1| 2}]]


 COLOR Statement

   Selects display colors

   SYNTAX  COLOR[[foreground]][[,[[background]][[,border]]]]  Screen mode 0
           COLOR[[background]][[,palette]]                    Screen mode 1
           COLOR[[foreground]][[,background]]                 Screen modes
                                                              7-10
           COLOR[[foreground]]                                Screen modes
                                                              12-13


 COM Statements

   Enables, disables, or inhibits event trapping of communications activity
   on a specified port

   SYNTAX  COM(n) ON COM(n) OFF COM(n) STOP


 COMMAND$ Function

   Returns the command line used to invoke the program

   SYNTAX  COMMAND$


 COMMON Statement

   Defines global variables for sharing between modules or for chaining to
   another program

   SYNTAX  COMMON[[SHARED]][[/blockname/]] variablelist


 CONST Statement

   Declares symbolic constants to use in place of numeric or string values

   SYNTAX  CONST constantname = expression [[,constantname = expression]]...


 COS Function

   Returns the cosine of an angle given in radians

   SYNTAX  COS(numeric-expression)


 CSNG Function

   Converts a numeric expression to a single-precision value

   SYNTAX  CSNG(numeric-expression)


 CSRLIN Function

   Returns the current line (row) position of the cursor

   SYNTAX  CSRLIN


 CVI, CVS, CVL, CVD Functions

   Convert strings containing numeric values to numbers

   SYNTAX  CVI(2-byte-string)
           CVS(4-byte-string)
           CVL(4-byte-string)
           CVD(8-byte-string)


 CVSMBF, CVDMBF Functions

   Convert strings containing Microsoft Binary format numbers to IEEE-format
   numbers

   SYNTAX  CVSMBF (4-byte-string)
           CVDMBF (8-byte-string)


 DATA Statement

   Stores the numeric and string constants used by a program's READ
   statements

   SYNTAX  DATA constant1 [[,constant2]]...


 DATE$ Function

   Returns a string containing the current date

   SYNTAX  DATE$


 DATE$ Statement

   Sets the current date

   SYNTAX  DATE$ = stringexpression


 DECLARE Statement (BASIC Procedures)

   Declares references to BASIC procedures and invokes argument type checking

   SYNTAX  DECLARE{FUNCTION | SUB } name [[([[parameterlist]])]]


 DECLARE Statement (Non-BASIC Procedures)

   Declares calling sequences for external procedures written in other
   languages

   SYNTAX 1  DECLARE FUNCTION name [[CDECL]]
             [[ALIAS "aliasname"]][[([[parameterlist]])]]

   SYNTAX 2  DECLARE SUB name [[CDECL]] [[ALIAS
             "aliasname"]][[([[parameterlist]])]]


 DEF FN Statement

   Defines and names a function

   SYNTAX 1  DEF FNname[[(parameterlist)]] = expression

   SYNTAX 2  DEF FNname[[(parameterlist)]]
             .
             .
             .
             FNname = expression
             .
             .
             .
             END DEF


 DEF SEG Statement

   Sets the current segment address for a subsequent PEEK function or a
   BLOAD, BSAVE, CALL ABSOLUTE, or POKE statement

   SYNTAX  DEF SEG[[=address]]


 DEFtype Statements

   Set the default data type for variables, DEF FN functions, and FUNCTION
   procedures

   SYNTAX  DEFINT letterrange [[,letterrange]]...
           DEFSNG letterrange [[,letterrange]]...
           DEFDBL letterrange [[,letterrange]]...
           DEFLNG letterrange [[,letterrange]]...
           DEFSTR letterrange [[,letterrange]]...


 DIM Statement

   Declares a variable and allocates storage space

   SYNTAX  DIM[[SHARED]] variable[[(subscripts)]] [[AS type]]
           [[,variable[[(subscripts)]] [[AStype]]]]...


 DO...LOOP Statements

   Repeats a block of statements while a condition is true or until a
   condition becomes true

   SYNTAX 1  DO     [[statementblock]]
             LOOP[[{WHILE| UNTIL} booleanexpression]]

   SYNTAX 2  DO[[{WHILE| UNTIL} booleanexpression]]
                  [[statementblock]]
             LOOP


 DRAW Statement

   Draws an object defined by stringexpression

   SYNTAX  DRAW stringexpression


 END Statement

   Ends a BASIC program, procedure, or block

   SYNTAX  END[[{DEF| FUNCTION | IF| SELECT| SUB | TYPE}]]


 ENVIRON$ Function

   Retrieves an environment string from the DOS environment-string table

   SYNTAX  ENVIRON$ (environmentstring)
           ENVIRON$ (n)


 ENVIRON Statement

   Modifies a parameter in the DOS environment-string table

   SYNTAX  ENVIRON stringexpression


 EOF Function

   Tests for the end-of-file condition

   SYNTAX  EOF(filenumber)


 ERASE Statement

   Reinitializes the elements of static arrays; deallocates dynamic arrays

   SYNTAX  ERASE arrayname [[,arrayname...]]


 ERDEV, ERDEV$ Functions

   Provides device-specific status information after an error

   SYNTAX  ERDEV
           ERDEV$


 ERR, ERL Functions

   Return error status

   SYNTAX  ERR
           ERL


 ERROR Statement

   Simulates the occurrence of a BASIC error or allows the user to define
   error codes

   SYNTAX  ERROR integerexpression


 EXIT Statement

   Exits a DEF FN function, DO...LOOP or FOR...NEXT loop, FUNCTION, or SUB

   SYNTAX  EXIT{DEF| DO| FOR| FUNCTION| SUB}


 EXP Function

   Calculates the exponential function

   SYNTAX  EXP(x)


 FIELD Statement

   Allocates space for variables in a random-access file buffer

   SYNTAX  FIELD[[#]]filenumber, fieldwidth AS stringvariable...


 FILEATTR Function

   Returns information about an open file

   SYNTAX  FILEATTR(filenumber,attribute)


 FILES Statement

   Prints the names of files residing on the specified disk

   SYNTAX  FILES[[filespec]]


 FIX Function

   Returns the truncated integer part of x

   SYNTAX  FIX(x)


 FOR...NEXT Statement

   Repeats a group of instructions a specified number of times

   SYNTAX  FOR counter = start TO end [[STEP increment]]
           .
           .
           .
           NEXT[[counter[[,counter...]]]]


 FRE Function

   Returns the amount of available memory

   SYNTAX 1  FRE(numeric-expression)

   SYNTAX 2  FRE(stringexpression)


 FREEFILE Function

   Returns the next free BASIC file number

   SYNTAX  FREEFILE


 FUNCTION Statement

   Declares the name, the parameters, and the code that form the body of a
   FUNCTION procedure

   SYNTAX  FUNCTION name [[(parameter-list)]][[STATIC]]
           .
           .
           .
           name = expression
           .
           .
           .
           END FUNCTION


 GET Statement──File I/O

   Reads from a disk file into a random-access buffer or variable

   SYNTAX  GET[[#]]filenumber[[,[[recordnumber]][[,variable]]]]


 GET Statement──Graphics

   Stores graphic images from the screen

   SYNTAX  GET[[STEP]](x1,y1) -[[STEP]](x2,y2),arrayname[[(indices)]]


 GOSUB...RETURN Statements

   Branches to, and returns from, a subroutine

   SYNTAX  GOSUB{linelabel1| linenumber1 }
           .
           .
           .
           RETURN[[linelabel2| linenumber2 ]]


 GOTO Statement

   Branches unconditionally to the specified line

   SYNTAX  GOTO{linelabel| linenumber}


 HEX$ Function

   Returns a string that represents the hexadecimal value of the decimal
   argument expression

   SYNTAX  HEX$(expression)


 IF...THEN...ELSE Statements

   Allows conditional execution, based on the evaluation of a Boolean
   expression

   SYNTAX 1 (SINGLE LINE)  IF booleanexpression THEN thenpart [[ELSE
                           elsepart]]

   SYNTAX 2 (BLOCK)   IF booleanexpression1 THEN
                           [[statementblock-1]]
                      [[ELSEIF booleanexpression2 THEN
                           [[statementblock-2]]]]
                      .
                      .
                      .
                      [[ELSE
                           [[statement-blockn]]]]
                      END IF


 INKEY$ Function

   Reads a character from the keyboard

   SYNTAX  INKEY$


 INP Function

   Returns the byte read from an I/O port

   SYNTAX  INP(port)


 INPUT$ Function

   Returns a string of characters read from the specified file

   SYNTAX  INPUT$(n[[,[[#]]filenumber]])


 INPUT Statement

   Allows input from the keyboard during program execution

   SYNTAX  INPUT[[;]][["promptstring"{; | ,}]] variablelist


 INPUT # Statement

   Reads data items from a sequential device or file and assigns them to
   variables

   SYNTAX  INPUT # filenumber, variablelist


 INSTR Function

   Returns the character position of the first occurrence of a string in
   another string

   SYNTAX  INSTR([[start,]]stringexpression1,stringexpression2)


 INT Function

   Returns the largest integer less than or equal to numeric-expression

   SYNTAX  INT(numeric-expression)


 IOCTL$ Function

   Receives a control data string from a device driver

   SYNTAX  IOCTL$ ([[#]]filenumber)


 IOCTL Statement

   Transmits a control data string to a device driver

   SYNTAX  IOCTL[[#]]filenumber, string


 KEY Statements

   Assign soft-key string values to function keys, then display the values
   and enable or disable the FUNCTION key display line

   SYNTAX  KEY n, stringexpression
           KEY LIST
           KEY ON
           KEY OFF


 KEY(n) Statements

   Start or stop trapping of specified keys

   SYNTAX  KEY(n) ON
           KEY(n) OFF
           KEY(n) STOP


 KILL Statement

   Deletes a file from disk

   SYNTAX  KILL filespec


 LBOUND Function

   Returns the lower bound (smallest available subscript) for the indicated
   dimension of an array

   SYNTAX  LBOUND(array[[,dimension]])


 LCASE$ Function

   Returns a string expression with all letters in lower-case

   SYNTAX  LCASE$ (stringexpression)


 LEFT$ Function

   Returns a string consisting of the leftmost n characters of a string

   SYNTAX  LEFT$(stringexpression,n)


 LEN Function

   Returns the number of characters in a string or the number of bytes
   required by a variable

   SYNTAX  LEN(stringexpression)
           LEN(variable)


 LET Statement

   Assigns the value of an expression to a variable

   SYNTAX  [[LET]]variable=expression


 LINE Statement

   Draws a line or box on the screen

   SYNTAX  LINE[[[[STEP]] (x1,y1)]] -[[STEP]]
           (x2,y2)[[,[[color]][[,[[B[[F]]]][[,style]]]]]]


 LINE INPUT Statement

   Inputs an entire line (up to 255 characters) to a string variable, without
   the use of delimiters

   SYNTAX  LINE INPUT[[;]] [["promptstring";]] stringvariable


 LINE INPUT # Statement

   Reads an entire line without delimiters from a sequential file to a string
   variable

   SYNTAX  LINE INPUT #filenumber,stringvariable


 LOC Function

   Returns the current position within the file

   SYNTAX  LOC(filenumber)


 LOCATE Statement

   Moves the cursor to the specified position

   SYNTAX  LOCATE[[row]][[,[[column]][[,[[cursor]][[,[[start,stop]]]]]]]]


 LOCK...UNLOCK Statement

   Controls access by other processes to all or part of an opened file

   SYNTAX  LOCK[[#]] filenumber [[,{record | [[start]] TO end}]]
           .
           .
           .
           UNLOCK[[#]] filenumber [[,{record | [[start]] TO end}]]


 LOF Function

   Returns the length of the named file in bytes

   SYNTAX  LOF(filenumber)


 LOG Function

   Returns the natural logarithm of a numeric expression

   SYNTAX  LOG(n)


 LPOS Function

   Returns the current position of the line printer's print head within the
   printer buffer

   SYNTAX  LPOS(n)


 LPRINT, LPRINT USING Statements

   Prints data on the printer LPT1:

   SYNTAX 1  LPRINT[[expressionlist]] [[{;|,}]]

   SYNTAX 2  LPRINT USING formatstring; expression-list [[{;|,}]]


 LSET Statement

   Moves data from memory to a random-access file buffer (in preparation for
   a PUT statement), copies one record variable to another, or left-justifies
   the value of a string in a string variable

   SYNTAX
           LSET{stringvariable=stringexpression|stringexpression1=stringexpre
           ssion2}


 LTRIM$ Function

   Returns a copy of a string with leading spaces removed

   SYNTAX  LTRIM$(stringexpression)


 MID$ Function

   Returns a substring of a string

   SYNTAX  MID$(stringexpression,start[[,length]])


 MID$ Statement

   Replaces a portion of a string variable with another string

   SYNTAX  MID$(stringvariable,start[[,length]])=stringexpression


 MKD$, MKI$, MKL$, MKS$ Functions

   Converts numeric values to string values

   SYNTAX  MKI$(integerexpression)
           MKS$(single-precision-expression)
           MKL$(long-integer-expression)
           MKD$(double-precision-expression)


 MKDIR Statement

   Creates a new directory

   SYNTAX  MKDIR pathname


 MKSMBF$, MKDMBF$ Functions

   Converts an IEEE-format number to a string containing a Microsoft Binary
   format number

   SYNTAX  MKSMBF$(single-precision-expression)
           MKDMBF$(double-precision-expression)


 NAME Statement

   Changes the name of a disk file or directory

   SYNTAX  NAME oldfilename AS newfilename


 OCT$ Function

   Returns a string representing the octal value of the numeric argument

   SYNTAX  OCT$(numeric-expression)


 ON ERROR Statement

   Enables error handling and specifies the first line of the error-handling
   routine

   SYNTAX  ON ERROR GOTO line


 ON event Statements

   Indicates the first line of an event-trapping subroutine

   SYNTAX  ON event GOSUB{linenumber | linelabel }


 ON UEVENT GOSUB Statement

   Defines the event-handler for a user-defined event

   SYNTAX  ON UEVENT GOSUB { linenumber| linelabel }


 ON...GOSUB, ON...GOTO Statements

   Branches to one of several specified lines, depending on the value of an
   expression

   SYNTAX 1  ON expression GOSUB{line-number-list | line-label-list }

   SYNTAX 2  ON expression GOTO{line-number-list | line-label-list }


 OPEN Statement

   Enables I/O to a file or device

   SYNTAX 1  OPEN file[[FOR mode1]] [[ACCESS access]] [[lock]] AS[[#]]
             filenum[[LEN=reclen]]

   SYNTAX 2  OPEN mode2,[[#]]filenum, file [[,reclen]]


 OPEN COM Statement

   Opens and initializes a communications channel for I/O

   SYNTAX  OPEN "COMn: optlist1 optlist2" [[FOR mode]] AS[[#]]filenum
           [[LEN=reclen]]


 OPTION BASE Statement

   Declares the default lower bound for array subscripts

   SYNTAX  OPTION BASE n


 OUT Statement

   Sends a byte to a machine I/O port

   SYNTAX  OUT port, data


 PAINT Statement

   Fills a graphics area with the color or pattern specified

   SYNTAX  PAINT[[STEP]] (x,y)[[,[[paint]] [[,[[bordercolor]]
           [[,background]]]]]]


 PALETTE, PALETTE USING Statements

   Changes one or more of the colors in the palette

   SYNTAX  PALETTE[[attribute,color]]
           PALETTE USING array-name [[(array-index)]]


 PCOPY Statement

   Copies one screen page to another

   SYNTAX  PCOPY sourcepage, destinationpage


 PEEK Function

   Returns the byte stored at a specified memory location

   SYNTAX  PEEK(address)


 PEN Function

   Reads the lightpen coordinates

   SYNTAX  PEN(n)


 PEN ON, OFF, and STOP Statements

   Enables, disables, or suspends lightpen event trapping

   SYNTAX  PEN ON
           PEN OFF
           PEN STOP


 PLAY Function

   Returns the number of notes currently in the background-music queue

   SYNTAX  PLAY (n)


 PLAY Statement

   Plays music as specified by a string

   SYNTAX  PLAY commandstring


 PLAY ON, OFF, and STOP Statements

   PLAY ON enables play event trapping, PLAY OFF disables play event
   trapping, and PLAY STOP suspends play event trapping.

   SYNTAX  PLAY ON
           PLAY OFF
           PLAY STOP


 PMAP Function

   Maps view-coordinate expressions to physical locations, or maps physical
   expressions to a view-coordinate location

   SYNTAX  PMAP (expression, function)


 POINT Function

   Reads the color number of a pixel from the screen or returns the pixel's
   coordinates

   SYNTAX  POINT (x,y)
           POINT (number)


 POKE Statement

   Writes a byte into a memory location

   SYNTAX  POKE address,byte


 POS Function

   Returns the current horizontal position of the cursor

   SYNTAX  POS(0)


 PRESET Statement

   Draws a specified point on the screen

   SYNTAX  PRESET[[STEP]](xcoordinate,ycoordinate) [[,color]]


 PRINT Statement

   Outputs data on the screen

   SYNTAX  PRINT[[expressionlist]] [[{,| ;}]]


 PRINT #, PRINT # USING Statements

   Writes data to a sequential file

   SYNTAX  PRINT #filenumber,[[USING stringexpression;]] expressionlist [[{,
           | ;}]]


 PRINT USING Statement

   Prints strings or numbers using a specified format

   SYNTAX  PRINT USING formatstring; expressionlist [[{,| ;}]]


 PSET Statement

   Draws a point on the screen

   SYNTAX  PSET[[STEP]](xcoordinate,ycoordinate) [[,color]]


 PUT Statement──File I/O

   Writes from a variable or a random-access buffer to a file

   SYNTAX  PUT[[#]]filenumber[[,[[recordnumber]][[,variable]]]]
           PUT[[#]]filenumber[[,{recordnumber|recordnumber,
           variable|,variable}]]


 PUT Statement──Graphics

   Places a graphic image obtained by a GET statement onto the screen

   SYNTAX  PUT[[STEP]] (x,y), arrayname[[(indices)]] [[,actionverb]]


 RANDOMIZE Statement

   Initializes (reseeds) the random-number generator

   SYNTAX  RANDOMIZE[[expression]]


 READ Statement

   Reads values from a DATA statement and assigns the values to variables

   SYNTAX  READ variablelist


 REDIM Statement

   Changes the space allocated to an array that has been declared $DYNAMIC

   SYNTAX  REDIM[[SHARED]] variable(subscripts)[[AS type]]
           [[,variable(subscripts)[[AS
           type]]]]...


 REM Statement

   Allows explanatory remarks to be inserted in a program

   SYNTAX 1  REM remark

   SYNTAX 2  ' remark


 RESET Statement

   Closes all disk files

   SYNTAX  RESET


 RESTORE Statement

   Allows DATA statements to be reread from a specified line

   SYNTAX  RESTORE[[{linenumber | linelabel }]]


 RESUME Statement

   Continues program execution after an error-trapping routine has been
   invoked

   SYNTAX  RESUME[[0]]
           RESUME NEXT
           RESUME { linenumber| linelabel }


 RETURN Statement

   Returns control from a subroutine

   SYNTAX  RETURN[[{linenumber | linelabel }]]


 RIGHT$ Function

   Returns the rightmost n characters of a string

   SYNTAX  RIGHT$(stringexpression,n)


 RMDIR Statement

   Removes an existing directory

   SYNTAX  RMDIR pathname


 RND Function

   Returns a single-precision random number between 0 and 1

   SYNTAX  RND[[(n)]]


 RSET Statement

   Moves data from memory to a random-access file buffer (in preparation for
   a PUT statement) or right-justifies the value of a string in a string
   variable

   SYNTAX  RSET stringvariable=stringexpression


 RTRIM$ Function

   Returns a string with trailing (right-hand) spaces removed

   SYNTAX  RTRIM$(stringexpression)


 RUN Statement

   Restarts the program currently in memory or executes a specified program

   SYNTAX  RUN[[{ linenumber | commandline }]]


 SADD Function

   Returns the address of the specified string expression

   SYNTAX  SADD(stringvariable)


 SCREEN Function

   Reads a character's ASCII value or its color from a specified screen
   location

   SYNTAX  SCREEN(row,column[[,colorflag]])


 SCREEN Statement

   Sets the specifications for the display screen

   SYNTAX  SCREEN[[mode]] [[,[[colorswitch]] ]][[,[[apage]] ]][[,[[vpage]]]]


 SEEK Function

   Returns the current file position

   SYNTAX  SEEK(filenumber)


 SEEK Statement

   Sets the position in a file for the next read or write

   SYNTAX  SEEK[[#]]filenumber,position


 SELECT CASE Statement

   Executes one of several statement blocks depending on the value of an
   expression

   SYNTAX  SELECT CASE testexpression
           CASE expressionlist1
                [[statementblock-1]]
           [[CASE expressionlist2
                [[statementblock-2]]]]
           .
           .
           .
           [[CASE ELSE
                [[statementblock-n]]]]
           END SELECT


 SETMEM Function

   Changes the amount of memory used by the far heap──the area where far
   objects and internal tables are stored

   SYNTAX  SETMEM(numeric-expression)


 SGN Function

   Indicates the sign of a numeric expression

   SYNTAX  SGN(numeric-expression)


 SHARED Statement

   Gives a SUB or FUNCTION procedure access to variables declared at the
   module level without passing them as parameters

   SYNTAX  SHARED variable [[AS type]] [[,variable [[AS type]]]]...


 SHELL Statement

   Exits the BASIC program, runs a .COM, .EXE, or .BAT program or a DOS
   command, and returns to the program at the line following the SHELL
   statement

   SYNTAX  SHELL[[commandstring]]


 SIN Function

   Returns the sine of the angle x, where x is in radians

   SYNTAX  SIN(x)


 SLEEP Statement

   Suspends execution of the calling program

   SYNTAX  SLEEP[[ seconds ]]


 SOUND Statement

   Generates sound through the speaker

   SYNTAX  SOUND frequency,duration


 SPACE$ Function

   Returns a string of spaces of length n

   SYNTAX  SPACE$(n)


 SPC Function

   Skips n spaces in a PRINT statement

   SYNTAX  SPC(n)


 SQR Function

   Returns the square root of n

   SYNTAX  SQR(n)


 STATIC Statement

   Makes simple variables or arrays local to either a DEF FN function, a
   FUNCTION, or a SUB and preserves values between calls

   SYNTAX  STATIC variablelist


 STICK Function

   Returns the x and y coordinates of the two joysticks

   SYNTAX  STICK(n)


 STOP Statement

   Terminates the program

   SYNTAX  STOP


 STR$ Function

   Returns a string representation of the value of a numeric expression

   SYNTAX  STR$(numeric-expression)


 STRIG Function and Statement

   Returns the status of a specified joystick trigger

   SYNTAX 1 (FUNCTION)  STRIG(n)

   SYNTAX 2 (STATEMENT)  STRIG{ON| OFF}


 STRIG ON, OFF, and STOP Statements

   Enable, disable, or inhibit trapping of joystick activity

   SYNTAX  STRIG(n) ON
           STRIG(n) OFF
           STRIG(n) STOP


 STRING$ Function

   Returns a string whose characters all have a given ASCII code or whose
   characters are all the first character of a string expression

   SYNTAX  STRING$(m,n)
           STRING$(m,stringexpression)


 SUB Statements

   Marks the beginning and end of a subprogram

   SYNTAX  SUB globalname[[(parameterlist)]] [[STATIC]]
           .
           .
           .
           [[EXIT SUB]]
           .
           .
           .
           END SUB


 SWAP Statement

   Exchanges the values of two variables

   SYNTAX  SWAP variable1,variable2


 SYSTEM Statement

   Closes all open files and returns control to the operating system

   SYNTAX  SYSTEM


 TAB Function

   Moves the print position

   SYNTAX  TAB(column)


 TAN Function

   Returns the tangent of the angle x, where x is in radians

   SYNTAX  TAN(x)


 TIME$ Function

   Returns the current time from the operating system

   SYNTAX  TIME$


 TIME$ Statement

   Sets the time

   SYNTAX  TIME$=stringexpression


 TIMER Function

   Returns the number of seconds elapsed since midnight

   SYNTAX  TIMER


 TIMER ON, OFF, and STOP Statements

   Enables, disables, or inhibits timer event trapping

   SYNTAX  TIMER ON
           TIMER OFF
           TIMER STOP


 TRON/TROFF Statements

   Traces the execution of program statements

   SYNTAX  TRON
           TROFF


 TYPE Statement

   Defines a data type containing one or more elements

   SYNTAX  TYPE usertype
              elementname AS    typename
              elementname AS    typename
              .
              .
              .
           END TYPE


 UBOUND Function

   Returns the upper bound (largest available subscript) for the indicated
   dimension of an array

   SYNTAX  UBOUND(array[[,dimension]])


 UCASE$ Function

   Returns a string expression with all letters in uppercase

   SYNTAX  UCASE$ (stringexpression)


 UEVENT Statement

   Enables, disables, or suspends event trapping for a user-defined event

   SYNTAX  UEVENT ON
           UEVENT OFF
           UEVENT STOP


 UNLOCK Statement

   Releases locks applied to parts of a file

   SYNTAX  UNLOCK[[#]] filenumber [[,{record | [[start]] TO end}]]


 VAL Function

   Returns the numeric value of a string of digits

   SYNTAX  VAL(stringexpression)


 VARPTR, VARSEG Functions

   Return the address of a variable

   SYNTAX  VARPTR(variablename)
           VARSEG(variablename)


 VARPTR$ Function

   Returns a string representation of a variable's address for use in DRAW
   and PLAY statements

   SYNTAX  VARPTR$(variablename)


 VIEW Statement

   Defines screen limits for graphics output

   SYNTAX  VIEW[[[[SCREEN]] (x1,y1)-(x2,y2)[[,[[color]] [[,border]]]]]]


 VIEW PRINT Statement

   Sets the boundaries of the screen text viewport

   SYNTAX  VIEW PRINT[[topline TO bottomline]]


 WAIT Statement

   Suspends program execution while monitoring the status of a machine input
   port

   SYNTAX  WAIT portnumber,and-expression[[,xor-expression]]


 WHILE...WEND Statement

   Executes a series of statements in a loop, as long as a given condition is
   true

   SYNTAX  WHILE condition
           .
           .
           .
           [[statements]]
           .
           .
           .
           WEND


 WIDTH Statement

   Assigns an output-line width to a file or device or changes the number of
   columns and lines displayed on the screen

   SYNTAX  WIDTH[[columns]][[,lines]]
           WIDTH{# filenumber | device} , width
           WIDTH LPRINT width


 WINDOW Statement

   Defines the logical dimensions of the current viewport

   SYNTAX  WINDOW[[[[SCREEN]] (x1,y1)-(x2,y2)]]


 WRITE Statement

   Sends data to the screen

   SYNTAX  WRITE[[expressionlist]]


 WRITE # Statement

   Writes data to a sequential file

   SYNTAX  WRITE #filenumber,expressionlist



 ────────────────────────────────────────────────────────────────────────────
 Chapter 9  Quick-Reference Tables

   Each section in this chapter summarizes a group of statements or functions
   that you typically use together. Each group is presented in a table, which
   lists the type of task performed (for example, looping or searching), the
   statement or function name, and the statement action.

   The following topics are summarized in tabular form:

   ■ Control-flow statements

   ■ Statements used in BASIC procedures

   ■ Standard I/O statements

   ■ File I/O statements

   ■ String-processing statements and functions

   ■ Graphics statements and functions

   ■ Trapping statements and functions

   You can use these tables both as a reference guide to what each statement
   or function does and as a way to identify related statements.


 9.1  Summary of Control-Flow Statements

   Table 9.1 lists the BASIC statements used to control the flow of a
   program's execution.

   Table 9.1  Statements Used in Looping and Decision-Making
╓┌─┌────────────────────┌────────────────────┌───────────────────────────────╖
   Task                 Statement            Action
   ──────────────────────────────────────────────────────────────────────────
   Looping              FOR...NEXT           Repeats statements between FOR
                                             and NEXT a specific number of
                                             times.

                        EXIT FOR             Provides an alternative way to
                                             exit a FOR...NEXT loop.

                        DO...LOOP            Repeats statements between DO
                                             and LOOP, either until a given
                                             condition is true (DO...LOOP
                                             UNTIL condition), or while a
                                             given condition is true
   Task                 Statement            Action
   ──────────────────────────────────────────────────────────────────────────
                                            given condition is true
                                             (DO...LOOP WHILE condition).

                        EXIT DO              Provides an alternative way to
                                             exit a DO...LOOP loop.

                        WHILE...WEND         Repeats statements between WHILE
                                             and WEND while a given condition
                                             is true (similar to DO WHILE
                                             condition...LOOP).

   Making decisions     IF...THEN...ELSE     Conditionally executes or
                                             branches to different
                                             statements.

                        SELECT CASE          Conditionally executes different
                                             statements.
   ──────────────────────────────────────────────────────────────────────────

   Task                 Statement            Action
   ──────────────────────────────────────────────────────────────────────────



 9.2  Summary of Statements Used in BASIC Procedures

   Table 9.2 lists the statements used in BASIC to define, declare, call,
   and pass arguments to BASIC procedures. Table 9.2 also lists the
   statements used to share variables among procedures, modules, and separate
   programs in a chain.

   Table 9.2  Statements Used in Procedures
╓┌─┌────────────────────┌────────────────────┌───────────────────────────────╖
   Task                 Statement            Action
   ──────────────────────────────────────────────────────────────────────────
   Defining a procedure FUNCTION...END       Mark the beginning and end,
                        FUNCTION             respectively, of a FUNCTION
                                             procedure.

                        SUB...END SUB        Mark the beginning and end,
   Task                 Statement            Action
   ──────────────────────────────────────────────────────────────────────────
                       SUB...END SUB        Mark the beginning and end,
                                             respectively, of a SUB
                                             procedure.

   Calling a procedure  CALL                 Transfers control to a BASIC SUB
                                             procedure, or to a procedure
                                             written in another programming
                                             language and compiled
                                             separately. (The CALL keyword is
                                             optional.)

   Exiting from a       EXIT FUNCTION        Provides another way to exit a
   procedure                                 FUNCTION procedure.

                        EXIT SUB             Provides an alternative way to
                                             exit a SUB procedure.

   Referencing a        DECLARE              Declares a FUNCTION or SUB and,
   procedure before it                       optionally, specifies the number
   Task                 Statement            Action
   ──────────────────────────────────────────────────────────────────────────
  procedure before it                       optionally, specifies the number
   is defined                                and type of its parameters.

   Sharing variables    COMMON               Shares variables among separate
   among modules,                            modules. When used with the
   procedures, or                            SHARED attribute, it shares
   programs                                  variables among different
                                             procedures in the same module.
                                             Also, passes variable values
                                             from current program to new
                                             program when control is
                                             transferred with the CHAIN
                                             statement.

                        SHARED               When used with the COMMON, DIM,
                                             or REDIM statement at the module
                                             level (for example, DIM SHARED),
                                             shares variables with every SUB
                                             or FUNCTION in a single module.
   Task                 Statement            Action
   ──────────────────────────────────────────────────────────────────────────
                                            or FUNCTION in a single module.

                                             When used by itself within a
                                             procedure, shares variables
                                             between that procedure and the
                                             module-level code.

   Preserving variable  STATIC               Forces variables to be local to
   values                                    a procedure or DEF FN function
                                             and preserves the value stored
                                             in the variable if the procedure
                                             or function is exited, then
                                             called again.

   Defining a multiline DEF FN...END DEF     Mark the beginning and end,
   function                                  respectively, of a multiline DEF
                                             FN function. (This is the old
                                             style for functions in BASIC──
                                             FUNCTION procedures provide a
   Task                 Statement            Action
   ──────────────────────────────────────────────────────────────────────────
                                            FUNCTION procedures provide a
                                             powerful alternative.)

   Exiting from a       EXIT DEF             Provides an alternative way to
   multiline function                        exit a multiline DEF FN
                                             function.

   Calling a BASIC      GOSUB                Transfers control to a specific
   subroutine                                line in a module. Control is
                                             returned from the subroutine to
                                             the line following the GOSUB
                                             statement with a RETURN
                                             statement. (This is the old
                                             style for subroutines in BASIC──
                                             SUB procedures provide a
                                             powerful alternative.)

   Transferring to      CHAIN                Transfers control from current
   another program                           program in memory to another
   Task                 Statement            Action
   ──────────────────────────────────────────────────────────────────────────
  another program                           program in memory to another
                                             program; use COMMON to pass
                                             variables to the new program.
   ──────────────────────────────────────────────────────────────────────────



 9.3  Summary of Standard I/O Statements

   Table 9.3 lists the statements and functions used in BASIC for standard
   I/O (typically, input from the keyboard and output to the screen).

   Table 9.3  Statements and Functions Used for Standard I/O
╓┌─┌────────────────────┌────────────────────┌───────────────────────────────╖
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
   Printing text on the PRINT                Outputs text to the screen.
   screen                                    Using PRINT with no arguments
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
  screen                                    Using PRINT with no arguments
                                             creates a blank line.

                        PRINT USING          Outputs formatted text to the
                                             screen.

   Changing the width   WIDTH                Changes the width of the screen
   of the output line                        to either 40 columns or 80
                                             columns and, on computers with
                                             an EGA or VGA, controls the
                                             number of lines on the screen
                                             (25 or 43).

                        WIDTH "SCRN:"        Assigns a maximum length to
                                             lines output to the screen when
                                             used before an OPEN "SCRN:"
                                             statement.

                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────

   Getting input from   INKEY$               Reads a character from the
   the keyboard                              keyboard (or a null string if no
                                             character is waiting).

                        INPUT$               Reads a specified number of
                                             characters from the keyboard and
                                             stores them in a single string
                                             variable.

                        INPUT                Reads input from the keyboard
                                             and stores it in a list of
                                             variables.

                        LINE INPUT           Reads a line of input from the
                                             keyboard and stores it in a
                                             single string variable.

                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────

   Positioning the      LOCATE               Moves the cursor to a specified
   cursor on the screen                      row and column.

                        SPC                  Skips spaces in printed output.

                        TAB                  Displays printed output in a
                                             given column.

   Getting information  CSRLIN               Tells which row or line position
   on cursor location                        the cursor is in.

                        POS(n)               Tells which column the cursor is
                                             in.

   Creating a text      VIEW PRINT           Sets the top and bottom rows for
   viewport                                  displaying text output.
   ──────────────────────────────────────────────────────────────────────────
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
  ──────────────────────────────────────────────────────────────────────────



 9.4  Summary of File I/O Statements

   Table 9.4 lists the statements and functions used in BASIC data-file
   programming.

   Table 9.4  Statements and Functions Used for Data-File I/O
╓┌─┌────────────────────┌────────────────────┌───────────────────────────────╖
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
   Creating a new file  OPEN                 Opens a file for retrieving or
   or accessing an                           storing records (I/O).
   existing file
   Closing a file       CLOSE                Ends I/O to a file.
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
  Closing a file       CLOSE                Ends I/O to a file.
   Storing data in a    PRINT #              Stores a list of variables as
   file                                      record fields in a previously
                                             opened file.
                        PRINT USING #        Similar to PRINT #, except PRINT
                                             USING # formats the record
                                             fields.
                        WRITE #              Stores a list of variables as
                                             record fields in a previously
                                             opened file.
                        WIDTH                Specifies a standard length for
                                             each record in a file.
                        PUT                  Stores the contents of a
                                             user-defined variable in a
                                             previously opened file.
   Retrieving data from INPUT #              Reads fields from a record and
   a file                                    assigns each field in the record
                                             to a program variable.
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                                            to a program variable.
                        INPUT$               Reads a string of characters
                                             from a file.
                        LINE INPUT #         Reads a record and stores it in
                                             a single string variable.
                        GET                  Reads data from a file and
                                             assigns the data to elements of
                                             a user-defined variable.
   Managing files on    FILES                Prints a listing of the files in
   disk                                      a specified directory.
                        FREEFILE             Returns the next available file
                                             number.
                        KILL                 Deletes a file from the disk.
                        NAME                 Changes a file's name.
   Getting information  EOF                  Tests whether all of the data
   about a file                              have been read from a file.
                        FILEATTR             Returns the number assigned by
                                             the operating system to an open
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                                            the operating system to an open
                                             file and a number that indicates
                                             the mode in which the file was
                                             opened (INPUT, OUTPUT, APPEND,
                                             BINARY, or RANDOM).
                        LOC                  Gives the current position
                                             within a file. With binary
                                             access, this is the byte
                                             position. With sequential
                                             access, this is the byte
                                             position divided by 128. With
                                             random access, this is the
                                             record number of the last record
                                             read or written.
                        LOF                  Gives the number of bytes in an
                                             open file.
                        SEEK (function)      Gives the location where the
                                             next I/O operation will take
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                                            next I/O operation will take
                                             place. With random access, this
                                             is the number of the next record
                                             to be read or written. With all
                                             other kinds of file access, this
                                             is the byte position of the next
                                             byte to be read or written.
   Moving around in a   SEEK (statement)     Sets the byte position for the
   file                                      next read or write operation in
                                             an open file.
   ──────────────────────────────────────────────────────────────────────────



 9.5  Summary of String-Processing Statements and Functions

   Table 9.5 lists the statements and functions available in BASIC for
   working with strings.

   Table 9.5  Statements and Functions Used for Processing Strings
╓┌─┌────────────────────┌────────────────────┌───────────────────────────────╖
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
   Getting part of a    LEFT$                Returns a given number of
   string                                    characters from the left side of
                                             a string.

                        RIGHT$               Returns a given number of
                                             characters from the right side
                                             of a string.

                        LTRIM$               Returns a copy of a string with
                                             leading blank spaces stripped
                                             away.

                        RTRIM$               Returns a copy of a string with
                                             trailing blank spaces stripped
                                             away.
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                                            away.

                        MID$ (function)      Returns a given number of
                                             characters from anywhere in a
                                             string.

   Searching strings    INSTR                Searches for a string within
                                             another string.

   Converting to        LCASE$               Returns a copy of a string with
   uppercase or                              all uppercase letters (A-Z)
   lowercase letters                         converted to lower-case letters
                                             (a-z); leaves lowercase letters
                                             and other characters unchanged.

                        UCASE$               Returns a copy of a string with
                                             all lowercase letters (a-z)
                                             converted to upper-case letters
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                                            converted to upper-case letters
                                             (A-Z); leaves uppercase letters
                                             and other characters unchanged.

   Changing strings     MID$ (statement)     Replaces part of a string with
                                             another string.

                        LSET                 Left justifies a string within a
                                             fixed-length string.

                        RSET                 Right justifies a string within
                                             a fixed-length string.

   Converting between   STR$                 Returns the string
   numbers and strings                       representation of the value of a
                                             numeric expression.

                        VAL                  Returns the numeric value of a
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                       VAL                  Returns the numeric value of a
                                             string expression.

   Converting numbers   CVtype               Changes numbers stored as
   to data-file                              strings back to Microsoft Binary
   strings, and                              format numbers in programs
   data-file strings to                      working with random-access files
   numbers                                  created with older versions of
                                             BASIC.

                        CVtypeMBF            Changes numbers stored as
                                             Microsoft Binary format strings
                                             to IEEE-format numbers.

                        MKtype$              Changes Microsoft Binary format
                                             numbers to strings suitable for
                                             storing in random-access files
                                             created with older versions of
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                                            created with older versions of
                                             BASIC.

                        MKtypeMBF$           Changes IEEE-format numbers to
                                             Microsoft Binary format strings.

   Creating strings of  SPACE$               Returns a string of blank
   repeating characters                      characters of a specified
                                             length.

                        STRING$              Returns a string consisting of
                                             one repeated character.

   Getting the length   LEN                  Tells how many characters are in
   of a string                               a string.

   Working with ASCII   ASC                  Returns the ASCII value of the
   values                                    given character.
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
  values                                    given character.

                        CHR$                 Returns the character with the
                                             given ASCII value.
   ──────────────────────────────────────────────────────────────────────────



 9.6  Summary of Graphics Statements and Functions

 Table 9.6 lists the statements and functions used in BASIC for pixel-based
 graphics.

   Table 9.6  Statements and Functions Used for Graphics Output
╓┌─┌────────────────────┌────────────────────┌───────────────────────────────╖
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
   Setting              SCREEN               Specifies a BASIC screen mode,
   screen-display                            which determines screen
   characteristics                           characteristics such as
                                             resolution and ranges for color
                                             numbers.

   Plotting or erasing  PSET                 Gives a pixel on the screen a
   a single point                            specified color using the
                                             screen's foreground color by
                                             default.

                        PRESET               Gives a pixel on the screen a
                                             specified color using the
                                             screen's background color by
                                             default, effectively erasing the
                                             pixel.

   Drawing shapes       LINE                 Draws a straight line or a box.
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
  Drawing shapes       LINE                 Draws a straight line or a box.

                        CIRCLE               Draws a circle or ellipse.

                        DRAW                 Combines many of the features of
                                             other BASIC graphics statements
                                             (drawing lines, moving the
                                             graphics cursor, scaling images)
                                             into an all-in-one graphics
                                             macro language.

   Defining screen      VIEW                 Specifies a rectangle on the
   coordinates                               screen (or viewport) as the area
                                             for graphics output.

                        WINDOW               Allows the user to choose new
                                             view coordinates for a viewport
                                             on the screen.
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                                            on the screen.

                        PMAP                 Maps physical pixel coordinates
                                             to view coordinates specified by
                                             the user in the current window,
                                             or vice versa.

                        POINT(number)        Returns the current physical or
                                             view coordinates of the graphics
                                             cursor, depending on the value
                                             for number.

   Using color          COLOR                Sets the default colors used in
                                             graphics output.

                        PALETTE              Assigns different colors to
                                             color numbers. Works only on
                                             systems equipped with an EGA or
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                                            systems equipped with an EGA or
                                             VGA.

                        POINT(x, y)          Returns the color number of a
                                             single pixel whose screen
                                             coordinates are x and y.

   Painting enclosed    PAINT                Fills an area on the screen with
   shapes                                    a color or pattern.

   Animating            GET                  Copies a rectangular area on the
                                             screen by translating the image
                                             to numeric data and storing the
                                             data in a numeric array.

                        PUT                  Displays an image on the screen
                                             that was previously copied with
                                             GET.
                        Statement or
   Task                 Function             Action
   ──────────────────────────────────────────────────────────────────────────
                                            GET.

                        PCOPY                Copies one screen page to
                                             another.
   ──────────────────────────────────────────────────────────────────────────



 9.7  Summary of Trapping Statements and Functions

   Table 9.7 lists the statements and functions used by BASIC to trap and
   process errors and events.

   Table 9.7  Statements and Functions Used in Error and Event Trapping
╓┌─┌────────────────────┌────────────────────┌───────────────────────────────╖
   Task                 Statement or         Action
                        Function
   ──────────────────────────────────────────────────────────────────────────
   Task                 Statement or         Action
                        Function
   ──────────────────────────────────────────────────────────────────────────
   Trapping errors      ON ERROR GOTO line   Causes a program to branch to
   while a program is                        the given line, where line
   running                                   refers either to a line number
                                             or line label. Branching takes
                                             place whenever an error occurs
                                             during execution.

                        RESUME               Returns control to the program
                                             after executing an
                                             error-handling routine. The
                                             program resumes at either the
                                             statement causing the error
                                             (RESUME [[0]]), the statement
                                             after the one causing the error
                                             (RESUME NEXT), or the line
                                             identified by line (RESUME
                                             line).

   Task                 Statement or         Action
                        Function
   ──────────────────────────────────────────────────────────────────────────

   Getting error-status ERR                  Returns the code for an error
   data                                      that occurs at run time.

                        ERL                  Returns the number of the line
                                             on which an error occurred (if
                                             program has line numbers).

                        ERDEV                Returns a device-specific error
                                             code for the last device (such
                                             as a printer) for which DOS
                                             detected an error.

                        ERDEV$               Returns the name of the last
                                             device for which DOS detected an
                                             error.

   Defining your own    ERROR                Simulates the occurrence of a
   Task                 Statement or         Action
                        Function
   ──────────────────────────────────────────────────────────────────────────
  Defining your own    ERROR                Simulates the occurrence of a
   error codes                               BASIC error; can also be used to
                                             define an error not trapped by
                                             BASIC.

   Trapping events      ON event GOSUB line  Causes a branch to the
   while a program is                        subroutine starting with line,
   running                                   where line refers either to a
                                             line number or line label,
                                             whenever the given event occurs
                                             during execution.

                        event ON             Enables trapping of the given
                                             event.

                        event OFF            Disables trapping of the given
                                             event.

   Task                 Statement or         Action
                        Function
   ──────────────────────────────────────────────────────────────────────────

                        event STOP           Suspends trapping of the given
                                             event.

                        RETURN               Returns control to the program
                                             after executing an
                                             event-handling subroutine. The
                                             program resumes at either the
                                             statement immediately following
                                             the place in the program where
                                             the event occurred (RETURN), or
                                             the line that is identified by
                                             line (RETURN line).
   ──────────────────────────────────────────────────────────────────────────



 ────────────────────────────────────────────────────────────────────────────
 Appendix A  Converting BASICA Programs to QuickBASIC

   QuickBASIC generally accepts BASIC language statements written for the
   BASIC interpreters used on IBM Personal Computers and compatibles: IBM
   Advanced Personal Computer BASIC Version A3.00 (BASICA) and Microsoft
   GW-BASIC(R). However, a few changes are required because of internal
   differences between QuickBASIC and these BASIC interpreters. Since the
   changes apply equally to both interpreters, this appendix uses the term
   BASICA to refer to both GW-BASIC and BASICA.

   This appendix provides information on:

   ■ Compatible source-file format

   ■ Statements and functions prohibited or requiring modification for
     QuickBASIC use

   ■ Editor differences in handling tabs

   The following sections describe only the changes required to compile and
   run a BASICA program with QuickBASIC Version 4.5. The chapters in this
   book provide information on how to use QuickBASIC features to enhance your
   existing BASICA programs.


 A.1  Source-File Format

   QuickBASIC Version 4.5 expects the source file to be in ASCII format or in
   QuickBASIC's own format. If you create a file with BASICA, it must be
   saved with the ,A option; otherwise, BASICA compresses the text of your
   program in a special format that QuickBASIC cannot read. If this happens,
   reload BASICA and resave the file in ASCII format, using the ,A option.
   For example, the following BASICA command saves the file MYPROG.BAS in
   ASCII format:

   SAVE "MYPROG.BAS",A


 A.2  Statements and Functions Prohibited in QuickBASIC

   The statements and functions listed below cannot be used in a QuickBASIC
   program because they perform editing operations on the source file,
   interfere with program execution, refer to a cassette device (not
   supported by QuickBASIC), or duplicate support provided by the QuickBASIC
   environment:


   ──────────────────────────────────────────────────────────────────────────
   AUTO                     LIST                    NEW

   CONT                     LLIST                   RENUM

   DEFUSR                   LOAD                    SAVE

   DELETE                   MERGE                   USR

   EDIT                     MOTOR
   ──────────────────────────────────────────────────────────────────────────


 A.3  Statements Requiring Modification

   If your BASICA program contains any of the statements listed in Table A.1,
   you probably need to modify your source code before you can run your
   program in QuickBASIC.

   Table A.1  Statements Requiring Modification
╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖
   Statement          Modification
   ──────────────────────────────────────────────────────────────────────────
   BLOAD/BSAVE        Memory locations may be different in QuickBASIC.

   CALL               The argument is the name of the SUB procedure being
                      called.

   CHAIN              QuickBASIC does not support the ALL, MERGE, DELETE, or
                      linenumber options.

   COMMON             COMMON statements must appear before any executable
                      statements.

   DEFtype            DEFtype statements should be moved to the beginning of
                      the BASICA source file.

   Statement          Modification
   ──────────────────────────────────────────────────────────────────────────

   DIM                All DIM statements declaring static arrays must appear
                      at the beginning of QuickBASIC programs.

   DRAW, PLAY         QuickBASIC requires that the VARPTR$ function be used
                      with embedded variables.

   RESUME             If an error occurs in a single-line function,
                      QuickBASIC attempts to resume program execution at the
                      line containing the function.

   RUN                For executable files produced by QuickBASIC, the object
                      of a RUN or CHAIN statement cannot be a .BAS file; it
                      must be an executable file. The R option in BASICA is
                      not supported. While in the QuickBASIC environment, the
                      object of a RUN or CHAIN statement is still a .BAS
                      file.

                      RUN{linenumber| linelabel}, however, is supported in
   Statement          Modification
   ──────────────────────────────────────────────────────────────────────────
                     RUN{linenumber| linelabel}, however, is supported in
                      QuickBASIC; this statement restarts the program at the
                      specified line.
   ──────────────────────────────────────────────────────────────────────────



 A.4  Editor Differences in Handling Tabs

   QuickBASIC uses individual spaces (rather than the literal tab character,
   ASCII 9) to represent indentation levels. The Tab Stops option in the
   Option menu's Display dialog box set the number of spaces per indentation
   level. (See Chapter 20, "The Options Menu," in Learning to Use Microsoft
   QuickBASIC for more information.)

   Some text editors use the literal tab character to represent multiple
   spaces when storing text files. The QuickBASIC editor treats literal tab
   characters in such files as follows:

   1. Literal tab characters inside quoted strings appear as the character
      shown for ASCII character 9 in the ASCII table in Appendix D,
      "Keyboard Scan Codes and ASCII Character Codes."

   2. Outside quoted strings, tab characters indent the text following them
      to the next indentation level.

   If you try to change the Tab Stops setting while such a program is loaded,
   QuickBASIC gives the following error message:

   Cannot change tab stops while file is loaded

   This is to prevent you from inadvertently reformatting old source files
   created with other editors. If you load such a file and then decide you
   prefer a different indentation, reset the indentation using the following
   procedure:

   1. Save your file to preserve any changes, then choose the New Program
      command from the File menu.

   2. Choose the Display command from the Options menu and set the Tab Stops
      option as described above.

   3. Choose the Open Program command from the File menu and reload your
      program. When your program is reloaded, the indentations will reflect
      the new setting of the Tab Stops option.

   Note that this procedure works only for old programs. Text created within
   QuickBASIC cannot be reformatted this way.



 ────────────────────────────────────────────────────────────────────────────
 Appendix B  Differences from Previous Versions of QuickBASIC

   QuickBASIC Version 4.5 contains many new features and enhancements over
   previous versions of QuickBASIC. This appendix describes the differences
   between Versions 2.0 and 4.5 of QuickBASIC. Unless otherwise stated,
   differences between Versions 2.0 and 4.5 also apply as differences between
   Versions 3.0 and 4.5. Differences between Versions 4.0 and 4.5 are
   primarily in the QuickBASIC environment.

   This appendix provides information on the following improvements in
   QuickBASIC Version 4.5:

   ■ Product capabilities and features

   ■ Environment enhancements

   ■ Improvements in compiling and debugging capabilities

   ■ Language changes

   ■ File compatibility


 B.1  QuickBASIC Features

   This section compares the features of Microsoft QuickBASIC Versions 4.5
   with those of previous versions. The features are listed in Table B.1 and
   described below.

   Table B.1  Features of Microsoft QuickBASIC Version 4.5
╓┌─┌───────────────────────────────┌─────────┌──────────┌─────────┌──────────╖
                                           QuickBASIC Version
   Feature                         2.0       3.0        4.0       4.5
   ──────────────────────────────────────────────────────────────────────────
   On-line QB Advisor (detailed    No        No         No        Yes
   reference)

   Selectable right mouse button   No        No         No        Yes
   function

   Instant Watches for variables   No        No         No        Yes
   and expressions

   Set default search paths        No        No         No        Yes

   User-defined types              No        No         Yes       Yes

   IEEE format, math coprocessor   No        Yes        Yes       Yes
   support

   On-line help                    No        No         Yes       Yes
                                           QuickBASIC Version
   Feature                         2.0       3.0        4.0       4.5
   ──────────────────────────────────────────────────────────────────────────
  On-line help                    No        No         Yes       Yes

   Symbol help                     No        No         No        Yes

   Long (32-bit) integers          No        No         Yes       Yes

   Fixed-length strings            No        No         Yes       Yes

   Syntax checking on entry        No        No         Yes       Yes

   Binary file I/O                 No        No         Yes       Yes

   FUNCTION procedures             No        No         Yes       Yes

   CodeView(R) support             No        No         Yes       Yes

   Compatibility with other        No        No         Yes       Yes
   languages
                                           QuickBASIC Version
   Feature                         2.0       3.0        4.0       4.5
   ──────────────────────────────────────────────────────────────────────────
  languages

   Multiple modules in memory      No        No         Yes       Yes

   ProKey TM, SideKick(R), and     No        Yes        Yes       Yes
   SuperKey(R) compatibility

   Insert/overtype modes           No        Yes        Yes       Yes

   WordStar(R)-style keyboard      No        No         Yes       Yes
   interface

   Recursion                       No        No         Yes       Yes

   Error listings during separate  No        Yes        Yes       Yes
   compilation

   Assembly-language listings      No        Yes        Yes       Yes
                                           QuickBASIC Version
   Feature                         2.0       3.0        4.0       4.5
   ──────────────────────────────────────────────────────────────────────────
  Assembly-language listings      No        Yes        Yes       Yes
   during separate compilation
   ──────────────────────────────────────────────────────────────────────────


 B.1.1  Features New to QuickBASIC 4.5

   You can now access on-line help for QuickBASIC's keywords, commands, and
   menus, as well as general topics and your own variables. Examples shown on
   help screens can be copied and pasted directly into your own program,
   reducing development time.

   For mouse users, you can now set the function of the right mouse button
   with the Right Mouse command from the Options menu. Use the function that
   best suits your needs. For more information see Chapter 19, "The Calls
   Menu," in Learning to Use Microsoft QuickBASIC.

   For faster debugging, QuickBASIC now offers an Instant Watch command for
   immediately identifying the value of a variable or the condition (true or
   false) of an expression. For more information see Chapter 18, "The Debug
   Menu," in Learning to Use Microsoft QuickBASIC.

   Version 4.5 also lets you set default search paths to specific types of
   files. This lets you organize your files by type and keep them in separate
   directories. QuickBASIC will search the correct directory after you set
   the new default search path. You can set default paths for executable,
   include, library, and help files.

 B.1.2  Features Introduced in QuickBASIC 4.0

   If you are new to QuickBASIC or unfamiliar with Version 4.0, you will want
   to review the following features introduced in QuickBASIC 4.0 and
   supported in the current version.

   B.1.2.1  User-Defined Types

   The TYPE statement allows you to create composite data types from simple
   data elements. Such data types are similar to C-language structures.
   User-defined types are discussed in Chapter 3, "File and Device I/O."

   B.1.2.2  IEEE Format and Math-Coprocessor Support

   Microsoft QuickBASIC provides IEEE-format numbers and math-coprocessor
   support. When no coprocessor is present, QuickBASIC emulates the
   coprocessor.

   Calculations done by programs compiled with QuickBASIC are generally more
   accurate and may produce results different from programs run under BASICA
   or versions of QuickBASIC prior to 4.0. Single-precision IEEE-format
   numbers provide an additional decimal digit of accuracy. When compared to
   Microsoft Binary format double-precision numbers, IEEE-format
   double-precision numbers provide an additional one to two digits in the
   mantissa and extend the range of the exponent.

   There are two ways to use QuickBASIC 4.0 and 4.5 with your old programs
   and existing data:

   1. Use the /MBF option. This way, you can use your old programs and data
      files without rewriting your programs or changing your files.

   2. Modify your data files and use the new QuickBASIC to recompile your
      programs. In the long run, this ensures compatibility with future
      versions of QuickBASIC and may produce faster programs. Only
      random-access files containing binary format real numbers need to be
      changed. Files containing only integers or string data can be used
      without modification. More information on these options is provided
      below.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     If assembly-language procedures that use real numbers are called from
     your program, they must be written so that they use IEEE-format numbers.
     This is the default for Microsoft Macro Assembler (MASM) Version 5.0 and
     later versions. With earlier versions, be sure to use the /R
     command-line option or the 8087 assembler directive.
   ──────────────────────────────────────────────────────────────────────────

   B.1.2.3  Ranges of IEEE-Format Numbers

   IEEE-format numbers have a wider range than Microsoft Binary format
   numbers, as shown in the following list:

   Type of Number           Range of Values
   ──────────────────────────────────────────────────────────────────────────
   Single precision         -3.37 * 10^38 to -8.43 * 10^-37
                            True zero

                            8.43 * 10^-37 to 3.37 * 10^38

   Double precision         -1.67 * 10^308 to -4.19 * 10^-307
                            True zero

                            4.19 * 10^-307 to 1.67 * 10^308
   ──────────────────────────────────────────────────────────────────────────

   Single-precision values are accurate to approximately seven digits.
   Double-precision values are accurate to either 15 or 16 digits.

   Note that double-precision values may have three digits in the exponent.
   This may cause problems in PRINT USING statements.

   B.1.2.4  PRINT USING and IEEE-Format Numbers

   Because double-precision IEEE-format numbers can have larger exponents
   than Microsoft Binary format double-precision numbers, you may need to use
   a special exponential format in PRINT USING statements. Use the new format
   if your program prints values with three-digit exponents. To print numbers
   with three-digit exponents, use five carets (^^^^^) instead of four carets
   to indicate exponential format:

   PRINT USING "+#.######^^^^^", Circumference#

   If an exponent is too large for a field, QuickBASIC replaces the first
   digit with a percent sign (%) to indicate the problem.

 B.1.3  Recompiling Old Programs with /MBF

   Old programs and files work with QuickBASIC Version 4.5 without
   modification if you recompile the programs with the /MBF command-line
   option. For example, to compile the program named multrgrs.bas, enter the
   following at the DOS prompt:

   BC multrgrs /MBF;

   Then link the program as you usually do. To recompile using the Make EXE
   File command, be sure to use the /MBF option when you start QuickBASIC.
   Then compile as you normally would.

   The /MBF option converts Microsoft Binary format numbers to IEEE format as
   they are read from a random-access file and converts them back to
   Microsoft Binary format before writing them to a file. This lets you do
   calculations with IEEE-format numbers while keeping the numbers in
   Microsoft Binary format in your files.

 B.1.4  Converting Files and Programs

   If you decide to convert your programs and data files rather than use the
   /MBF command-line option, you need to do two things:

   1. Recompile your programs.

   2. Convert your data files.

   Your old QuickBASIC programs should compile without modification. However,
   do not use the /MBF option when recompiling. Your program will not work
   with your new data files if you use the /MBF option.

   Data files containing real numbers need to be converted so that real
   numbers are stored in IEEE format. QuickBASIC Version 4.5 includes eight
   functions that help you do this.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     You do not need to convert your data files if they contain only integer
     and string data. Only files containing real numbers must be converted.
   ──────────────────────────────────────────────────────────────────────────

   Version 4.5 has the familiar CVS, CVD, MKS$, and MKD$ functions for
   reading and writing real numbers from or to random-access files. However,
   these functions now handle real numbers stored in your files in IEEE
   format, not Microsoft Binary format. To handle numbers in Microsoft Binary
   format, Version 4.5 includes the functions CVSMBF, CVDMBF, MKSMBF$, and
   MKDMBF$.

   With these functions, you can write a short program that reads records
   from the old file (using Microsoft Binary format as necessary), converts
   the real-number fields to IEEE format, places the fields in a new record,
   and writes out the new record.

   Examples

   The following program copies an old data file to a new file, making the
   necessary conversions:

   ' Define types for old and new file buffers:
   TYPE Oldbuf
      ObsId AS STRING * 20
      XPos AS STRING * 4
      YPos AS STRING * 4
      FuncVal AS STRING * 8
   END TYPE

   TYPE NewBuf
      ObsId AS STRING * 20
      XPos AS SINGLE
      YPos AS SINGLE
      FuncVal AS DOUBLE
   END TYPE

   ' Declare buffers:
   DIM OldFile AS Oldbuf, NewFile AS NewBuf

   ' Open the old and new data files:
   OPEN "OLDMBF.DAT" FOR RANDOM AS #1 LEN=LEN(OldFile)
   OPEN "NEWIEEE.DAT" FOR RANDOM AS #2 LEN=LEN(NewFile)

   I=1

   ' Read the first old record:
   GET #1,I,OldFile

   DO UNTIL EOF(1)

   ' Move the fields to the new record fields, converting
   ' the real-number fields:
      NewFile.ObsId=OldFile.ObsId
      NewFile.XPos=CVSMBF(OldFile.XPos)
      NewFile.YPos=CVSMBF(OldFile.YPos)
      NewFile.FuncVal=CVDMBF(OldFile.FuncVal)

   ' Write the converted fields to the new file:
      PUT #2,I,NewFile
      I=I+1

   ' Read next record from the old file:
      GET #1,I,OldFile
   LOOP

   CLOSE #1, #2

   Each record in the two files has four fields: an identifier field, two
   fields containing single-precision real numbers, and a final field
   containing a double-precision real number.

   Most of the conversion work is done with the functions CVDMBF and CVSMBF.
   For example, the following program line converts the double-precision
   field:

   NewFile.FuncVal=CVDMBF(OldFile.FuncVal)

   The eight bytes in the record field OldFile.FuncVal are converted from a
   Microsoft Binary format double-precision value to an IEEE-format
   double-precision value by the function CVDMBF. This value is stored in the
   corresponding field in the new record, which is later written to the new
   file by the PUT statement.

 B.1.5  Other QuickBASIC Features

   QuickBASIC 4.0 introduced the following features and tools that made
   QuickBASIC a development package appreciated by the professional without
   overwhelming the novice. QuickBASIC 4.5 supports all these same features,
   along with some additional refinements.

   B.1.5.1  Long (32-Bit) Integers

   Long (32-bit) integers eliminate rounding errors in calculations with
   numbers in the range -2,147,483,648 to 2,147,483,647, and they provide
   much faster whole-number calculations in this range than do floating-point
   types.

   B.1.5.2  Fixed-Length Strings

   Fixed-length strings let you incorporate string data into user-defined
   types. See Chapter 4, "String Processing," for more information.

   B.1.5.3  Syntax Checking on Entry

   If syntax checking is turned on, QuickBASIC checks each line as you enter
   it for syntax and duplicate-definition errors. See Chapter 12, "Using the
   Editor," in Learning to Use Microsoft QuickBASIC for an explanation of
   syntax checking and other smart-editor features.

   B.1.5.4  Binary File I/O

   Versions 4.0 and 4.5 provide binary access to files. This is useful for
   reading and modifying files saved in non-ASCII format. The major benefit
   of binary access is that it does not force you to treat a file as a
   collection of records. If a file is opened in binary mode, you can move
   forward or backward to any byte position in the file, then read or write
   as many bytes as you want. Thus, different I/O operations on the same file
   can GET or PUT a varying number of bytes──unlike with random access, where
   the number of bytes is fixed by the predefined length of a single record.

   See Chapter 3, "File and Device I/O," for more information about
   accessing binary files.

   B.1.5.5  FUNCTION Procedures

   FUNCTION procedures allow you to place a function in one module and call
   it from a different module. See Chapter 2, "SUB and FUNCTION Procedures,"
   for more information about using FUNCTION procedures.

   In versions prior to 4.0, a SUB procedure and a variable could have the
   same name. Now, SUB and FUNCTION procedure names must be unique.

   B.1.5.6  Support for the CodeView(R) Debugger

   You can use the command-line tools BC.EXE and LINK.EXE to create
   executable files compatible with the Microsoft CodeView debugger, a
   powerful tool included with the Microsoft Macro Assembler (Version 5.0 or
   later) and with Microsoft C (Version 5.0 or later). Modules compiled with
   BC can be linked with modules compiled with other Microsoft languages in
   such a way that the final executable file can be debugged using the
   CodeView debugger. See Appendix G, "Compiling and Linking from DOS," for
   more information.

   B.1.5.7  Other-Language Compatibility

   QuickBASIC Version 4.5 allows you to call routines written in other
   Microsoft languages using C or Pascal calling conventions. Arguments are
   passed by NEAR or FAR reference, or by value. Other-language code may be
   placed in Quick libraries or linked into executable files.

   The PTR86 routine is not supported in QuickBASIC, Version 4.5; use the
   VARPTR and VARSEG functions instead.

   B.1.5.8  Multiple Modules in Memory

   You can load multiple program modules into memory simultaneously. Versions
   previous to 4.0 permitted only one module to be in memory at a time. Now
   you can edit, execute, and debug multiple-module programs within the
   QuickBASIC environment. See Chapter 2, "SUB and FUNCTION Procedures," and
   Chapter 7, "Programming with Modules," for more information about using
   multiple modules.

   B.1.5.9  ProKey TM, SideKick(R), and SuperKey(R) Compatibility

   You can use ProKey, SideKick, and SuperKey within the QuickBASIC
   environment. Other keyboard-reprogramming or desktop software may not work
   with QuickBASIC. Check with the suppliers or manufacturers of other
   products to find out about the product's compatibility with QuickBASIC
   Version 4.5.

   B.1.5.10  Insert and Overtype Modes

   Pressing INS toggles the editing mode between insert and overtype. When
   overtype mode is on, the cursor changes from a blinking underline to a
   block. Note that INS replaces the CTRL+O insert/overtype toggle in Version
   3.0.

   In insert mode, the editor inserts a typed character at the cursor
   position. In overtype mode, the editor replaces the character under the
   cursor with the character you type. Insert mode is the default mode.

   B.1.5.11  WordStar(R)-Style Keyboard Commands

   QuickBASIC supports many of the key sequences familiar to WordStar users.
   A complete list of WordStar-style key commands appears in Chapter 12,
   "Using the Editor," in Learning to Use Microsoft QuickBASIC.

   B.1.5.12  Recursion

   QuickBASIC Versions 4.0 and 4.5 support recursion, which is the ability of
   a procedure to call itself. Recursion is useful for solving certain
   problems, such as sorting. See Chapter 2, "SUB and FUNCTION Procedures,"
   for more information about using recursion.

   B.1.5.13  Error Listings during Separate Compilation

   QuickBASIC displays descriptive error messages when you compile programs
   using the BC command. Using BC, you can redirect the error messages to a
   file or device to get a copy of the compilation errors. See Appendix G,
   "Compiling and Linking from DOS," for more information about the BC
   command.

   Examples

   The following examples show how to use the BC command line for error
   display:

   Command Line             Action
   ──────────────────────────────────────────────────────────────────────────
   BC TEST.BAS;             Compiles the file named TEST.BAS and displays
                            errors on the screen

   BC TEST.BAS; > TEST.ERR  Compiles the file TEST.BAS and redirects error
                            messages to the file named TEST.ERR
   ──────────────────────────────────────────────────────────────────────────

   B.1.5.14  Assembly-Language Listings during Separate Compilation

   The BC command's /A option produces a listing of the assembly-language
   code produced by the compiler. See Appendix G, "Compiling and Linking
   from DOS," for more information.


 B.2  Differences in the Environment

   The QuickBASIC programming environment now provides more flexible command
   selection, additional window options, and more menu commands. Sections
   B.2.1-B.2.5 describes the differences in the programming environment
   between Version 4.5 and earlier versions.

 B.2.1  Choosing Commands and Options

   QuickBASIC Version 4.5 gives you flexibility in how you choose commands
   from menus and options from dialog boxes.

   Version 4.5 allows you to select any menu by pressing the ALT key followed
   by a mnemonic key. Each menu command and dialog box option also has its
   own mnemonic key, which immediately executes the command or selects the
   item. The mnemonic keys appear in intense video.

   In Version 4.5 the ENTER key functions the same way as the SPACEBAR did in
   versions 3.0 and earlier. You can press ENTER to execute a command from a
   dialog box.

 B.2.2  Windows

   Version 4.5 allows up to two work-area windows (referred to as View
   windows), a Help window, and a separate Immediate window. Versions prior
   to 4.0 supported only two windows: one work area and the error-message
   window.

 B.2.3  New Menu

   QuickBASIC Version 4.5 has a new menu, the Options menu. The Options menu
   accesses special QuickBASIC controls that manipulate the screen display
   attributes, the function of the right mouse button, the default path to
   specific file types, syntax checking, and Full Menus control.

 B.2.4  Menu Commands

   The Debug and Help menus, which appeared in earlier versions of
   QuickBASIC, have some new commands. Table B.2 lists the new commands in
   these menus, as well as the commands from the new Options menu.

   Table B.2  Menus with New Commands in QuickBASIC Version 4.5
╓┌─┌───────────┌────────────────────────┌────────────────────────────────────╖
   Menu        Command                  Description
   ──────────────────────────────────────────────────────────────────────────
   Debug       Add Watch                Adds variable or expression to Watch
                                        window

               Instant Watch (New)      Immediately checks the value of a
                                        variable or expression

               Watchpoint               Adds a watchpoint to the Watch window

               Delete Watch             Selectively removes item from Watch
                                        window

               Delete All Watch         Removes all items from the Watch
                                        window

               Trace On                 Toggles tracing on and off

               History On               Records last 20 executed statements
   Menu        Command                  Description
   ──────────────────────────────────────────────────────────────────────────
              History On               Records last 20 executed statements

               Toggle Breakpoint        Toggles a breakpoint on the current
                                        line on and off

               Clear All Breakpoints    Removes all breakpoints

               Break on Errors (New)    Halts program execution if an error
                                        occurs, regardless of any error
                                        handling

               Set Next Statement       Sets the next statement to execute
                                        when a suspended program continues
                                        running

   Option      Display (New)            Customizes the screen elements
   (New)
               Set Paths (New)          Alters default search paths for
                                        specific types of files
   Menu        Command                  Description
   ──────────────────────────────────────────────────────────────────────────
                                       specific types of files

               Right Mouse (New)        Selects the function for the right
                                        mouse button

               Syntax Checking          Toggles automatic syntax checking on
                                        and off

               Full Menus (New)         Toggles between Full Menus and Easy
                                        Menus

   Help        Index (New)              Displays an alphabetical list of
                                        QuickBASIC keywords and a brief
                                        description of each

               Contents (New)           Displays a visual outline of contents

               Topic                    Provides information on variables,
                                        keywords
   Menu        Command                  Description
   ──────────────────────────────────────────────────────────────────────────
                                       keywords

               Help on Help (New)       Describes how to use Help and common
                                        keyword shortcuts
   ──────────────────────────────────────────────────────────────────────────


   The Version 3.0 Debug option is removed from the Run menu. In Version 4.5
   you can debug at any time, using the debugging commands in the Debug menu.

 B.2.5  Editing-Key Changes

   The QuickBASIC keyboard interface has been extended to include editing key
   sequences similar to those in the WordStar editor. (See Chapter 12, "Using
   the Editor," and Chapter 13, "The Edit Menu," in Learning to Use Microsoft
   QuickBASIC for more information about editing.) The functions performed by
   the QuickBASIC Version 2.0 key sequences listed in Table B.3 are changed
   in QuickBASIC Versions 4.0 and 4.5.

   Table B.3  Editing-Key Changes
                            QuickBASIC              QuickBASIC
   Function                 2.0 Key                 4.5 Key
   ──────────────────────────────────────────────────────────────────────────
   Undo                     SHIFT+ESC               ALT+BKSP

   Cut                      DEL                     SHIFT+DEL

   Copy                     F2                      CTRL+INS

   Paste                    INS                     SHIFT+INS

   Clear                    ──                      DEL

   Overtype                 ──                      INS
   ──────────────────────────────────────────────────────────────────────────


 B.3  Differences in Compiling and Debugging

   In the QuickBASIC 4.5 programming environment, compiling and debugging are
   not separate operations. Your program is always ready to run, and you can
   debug your code in several ways while you program. This section describes
   the differences in compiling and debugging features between QuickBASIC
   Versions 4.0 and 4.5 and previous versions.

 B.3.1  Command-Line Differences

   QuickBASIC Versions 4.0 and 4.5 support Version 2.0 command-line options
   only for the QB command, not the BC command. To compile a program outside
   of the QuickBASIC environment, use the BC command, which is described in
   Appendix G, "Compiling and Linking from DOS."

   Versions 4.0 and 4.5 do not require any of the Compile options listed in
   Table 4.1 of the Microsoft QuickBASIC Version 2.0 manual. If you attempt
   to invoke QuickBASIC using these as command-line options, an error message
   appears. Similarly, it was necessary to choose certain compiler options
   from the Compile dialog box in Version 3.0; this is now done
   automatically. Table B.4 describes the way in which QuickBASIC now
   supports the functionality of these options.

   Table B.4  QB and BC Options Not Used in QuickBASIC Versions 4.0 or 4.5
   Version 2.0              Version 4.5
   ──────────────────────────────────────────────────────────────────────────
   On Error (/E)            Automatically set whenever an ON ERROR statement
                            is present.

   Debug (/D)               Always on when you run a program within the
                            QuickBASIC environment. When producing executable
                            programs on disk or Quick libraries, use the
                            Produce Debug Code option.

   Checking between         Automatically set whenever an ON event statement
   Statements (/V) and      is present.
   Event Trapping (/W)

   Resume Next (/X)         Automatically set whenever a RESUME NEXT
                            statement is present.

   Arrays in Row Order (/R) Available only when compiling with BC.

   Minimize String Data     The default for QB. To turn off this option, you
   (/S)                     must compile from the command line with BC.
   ──────────────────────────────────────────────────────────────────────────

   The options listed in Table B.5 are now available for the QB and BC
   commands.

   Table B.5  Options Introduced in Version 4.0 for the QB and BC Commands
╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
   Option                   Description
   ──────────────────────────────────────────────────────────────────────────
   /AH                      Allows dynamic arrays of records, fixed-length
                            strings, and numeric data to be larger than 64K
                            each. If this option is not specified, the
                            maximum size for each array is 64K. Note that
                            this option has no effect on the way data items
                            are passed to procedures. (This option is used
                            with the QB and BC commands.)

   /H                       Displays the highest resolution possible on your
                            hardware. For example, if you have an EGA,
                            QuickBASIC displays 43 lines and 80 columns of
                            text. (This option is used only with the QB
   Option                   Description
   ──────────────────────────────────────────────────────────────────────────
                           text. (This option is used only with the QB
                            command.)

   /MBF                     Converts Microsoft Binary format numbers to IEEE
                            format. See Section B.1.2.3 for more information
                            about this option (used with the QB and BC
                            commands).

   /RUN sourcefile          Runs sourcefile immediately, without first
                            displaying the QuickBASIC programming
                            environment. (This option is used only with the
                            QB command.)
   ──────────────────────────────────────────────────────────────────────────


 B.3.2  Separate Compilation Differences

 Versions 4.0 and 4.5 do not allow separate compilation with the QB command.
 Use the BC command described in Appendix G, "Compiling and Linking from
 DOS" to compile and link files without entering the programming environment.

 B.3.3  User Libraries and BUILDLIB

   User libraries created for previous versions are not compatible with
   Versions 4.0 and 4.5. You must rebuild the library from the original
   source files.

   User libraries are now called Quick libraries. There is no change in their
   function or use. The file-name extension of these libraries is now .QLB
   instead of .EXE. The BUILDLIB utility is no longer required. Quick
   libraries are now created from within the programming environment or from
   the link command line. See Appendix H, "Creating and Using Quick
   Libraries," for more information on this topic.

 B.3.4  Restrictions on Include Files

   Include files can contain SUB or FUNCTION procedure declarations but not
   definitions. If you need to use an old include file with procedure
   definitions in it, use the Merge command from the File menu to insert the
   include file into the current module. When you merge an include file
   containing a SUB procedure, the text of the procedure does not appear in
   the currently active window. To view or edit its text, choose the SUBs
   command from the View menu, then select the procedure name in the list
   box. Once the text is merged, you can run the program.

   Alternatively, you may decide to put your SUB procedure in a separate
   module. In this case, you must take one of the following two steps for any
   shared variables (variables declared in a COMMONSHARED or [[RE]]DIM SHARED
   statement outside the SUB procedure, or in a SHARED statement inside the
   SUB procedure), because variables declared this way are shared only within
   a single module:

   1. Share the variables between the modules by listing them in COMMON
      statements at the module level in both modules.

   2. Pass the variables to the SUB procedure in an argument list.

   See Chapter 2, "SUB and FUNCTION Procedures," and Chapter 7,
   "Programming with Modules," for additional information on modules and
   procedures.

 B.3.5  Debugging

   QuickBASIC now helps you debug your programs faster by providing the
   following debugging features:

   1. Multiple breakpoints

   2. Watch expressions, watchpoints, and instant watches

   3. Improved program tracing

   4. Full-screen window that displays program text during single-stepping

   5. The ability to change variable values during execution, then continue

   6. The ability to edit the program, then continue execution without
      restarting

   7. History feature

   8. Calls menu

   9. Symbol help

   The debugging function-key sequences listed in Table B.6 are changed from
   QuickBASIC Version 2.0:

   Table B.6  Debugging-Key Changes
                            QuickBASIC              QuickBASIC
   Function                 Version 2.0 Key         Version 4.5 Key
   ──────────────────────────────────────────────────────────────────────────
   Trace                    ALT+F8                  F8

   Step                     ALT+F9                  F10
   ──────────────────────────────────────────────────────────────────────────

   Note that animation is turned on when you toggle on the Trace On command
   from the Debug menu, then run your program.

   See Chapter 9, "Debugging While You Program," in Learning to Use Microsoft
   QuickBASIC for more information.


 B.4  Changes to the BASIC Language

   This section describes enhancements and changes to the BASIC language in
   Version 4.5 and earlier versions of QuickBASIC. Table B.7 lists the
   keywords affected by these changes and shows which version of QuickBASIC
   is affected by each change. A more detailed explanation of the changes
   appears after the table.

   Table B.7  Changes to the BASIC Language
╓┌─┌───────────────────────────────┌─────────┌──────────┌─────────┌──────────╖
                                           QuickBASIC Version
   Keyword                         2.0       3.0        4.0       4.5
   ──────────────────────────────────────────────────────────────────────────
   AS                              No        No         Yes       Yes

   CALL                            No        No         Yes       Yes

   CASE                            No        Yes        Yes       Yes

   CLEAR                           No        No         Yes       Yes
                                           QuickBASIC Version
   Keyword                         2.0       3.0        4.0       4.5
   ──────────────────────────────────────────────────────────────────────────
  CLEAR                           No        No         Yes       Yes

   CLNG                            No        No         Yes       Yes

   CLS                             No        Yes        Yes       Yes

   COLOR                           No        No         Yes       Yes

   CONST                           No        Yes        Yes       Yes

   CVL                             No        No         Yes       Yes

   CVSMBF, CVDMBF                  No        Yes        Yes       Yes

   DECLARE                         No        No         Yes       Yes

   DEFLNG                          No        No         Yes       Yes

                                           QuickBASIC Version
   Keyword                         2.0       3.0        4.0       4.5
   ──────────────────────────────────────────────────────────────────────────

   DIM                             No        No         Yes       Yes

   DO...LOOP                       No        Yes        Yes       Yes

   EXIT                            No        Yes        Yes       Yes

   FILEATTR                        No        No         Yes       Yes

   FREEFILE                        No        No         Yes       Yes

   FUNCTION                        No        No         Yes       Yes

   GET                             No        No         Yes       Yes

   LCASE$                          No        No         Yes       Yes

   LEN                             No        No         Yes       Yes
                                           QuickBASIC Version
   Keyword                         2.0       3.0        4.0       4.5
   ──────────────────────────────────────────────────────────────────────────
  LEN                             No        No         Yes       Yes

   LSET                            No        No         Yes       Yes

   LTRIM$                          No        No         Yes       Yes

   MKL$                            No        No         Yes       Yes

   MKSMBF$, MKDMBF$                No        Yes        Yes       Yes

   OPEN                            No        No         Yes       Yes

   ON UEVENT                       No        No         No        Yes

   PALETTE                         No        No         Yes       Yes

   PUT                             No        No         Yes       Yes

                                           QuickBASIC Version
   Keyword                         2.0       3.0        4.0       4.5
   ──────────────────────────────────────────────────────────────────────────

   RTRIM$                          No        No         Yes       Yes

   SCREEN                          No        No         Yes       Yes

   SEEK                            No        No         Yes       Yes

   SELECT CASE                     No        Yes        Yes       Yes

   SETMEM                          No        No         Yes       Yes

   SLEEP                           No        No         No        Yes

   STATIC                          No        No         Yes       Yes

   TYPE                            No        No         Yes       Yes

   UCASE$                          No        No         Yes       Yes
                                           QuickBASIC Version
   Keyword                         2.0       3.0        4.0       4.5
   ──────────────────────────────────────────────────────────────────────────
  UCASE$                          No        No         Yes       Yes

   UEVENT                          No        No         No        Yes

   VARPTR                          No        No         Yes       Yes

   VARSEG                          No        No         Yes       Yes

   WIDTH                           No        Yes        Yes       Yes
   ──────────────────────────────────────────────────────────────────────────


   The following section explains in more detail the differences in the
   keywords summarized above.

╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
   AS                 The AS clause allows the use of user-defined types in
                      DIM, COMMON, and SHARED statements and in DECLARE, SUB,
                      and FUNCTION parameter lists.

   CALL               The use of CALL is optional for calling subprograms
                      declared with the DECLARE statement.

   CLEAR              The CLEAR statement no longer sets the total size of
                      the stack; it sets only the stack size required by the
                      program. QuickBASIC sets the stack size to the amount
                      specified by the CLEAR statement plus what QuickBASIC
                      itself requires.

   CLNG               The CLNG function rounds its argument and returns a
                      long (four-byte) integer that is equal to the argument.

   CLS                The CLS statement has been modified to give you greater
                      flexibility in clearing the screen. Note that
                      QuickBASIC no longer clears the screen automatically at
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
                     QuickBASIC no longer clears the screen automatically at
                      the beginning of each program, as was true in earlier
                      versions.

   COLOR, SCREEN,     The COLOR, SCREEN, PALETTE, and WIDTH statements are
   PALETTE, WIDTH     extended to include screen modes available with the IBM
                      PS/2(R) VGA and Multicolor Graphics Array (MCGA) cards.

   CONST              The CONST statement lets you define symbolic constants
                      to improve program readability and ease program
                      maintenance.

   CVL                The CVL function is used to read long integers stored
                      as strings in random-access data files. CVL converts a
                      four-byte string created with the MKL$ function back to
                      a long integer for use in your BASIC program.

   CVSMBF, CVDMBF     The CVSMBF and CVDMBF functions convert strings
                      containing Microsoft Binary format numbers to
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
                     containing Microsoft Binary format numbers to
                      IEEE-format numbers. Although QuickBASIC Version 4.5
                      supports these statements, they are considered obsolete
                      since the IEEE-format is now the QuickBASIC standard.

   DECLARE            The DECLARE statement allows you to call procedures
                      from different modules, check the number and type of
                      arguments passed, and call procedures before they are
                      defined.

   DEFLNG             The DEFLNG statement declares all variables, DEF FN
                      functions, and FUNCTION procedures as having the
                      long-integer type. That is, unless a variable or
                      function has been declared in an AS type clause, or it
                      has an explicit type-definition suffix such as % or $,
                      it is a long integer by default.

   DIM                The DIM statement's TO clause lets you specify
                      subscripts of any integer value, giving you greater
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
                     subscripts of any integer value, giving you greater
                      flexibility in array declarations.

   DO...LOOP          Using DO...LOOP statements gives you more powerful
                      loops that allow you to write programs with better
                      structure.

   EXIT               The use of EXIT {DEF | DO | FOR | FUNCTION | SUB}
                      statements provides convenient exits from loops and
                      procedures.

   FREEFILE, FILEATTR The FREEFILE and FILEATTR functions help you write
                      applications that do file I/O in a multiple-module
                      environment.

   FUNCTION           The FUNCTION...END FUNCTION procedure allows you to
                      define a multiline procedure that you call from within
                      an expression. These procedures behave much like
                      intrinsic functions such as ABS or multiline DEF FN
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
                     intrinsic functions such as ABS or multiline DEF FN
                      functions from QuickBASIC Versions 1.0-3.0. However,
                      unlike a DEF FN function, a FUNCTION procedure can be
                      defined in one module and called from another. Also,
                      FUNCTION procedures have local variables and support
                      recursion.

   GET, PUT           For I/O operations, the syntax of the GET and PUT
                      statements is expanded to include records defined with
                      TYPE...END TYPE statements. This makes use of the FIELD
                      statement unnecessary.

   LCASE$, UCASE$,    The following string-handling functions are available
   LTRIM$, RTRIM$     in Version 4.5:

                      Function          Return Value
                      LCASE$            A copy of the string with all letters
                                        converted to lowercase
                      UCASE$            A copy of the string with all letters
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
                     UCASE$            A copy of the string with all letters
                                        converted to uppercase
                      LTRIM$            A copy of the string with all leading
                                        blanks removed
                      RTRIM$            A copy of the string with all
                                        trailing blanks removed
                      LEN               The LEN function has been extended to
                                        return the number of bytes required
                                        by any scalar or record variable,
                                        constant, expression, or array
                                        element.

   LSET               The LSET statement is extended to include record
                      variables as well as string variables. This allows you
                      to assign one record variable to another record
                      variable even when the records are not similar.

   MKL$               The MKL$ function is used to convert long integers to
                      strings that can be stored in random-access data files.
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
                     strings that can be stored in random-access data files.
                      Use the CVL function to change the string back to a
                      long integer.

   MKSMBF$, MKDMBF$   The MKSMBF$ and MKDMBF$ functions convert IEEE-format
                      numbers to strings containing a Microsoft Binary format
                      number. They are obsolete (but supported) in Version
                      4.5, which uses the IEEE-format.

   ON UEVENT          The ON UEVENT statement directs the program to a
                      specified location when a user-defined event (a UEVENT)
                      occurs. Use it in the same fashion as other
                      event-handling statements.

   OPEN               The OPEN statement now opens two files with the same
                      name for OUTPUT or APPEND as long as the path names are
                      different. For example, the following is now permitted:

                      OPEN "SAMPLE" FOR APPEND AS #1
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
                     OPEN "SAMPLE" FOR APPEND AS #1
                      OPEN "TMP\SAMPLE" FOR APPEND AS #2

                      A binary file mode has been added to the OPEN statement
                      syntax. See Chapter 3, "File and Device I/O," for
                      information about using this mode.

   SEEK               The SEEK statement and function allow you to position a
                      file at any byte or record. See Chapter 3, "File and
                      Device I/O," for more information.

   SELECT CASE        The use of SELECT CASE statements provides a way to
                      simplify complex condition testing. The CASE clause of
                      the SELECT CASE statement now accepts any expression
                      (including variable expressions) as an argument; in
                      previous versions, only constant expressions were
                      permitted.

   SETMEM             The SETMEM function facilitates mixed-language
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
  SETMEM             The SETMEM function facilitates mixed-language
                      programming by allowing you to decrease the amount of
                      dynamic memory allocated by BASIC so it can be used by
                      procedures in other languages.

   SLEEP              The SLEEP statement causes the program to pause for an
                      indicated period of time or until the user presses a
                      key or an enabled event occurs. The optional argument
                      indicates the length of the pause (in seconds).

   STATIC             Omitting the STATIC attribute from SUB and FUNCTION
                      statements causes variables to be allocated when the
                      procedures are called, instead of when they are
                      defined. Such variables do not retain their values
                      between procedure calls.

   TYPE               The TYPE...END TYPE statement lets you define a data
                      type containing elements of different fundamental
                      types. This simplifies defining and accessing
   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────
                     types. This simplifies defining and accessing
                      random-access file records.

   UEVENT             Enables, suspends, or disables a user-defined event.
   {ON|STOP|OFF}      The UEVENT statements are used in the same way as other
                      event-trapping statements.

   VARPTR             The VARPTR function now returns the 16-bit integer
                      offset of the BASIC variable or array element. The
                      offset is from the beginning of the segment that
                      contains the variable or array element.

   VARSEG             The VARSEG function returns the segment address of its
                      argument. This allows you to set DEF SEG appropriately
                      for use with PEEK, POKE, BLOAD, BSAVE, and CALL
                      ABSOLUTE. It also permits you to get the appropriate
                      segment for use with CALL INTERRUPT when executing
                      operating-system or BIOS interrupts.

   Keywords           Explanation
   ──────────────────────────────────────────────────────────────────────────

   WIDTH              A new argument on the WIDTH statement lets your
                      programs use the extended line modes on machines
                      equipped with EGA, VGA, and MCGA adapter cards.
   ──────────────────────────────────────────────────────────────────────────


   ──────────────────────────────────────────────────────────────────────────
   NOTE
     You can no longer conditionally execute NEXT and WEND statements using
     the single-line IF...THEN...ELSE statement.
   ──────────────────────────────────────────────────────────────────────────


 B.5  File Compatibility

   All versions of QuickBASIC are source-code compatible; source code created
   for a previous version compiles under Version 4.5, except as noted in
   Section B.3.4, "Restrictions on Include Files." QuickBASIC 4.5 translates
   QuickBASIC 4.0 binary files. If you encounter difficulty translating other
   binary files, save the program as an ASCII (text) format in QuickBASIC
   4.0, then load it with QuickBASIC 4.5. You must recompile object files and
   user libraries created with previous versions of QuickBASIC.



 ────────────────────────────────────────────────────────────────────────────
 Appendix C  Limits in QuickBASIC

   QuickBASIC and the BC compiler offer programming versatility, but both
   have limitations in order to keep file size and complexity manageable. As
   a result, you may reach these limits in some situations. This appendix
   lists the boundaries you may encounter.

   Table C.1  QuickBASIC Limits
╓┌─┌────────────────────────┌───────────────────────┌────────────────────────╖
                            Maximum                 Minimum
   ──────────────────────────────────────────────────────────────────────────
   Names and Strings
   Variable names           40 characters           1 character
                            Maximum                 Minimum
   ──────────────────────────────────────────────────────────────────────────
  Variable names           40 characters           1 character

   String length            32,767 characters       0 characters

   Integers                 32,767                  -32,768

   Long integers            2,147,483,647           -2,147,483,648

   Single-precision numbers 3.402823 E+38           1.401298 E-45
   (positive)

   Single-precision numbers -1.401298 E-45          -3.402823 E+38
   (negative)

   Double-precision numbers 1.797693134862315 D+308 4.940656458412465 D-324
   (positive)

   Double-precision numbers -4.940656458412465      -1.797693134862315 D+308
   (negative)               D-324
                            Maximum                 Minimum
   ──────────────────────────────────────────────────────────────────────────
  (negative)               D-324

   Arrays
   Array size (all
   elements)
     Static                 65,535 bytes (64K)      1
     Dynamic                Available memory

   Array dimensions         8                       1

   Array subscripts         32,767                  -32,768

   Files and Procedures
   Number of arguments      60 interpreted          0 passed to a procedure

   Nesting of include files 5 levels                0

   Procedure size           65,535 bytes (64K)      0
   (interpreted)
                            Maximum                 Minimum
   ──────────────────────────────────────────────────────────────────────────
  (interpreted)

   Module size (compiled)   65,535 bytes (64K)      0

   Data files open          255                     0 simultaneously

   Data file record number  2,147,483,647           1

   Data file record size    32,767 bytes (32K)      1 byte
   (bytes)

   Data file size           Available disk space    0

   Path names               127 characters          1 character

   Error message numbers    255                     1

   Editing in the Quick-BASIC Environment
   Text box entry           128 characters          0 characters
                            Maximum                 Minimum
   ──────────────────────────────────────────────────────────────────────────
  Text box entry           128 characters          0 characters

   "Search for" string      128                     1

   "Change to" string       40                      0

   Placemarkers             4                       0

   Watchpoints and/or watch 8                       0 expressions

   Number of lines in       10                      0 Immediate window

   Characters in View       255                     0 window on one line

   Length of COMMAND$       124                     0 string
   ──────────────────────────────────────────────────────────────────────────



 ────────────────────────────────────────────────────────────────────────────
 Appendix D  Keyboard Scan Codes and ASCII Character Codes


 D.1  Keyboard Scan Codes

   The table on the next page shows the DOS keyboard scan codes. These codes
   are returned by the INKEY$ function.

   Key combinations with NUL in the Char column return two bytes──a null byte
   (&H00) followed by the value listed in the Dec and Hex columns. For
   example, pressing ALT+F1 returns a null byte followed by a byte containing
   104 (&H68).

   ┌────────┬───────┬────────────┬─────────────┬─────────────┬──────────────┐
   │        │       │            │ ASCII or    │  ASCII or   │   ASCII or   │
   │        │ Scan  │ ASCII or   │ Extended    │  Extended   │   Extended   │
   │  Key   │ Code  │ Extended   │ with SHIFT  │  with CTRL  │   with ALT   │
   ├────────┼───────┼────────────┼─────────────┼─────────────┼──────────────┤
   │        │Dec Hex│Dec Hex Char│Dec Hex Char │Dec Hex Char │ Dec Hex Char │
   ├────────┼───────┼────────────┼─────────────┼─────────────┼──────────────┤
   │ESC     │ 1  01 │ 27  1B     │ 27  1B      │ 27  1B      │              │
   │1!      │ 2  02 │ 49  31  1  │ 33  21   !  │             │ 120  78  NUL │
   │2@      │ 3  03 │ 50  32  2  │ 64  40   @  │  3  03 NUL  │ 121  79  NUL │
   │3#      │ 4  04 │ 51  33  3  │ 35  23   #  │             │ 122  7A  NUL │
   │4$      │ 5  05 │ 52  34  4  │ 36  24   $  │             │ 123  7B  NUL │
   │5%      │ 6  06 │ 53  35  5  │ 37  25   %  │             │ 124  7C  NUL │
   │6^      │ 7  07 │ 54  36  6  │ 94  5E   ^  │ 30  IE      │ 125  7D  NUL │
   │7&      │ 8  08 │ 55  37  7  │ 38  26   &  │             │ 126  7E  NUL │
   │8*      │ 9  09 │ 56  38  8  │ 42  2A   *  │             │ 127  7F  NUL │
   │9(      │10  0A │ 57  39  9  │ 40  28   (  │             │ 128  80  NUL │
   │0)      │11  0B │ 48  30  0  │ 41  29   )  │             │ 129  81  NUL │
   │-_      │12  0C │ 45  2D  -  │ 95  5F   -  │ 31  IF      │ 130  82  NUL │
   │=+      │13  0D │ 61  3D  =  │ 43  2B   +  │             │ 131  83  NUL │
   │BKSP    │14  0E │  8  08     │  8  08      │127  7F      │              │
   │TAB     │15  0F │  9  09     │ 15  OF   NUL│             │              │
   │Q       │16  10 │113  71  q  │ 81  51   Q  │ 17  11      │  16  10  NUL │
   │W       │17  11 │119  77  w  │ 87  57   W  │ 23  17      │  17  11  NUL │
   │E       │18  12 │101  65  e  │ 69  45   E  │  5  05      │  18  12  NUL │
   │R       │19   13│114  72   r │ 82  52   R  │ 18  12      │  19  13  NUL │
   │T       │20   14│116  74   t │ 84  54   T  │ 20  14      │  20  14  NUL │
   │Y       │21   15│121  79   y │ 89  59   Y  │ 25  19      │  21  15  NUL │
   │U       │22   16│117  75   u │ 85  55   U  │ 21  15      │  22  16  NUL │
   │I       │23   17│105  69   i │ 73  49   I  │  9  09      │  23  17  NUL │
   │O       │24   18│111  6F   o │ 79  4F   O  │ 15  0F      │  24  18  NUL │
   │P       │25   19│112  70   p │ 80  50   P  │ 16  10      │  25  19  NUL │
   │[{      │26   1A│ 91  5B   [ │123  7B   {  │ 27  1B      │              │
   │]}      │27   1B│ 93  5D   ] │125  7D   }  │ 29  1D      │              │
   │ENTER   │28   1C│ 13  OD   CR│ 13  OD   CR │ 10  OA   LF │              │
   │CTRL    │29   1D│            │             │             │              │
   │A       │30   1E│ 97  61   a │ 65  41   A  │  1  01      │  30  1E  NUL │
   │S       │31   1F│115  73   s │ 83  53   S  │ 19  13      │  31  1F  NUL │
   │D       │32   20│100  64   d │ 68  44   D  │  4  04      │  32  20  NUL │
   │F       │33   21│102  66   f │ 70  46   F  │  6  06      │  33  21  NUL │
   │G       │34   22│103  67   g │ 71  47   G  │  7  07      │  34  22  NUL │
   │H       │35   23│104  68   h │ 72  48   H  │  8  08      │  35  23  NUL │
   │J       │36   24│106  6A   j │ 74  4A   J  │ 10  0A      │  36  24  NUL │
   │K       │37   25│107  6B   k │ 75  4B   K  │ 11  0B      │  37  25  NUL │
   │L       │38   26│108  6C   l │ 76  4C   L  │ 12  0C      │  38  26  NUL │
   │;:      │39   27│ 59  3B   ; │ 58  3A   :  │             │              │
   │'"      │40   28│ 39  27   ' │ 34  22   "  │             │              │
   │`~      │41   29│ 96  60   ` │126  7E   ~  │             │              │
   │L SHIFT │42   2A│            │             │             │              │
   │\|      │43   2B│ 92  5C   \ │124  7C   |  │ 28  1C      │              │
   │Z       │44  2C │122  7A  z  │ 90  5A   Z  │ 26  1A      │  44  2C  NUL │
   │X       │45  2D │120  78  x  │ 88  58   X  │ 24  18      │  45  2D  NUL │
   │C       │46  2E │ 99  63  c  │ 67  43   C  │  3  03      │  46  2E  NUL │
   │V       │47  2F │118  76  v  │ 86  56   V  │ 22  16      │  47  2F  NUL │
   │B       │48  30 │ 98  62  b  │ 66  42   B  │  2  OE      │  48  30  NUL │
   │N       │49  31 │110  6E  n  │ 78  4E   N  │ 14  OD      │  49  31  NUL │
   │M       │50  32 │109  6D  m  │ 77  4D   M  │ 13          │  50  32  NUL │
   │,<      │51  33 │ 44  2C  '  │ 60  3C   <  │             │              │
   │.>      │52  34 │ 46  2E  .  │ 62  3E   >  │             │              │
   │/?      │53  35 │ 47  2F  /  │ 63  3F   ?  │             │              │
   │R SHIFT │54  36 │            │             │             │              │
   │* PRTSC │55  37 │ 42  2A  *  │     INT  5 │ 16  10      │              │
   │ALT     │56  38 │            │             │             │              │
   │SPACE   │57  39 │ 32  20  SPC│ 32  20   SPC│ 32  20  SPC │  32  20  SPC │
   │CAPS    │58  3A │            │             │             │              │
   │F1      │59  3B │ 59  3B  NUL│ 84  54   NUL│ 94  5E  NUL │ 104  68  NUL │
   │F2      │60  3C │ 60  3C  NUL│ 85  55   NUL│ 95  5F  NUL │ 105  69  NUL │
   │F3      │61  3D │ 61  3D  NUL│ 86  56   NUL│ 96  60  NUL │ 106  6A  NUL │
   │F4      │62  3E │ 62  3E  NUL│ 87  57   NUL│ 97  61  NUL │ 107  6B  NUL │
   │F5      │63  3F │ 63  3F  NUL│ 88  58   NUL│ 98  62  NUL │ 108  6C  NUL │
   │F6      │64  40 │ 64  40  NUL│ 89  59   NUL│ 99  63  NUL │ 109  6D  NUL │
   │F7      │65  41 │ 65  41  NUL│ 90  5A   NUL│100  64  NUL │ 110  6E  NUL │
   │F8      │66  42 │ 66  46  NUL│ 91  5B   NUL│101  65  NUL │ 111  6F  NUL │
   │F9      │67  43 │ 67  43  NUL│ 92  5C   NUL│102  66  NUL │ 112  70  NUL │
   │F10     │68  44 │ 68  44  NUL│ 93  5D   NUL│103  67  NUL │ 113  71  NUL │
   │NUM     │69  45 │            │             │             │              │
   │SCROLL  │70  46 │            │             │             │              │
   │HOME    │71  47 │ 71  47 NUL │ 55  37   7  │119  77  NUL │              │
   │UP      │72  48 │ 72  48 NUL │ 56  38   8  │             │              │
   │PGUP    │73  49 │ 73  49 NUL │ 57  39   9  │132  84  NUL │              │
   │GREY-   │74  4A │ 45  2D  -  │ 45  2D   -  │             │              │
   │LEFT    │75  4B │ 75  4B NUL │ 52  34   4  │115  73  NUL │              │
   │CENTER  │76  4C │            │ 53  35   5  │             │              │
   │RIGHT   │77  4D │ 77  4D NUL │ 54  36   6  │116  74  NUL │              │
   │GREY+   │78  4E │ 43  2B  +  │ 43  2b   +  │             │              │
   │END     │79  4F │ 79  4F NUL │ 49  31   1  │117  75  NUL │              │
   │DOWN    │80  50 │ 80  50 NUL │ 50  32   2  │             │              │
   │PGDN    │81  51 │ 81  51 NUL │ 51  33   3  │118  76  NUL │              │
   │INS     │82  52 │ 82  52 NUL │ 48  30   0  │             │              │
   │DEL     │83  53 │ 83  53 NUL │ 46  2E   .  │             │              │
   └────────┴───────┴────────────┴─────────────┴─────────────┴──────────────┘


 D.2  ASCII Character Codes

   ┌─────────────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
   │Ctrl D   H  Char Code│  │Dec Hex Char│  │Dec Hex Char│  │Dec Hex Char│
   ├───┬───┬───┬────┬────┤  ├───┬───┬────┤  ├───┬───┬────┤  ├───┬───┬────┤
   │^@ │  0│00 │    │ NUL│  │ 32│ 20│    │  │ 64│40 │ @  │  │ 96│60 │ `  │
   │^A │  1│01 │ 
  │ SOH│  │ 33│ 21│ !  │  │ 65│41 │ A  │  │ 97│61 │ a  │
   │^B │  2│02 │   │ STX│  │ 34│ 22│ "  │  │ 66│42 │ B  │  │ 98│62 │ b  │
   │^C │  3│03 │   │ ETX│  │ 35│ 23│ #  │  │ 67│43 │ C  │  │ 99│63 │ c  │
   │^D │  4│04 │   │ EOT│  │ 36│ 24│ $  │  │ 68│44 │ D  │  │100│64 │ d  │
   │^E │  5│05 │   │ ENQ│  │ 37│ 25│ %  │  │ 69│45 │ E  │  │101│65 │ e  │
   │^F │  6│06 │   │ ACK│  │ 38│ 26│ &  │  │ 70│46 │ F  │  │102│66 │ f  │
   │^G │  7│07 │   │ BEL│  │ 39│ 27│ '  │  │ 71│47 │ G  │  │103│67 │ g  │
   │^H │  8│08 │   │ BS │  │ 40│ 28│ (  │  │ 72│48 │ H  │  │104│68 │ h  │
   │^I │  9│09 │    │ HT │  │ 41│ 29│ )  │  │ 73│49 │ I  │  │105│69 │ i  │
   │^J │ 10│0A │    │ LF │  │ 42│ 2A│ *  │  │ 74│4A │ J  │  │106│6A │ j  │
   │^K │ 11│0B │    │ VT │  │ 43│ 2B│ +  │  │ 75│4B │ K  │  │107│6B │ k  │
   │^L │ 12│0C │    │ FF │  │ 44│ 2C│ ,  │  │ 76│4C │ L  │  │108│6C │ l  │
   │^M │ 13│0D │    │ CR │  │ 45│ 2D│ -  │  │ 77│4D │ M  │  │109│6D │ m  │
   │^N │ 14│0E │   │ SO │  │ 46│ 2E│ .  │  │ 78│4E │ N  │  │110│6E │ n  │
   │^O │ 15│0F │    │ SI │  │ 47│ 2F│ /  │  │ 79│4F │ O  │  │111│6F │ o  │
   │^P │ 16│10 │   │ DLE│  │ 48│ 30│ 0  │  │ 80│50 │ P  │  │112│70 │ p  │
   │^Q │ 17│11 │   │ DC1│  │ 49│ 31│ 1  │  │ 81│51 │ Q  │  │113│71 │ q  │
   │^R │ 18│12 │   │ DC2│  │ 50│ 32│ 2  │  │ 82│52 │ R  │  │114│72 │ r  │
   │^S │ 19│13 │   │ DC3│  │ 51│ 33│ 3  │  │ 83│53 │ S  │  │115│73 │ s  │
   │^T │ 20│14 │   │ DC4│  │ 52│ 34│ 4  │  │ 84│54 │ T  │  │116│74 │ t  │
   │^U │ 21│15 │   │ NAK│  │ 53│ 35│ 5  │  │ 85│55 │ U  │  │117│75 │ u  │
   │^V │ 22│ 16│   │ SYN│  │ 54│ 36│ 6  │  │ 86│ 56│ V  │  │118│ 76│ v  │
   │^W │ 23│ 17│   │ ETB│  │ 55│ 37│ 7  │  │ 87│ 57│ W  │  │119│ 77│ w  │
   │^X │ 24│ 18│   │ CAN│  │ 56│ 38│ 8  │  │ 88│ 58│ X  │  │120│ 78│ x  │
   │^Y │ 25│ 19│   │ EM │  │ 57│ 39│ 9  │  │ 89│ 59│ Y  │  │121│ 79│ y  │
   │^Z │ 26│ 1A│   │ SUB│  │ 58│ 3A│ :  │  │ 90│ 5A│ Z  │  │122│ 7A│ z  │
   │^[ │ 27│ 1B│   │ ESC│  │ 59│ 3B│ ;  │  │ 91│ 5B│ [  │  │123│ 7B│ {  │
   │^\ │ 28│ 1C│   │ FS │  │ 60│ 3C│ <  │  │ 92│ 5C│ \  │  │124│ 7C│ |  │
   │^} │ 29│ 1D│   │ GS │  │ 61│ 3D│ =  │  │ 93│ 5D│ ]  │  │125│ 7D│ }  │
   │^^ │ 30│ 1E│   │ RS │  │ 62│ 3E│ >  │  │ 94│ 5E│ ^  │  │126│ 7E│ ~  │
   │^_ │ 31│ 1F│   │ US │  │ 63│ 3F│ ?  │  │ 95│ 5F│ _  │  │127│ 7F│    │
   └───┴───┴───┴────┴────┘  └───┴───┴────┘  └───┴───┴────┘  └───┴───┴────┘


            ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
            │Dec Hex Char│  │Dec Hex Char│  │Dec Hex Char│  │Dec Hex Char│
            ├───┬───┬────┤  ├───┬───┬────┤  ├───┬───┬────┤  ├───┬───┬────┤
            │128│ 80│ Ç  │  │160│ A0│ á  │  │192│ C0│ └  │  │224│ E0│ α  │
            │129│ 81│ ü  │  │161│ A1│ í  │  │193│ C1│ ┴  │  │225│ E1│ ß  │
            │130│ 82│ é  │  │162│ A2│ ó  │  │194│ C2│ ┬  │  │226│ E2│ Γ  │
            │131│ 83│ â  │  │163│ A3│ ú  │  │195│ C3│ ├  │  │227│ E3│ π  │
            │132│ 84│ ä  │  │164│ A4│ ñ  │  │196│ C4│ ─  │  │228│ E4│ Σ  │
            │133│ 85│ à  │  │165│ A5│ Ñ  │  │197│ C5│ ┼  │  │229│ E5│ σ  │
            │134│ 86│ å  │  │166│ A6│ ª  │  │198│ C6│ ╞  │  │230│ E6│ µ  │
            │135│ 87│ ç  │  │167│ A7│ º  │  │199│ C7│ ╟  │  │231│ E7│ τ  │
            │136│ 88│ ê  │  │168│ A8│ ¿  │  │200│ C8│ ╚  │  │232│ E8│ Φ  │
            │137│ 89│ ë  │  │169│ A9│ ⌐  │  │201│ C9│ ╔  │  │233│ E9│ Θ  │
            │138│ 90│ è  │  │170│ AA│ ¬  │  │202│ CA│ ╩  │  │234│ EA│ Ω  │
            │139│ 91│ ï  │  │171│ AB│ ½  │  │203│ CB│ ╦  │  │235│ EB│ δ  │
            │140│ 92│ î  │  │172│ AC│ ¼  │  │204│ CC│ ╠  │  │236│ EC│ ∞  │
            │141│ 93│ ì  │  │173│ AD│ ¡  │  │205│ CD│ ═  │  │237│ ED│ φ  │
            │142│ 94│ Ä  │  │174│ AE│ «  │  │206│ CE│ ╬  │  │238│ EE│ ε  │
            │143│ 95│ Å  │  │175│ AF│ »  │  │207│ CF│ ╧  │  │239│ EF│ ∩  │
            │144│ 96│ É  │  │176│ B0│ ░  │  │208│ D0│ ╨  │  │240│ F0│ ≡  │
            │145│ 97│ æ  │  │177│ B1│ ▒  │  │209│ D1│ ╤  │  │241│ F1│ ±  │
            │146│ 98│ Æ  │  │178│ B2│ ▓  │  │210│ D2│ ╥  │  │242│ F2│ ≥  │
            │147│ 99│ ô  │  │179│ B3│ │  │  │211│ D3│ ╙  │  │243│ F3│ ≤  │
            │148│ 9A│ ö  │  │180│ B4│ ┤  │  │212│ D4│ ╘  │  │244│ F4│ ⌠  │
            │149│ 9B│ ò  │  │181│ B5│ ╡  │  │213│ D5│ ╒  │  │245│ F5│ ⌡  │
            │150│ 96│ û  │  │182│ B6│ ╢  │  │214│ D6│ ╓  │  │246│ F6│ ÷  │
            │151│ 97│ ù  │  │183│ B7│ ╖  │  │215│ D7│ ╫  │  │247│ F7│ ≈  │
            │152│ 98│ ÿ  │  │184│ B8│ ╕  │  │216│ D8│ ╪  │  │248│ F8│ °  │
            │153│ 99│ Ö  │  │185│ B9│ ╣  │  │217│ D9│ ≈  │  │249│ F9│ ∙  │
            │154│ 9A│ Ü  │  │186│ BA│ ║  │  │218│ DA│ ┌  │  │250│ FA│ ·  │
            │155│ 9B│ ¢  │  │187│ BB│ ╗  │  │219│ DB│ █  │  │251│ FB│ √  │
            │156│ 9C│ £  │  │188│ BC│ ╝  │  │220│ DC│ ▄  │  │252│ FC│ ⁿ  │
            │157│ 9D│ ¥  │  │189│ BD│ ╜  │  │221│ DD│ ▌  │  │253│ FD│ ²  │
            │158│ 9E│ ₧  │  │190│ BE│ ╛  │  │222│ DE│ ▐  │  │254│ FE│ ■  │
            │159│ 9F│ ƒ  │  │191│ BF│ ┐  │  │223│ DF│ ▀  │  │255│ FF│    │
            └───┴───┴────┘  └───┴───┴─┴──┘  └───┴───┴────┘  └───┴───┴────┘



 ────────────────────────────────────────────────────────────────────────────
 Appendix E  BASIC Reserved Words

   The following is a list of Microsoft BASIC reserved words:

   ──────────────────────────────────────────────────────────────────────────
   ABS               ELSE             LOOP              SEEK
   ACCESS             ELSEIF           LPOS              SEG
   ALIAS              END              LPRINT            SELECT
   AND                ENDIF            LSET              SETMEM
   ANY                ENVIRON          LTRIM$            SGN
   APPEND             ENVIRON$         MID$              SHARED
   AS                 EOF              MKD$              SHELL
   ASC               EQV               MKDIR             SIGNAL
   ATN               ERASE            MKDMBF$           SIN
   BASE               ERDEV            MKI$              SINGLE
   BEEP              ERDEV$           MKL$              SLEEP
   BINARY             ERL              MKS$              SOUND
   BLOAD             ERR              MKSMBF$           SPACE$
   BSAVE             ERROR            MOD                SPC
   BYVAL              EXIT             NAME              SQR
   CALL              EXP              NEXT              STATIC
   CALLS             FIELD            NOT                STEP
   CASE              FILEATTR         OCT$              STICK
   CDBL              FILES            OFF                STOP
   CDECL              FIX              ON                 STR$
   CHAIN             FOR              OPEN              STRIG
   CHDIR             FRE              OPTION            STRING
   CHR$              FREEFILE         OR                 STRING$
   CINT              FUNCTION         OUT               SUB
   CIRCLE            GET              OUTPUT             SWAP
   CLEAR             GOSUB            PAINT             SYSTEM
   CLNG              GOTO             PALETTE           TAB
   CLOSE             HEX$             PCOPY             TAN
   CLS               IF               PEEK              THEN
   COLOR             IMP               PEN               TIME$
   COM               INKEY$           PLAY              TIMER
   COMMAND$          INP              PMAP              TO
   COMMON            INPUT            POINT             TROFF
   CONST             INPUT$           POKE              TRON
   COS               INSTR            POS               TYPE
   CSNG              INT              PRESET            UBOUND
   CSRLIN            INTEGER           PRINT             UCASE$
   CVD               IOCTL            PSET              UEVENT
   CVDMBF            IOCTL$            PUT               UNLOCK
   CVI               IS                RANDOM             UNTIL
   CVL               KEY              RANDOMIZE         USING
   CVS               KILL             READ              VAL
   CVSMBF            LBOUND           REDIM             VARPTR
   DATA              LCASE$           REM               VARPTR$
   DATE$             LEFT$            RESET             VARSEG
   DECLARE           LEN              RESTORE           VIEW
   DEF               LET              RESUME            WAIT
   DEFDBL            LINE             RETURN            WEND
   DEFINT            LIST              RIGHT$            WHILE
   DEFLNG            LOC              RMDIR             WIDTH
   DEFSNG            LOCAL             RND               WINDOW
   DEFSTR            LOCATE           RSET              WRITE
   DIM               LOCK             RTRIM$            XOR
   DO                LOF              RUN
   DOUBLE             LOG              SADD
   DRAW              LONG              SCREEN
   ──────────────────────────────────────────────────────────────────────────



 ────────────────────────────────────────────────────────────────────────────
 Appendix F  Metacommands

   This appendix describes the QuickBASIC metacommands──commands that direct
   QuickBASIC to handle your program in a particular way. The first section
   describes the format used for metacommands. The next two sections describe
   specific metacommands.

   By using the metacommands, you can:

   ■ Read in and compile other BASIC source files at specific points during
     compilation ($INCLUDE)

   ■ Control the allocation of dimensioned arrays ($STATIC and $DYNAMIC)


 F.1  Metacommand Syntax

   Metacommands begin with a dollar sign ($) and are always enclosed in a
   program comment. More than one metacommand can be given in one comment.
   Multiple metacommands are separated by white-space characters (space or
   tab). Metacommands that take arguments have a colon between the
   metacommand and the argument:

   REM $METACOMMAND [[ : argument ]]

   String arguments must be enclosed in single quotation marks. White-space
   characters between elements of a metacommand are ignored. The following
   are all valid forms for metacommands:

   REM $STATIC $INCLUDE:  'datadefs.bi'
   REM     $STATIC    $INCLUDE :  'datadefs.bi'
   ' $STATIC $INCLUDE: 'datadefs.bi'
   '     $STATIC    $INCLUDE :  'datadefs.bi'

   Note that no spaces appear between the dollar sign and the rest of the
   metacommand.

   If you want to refer to a metacommand in a description but do not want it
   to execute, place a character that is not a tab or space before the first
   dollar sign on the line. For example, on the following line both
   metacommands are ignored:

   REM x$STATIC $INCLUDE:  'datadefs.bi'


 F.2  Processing Additional Source Files: $INCLUDE

   The $INCLUDE metacommand instructs the compiler to temporarily switch from
   processing one file and instead to read program statements from the BASIC
   file named in the argument. When the end of the included file is reached,
   the compiler returns to processing the original file. Because compilation
   begins with the line immediately following the line in which $INCLUDE
   occurred, $INCLUDE should be the last statement on a line. The following
   statement is correct:

   DEFINT I-N   ' $INCLUDE: 'COMMON.BAS'

   There are two restrictions on using include files:

   1. Included files must not contain SUB or FUNCTION statements.

   2. Included files created with BASICA must be saved with the ,A option.


 F.3  Dimensioned Array Allocation: $STATIC and $DYNAMIC

   The $STATIC and $DYNAMIC metacommands tell the compiler how to allocate
   memory for arrays. Neither of these metacommands takes an argument:

   'Make all arrays dynamic.

   '$DYNAMIC

   $STATIC sets aside storage for arrays during compilation. When the $STATIC
   metacommand is used, the ERASE statement reinitializes all array values to
   zero (numeric arrays) or the null string (string arrays) but does not
   remove the array. The REDIM statement has no effect on $STATIC arrays.

   $DYNAMIC allocates storage for arrays while the program is running. This
   means that the ERASE statement removes the array and frees the memory it
   took for other uses. You can also use the REDIM statement to change the
   size of a $DYNAMIC array.

   The $STATIC and $DYNAMIC metacommands affect all arrays except implicitly
   dimensioned arrays (arrays not declared in a DIM statement). Implicitly
   dimensioned arrays are always allocated as if $STATIC had been used.



 ────────────────────────────────────────────────────────────────────────────
 Appendix G  Compiling and Linking from DOS

   This appendix explains how to compile and link outside the QuickBASIC
   environment. You might want to do this for some of the following reasons:

   ■ To use a different text editor

   ■ To create executable programs that can be debugged with the Microsoft
     CodeView debugger

   ■ To create listing files for use in debugging a stand-alone executable
     program

   ■ To use options not available within the QuickBASIC environment, such as
     storing arrays in row order

   ■ To link with NOCOM.OBJ or NOEM.OBJ (files supplied with QuickBASIC),
     which reduce the size of executable files in programs that do not use
     the COM statement or are always used with a math coprocessor

   When you finish this appendix you will understand how to

   ■ Compile from the DOS command line with the BC command

   ■ Create executable files and link program object files with the LINK
     command

   ■ Create and maintain stand-alone (.LIB) libraries with the LIB command


 G.1  BC, LINK, and LIB

   The Microsoft QuickBASIC package includes BC, LINK, and LIB. The following
   list describes how these special tools are used when compiling and linking
   outside of the QuickBASIC environment:

╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖
   Program            Function
   ──────────────────────────────────────────────────────────────────────────
   BC.EXE             When you choose the Make EXE File or Make Library
                      command from the Run menu, QuickBASIC invokes the BASIC
                      command-line compiler (BC) to produce intermediate
                      program files called object files. These object files
                      will be linked together to form your program or Quick
                      library. BC is also available any time you want to
                      compile programs outside of the QuickBASIC environment.
                      You may prefer to use BC if you want to compile
                      programs you have written with another text editor.
                      However, you only need to use BC from the command line
                      if your program is too large to compile in memory
                      within the QuickBASIC environment or if you want your
                      executable files to be compatible with the Microsoft
                      CodeView debugger.

   LINK.EXE           QuickBASIC uses the Microsoft Overlay Linker (LINK) to
                      link object files produced by BC with the appropriate
   Program            Function
   ──────────────────────────────────────────────────────────────────────────
                     link object files produced by BC with the appropriate
                      libraries to produce an executable file. You can use
                      LINK directly whenever you want to link object files or
                      make Quick libraries.

   LIB.EXE            The Microsoft Library Manager (LIB) creates stand-alone
                      libraries from the object files produced by BC.
                      QuickBASIC itself uses LIB to create such libraries and
                      then uses them when you choose the Make EXE File
                      command from the Run menu.

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



 G.2  The Compiling and Linking Process

   To create a stand-alone program from a BASIC source file when you are
   outside of the QuickBASIC environment, follow these steps:

   1. Compile each source file, creating an object file.

   2. Link the object files using LINK. LINK includes one or more stand-alone
      libraries and creates an executable file. LINK makes sure that all the
      procedure calls in the source files match up with the procedures in the
      libraries or with procedures in other object files before it creates an
      executable file.

   You can use either of the following methods of compiling and linking:

   ■ Compile and link in separate steps by using the BC and LINK commands.

   ■ Create a batch file containing all the compiling and linking commands.
     This method is most useful if you use the same options whenever you
     compile and link your programs.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     When QuickBASIC compiles and links your program from within the
     environment, the /E linker option is set automatically. However, when
     you use the LINK command outside the QuickBASIC environment, you must
     explicitly specify the /E option to minimize the size of the executable
     file and maximize program-loading speed.
   ──────────────────────────────────────────────────────────────────────────

   When compiling and linking from DOS, the paths you defined in the Options
   menu are not used. To search for include and library files the way you
   specified on the Options menu, you must set the DOS environment variables
   LIB and INCLUDE to point to the appropriate directories. Otherwise the
   compiler and/or linker might generate File not found errors.

   Sections G.3 and G.4 explain how to compile and link in separate steps.


 G.3  Compiling with the BC Command

   You can compile with the BC command in either of the following ways:

   ■ Type all information on a single command line, using the following
     syntax:

     BC sourcefile [[,[[objectfile]] [[,[[listingfile]]]]]]
     [[optionslist]][[;]]

   ■ Type

     BC

     and respond to the following prompts:

     Source Filename [.BAS]:
     Object Filename [basename.OBJ]:
     Source Listing: [NUL.LST]:

   Table G.1 shows the input you must give on the BC command line or in
   response to each prompt:

   Table G.1  Input to the BC Command
   Field              Prompt            Input
   ──────────────────────────────────────────────────────────────────────────
   sourcefile         "Source Filename" The name of your source file

   objectfile         "Object Filename" The name of the object file you are
                                        creating

   listingfile        "Source Listing"  The name of the file containing a
                                        source listing. The source-listing
                                        file contains the address of each
                                        line in your source file, the text of
                                        the source file, its size, and any
                                        error messages produced during
                                        compilation.

   optionslist        Gives options     Any of the compiler options described
                      after any         in Section G.3.2, "Using BC Command
                      response          Options"
   ──────────────────────────────────────────────────────────────────────────

 G.3.1  Specifying File Names

   The BC command makes certain assumptions about the files you specify,
   based on the path names and extensions you use for the files. The
   following sections describe these assumptions and other rules for
   specifying file names to the BC command.

   G.3.1.1  Uppercase and Lowercase Letters

   You can use any combination of uppercase and lowercase letters for file
   names; the compiler accepts uppercase and lowercase letters
   interchangeably.

   Example

   The BC command considers the following three file names to be equivalent:

   abcde.BAS
   ABCDE.BAS
   aBcDe.Bas

   G.3.1.2  File-Name Extensions

   A DOS file name has two parts: the "base name," which includes everything
   up to (but not including) the period (.), and the "extension," which
   includes the period and up to three characters following the period. In
   general, the extension identifies the type of file (for example, whether
   the file is a BASIC source file, an object file, an executable file, or a
   stand-alone library).

   BC and LINK use the file-name extensions described in the following list:

   Extension                File Description
   ──────────────────────────────────────────────────────────────────────────
   .BAS                     BASIC source file

   .OBJ                     Object file

   .LIB                     Stand-alone library file

   .LST                     Listing file produced by BC

   .MAP                     File of symbols from the linked program

   .EXE                     Executable file

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

   G.3.1.3  Path Names

   Any file name can include a full or partial path name. A full path name
   starts with the drive name; a partial path name has one or more directory
   names preceding the file name, but does not include a drive name.

   Giving a full path name allows you to specify files in different paths as
   input to the BC command and lets you create files on different drives or
   in different directories on the current drive.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     For files that you are creating with BC, you can give a path name ending
     in a backslash (\) to create the file in that path. When it creates the
     file, BC uses the default name for the file.
   ──────────────────────────────────────────────────────────────────────────

 G.3.2  Using BC Command Options

   Options to the BC command consist of either a forward-slash character (/)
   or a dash (-) followed by one or more letters. (The forward slash and the
   dash can be used interchangeably. In this manual, forward slashes are used
   for options.)

   The BC command-line options are explained in the following list:

╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖
   Option             Description
   ──────────────────────────────────────────────────────────────────────────
   /A                 Creates a listing of the disassembled object code for
                      each source line and shows the assembly-language code
                      generated by the compiler.

   /AH                Allows dynamic arrays of records, fixed-length strings,
                      and numeric data to occupy all of available memory. If
                      this option is not specified, the maximum size is 64K
                      per array. Note that this option has no effect on the
                      way data items are passed to procedures.

   /C:buffersize      Sets the size of the buffer receiving remote data for
                      each communications port when using an asynchronous
   Option             Description
   ──────────────────────────────────────────────────────────────────────────
                     each communications port when using an asynchronous
                      communications adapter. (The transmission buffer is
                      allocated 128 bytes for each communications port and
                      cannot be changed on the BC command line.) This option
                      has no effect if the asynchronous communications card
                      is not present. The default buffer size is 512 bytes
                      total for both ports; the maximum size is 32,767 bytes.

   /D                 Generates debugging code for run-time error checking
                      and enables CTRL+BREAK. This option is the same as the
                      Produce Debug Code option from the Run menu's Make EXE
                      File command within the QuickBASIC environment.

   /E                 Indicates presence of ON ERROR with RESUME linenumber
                      statements. (See also the discussion of the /X option
                      in this list.)

   /MBF               The intrinsic functions MKS$, MKD$, CVS, and CVD are
                      converted to MKSMBF$, MKDMBF$, CVSMBF, and CVDMBF,
   Option             Description
   ──────────────────────────────────────────────────────────────────────────
                     converted to MKSMBF$, MKDMBF$, CVSMBF, and CVDMBF,
                      respectively. This allows your QuickBASIC program to
                      read and write floating-point values stored in
                      Microsoft Binary format.

   /O                 Substitutes the BCOM45.LIB run-time library for
                      BRUN45.LIB. See Chapter 16, "The Run Menu," in Learning
                      to Use Microsoft QuickBASIC for more information about
                      using these libraries.

   /R                 Stores arrays in row-major order. BASIC normally stores
                      arrays in column-major order. This option is useful if
                      you are using other-language routines that store arrays
                      in row order.

   /S                 Writes quoted strings to the object file instead of the
                      symbol table. Use this option when an Out of memory
                      error message occurs in a program that has many string
                      constants.
   Option             Description
   ──────────────────────────────────────────────────────────────────────────
                     constants.

   /V                 Enables event trapping for communications (COM),
                      lightpen (PEN), joystick (STRIG), timer (TIMER), music
                      buffer (PLAY) and function keys (KEY). Use this option
                      to check between statements for an occurrence of an
                      event.

   /W                 Enables event trapping for the same statements as /V,
                      but checks at each line number or label for occurrence
                      of an event.

   /X                 Indicates presence of ON ERROR with RESUME, RESUME
                      NEXT, or RESUME 0.

   /ZD                Produces an object file containing line-number records
                      corresponding to the line numbers of the source file.
                      This option is useful when you want to perform
                      source-level debugging using the Microsoft Symbolic
   Option             Description
   ──────────────────────────────────────────────────────────────────────────
                     source-level debugging using the Microsoft Symbolic
                      Debug Utility (SYMDEB), available with the Microsoft
                      Macro Assembler, Version 4.0.

   /ZI                Produces an object file of debugging information used
                      by the Microsoft CodeView debugger, available with
                      Microsoft C, Version 5.0 and later and Microsoft Macro
                      Assembler, Version 5.0 and later.
   ──────────────────────────────────────────────────────────────────────────


 G.4  Linking

   After compiling your program, you must link the object file with the
   appropriate libraries to create an executable program. You can use the
   LINK command in any of the following ways:

   ■ Give the input on a command line of the following form:

     LINK objfile [[,[[exefile]][[,[[mapfile]][[,[[lib]]]]]]
     [[linkopts]][[;]]]]

     The command line cannot be longer than 128 characters.

   ■ Type

     LINK

     and respond to the following prompts:

     Object Modules [.OBJ]:
     Run File [basename.EXE]:
     List File [NUL.MAP]:
     Libraries [.LIB]:

     To give more files for any prompt, type a plus sign (+) at the end of
     the line. The prompt reappears on the next line, and you can continue
     typing input for the prompt.

   ■ Set up a "response file" (a file containing responses to the LINK
     command prompts), and then type a LINK command of the following form:

     LINK @filename

     Here, filename is the name of the response file. You can append linker
     options to any response or give options on one or more separate lines.
     The responses must be in the same order as the LINK command prompts
     discussed above. You can also enter the name of a response file after
     any linker prompt, or at any position in the LINK command line.

   Table G.2 shows the input you must give on the LINK command line, or in
   response to each prompt.

   Table G.2  Input to the LINK Command
╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
   Field                    Prompt
                            Input
   ──────────────────────────────────────────────────────────────────────────
   objfile                  "Object Modules"
                            One or more object files that you are linking.
                            The object files should be separated by either
   Field                    Prompt
                            Input
   ──────────────────────────────────────────────────────────────────────────
                           The object files should be separated by either
                            plus signs or spaces.

   exefile                  "Run File"
                            Name of the executable file you are creating, if
                            you want to give it a name or extension other
                            than the default. You should always use the .EXE
                            extension, since DOS expects executable files to
                            have this extension.

   mapfile                  "List File"
                            Name of the file containing a symbol map listing,
                            if you are creating one. You can also specify
                            one of the following DOS device names to direct
                            the map file to that device: AUX for an auxiliary
                            device, CON for the console (terminal), PRN for a
                            printer device, or NUL for no device (so that no
                            map file is created). See Section G.4.6.11 for a
   Field                    Prompt
                            Input
   ──────────────────────────────────────────────────────────────────────────
                           map file is created). See Section G.4.6.11 for a
                            sample map file and information about its
                            contents.

   lib                      "Libraries"
                            One or more stand-alone libraries (or directories
                            to be searched for stand-alone libraries)
                            separated by plus signs or spaces. The
                            "Libraries" prompt allows you to specify up to 16
                            libraries; any additional libraries are ignored.
                            See Section G.4.3 for rules for specifying
                            library names to the linker.

   linkopts                 Gives options after any response
                            Any of the LINK options described in Sections
                            G.4.6.2-G.4.6.15. You can specify LINK options
                            anywhere on the command line.

   Field                    Prompt
                            Input
   ──────────────────────────────────────────────────────────────────────────

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


   If you are using a response file, each response must follow the rules
   outlined in Table G.2.

 G.4.1  Defaults for LINK

   You can choose defaults for any of the information that LINK needs in any
   of the following ways:

   ■ To choose the default for any command-line entry, omit the file name or
     names before the entry and type only the required comma. The only
     exception to this is the default for the mapfile entry: if you use a
     comma as a placeholder for this entry, LINK creates a map file.

   ■ To choose the default for any prompt, press ENTER.

   ■ To choose the defaults for all remaining command-line entries or
     prompts, type a semicolon after any entry or prompt. The only required
     input is one or more object-file names.

   The following list shows the defaults that LINK uses for executable files,
   map files, and libraries:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
   File Type                Default
   ──────────────────────────────────────────────────────────────────────────
   Executable               Base name of the first object file given, plus
                            the .EXE extension. To rename the executable
                            file, you are required to specify only the new
                            base name; if you give a file name with no
                            extension, LINK automatically appends the .EXE
                            extension.

   Map                      The special file name NUL.MAP, which tells LINK
                            not to create a map file. To create a map file,
                            you are required to specify only the base name;
   File Type                Default
   ──────────────────────────────────────────────────────────────────────────
                           you are required to specify only the base name;
                            if you give a file name with no extension, LINK
                            automatically appends the .MAP extension.

   Libraries                Libraries named in the given object files. If you
                            choose the Stand-Alone EXE File option,
                            BCOM45.LIB is the default library; otherwise, the
                            default is BRUN45.LIB. If you specify a library
                            other than a default library, you must give only
                            the base name; if you give a library name with no
                            extension, LINK automatically appends the .LIB
                            extension. See Section G.4.3 for information
                            about specifying libraries other than the default
                            libraries.
   ──────────────────────────────────────────────────────────────────────────


   ──────────────────────────────────────────────────────────────────────────
   NOTE
     When linking a stand-alone executable file, if your program does not use
     the COM statement, your program will be about 4K smaller if you link
     with NOCOM.OBJ, a file supplied with QuickBASIC.
   ──────────────────────────────────────────────────────────────────────────

   Examples

   The following example shows a response file. It tells LINK to link
   together the four object modules FRAME, TEXT, TABLE, and LINEOUT. The
   executable file FRAME.EXE and the map file named FRAMESYM.MAP are
   produced. The /PAUSE option causes LINK to pause before producing the
   executable file to permit disk swapping, if necessary. The /MAP option
   tells LINK to include public symbols and addresses in the map file. LINK
   also links any needed routines from the library file GRAF.LIB. See
   Sections G.4.6.2 and G.4.6.11 for more information on /PAUSE and /MAP
   options.

   FRAME TEXT TABLE LINEOUT
   /PAUSE /MAP
   FRAMESYM
   GRAF.LIB

   In the following example, LINK loads and links the object files FRAME.OBJ,
   TEXT.OBJ, TABLE.OBJ, and LINEOUT.OBJ, searching for unresolved references
   in the library file COBLIB.LIB. By default, the executable file is named
   FRAME.EXE. A map file called FRAMESYM.MAP is also produced.

   LINK FRAME+TEXT+TABLE+LINEOUT, ,FRAMESYM, COBLIB.LIB

   The example that follows illustrates how to continue any prompt by typing
   a plus sign (+) at the end of your response. The example links all of the
   given object files, then creates an executable file. Since a semicolon is
   typed as a response to the "Run File" prompt, the executable file is given
   the default name, which is the base name of the first object file given
   (FRAME), plus the .EXE extension. The defaults are also used for the
   remaining prompts. As a result, no map file is created, and the default
   libraries named in the object files are used for linking.

   LINK

   Object Modules [.OBJ]: FRAME TEXT TABLE LINEOUT+
   Object Modules [.OBJ]: BASELINE REVERSE COLNUM+
   Object Modules [.OBJ]: ROWNUM
   Run File [FRAME.EXE]: ;

 G.4.2  Specifying Files to LINK

   The rules for specifying file names to the linker are the same as for
   specifying file names to the BC command: uppercase and lowercase letters
   can be used interchangeably, and file names can include path names to tell
   LINK to look for files or create files in the given path. See Section
   G.3.1 for more information.

 G.4.3  Specifying Libraries to LINK

   Ordinarily, you do not need to give LINK a stand-alone-library name. When
   the BC command creates object files, it places in each object file the
   name of the correct stand-alone library for that object file. When the
   object file is passed to the linker, LINK looks for a library with the
   same name as the name in the object file and links the object file with
   that library automatically.

   To link object files with a stand-alone library other than the default,
   give the name of the nondefault library to LINK. You can give the library
   name in either of the following ways:

   ■ After the third comma on the LINK command line. Commas follow the list
     of object-file names, the executable-file name, and the listing-file
     name. The final name is the library name.

   ■ In response to the "Libraries" prompt of the LINK command.

   LINK searches libraries you specify to resolve external references before
   it searches default libraries.

   You might want to link with a stand-alone library other than the default
   to

   ■ Link with additional stand-alone libraries.

   ■ Link with libraries in different paths. If you specify a complete path
     name for the library, LINK only looks in that path for the library.
     Otherwise, it looks in the following three locations:

     1. The current working directory

     2. Any paths or drives you specify after the third comma on the LINK
        command line

     3. The locations given by the LIB environment variable

   ■ Ignore the library named in the object file. In this case, you must give
     the LINK option /NOD in addition to specifying the library you want to
     use for linking. See Section G.4.6.8 for more information about the
     /NOD option.

 G.4.4  Memory Requirements for LINK

   LINK uses available memory for the linking session. If the files to be
   linked create an output file that exceeds available memory, LINK creates a
   temporary disk file to serve as memory. This temporary file is handled in
   one of the following ways, depending on the DOS version:

   ■ LINK uses the directory specified by the TMP environment variable from
     DOS for the purpose of creating a temporary file. For example, if the
     TMP variable was set to C:\TEMPDIR, then LINK would put the temporary
     file in C:\TEMPDIR.

     If there is no TMP environment variable, or if the directory specified
     by TMP does not exist, then LINK puts the temporary file in the current
     working directory.

   ■ If LINK is running on DOS Version 3.0 or later, it uses a DOS system
     call to create a temporary file with a unique name in the temporary-file
     directory.

   ■ If LINK is running on a version of DOS prior to 3.0, it creates a
     temporary file named VM.TMP.

   When the linker creates a temporary disk file, you see the message

   Temporary file tempfile has been created.
   Do not change diskette in drive, letter

   where tempfile is ".\" followed by either the file name VM.TMP or a name
   generated by DOS, and letter is the drive containing the temporary file.

   The message

   Do not change diskette in drive

   does not appear unless the drive named letter is a floppy-disk drive. If
   this message appears, do not remove the disk from the drive until the
   linking session ends. If you remove the disk, linker operations will be
   unpredictable, and you may see the following message:

   unexpected end-of-file on scratch file

   If you see this message, rerun the linking session.

   The temporary file that LINK creates is a working file only. LINK deletes
   it at the end of the session.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Do not give any of your own files the name VM.TMP. LINK displays an
     error message if it finds an existing file with this name.
   ──────────────────────────────────────────────────────────────────────────

 G.4.5  Linking with Mixed-Language Programs

   You can link mixed-language programs with LINK. However, problems can
   result from linking .OBJ files from within the other language. Different
   assumptions by different linkers can corrupt QuickBASIC files.

   The following sections discuss linking with modules written in Pascal,
   FORTRAN, and assembly language.

   G.4.5.1  Pascal and FORTRAN Modules in QuickBASIC Programs

   Modules compiled with Microsoft Pascal or FORTRAN can be linked with BASIC
   programs, as described in the Microsoft Mixed-Language Programming Guide.
   They can also be incorporated in Quick libraries. However, QuickBASIC
   programs containing code compiled with Microsoft Pascal must allocate at
   least 2K near-heap space for Pascal. The following example does this by
   using the DIM statement to allocate a static array of 2K or greater in a
   named common block called NMALLOC:

   DIM name%(2048) : COMMON SHARED /NMALLOC/ name%()

   The Pascal run-time module assumes it always has at least 2K of near-heap
   space available. If the Pascal code cannot allocate the required space,
   QuickBASIC may crash. This applies to Pascal code in Quick libraries and
   to Pascal code linked into executable files. The situation is similar for
   FORTRAN I/O, which also requires near buffer space, and which can be
   provided by using an NMALLOC common block.

   G.4.5.2  STATIC Array Allocation in Assembly-Language Routines

   Use the SEG or CALLS keywords or far pointers to pass static array data to
   assembly-language routines. You cannot assume data is in a particular
   segment. Alternatively, you can declare all arrays dynamic (still using
   far pointers) since BC and the QuickBASIC environment handle dynamic
   arrays identically.

   G.4.5.3  References to DGROUP in Extended Run-Time Modules

   For mixed-language programs that use the CHAIN command, you should make
   sure that any code built into an extended run-time module does not contain
   any references to DGROUP. (The CHAIN command causes DGROUP to move, but
   does not update references to DGROUP.) This rule applies only to
   mixed-language programs; because BASIC routines never refer to DGROUP, you
   can ignore this caution for programs written entirely in BASIC.

   To avoid this problem, you can use the value of SS, since BASIC always
   assumes that SS coincides with DGROUP.

 G.4.6  Using LINK Options

   LINK options begin with the linker's option character, which is the
   forward slash (/).

   Case is not significant in LINK options; for example, /NOI and /noi are
   equivalent.

   You can abbreviate LINK options to save space and effort. The minimum
   valid abbreviation for each option is indicated in the syntax of the
   option. For example, several options begin with the letters "NO";
   therefore, abbreviations for those options must be longer than "NO" to be
   unique. You cannot use "NO" as an abbreviation for the /NOIGNORECASE
   option, since LINK cannot tell which of the options beginning with "NO"
   you intend. The shortest valid abbreviation for this option is /NOI.

   Abbreviations must begin with the first letter of the option and must be
   continuous through the last letter typed. No gaps or transpositions are
   allowed.

   Some LINK options take numeric arguments. A numeric argument can be any of
   the following:

   ■ A decimal number from 0 to 65,535.

   ■ An octal number from 0 to 0177777. A number is interpreted as octal if
     it starts with a zero (0). For example, the number 10 is a decimal
     number, but the number 010 is an octal number, equivalent to 8 in
     decimal.

   ■ A hexadecimal number from 0 to 0xFFFF. A number is interpreted as
     hexadecimal if it starts with a zero followed by an x or an X. For
     example, 0x10 is a hexadecimal number, equivalent to 16 in decimal.

   LINK options affect all files in the linking process, regardless of where
   the options are specified.

   If you usually use the same set of LINK options, you can use the LINK
   environment variable in DOS to specify certain options each time you link.
   If you set this variable, LINK checks it for options and expects to find
   options listed exactly as you would type them on the command line. You
   cannot specify file-name arguments in the LINK environment variable.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     A command-line option overrides the effect of any environment-variable
     option with which it conflicts. For example, the command-line option
     /SE:256 cancels the effect of the environment-variable option /SE:512.
     To prevent an option in the environment variable from being used, you
     must reset the environment variable itself.
   ──────────────────────────────────────────────────────────────────────────

   Example

   In the following example, the file TEST.OBJ is linked with the options
   /SE:256 and /CO. After that, the file PROG.OBJ is linked with the option
   /NOD, as well as with the options /SE:256 and /CO.

   SET LINK=/SE:256 /CO
   LINK TEST;
   LINK /NOD PROG;

   G.4.6.1  Viewing the Options List (/HE)

   /HE[[LP]]

   The /HE option tells LINK to display a list of the available LINK options
   on the screen.

   G.4.6.2  Pausing during Linking (/PAU)

   /PAU[[SE]]

   The /PAU option tells LINK to pause in the link session and display a
   message before it writes the executable file to disk. This allows you to
   insert a new disk to hold the executable file.

   If you specify the /PAUSE option, LINK displays the following message
   before it creates the executable file:

   About to generate .EXE file
   Change diskette in drive letterand press <ENTER>

   The letter corresponds to the current drive. LINK resumes processing when
   you press the ENTER key.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Do not remove the disk on which the list file is created or the disk
     used for the temporary file. If a temporary file is created on the disk
     you plan to swap, press CTRL+C to terminate the linking session.
     Rearrange your files so that the temporary file and the executable file
     can be written to the same disk. Then try linking again.
   ──────────────────────────────────────────────────────────────────────────

   G.4.6.3  Displaying Linker Process Information (/I)

   /I[[NFORMATION]]

   The /I option displays information about the linking process, including
   the phase of linking and the names of the object files being linked.

   This option helps you determine the locations of the object files being
   linked and the order in which they are linked.

   G.4.6.4  Preventing Linker Prompting (/B)

   /B[[ATCH]]

   The /B option tells LINK not to prompt you for a new path name whenever it
   cannot find a library or object file that it needs. When this option is
   used, the linker simply continues to execute without using the file in
   question.

   This option can cause unresolved external references. It is intended
   primarily to let you use batch or MAKE files to link many executable files
   with a single command if you do not want LINK to stop processing if it
   cannot find a required file. It is also useful when you are redirecting
   the LINK command line to create a file of linker output for future
   reference. However, this option does not prevent LINK from prompting for
   arguments missing from the LINK command line.

   G.4.6.5  Creating Quick Libraries (/Q)

   /Q[[UICKLIB]]

   The /Q option tells LINK to combine the object files you specify into a
   Quick library. When you start the QuickBASIC environment, you can give the
   /L option on the QB command line to load the Quick library. If you use the
   /Q option, be sure to specify BQLB45.LIB in the library list in order to
   include QuickBASIC Quick-library support routines.

   See Appendix H, "Creating and Using Quick Libraries," for more
   information about creating and loading Quick libraries.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     You cannot use the /EXEPACK option with the /Q option.
   ──────────────────────────────────────────────────────────────────────────

   G.4.6.6  Packing Executable Files (/E)

   /E[[XEPACK]]

   The /E option removes sequences of repeated bytes (typically null
   characters) and optimizes the "load-time relocation table" before creating
   the executable file. The load-time relocation table is a table of
   references relative to the start of the program. Each reference changes
   when the executable image is loaded into memory and an actual address for
   the entry point is assigned.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Executable files linked with this option may be smaller and load faster
     than files linked without this option.
   ──────────────────────────────────────────────────────────────────────────

   G.4.6.7  Disabling Segment Packing (/NOP)

   /NOP[[ACKCODE]]

   The /NOP option is normally not necessary because code-segment packing is
   normally turned off. However, if a DOS environment variable such as LINK
   turns on code-segment packing automatically, you can use the /NOP option
   to turn segment packing back off again.

   G.4.6.8  Ignoring the Usual BASIC Libraries (/NOD)

   /NOD[[EFAULTLIBRARYSEARCH]]

   When it creates an object file, BC includes the names of the "standard"
   libraries──libraries that LINK searches to resolve external references.
   The /NOD option tells LINK not to search any library specified in an
   object file to resolve external references.

   In general, QuickBASIC programs do not work correctly without the standard
   QuickBASIC libraries (BRUN45.LIB and BCOM45.LIB). Thus, if you use the
   /NOD option, you should explicitly give the path name of the required
   standard library.

   G.4.6.9  Ignoring Dictionaries (/NOE)

   /NOE[[XTDICTIONARY]]

   If LINK suspects that a public symbol has been redefined, it prompts you
   to link again with the /NOE option. When you do so, it searches the
   individual object files, rather than "dictionaries" it has created, to
   resolve conflicts. For example, when linking a program with 87.LIB or
   NOCOM.OBJ, you must use the /NOE option.

   G.4.6.10  Setting Maximum Number of Segments (/SE)

   /SE[[GMENTS]]:number

   The /SE option controls the number of segments that LINK allows a program
   to have. The default is 128, but you can set number to any value
   (specified as decimal, octal, or hexadecimal) in the range 1-1024
   (decimal).

   For each segment, LINK must allocate space to keep track of segment
   information. When you set the segment limit higher than 128, LINK
   allocates more space for segment information. For programs with fewer than
   128 segments, you can minimize the amount of storage LINK needs by setting
   number to reflect the actual number of segments in the program. LINK
   displays an error message if this number is too high for the amount of
   memory it has available.

   G.4.6.11  Creating a Map File (/M)

   /M[[AP]]

   The /M option creates a map file. A map file lists the segments of a
   program and the program's public symbols. LINK always tries to allocate
   all of the available memory for sorting public symbols. If the number of
   symbols exceeds the memory limit, then LINK generates an unsorted list.
   The map file mapfile contains a list of symbols sorted by address;
   however, it does not contain a list sorted by name. A sample map file is
   shown below:

   Start  Stop   Length Name                   Class
    00000H 01E9FH 01EA0H _TEXT                  CODE
    01EA0H 01EA0H 00000H C_ETEXT                ENDCODE
   .
   .
   .

   The information in the columns Start and Stop shows the 20-bit address (in
   hexadecimal) of each segment, relative to the beginning of the load
   module. The load module begins at location zero. The column Length gives
   the length of the segment in bytes. The column Name gives the name of the
   segment; the column Class gives information about the segment type. See
   the Microsoft MS-DOS Programmer's Reference for information about groups,
   segments, and classes.

   The starting address and name of each group appear after the list of
   segments. A sample group listing is shown below:

   Origin   Group
   01EA:0   DGROUP

   In this example, DGROUP is the name of the data group.

   The map file shown below contains two lists of global symbols: the first
   list is sorted in ASCII-character order by symbol name; the second, by
   symbol address. The notation Abs appears next to the names of absolute
   symbols (symbols containing 16-bit constant values that are not associated
   with program addresses).

   Many of the global symbols that appear in the map file are symbols used
   internally by the compiler and linker. These symbols usually begin with
   the characters B$ or end with QQ.

   Address         Publics by Name

    01EA:0096       STKHQQ
    0000:1D86       B$Shell
    01EA:04B0       _edata
    01EA:0910       _end
   .
   .
   .
    01EA:00EC       __abrkp
    01EA:009C       __abrktb
    01EA:00EC       __abrktbe
    0000:9876  Abs  __acrtmsg
    0000:9876  Abs  __acrtused
   .
   .
   .
    01EA:0240       ___argc
    01EA:0242       ___argv

    Address         Publics by Value

    0000:0010       _main
    0000:0047       _htoi
   .
   .
   .

   The addresses of the external symbols are in the frame:offset format,
   showing the location of the symbol relative to zero (the beginning of the
   load module).

   Following the lists of symbols, the map file gives the program entry
   point, as shown in the following example:

   Program entry point at 0000:0129

   A map file can also be specified by giving a map-file name on the LINK
   command line or by giving a map-file name in response to the "List File"
   prompt.

   G.4.6.12  Including Line Numbers in a Map File (/LI)

   /LI[[NENUMBERS]]

   The /LI option creates a map file and includes the line numbers and
   associated addresses of the source program. If you are compiling and
   linking in separate steps, this option has an effect only if you are
   linking object files compiled with the /M option.

   G.4.6.13  Packing Contiguous Segments (/PAC)

   /[[NO]]PAC[[KCODE]][[:number]]

   The /PAC option tells LINK to group neighboring code segments. Code
   segments in the same group share the same segment address; all offset
   addresses are then adjusted upward as needed. As a result, many
   instructions that would otherwise have different segment addresses share
   the same segment address.

   If specified, number is the size limit of groups formed by /PAC. LINK
   stops adding segments to a particular group as soon as it cannot add a
   segment to the group without exceeding number. At that point, LINK starts
   forming a new group with the remaining code segments. If number is not
   given, the default is 65,530.

   Although LINK does not pack neighboring segments unless you explicitly ask
   for it, you can use the /NOPACKCODE option to turn off segment packing if,
   for example, you have given the /PAC option in the LINK environment
   variable in DOS.

   G.4.6.14  Using the CodeView Debugger (/CO)

   /CO[[DEVIEW]]

   The /CO option prepares an executable file for debugging using the
   CodeView debugger. If you are compiling and linking in separate steps,
   this option has an effect only if you are linking object files compiled
   with the /ZI option of the BC command. Similarly, it should not be used in
   conjunction with the LINK command's /Q option, because a Quick library
   cannot be debugged with the CodeView debugger.

   G.4.6.15  Distinguishing Case (/NOI)

   /NOI[[GNORECASE]]

   The /NOI option tells LINK to distinguish between uppercase and lowercase
   letters; for example, LINK would consider the names ABC, abc, and Abc to
   be three separate names. When you link, do not specify the /NOI option on
   the LINK command line.

 G.4.7  Other LINK Command-Line Options

   Not all options of the LINK command are suitable for use with QuickBASIC
   programs. The following LINK options can be used with Microsoft QuickBASIC
   programs; however, they are never required, since they request actions
   that the BC command or QuickBASIC performs automatically:

╓┌─┌─────────────────────────────┌───────────────────────────────────────────╖
   Option                        Action
   ──────────────────────────────────────────────────────────────────────────
   /CP[[ARMAXALLOC]]:number      Sets the maximum number of 16-byte
                                 paragraphs needed by the program when it is
                                 loaded into memory to number, an integer
                                 between 1 and 65,535, inclusive. The
                                 operating system uses this value when
                                 allocating space for the program before
                                 loading it. Although you can use this option
                                 on the LINK command line, it has no effect
                                 because, while it is running, your BASIC
                                 program controls memory.

   /DO[[SSEG]]                   Forces segments to be ordered using the
                                 defaults for Microsoft high-level language
                                 products. QuickBASIC programs always use
                                 this segment order by default.

   /ST[[ACK]]:number             Specifies the size of the stack for your
   Option                        Action
   ──────────────────────────────────────────────────────────────────────────
  /ST[[ACK]]:number             Specifies the size of the stack for your
                                 program, where number is any positive value
                                 (decimal, octal, or hexadecimal) up to
                                 65,535 (decimal) representing the size, in
                                 bytes, of the stack. The standard BASIC
                                 library sets the default stack size to 2K.

   /DS[[ALLOCATE]]               Loads all data starting at the high end of
                                 the default data segment.

   /HI[[GH]]                     Places the executable file as high in memory
                                 as possible.

   /NOG[[ROUPASSOCIATION]]       Tells LINK to ignore group associations when
                                 assigning addresses to data and code items.

   /O[[VERLAYINTERRUPT]]:number  Specifies an interrupt number other than
                                 0x3F for passing control to overlays.
   ──────────────────────────────────────────────────────────────────────────
   Option                        Action
   ──────────────────────────────────────────────────────────────────────────
  ──────────────────────────────────────────────────────────────────────────


   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Do not use the /DS, /HI, /NOG, or /O options when linking object files
     compiled with BC. They are suitable only for object files created by the
     Microsoft Macro Assembler (MASM).
   ──────────────────────────────────────────────────────────────────────────


 G.5  Managing Stand-Alone Libraries: LIB

   The Microsoft Library Manager (LIB) manages the contents of stand-alone
   libraries. A stand-alone library is made up of "object modules"──that is,
   object files combined to form a library. Unlike an object file, an object
   module does not exist independently of its library, and does not have a
   path name or extension associated with its file name. Using LIB, you can:

   ■ Combine object files to create a new library

   ■ Add object files to an existing library

   ■ Delete or replace the object modules of an existing library

   ■ Extract object modules from an existing library and place them in
     separate object files

   ■ Combine the contents of two existing libraries into a new library

   When updating an existing library, LIB performs all of its operations on a
   copy of the library. This mechanism ensures that you have a backup copy of
   any library you update in case of problems with the updated version of the
   library.

 G.5.1  Running LIB

   You can give the LIB command input in any of the following ways:

   ■ Specify the input on a command line of the following form:

     LIB oldlib [[/P[[AGESIZE]]:number]]
     [[commands]][[,[[listfile]][[,[[newlib]]]]]][[;]]

     The command line has a maximum length of 128 characters.

   ■ Type

     lib

     and respond to the following prompts:

     Library name:
     Operations:
     List file:
     Output library:

     To give more files for any prompt, type an ampersand (&) at the end of
     the line. The prompt reappears on the next line, and you can continue
     typing input for the prompt.

   ■ Set up a response file, a file with responses to LIB command prompts,
     then type a LIB command of the following form:

     LIB @filename

   Here, filename is the name of the response file. The responses must be in
   the same order as the LIB prompts discussed above. You can also enter the
   name of a response file after any LINK prompt, or at any position in the
   LIB command line.

   Table G.3 shows the input you must give on the LIB command line, or in
   response to each prompt. If you are using a response file, each response
   must follow the rules outlined in this table.

   Table G.3  Input to the LIB Command
╓┌─┌───────────┌────────────────────────┌────────────────────────────────────╖
   Field       Prompt                   Input
   ──────────────────────────────────────────────────────────────────────────
   oldlib      "Library name"           Name of the library you are changing
                                        or creating. If this library does not
                                        exist, LIB asks if you want to create
   Field       Prompt                   Input
   ──────────────────────────────────────────────────────────────────────────
                                       exist, LIB asks if you want to create
                                        it. Type the letter y to create a new
                                        library or the letter n to terminate
                                        LIB. This message is suppressed if
                                        you type command characters, a comma,
                                        or a semicolon after the library
                                        name. A semicolon tells LIB to
                                        perform a consistency check on the
                                        library; in this case, it displays a
                                        message if it finds errors in any
                                        library module.

   /P:number   /P:number after "Library The library page size. This sets the
               name" prompt             page size for the library to number,
                                        where number is an integer power of 2
                                        between 16 and 32,768, inclusive. The
                                        default page size for a new library
                                        is 16 bytes. Modules in the library
                                        are always aligned to start at a
   Field       Prompt                   Input
   ──────────────────────────────────────────────────────────────────────────
                                       are always aligned to start at a
                                        position that is a multiple of the
                                        page size (in bytes) from the
                                        beginning of the file.

   /I          None                     Tells LIB to ignore case when
                                        comparing symbols (default). Use when
                                        combining with libraries that are
                                        case sensitive.

   /NOE        None                     Tells LIB not to generate an extended
                                        dictionary.

   /NOI        None                     Tells LIB to compare case when
                                        comparing symbols (LIB remains case
                                        sensitive).

   commands    "Operations"             Command symbols and object files that
                                        tell LIB what changes to make in the
   Field       Prompt                   Input
   ──────────────────────────────────────────────────────────────────────────
                                       tell LIB what changes to make in the
                                        library.

   listfile    "List file"              Name of a cross-reference-listing
                                        file. No listing file is created if
                                        you do not give a file name.

   newlib      "Output library"         Name of the changed library that LIB
                                        creates as output. If you do not give
                                        a new library name, the original,
                                        unchanged library is saved in a
                                        library file with the same name but
                                        with a .BAK extension replacing the
                                        .LIB extension.
   ──────────────────────────────────────────────────────────────────────────


 G.5.2  Usual Responses for LIB

   LIB has its own built-in (default) responses. You can choose these usual
   responses for any of the information that LIB needs, in any the following
   ways:

   ■ To choose the default for any command-line entry, omit the file name or
     names before the entry and type only the required comma. The only
     exception to this is the default for the listfile entry: if you omit
     this entry, LIB creates a cross-reference-listing file.

   ■ To choose the default for any prompt, press ENTER.

   ■ To choose the defaults for all command-line entries or prompts that
     follow an entry or prompt, type a semicolon (;) after that entry or
     prompt. The semicolon should be the last character on the command line.

   The following list shows the defaults that LIB uses for
   cross-reference-listing files and output libraries:

   File               Default
   ──────────────────────────────────────────────────────────────────────────
   Cross-reference    The special file name NUL, which tells the linker not
   listing            to create a cross-reference-listing file

   Output library     The oldlib entry or the response to the "Library name"
                      prompt
   ──────────────────────────────────────────────────────────────────────────

 G.5.3  Cross-Reference-Listing Files

   A cross-reference-listing file tracks which routines are contained in a
   stand-alone library and the original object files they came from. A
   cross-reference-listing file contains the following lists:

   ■ An alphabetical list of all public symbols in the library. Each symbol
     name is followed by the name of the module in which it is defined.

   ■ A list of the modules in the library. Under each module name is an
     alphabetical listing of the public symbols defined in that module.

 G.5.4  Command Symbols

   To tell LIB what changes you want to make to a library, type a command
   symbol such as +, -, -+, *, or -*, followed immediately by a module name,
   object-file name, or library name. You can specify more than one
   operation, in any order.

   The following list shows each LIB command symbol, the type of file name to
   specify with the symbol, and what the symbol does:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
   Command                  Meaning
   ──────────────────────────────────────────────────────────────────────────
   +{objfile | lib}         Adds the given object file to the input library
                            and makes that object file the last module in the
                            library, if given with an object-file name. You
                            can use a path name for the object file name.
                            Since LIB automatically supplies the .OBJ
                            extension, you can omit the extension from the
                            object-file name.

                            If given with a library name, the plus sign (+)
                            adds the contents of that library to the input
                            library. The library name must have the .LIB
   Command                  Meaning
   ──────────────────────────────────────────────────────────────────────────
                           library. The library name must have the .LIB
                            extension.

   -module                  Deletes the given module from the input library.
                            A module name does not have a path name or an
                            extension.

   -+module                 Replaces the given module in the input library.
                            Module names have no path names and no
                            extensions. LIB deletes the given module, then
                            appends the object file that has the same name as
                            the module. The object file is assumed to have an
                            .OBJ extension and to reside in the current
                            working directory.

   *module                  Copies the given module from the library to an
                            object file in the current working directory. The
                            module remains in the library file. When LIB
                            copies the module to an object file, it adds the
   Command                  Meaning
   ──────────────────────────────────────────────────────────────────────────
                           copies the module to an object file, it adds the
                            .OBJ extension. You cannot override the .OBJ
                            extension, drive designation, or path name given
                            to the object file. However, you can later rename
                            the file or copy it to whatever location you
                            like.

   -*module                 Moves the given object module from the library to
                            an object file. This operation is equivalent to
                            copying the module to an object file, as
                            described above, then deleting the module from
                            the library.
   ──────────────────────────────────────────────────────────────────────────


   Examples

   The example below uses the replace command symbol (-+) to instruct LIB to
   replace the HEAP module in the library LANG.LIB. LIB deletes HEAP from the
   library, then appends the object file HEAP.OBJ as a new module in the
   library. The semicolon at the end of the command line tells LIB to use the
   default responses for the remaining prompts. This means that no listing
   file is created and that the changes are written to the original library
   file instead of creating a new library file.

   LIB LANG-+HEAP;

   The examples below perform the same function as the first example in this
   section, but in two separate operations, using the add (+) and delete (-)
   command symbols. The effect is the same for these examples because delete
   operations are always carried out before add operations, regardless of the
   order of the operations in the command line. This order of execution
   prevents confusion when a new version of a module replaces an old version
   in the library file.

   LIB LANG-HEAP+HEAP;

   LIB LANG+HEAP-HEAP;

   The example below causes LIB to perform a consistency check of the library
   file FOR.LIB. No other action is performed. LIB displays any consistency
   errors it finds and returns to the operating-system level.

   LIB FOR;

   The following example tells LIB to perform a consistency check on the
   library file LANG.LIB and then create the cross-reference-listing file
   LCROSS.PUB.

   LIB LANG,LCROSS.PUB

   The next example instructs LIB to move the module STUFF from the library
   FIRST.LIB to an object file called STUFF.OBJ. The module STUFF is removed
   from the library in the process. The module MORE is copied from the
   library to an object file called MORE.OBJ; the module remains in the
   library. The revised library is called SECOND.LIB. It contains all the
   modules in the library FIRST.LIB except STUFF, which was removed by using
   the move command symbol (-*). The original library, FIRST.LIB, remains
   unchanged.

   LIB FIRST -*STUFF *MORE, ,SECOND

   The contents of the response file below cause LIB to delete the module
   HEAP from the LIBFOR.LIB library file, extract (without deleting) FOIBLES
   and place it in an object file named FOIBLES.OBJ, and append the object
   files CURSOR.OBJ and HEAP.OBJ as the last two modules in the library.
   Finally, LIB creates the cross-reference-listing file CROSSLST.

   LIBFOR
   +CURSOR+HEAP-HEAP*FOIBLES
   CROSSLST

 G.5.5  LIB Options

   LIB has four options. Specify options on the command line following the
   required library-file name and preceding any commands.

   G.5.5.1  Ignoring Case for Symbols

   /I[[GNORECASE]]

   The /I option tells LIB to ignore case when comparing symbols, as LIB does
   by default. Use this option when you are combining a library that is
   marked /NOI (described below) with others that are unmarked and you want
   the new library to be unmarked.

   G.5.5.2  Ignoring Extended Dictionaries

   /NOE[[XTDICTIONARY]]

   The /NOE option tells LIB not to generate an extended dictionary. The
   extended dictionary is an extra part of the library that helps the linker
   process libraries faster.

   Use the /NOE option if you get errors U1171 or U1172, or if the extended
   dictionary causes problems with LINK. See Section G.4.6.9 for more
   information on how LINK uses the extended dictionary.

   G.5.5.3  Distinguishing Case for Symbols

   /NOI[[GNORECASE]]

   The /NOI option tells LIB not to ignore case when comparing symbols; that
   is, /NOI makes LIB case sensitive. By default, LIB ignores case. Using
   this option allows symbols that are the same except for case, such as
   SPLINE and Spline, to be put in the same library.

   Note that when you create a library with the /NOI option, LIB marks the
   library internally to indicate that /NOI is in effect. Earlier version of
   LIB did not mark libraries in this way. If you combine multiple libraries,
   and any one of them is marked /NOI, then /NOI is assumed to be in effect
   for the output library.

   G.5.5.4  Setting Page Size

   /P[[AGESIZE]]:number

   The page size of a library affects the alignment of modules stored in the
   library. Modules in the library are always aligned to start at a position
   that is a multiple of the page size (in bytes) from the beginning of the
   file. The default page size for a newly created library is 16 bytes.

   You can set a different library page size while you are creating a library
   or change the page size of an existing library by adding the following
   option after the oldlib entry on the LIB command line or after the name
   you type in response to the "Library name" prompt:

   The number specifies the new library page size. It must be an integer
   value representing a power of 2 between the values 16 and 32,768.

   The library page size determines the number of modules the library can
   hold. Thus, increasing the page size allows you to include more modules in
   the library. However, the larger the page size, the larger the amount of
   wasted storage space in the library (on the average, pagesize/2 bytes). In
   most cases you should use a small page size unless you need to put a very
   large number of modules in a library.

   The page size also determines the maximum possible size of the library.
   This limit is number * 65,536. For example, if you invoke LIB with the
   option /P:16, the library must be smaller than one megabyte (16 * 65,536
   bytes).



 ────────────────────────────────────────────────────────────────────────────
 Appendix H  Creating and Using Quick Libraries

   This appendix describes how to create and maintain libraries from within
   the QuickBASIC programming environment. A library is a file containing the
   contents of several modules under a single file name. When you finish this
   appendix you will know how to:

   ■ Make libraries from within the QuickBASIC environment

   ■ Load a Quick library when running a QuickBASIC program

   ■ View the contents of a Quick library

   ■ Add routines written in other languages to a Quick library


 H.1  Types of Libraries

   QuickBASIC provides tools for creating two different types of libraries,
   which are identified by different file-name extensions:

   Extension                Function
   ──────────────────────────────────────────────────────────────────────────
   .QLB                     The .QLB extension characterizes a Quick library,
                            a special kind of library that permits easy
                            addition of frequently used procedures to your
                            programs. A Quick library can contain procedures
                            written in QuickBASIC or other Microsoft
                            languages such as Microsoft C.

   .LIB                     The .LIB extension characterizes a stand-alone
                            (.LIB) library, one that is created with the
                            Microsoft Library Manager, LIB. When QuickBASIC
                            makes a Quick library, it simultaneously creates
                            a .LIB library containing the same procedures in
                            a somewhat different form.
   ──────────────────────────────────────────────────────────────────────────

   You can generate both types of libraries from within the programming
   environment or from the command line. You can think of a Quick library as
   a group of procedures appended to QuickBASIC when the library is loaded
   with QuickBASIC. Libraries with the .LIB extension are essentially
   independent, compiled procedures. They can either be added to a Quick
   library or linked with a main module to create a file that is executable
   from the DOS command line.

   This appendix discusses the use of command-line utilities for some common
   cases, but you should refer to Appendix G, "Compiling and Linking from
   DOS," for a full explanation of using those utilities.


 H.2  Advantages of Quick Libraries

   Quick libraries facilitate program development and maintenance. As
   development progresses on a project and modules become stable components
   of your program, you can add them to a Quick library, then set aside the
   source files for the original modules until you want to improve or
   maintain those source files. Thereafter you can load the library along
   with QuickBASIC, and your program has instant access to all procedures in
   the library.

   Procedures in a Quick library behave like QuickBASIC's own statements. If
   properly declared, a SUB procedure in a Quick library can even be invoked
   without a CALL statement. See Chapter 2, "SUB and FUNCTION Procedures,"
   for more information on calling a SUB procedure with or without the CALL
   keyword.

   Procedures in a Quick library can be executed directly from the Immediate
   window, just like BASIC statements. This means that you can test their
   effects before using them in other programs.

   If you codevelop programs with others, Quick libraries make it easy to
   update a pool of common procedures. If you wish to offer a library of
   original procedures for commercial distribution, all QuickBASIC
   programmers will be able to use them immediately to enhance their own
   work. You could leave your custom Quick library on a bulletin board for
   others to try before purchasing. Because Quick libraries contain no source
   code and can only be used within the QuickBASIC programming environment,
   your proprietary interests are protected while your marketing goals are
   advanced.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Quick libraries have the same function as user libraries in QuickBASIC
     Versions 2.0 and 3.0. However, you cannot load a user library as a Quick
     library. You must recreate the library from the original source code, as
     described below.
   ──────────────────────────────────────────────────────────────────────────


 H.3  Creating a Quick Library

   A Quick library automatically contains all modules, both main and nonmain,
   present in the QuickBASIC environment when you create the new library. It
   also contains the contents of any other Quick library that you loaded when
   starting QuickBASIC. If you load a whole program but only want certain
   modules to be put in the library, you must explicitly unload those you
   don't want. You can unload modules with the File menu's Unload File
   command.

   You can quickly determine which modules are loaded by checking the list
   box of the SUBs command on the View menu. However, this method does not
   show which procedures a loaded library contains. The QLBDUMP.BAS utility
   program, described in Section H.4.3, "Viewing the Contents of a Quick
   Library," allows you to list all the procedures in a library.

   Only whole modules can be put into a library. That is, you cannot select
   one procedure from among many in a module. If you want to enter only
   certain procedures from a module, put the procedures you want in a
   separate module, then put that module into a library.

   A Quick library must be self-contained. A procedure in a Quick library can
   only call other procedures within the same Quick library. Procedure names
   must be unique within the library.

   With large programs, you can reduce loading time by putting as many
   routines as possible in Quick libraries. Putting many routines in Quick
   libraries is also an advantage if you plan to make the program into a
   stand-alone executable file later, since the contents of libraries are
   simply linked without recompiling.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     Your main module may or may not contain procedures. If it does and you
     incorporate those procedures in the library, the entire main module goes
     in the library, too. This does not cause an error message, but the
     module-level code in the library can never be executed unless one of its
     procedures contains a routine (such as ON ERROR) that explicitly passes
     control to the module level. Even if that is the case, much of the
     module-level code may be extraneous. If you organize your procedures in
     modules that are frequently used together, your Quick libraries are
     likely to be less cluttered with useless code.
   ──────────────────────────────────────────────────────────────────────────

 H.3.1  Files Needed to Create a Quick Library

   To create a Quick library, make sure that the proper files are available
   before you begin. If you don't have a hard disk, you should keep your
   files and the other programs on several floppy disks. QuickBASIC prompts
   you for a path name when it cannot find a file; when this happens, insert
   the correct disk and respond to the prompt.

   Make sure that the following files are in the current working directory or
   accessible to QuickBASIC through the appropriate DOS environment
   variables:

   File                     Purpose
   ──────────────────────────────────────────────────────────────────────────
   QB.EXE                   Directs the process of creating a Quick library.
                            If you are working only with QuickBASIC modules,
                            you can do everything in one step from within the
                            QuickBASIC environment.

   BC.EXE                   Creates object files from source code.

   LINK.EXE                 Links object files.

   LIB.EXE                  Manages stand-alone libraries of object modules.

   BQLB45.LIB               Supplies routines needed by your Quick library.
                            This library is a stand-alone library that is
                            linked with objects in your library to form a
                            Quick library.
   ──────────────────────────────────────────────────────────────────────────

 H.3.2  Making a Quick Library

   Most of the time you create Quick libraries from within the QuickBASIC
   environment. Occasionally, you may want to update a library or include
   routines from other Microsoft languages in your Quick library. In these
   cases, begin by constructing a base library of the non-BASIC routines from
   outside the environment by invoking LINK and LIB directly. Then you can
   add the most current QuickBASIC modules from within QuickBASIC.

 H.3.3  Making a Quick Library from within the Environment

   When making a library from within the QuickBASIC environment, the first
   consideration is whether the library to be made is totally new or an
   update of an existing library. If it is to be an update, you should start
   QuickBASIC with the /L command-line option, supplying the name of the
   library to be updated as a command-line argument. At the same time, you
   can also include the name of a program whose modules you want to put in
   the library. In this case QuickBASIC loads all the modules specified in
   that program's .MAK file.

   H.3.3.1  Unloading Unwanted Files

   If you load your program when starting QuickBASIC, be sure to unload any
   modules you don't want in the Quick library, including the main module
   (unless it contains procedures you want in the library).

   Follow these steps to unload modules:

   1. Choose the Unload File command from the File menu.

   2. Select the module you want to unload from the list box, then press
      ENTER.

   3. Repeat steps 1 and 2 until you have unloaded all unwanted modules.

   H.3.3.2  Loading Desired Files

   Alternatively, you can simply start QuickBASIC, with or without a library
   specification, and load the modules you want one at a time from within the
   environment. In this case, you load each module using the Load File
   command from the File menu.

   To load one module at a time with QuickBASIC:

   1. Choose the File menu's Load File command.

   2. Select the name of a module you want to load from the list box.

   3. Repeat steps 1 and 2 until all you have loaded all the modules you
      want.

   H.3.3.3  Creating a Quick Library

   Once you have loaded the previous library (if any) and all the new modules
   you want to include in the Quick library, choose the Make Library command
   from the Run menu. The dialog box shown in Figure H.1 appears.


                              Type Quick-library file name here.
                                │
   ┌────────────────────────────┼─Make Library───────────────────────────┐
   │                          ┌─┼─────────────────────────────────────┐  │
   │ Quick-Library File Name: │                                       │  │
   │                          └───────────────────────────────────────┘  │
   │ [X] Produce Debug Code                                              │
   ├─────────────────────────────────────────────────────────────────────┤
   │ < Make Library >   <Make Library and Exit >   < Cancel >   < Help > │
   └───────────────────────────────┼─────────────────────────────────────┘
                                   │
                                   │Makes a library
                                    and exits to DOS

   Figure H.1 Make Library Dialog Box

   To create a Quick library, perform the following steps:

   1. Enter the name of the library you wish to create in the Quick-Library
      File Name text box.

      If you enter only a base name (that is, a file name with no extension),
      QuickBASIC automatically appends the extension .QLB when it creates the
      library. If you want your library to have no extension, add a
      terminating period (.) to the base name. Otherwise, you may enter any
      base name and extension you like (except the name of a loaded Quick
      library), consistent with DOS file-name rules.

   2. Select the Produce Debug Code check box only if you are specifically
      trying to track a bug you believe to be in a library that you are
      updating. It makes your library larger, slows program execution and
      gives only a small amount of error control, mostly in regard to
      checking of array bounds.

   3. Create the Quick library:

      ■ Choose the Make Library command button if you want to remain in the
        environment after the Quick library is created.

      ■ Choose the Make Library and Exit command button if you want to return
        to the DOS command level after the Quick library is created.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     When you make a Quick library, be aware that if it is ever to be used
     with a nonlibrary module that needs to trap events such as keystrokes,
     then one of the modules in the library must contain at least one
     event-trapping statement. This statement can be as simple as TIMER OFF,
     but without it events are not trapped correctly in the Quick library.
   ──────────────────────────────────────────────────────────────────────────


 H.4  Using Quick Libraries

   This section explains how to load a Quick library when you start
   QuickBASIC and how to view the contents of a Quick library. It also gives
   facts that you should remember when procedures within a Quick library
   perform floating-point arithmetic.

 H.4.1  Loading a Quick Library

   To load a Quick library, you must specify the name of the desired library
   on the command line when you start QuickBASIC using the following syntax:

   QB[[programname]] /L [[libraryname]]

   If you start QuickBASIC with the /L option and supply the name of a
   library (libraryname), QuickBASIC loads the specified library and places
   you in the programming environment. The contents of the library are now
   available for use. If you start QuickBASIC with the /L option but don't
   specify a library, QuickBASIC loads the library QB.QLB (see Section H.5).

   You can also start QuickBASIC with the /RUN option followed by both a
   program name (programname) and the /L option. In this case, QuickBASIC
   loads both the program and the specified Quick library, then runs the
   program without stopping at the programming environment.

   ──────────────────────────────────────────────────────────────────────────
   NOTE
     When using Quick libraries to represent program modules, remember to
     update the .MAK file to keep it consistent with the modules in the
     evolving program. (This is done with the Unload File command from the
     File menu.) If the .MAK file is not up to date, it may cause QuickBASIC
     to load a module containing a procedure definition with the same name as
     one defined in the Quick library, which in turn causes the error message
     Duplicate definition.
   ──────────────────────────────────────────────────────────────────────────

   You can load only one Quick library at a time. If you specify a path,
   QuickBASIC looks where you indicate; otherwise, QuickBASIC searches for
   the Quick library in the following three locations:

   1. The current directory.

   2. The path specified for libraries by the Set Paths command.

   3. The path specified by the LIB environment variable. (See your DOS
      documentation for information about environment variables.)

   Example

   The following command starts QuickBASIC and runs the program REPORT.BAS
   using the routines in the library FIGS.QLB:

   QB /RUN REPORT.BAS /L FIGS.QLB

 H.4.2  Floating-Point Arithmetic in Quick Libraries

   BASIC procedures within Quick libraries represent code compiled with the
   BC command-line compiler. These procedures share significant
   characteristics with executable files. For example, both executable files
   and Quick libraries perform floating-point arithmetic faster and with a
   higher degree of accuracy than the same calculations performed within the
   QuickBASIC environment. For more information, see Chapter 16, "The Run
   Menu," in Learning to Use Microsoft QuickBASIC.

 H.4.3  Viewing the Contents of a Quick Library

   Because a Quick library is essentially a binary file, you cannot view its
   contents with a text editor to find out what it contains. Your
   distribution disk includes the QLBDUMP.BAS utility, which allows you to
   list all the procedures and data symbols in a given library. Follow these
   steps to view the contents of a Quick library:

   1. Start QuickBASIC.

   2. Load and run QLBDUMP.BAS.

   3. Enter the name of the Quick library you wish to examine in response to
      the prompt. You do not need to include the .QLB extension when you type
      the file name; however, supplying the extension does no harm.

      If the specified file exists and it is a Quick library, the program
      displays a list of all the symbol names in the library. In this
      context, symbol names correspond to the names of procedures in the
      library.

   See Chapter 3, "File and Device I/O," for a commented listing of
   QLBDUMP.BAS.


 H.5  The Supplied Library (QB.QLB)

   If you invoke QuickBASIC with the /L option, but do not supply a Quick
   library name, QuickBASIC automatically loads a library named QB.QLB,
   included with the QuickBASIC package. This file contains three routines,
   INTERRUPT, INT86OLD, and ABSOLUTE, that provide software-interrupt support
   for system-service calls and support for CALL ABSOLUTE. To use the
   routines in QB.QLB, you must specify it (or another library into which
   those routines have been incorporated) on the command line when you invoke
   QuickBASIC. If you wish to use these routines along with other routines
   that you have placed in libraries, make a copy of the QB.QLB library and
   use it as a basis for building a library containing all the routines you
   need.


 H.6  The .QLB File-Name Extension

   The extension .QLB is just a convenient convention. You can use any
   extension for your Quick library files, or no extension at all. However,
   in processing the /L libraryname option, QuickBASIC assumes that the
   listed libraryname has the .QLB extension if no other extension is
   specified. If your Quick library has no extension, you must put a period
   after the Quick-library name (libraryname.) or QuickBASIC searches for a
   file with your base name and the .QLB extension.


 H.7  Making a Library from the Command Line

   After making a library from within the QuickBASIC environment, you will
   notice the appearance of extra files with the extensions .OBJ and .LIB. In
   creating Quick libraries, QuickBASIC actually directs the work of three
   other programs, BC, LINK, and LIB, and then combines what they produce
   into both a Quick library and a stand-alone (.LIB) library. Once the
   process is complete, there is one object (.OBJ) file for each module in
   your Quick library and a single library (.LIB) file containing an object
   module for each object file. The files with the extension .OBJ are now
   extraneous and can be deleted. However, files with the extension .LIB are
   very important and should be preserved. These parallel libraries are the
   files QuickBASIC uses to create executable files of your programs.

   You can use the programs LINK and LIB to create both Quick libraries and
   stand-alone (.LIB) libraries from the command line in batch mode. If you
   want to use routines originally written and compiled in other languages in
   QuickBASIC, you must first put the other-language routines in a Quick
   library via the command line. Once the other-language routines are in the
   library, you can incorporate your BASIC modules from the command line or
   from within the QuickBASIC environment.

   Professional software developers should be sure to deliver both the Quick
   (.QLB) and stand-alone (.LIB) versions of libraries to customers. Without
   the .LIB libraries, end users would not be able to use your library
   routines in executable files produced with QuickBASIC.

   When you create a Quick library using LINK, the library BQLB45.LIB must
   always be specified after the third comma on the LINK command line or in
   response to the "Libraries" prompt.


 H.8  Using Routines from Other Languages in a Quick Library

   To place routines from other languages in a Quick library, you must start
   with precompiled or preassembled object files that contain the
   other-language routines you wish to use. Several other languages are
   suitable for this purpose, including Microsoft C, Microsoft Macro
   Assembler, Microsoft Pascal, Microsoft FORTRAN, and any other language
   that creates object files compatible with the Microsoft language family.

 H.8.1  Building a Quick Library

   The following is a typical scenario for building a Quick library
   containing routines from other languages:

   1. Suppose you begin with three modules, created in FORTRAN, C, and Macro
      Assembler. First you compile or assemble each module with the proper
      language translator to produce object files called here FOR.OBJ, C.OBJ,
      and ASM.OBJ.

   2. You then link the object files with the LINK option /Q, which instructs
      the linker to produce a Quick library file, as shown in the following
      command line:

      LINK /Q FOR.OBJ C.OBJ ASM.OBJ, MIXED.QLB,,BQLB45.LIB;

      The linker interprets the entry that follows the names of the object
      files (in this case MIXED.QLB) as the file name by which the linked
      modules will be known. Thus, in this case, the Quick library file is
      named MIXED.QLB.

   3. Now create a parallel .LIB library, using the same object files you
      just used to make the Quick library. In this case the first name
      following the LIB command is the name of the .LIB library:

      LIB MIXED.LIB+FOR.OBJ+C.OBJ+ASM.OBJ;

      It is easy to overlook this step when making a library that contains
      other-language routines, but this step is crucial if you hope to use
      the library to create a stand-alone executable file. Without these
      parallel stand-alone (.LIB) libraries, QuickBASIC cannot create an
      executable file containing their routines.

   4. With the other-language routines now in a Quick library and the
      original object files in a stand-alone library having the same base
      name, you can return to the QuickBASIC environment and build as many
      BASIC modules into the library as available memory permits.

   See Appendix G, "Compiling and Linking from DOS," for a complete
   description of the features of LINK and LIB.

 H.8.2  Quick Libraries with Leading Zeros in the First Code Segment

   A Quick library containing leading zeros in the first code segment is
   invalid, causing the message Error in loading file filename - Invalid
   format when you try to load it in QuickBASIC. For example, this can occur
   if an assembly-language routine puts data that is initialized to zero in
   the first code segment and it is subsequently listed first on the LINK
   command line when you make a Quick library. If you have this problem, do
   one of the following two things:

   1. Link with a BASIC module first on the LINK command line.

   2. Make sure that, in whatever module comes first on the LINK command
      line, the first code segment starts with a nonzero byte.

 H.8.3  The B_OnExit Routine

   QuickBASIC provides a BASIC system-level function, B_OnExit. You can use
   B_OnExit when your other-language routines take special actions that need
   to be undone before leaving the program (intentionally or otherwise) or
   rerunning the program. For example, within the QuickBASIC environment, an
   executing program that calls other-language routines in a Quick library
   may not always run to normal termination. If such routines need to take
   special actions at termination (for example, deinstallation of previously
   installed interrupt vectors), you can guarantee that your termination
   routines will always be called if you include an invocation of B_OnExit in
   the routine. The following example illustrates such a call (for
   simplicity, the example omits error-handling code). Note that such a
   function would be compiled in C in large model.

   #include <malloc.h>

   extern pascal far B_OnExit();  /* Declare the routine   */

   int *p_IntArray;

   void InitProc()
   {
      void TermProc();     /* Declare TermProc function    */

      /* Allocate far space for 20-integer array:          */

      p_IntArray = (int *)malloc(20*sizeof(int));

      /* Log termination routine (TermProc) with BASIC:    */

      B_OnExit(TermProc);
   }

                          /* The TermProc function is      */
   void TermProc()        /* called before any restarting  */
   {                      /* or termination of program.    */

      free(p_IntArray);   /* Release far space allocated   */
   }                      /* previously by InitProc.       */

   If the InitProc function were in a Quick library, the call to B_OnExit
   would insure proper release of the space reserved in the call to malloc,
   should the program crash. The routine could be called several times, since
   the program can be executed several times from the QuickBASIC environment.
   However, the TermProc function itself would be called only once each time
   the program runs.

   The following BASIC program is an example of a call to the InitProc
   function:

   DECLARE SUB InitProc CDECL

   X = SETMEM(-2048)       ' Make room for the malloc memory
                           ' allocation in C function.
   CALL InitProc
   END

   If more than 32 routines are registered, B_OnExit returns NULL, indicating
   there is not enough space to register the current routine. (Note that
   B_OnExit has the same return values as the Microsoft C run-time-library
   routine onexit.)

   B_OnExit can be used with any other-language (including assembly-language)
   routines you place in a Quick library. With programs compiled and linked
   completely from the command line, B_OnExit is optional.


 H.9  Memory Considerations with Quick Libraries

   Because a Quick library is essentially an executable file (although it
   cannot be invoked by itself from the DOS command line), it is quite large
   in comparison to the sum of the sizes of its source files. This puts an
   upper limit on the number of routines you can put in a Quick library. To
   determine how large your Quick library can be, add up the memory required
   for DOS, QB.EXE, and your program's main module. An easy way to estimate
   these factors is to boot your machine, start QuickBASIC with your program,
   and enter this command in the Immediate window:

   PRINT FRE (-1)

   This command shows you the number of bytes of free memory. This indicates
   the maximum size for any Quick library associated with this program. In
   most cases the amount of memory required for a Quick library is about the
   same as the size of its disk file. One exception to this rule of thumb is
   a library with procedures that use a lot of strings; such a program may
   require somewhat more memory.


 H.10  Making Compact Executable Files

   As discussed above, when QuickBASIC creates a Quick library, it also
   creates a stand-alone (.LIB) library of object modules in which each
   object module corresponds to one of the modules in the Quick library. When
   you make an executable file, QuickBASIC searches the stand-alone (.LIB)
   library for object modules containing the procedures referenced in the
   program.

   If an object module in the library does not contain procedures referenced
   in the program, it is not included in the executable file. However, a
   single module may contain many procedures, and if even one of them is
   referenced in the program all are included in the executable file.
   Therefore, even if a program uses only one of four procedures in a certain
   module, that entire module becomes part of the final executable file.

   To make your executable files as compact as possible, you should maintain
   a library in which each module contains only closely related procedures.
   If you have any doubts about what a library contains, list its contents
   with the utility QLBDUMP.BAS, described in Section H.4.3, "Viewing the
   Contents of a Quick Library."



 ────────────────────────────────────────────────────────────────────────────
 Appendix I  Error Messages

   During development of a BASIC program with QuickBASIC, the following types
   of errors can occur:

   ■ Invocation errors

   ■ Compile-time errors

   ■ Link-time errors

   ■ Run-time errors

   Each type of error is associated with a particular step in the program
   development process. Invocation errors occur when you invoke QuickBASIC
   with the QB or BC commands. Compile-time errors (and warnings) occur
   during compilation, and run-time errors occur when the program is
   executing. Link-time errors occur only when you use the LINK command to
   link object files created with BC or other language compilers.

   Section I.2 lists alphabetically the invocation, compile-time, and
   run-time error messages, along with any error codes that are assigned.
   Table I.1 lists the run-time error messages and error codes in numerical
   order. Section I.3 lists the Microsoft Overlay Linker error messages, and
   Section I.4, the Microsoft Library Manager error messages.


 I.1  Error-Message Display

   When a run-time error occurs within the QuickBASIC environment (with
   default screen options), the error message appears in a dialog box and the
   cursor is placed on the line where the error occurred.

   In stand-alone executable programs (that is, programs that are executed by
   entering the base name of the executable file at the system prompt), the
   run-time system prints the error messages followed by an address, unless
   the /D, /E, or /W option is specified on the BC command line. In those
   cases, the error message is followed by the number of the line in which
   the error occurred. The standard forms of this type of error message are
   as follows:

   Error n in module module-name at address segment:offset

   and

   Error n in line linenumber of module module-name at
   address segment:offset

   An ERR code is listed for some errors. If an error occurs, the value
   returned by ERR is set to the appropriate code when an error-trapping
   subroutine is entered. (Error-trapping routines are entered via the ON
   ERROR statement.) The ERR value remains unchanged until a RESUME statement
   returns control to the main program. See Chapter 6, "Error and Event
   Trapping," for more information.

   Table I.1 lists the error codes in numerical order. See the alphabetical
   listing for explanations of the errors.

   Table I.1  Run-Time Error Codes
╓┌─┌────────┌───────────────────────────┌────────┌───────────────────────────╖
   Code     Description                 Code     Description
   ──────────────────────────────────────────────────────────────────────────
   2        Syntax error                53       File not found

   3        RETURN without GOSUB        54       Bad file mode

   4        Out of DATA                 55       File already open

   5        Illegal function call       56       FIELD statement active

   6        Overflow                    57       Device I/O error
   Code     Description                 Code     Description
   ──────────────────────────────────────────────────────────────────────────
  6        Overflow                    57       Device I/O error

   7        Out of memory               58       File already exists

   9        Subscript out of range      59       Bad record length

   10       Duplicate definition        61       Disk full

   11       Division by zero            62       Input past end of file

   13       Type mismatch               63       Bad record number

   14       Out of string space         64       Bad file name

   16       String formula too complex  67       Too many files

   19       No RESUME                   68       Device unavailable

   20       RESUME without error        69       Communication-buffer
   Code     Description                 Code     Description
   ──────────────────────────────────────────────────────────────────────────
  20       RESUME without error        69       Communication-buffer
                                                 overflow

   24       Device timeout              70       Permission denied

   25       Device fault                71       Disk not ready

   27       Out of paper                72       Disk-media error

   39       CASE ELSE expected          73       Advanced feature unavailable

   40       Variable required           74       Rename across disks

   50       FIELD overflow              75       Path/File access error

   51       Internal error              76       Path not found

   52       Bad file name or number
   ──────────────────────────────────────────────────────────────────────────
   Code     Description                 Code     Description
   ──────────────────────────────────────────────────────────────────────────
  ──────────────────────────────────────────────────────────────────────────



 I.2  Invocation, Compile-Time, and Run-Time Error Messages

 Advanced feature unavailable

   You are attempting to use a feature of QuickBASIC that is available with
   another version of BASIC, or supported only under a later version of DOS.
   (Compile-time or run-time error)

   ERR code: 73

 Argument-count mismatch

   You are using an incorrect number of arguments with a BASIC subprogram or
   function. (Compile-time error)

 Array already dimensioned

   This error can be caused by any of the following:

   ■ More than one DIM statement for the same static array.

   ■ A DIM statement after the initial use of an array. Dynamic arrays must
     be deallocated with the ERASE statement before they can be redimensioned
     with DIM; dynamic arrays may also be redimensioned with the REDIM
     statement.

   ■ An OPTION BASE statement that occurs after an array is dimensioned.

   (Compile-time or run-time error)

 Array not defined

   An array is referenced but never defined. (Compile-time error)

 Array not dimensioned

   An array is referenced but not dimensioned. If you are compiling the
   program with BC, this error is not "fatal"; the program will execute,
   although program results may be incorrect. (Compile-time warning)

 Array too big

   There is not enough user data space to accommodate the array declaration.
   Reduce the size of the array or use the $DYNAMIC metacommand. You may also
   get this error if the array size exceeds 64K, the array is not dynamic,
   and the /AH option is not used. Reduce the size of the array, or make the
   array dynamic and use the /AH command-line option. (Compile-time error)

 AS clause required

   A variable declared with an AS clause is referenced without one. If the
   first declaration of a variable has an AS clause, every subsequent DIM,
   REDIM, SHARED, and COMMON statement that references that variable must
   have an AS clause. (Compile-time error)

 AS clause required on first declaration

   A variable that has not been declared using an AS clause is being
   referenced with an AS clause. (Compile-time error)

 AS missing

   The compiler expects an AS keyword, as in OPEN "FILENAME" FOR INPUT AS #1.
   (Compile-time error)

 Asterisk missing

   The asterisk is missing from a string definition in a user type.
   (Compile-time error)

 Bad file mode

   This error occurs in the following situations:

   ■ The program tries to use PUT or GET with a sequential file or execute an
     OPEN statement with a file mode other than I, O, or R.

   ■ The program tries to use a FIELD statement with a file not opened for
     random access.

   ■ The program tries to print to a file opened for input.

   ■ The program tries to read from a file opened for output or appending.

   ■ QuickBASIC tries to use an include file previously saved in compressed
     format. Include files must be saved in text format. Reload the include
     file, save it in text format, then try to run the program again.

   ■ You try to load a corrupt binary program.

   (Run-time error)

   ERR code: 54

 Bad file name

   An illegal form is used for the file name with LOAD, SAVE, KILL, or OPEN
   (for example, the file name has too many characters). (Run-time error)

   ERR code: 64

 Bad file name or number

   A statement or command references a file with a file name or number that
   is not specified in the OPEN statement or is out of the range of file
   numbers specified earlier in the program. (Run-time error)

   ERR code: 52

 Bad record length

   A GET or PUT statement that specified a record variable whose length did
   not match the record length specified in the corresponding OPEN statement
   was executed. (Run-time error)

   ERR code: 59

 Bad record number

   In a PUT or GET statement, the record number is less than or equal to
   zero. (Run-time error)

   ERR code: 63

 BASE missing

   QuickBASIC expected the keyword BASE here, as in OPTION BASE.
   (Compile-time error)

 Binary source file

   The file you have attempted to compile is not an ASCII file. All source
   files saved by BASICA should be saved with the ,A option. QuickBASIC also
   uses this message to warn you when you try to use the /ZI or /ZD CodeView
   options with binary source files. (Compile-time error)

 Block IF without END IF

   There is no corresponding END IF in a block IF construct. (Compile-time
   error)

 Buffer size expected after /C:

   You must specify a buffer size after the /C option. (BC invocation error)

 BYVAL allowed only with numeric arguments

   BYVAL does not accept string or record arguments. (Compile-time error)

 /C: buffer size too large

   The maximum size of the communications buffer is 32,767 bytes. (BC
   invocation error)

 Cannot continue

   While debugging, you have made a change that prevents execution from
   continuing. (Run-time error)

 Cannot find file (filename). Input path:

   This error occurs when QuickBASIC cannot find a Quick library or utility
   (BC.EXE, LINK.EXE, LIB.EXE, or QB.EXE) required by the program. Enter the
   correct path name, or press CTRL+C to return to the DOS prompt. (QB
   invocation error)

 Cannot generate listing for BASIC binary source files

   You are attempting to compile a binary source file with the BC command and
   the /A option. Recompile without the /A option. (BC invocation error)

 Cannot start with `FN'

   You used "FN" as the first two letters of a subprogram or variable name.
   "FN" can only be used as the first two letters when calling a DEF FN
   function. (Compile-time error)

 CASE ELSE expected

   No matching case was found for an expression in a SELECT CASE statement.
   (Run-time error)

   ERR code: 39

 CASE without SELECT

   The first part of a SELECT CASE statement is missing or misspelled.
   (Compile-time error)

 Colon expected after /C

   A colon is required between the option and the buffer size argument. (BC
   invocation error)

 Comma missing

   QuickBASIC expects a comma. (Compile-time error)

 COMMON and DECLARE must precede executable statements

   A COMMON statement or a DECLARE statement is misplaced. COMMON and DECLARE
   statements must appear before any executable statements. All BASIC
   statements are executable except the following:

   ■ COMMON

   ■ DEFtype

   ■ DIM (for static arrays)

   ■ OPTION BASE

   ■ REM

   ■ TYPE

   ■ All metacommands

   (Compile-time error)

 COMMON in Quick library too small

   More common variables are specified in the module than in the currently
   loaded Quick library. (Compile-time error)

 COMMON name illegal

   QuickBASIC encountered an illegal /blockname/ specification (for example,
   a blockname that is a BASIC reserved word) in a named COMMON block.
   (Compile-time error).

 Communication-buffer overflow

   During remote communications, the receive buffer overflowed. The size of
   the receive buffer is set by the /C command line option or the RB option
   in the OPEN COM statement. Try checking the buffer more frequently (with
   the LOC function) or emptying it more often (with the INPUT$ function).
   (Run-time error)

   ERR code: 69

 CONST/DIM SHARED follows SUB/FUNCTION

   CONST and DIM SHARED statements should appear before any subprogram or
   FUNCTION procedure definitions. If you are compiling your program with BC,
   this error is not "fatal"; the program will execute, although the results
   may be incorrect. (Compile-time warning)

 Control structure in IF...THEN...ELSE incomplete

   An unmatched NEXT, WEND, END IF, END SELECT, or LOOP statement appears in
   a single-line IF...THEN...ELSE statement. (Compile-time error)

 Data-memory overflow

   There is too much program data to fit in memory. This error is often
   caused by too many constants, or too much static array data. If you are
   using the BC command, or the Make EXE File or Make Library commands, try
   turning off any debugging options. If memory is still exhausted, break
   your program into parts and use the CHAIN statement or use the $DYNAMIC
   metacommand. (Compile-time error)

 DECLARE required

   An implicit SUB or FUNCTION procedure call appears before the procedure
   definition. (An implicit call does not use the CALL statement.) All
   procedures must be defined or declared before they are implicitly called.
   (Compile-time error)

 DEF FN not allowed in control statements

   DEF FN function definitions are not permitted inside control constructs
   such as IF...THEN...ELSE and SELECT CASE. (Compile-time error)

 DEF without END DEF

   There is no corresponding END DEF in a multiline function definition.
   (Compile-time error)

 DEFtype character specification illegal

   A DEFtype statement is entered incorrectly. DEF can only be followed by
   LNG, DBL, INT, SNG, STR, or (for user-defined functions) a blank space.
   (Compile-time error)

 Device fault

   A device has returned a hardware error. If this message occurs while data
   are being transmitted to a communications file, it indicates that the
   signals being tested with the OPEN COM statement were not found in the
   specified period of time. (Run-time error)

   ERR code: 25

 Device I/O error

   An I/O error occurred on a device I/O operation. The operating system
   cannot recover from the error. (Run-time error)

   ERR code: 57

 Device timeout

   The program did not receive information from an I/O device within a
   predetermined amount of time. (Run-time error)

   ERR code: 24

 Device unavailable

   The device you are attempting to access is not on line or does not exist.

   (Run-time error)

   ERR code: 68

 Disk full

   There is not enough room on the disk for the completion of a PRINT, WRITE,
   or CLOSE operation. This error can also occur if there is not enough room
   for QuickBASIC to write out an object or executable file. (Run-time error)

   ERR code: 61

 Disk-media error

   Disk-drive hardware has detected a physical flaw on the disk. (Run-time
   error)

   ERR code: 72

 Disk not ready

   The disk-drive door is open, or no disk is in the drive. (Run-time error)

   ERR code: 71

 Division by zero

   A division by zero is encountered in an expression, or an exponentiation
   operation results in zero being raised to a negative power. (Compile-time
   or run-time error)

   ERR code: 11

 DO without LOOP

   The terminating LOOP clause is missing from a DO...LOOP statement.
   (Compile-time error)

 Document too large

   Your document exceeds QuickBASIC's internal limit. Divide the document
   into separate files.

 Duplicate definition

   You are using an identifier that has already been defined. For example,
   you are attempting to use the same name in a CONST statement and as a
   variable definition, or the same name for a procedure and a variable.

   This error also occurs if you attempt to redimension an array. You must
   use DIM or REDIM when redimensioning dynamic arrays. (Compile-time or
   run-time error)

   ERR code: 10

 Duplicate label

   Two program lines are assigned the same number or label. Each line number
   or label in a module must be unique. (Compile-time error)

 Dynamic array element illegal

   Dynamic array elements are not allowed with VARPTR$. (Compile-time error)

 Element not defined

   A user-defined type element is referenced but not defined. For example, if
   the user-defined type MYTYPE contained elements A, B, and C, then an
   attempt to use the variable D as an element of MYTYPE would cause this
   message to appear. (Compile-time error)

 ELSE without IF

   An ELSE clause appears without a corresponding IF. Sometimes this error is
   caused by incorrectly nested IF statements. (Compile-time error)

 ELSEIF without IF

   An ELSEIF statement appears without a corresponding IF. Sometimes this
   error is caused by incorrectly nested IF statements. (Compile-time error)

 END DEF without DEF

   An END DEF statement has no corresponding DEF statement. (Compile-time
   error)

 END IF without block IF

   The beginning of an IF block is missing. (Compile-time error)

 END SELECT without SELECT

   The end of a SELECT CASE statement appears without a beginning SELECT
   CASE. The beginning of the SELECT CASE statement may be missing or
   misspelled. (Compile-time error)

 END SUB or END FUNCTION must be last line in window

   You are attempting to add code after a procedure. You must either return
   to the main module or open another module. (Compile-time error)

 END SUB/FUNCTION without SUB/FUNCTION

   You deleted the SUB or FUNCTION statement. (Compile-time error)

 END TYPE without TYPE

   An END TYPE statement is used outside a TYPE declaration. (Compile-time
   error)

 Equal sign missing

   QuickBASIC expects an equal sign. (Compile-time error)

 Error during QuickBASIC initialization

   Several conditions can cause this error. It is most commonly caused when
   there is not enough memory in the machine to load QuickBASIC. If you are
   loading a Quick library, try reducing the size of the library.

   This error may occur when you attempt to use QuickBASIC on unsupported
   hardware. (QB invocation error)

 Error in loading file (filename)──Cannot find file

   This error occurs when redirecting input to QuickBASIC from a file. The
   input file is not at the location specified on the command line. (QB
   invocation error)

 Error in loading file (filename)──Disk I/O error

   This error is caused by physical problems accessing the disk, for example,
   if the drive door is left open. (QB invocation error)

 Error in loading file (filename)──DOS memory-area error

   The area of memory used by DOS has been written to, either by an assembly
   language routine or with the POKE statement. (QB invocation error)

 Error in loading file (filename)──Invalid format

   You are attempting to load a Quick library that is not in the correct
   format. This error can occur if you are attempting to use a Quick library
   created with a previous version of QuickBASIC, if you are trying to use a
   file that has not been processed with QuickBASIC's Make Library command or
   the /QU option from LINK, or if you are trying to load a stand-alone
   (.LIB) library with QuickBASIC. (QB invocation error)

 Error in loading file (filename)──Out of memory

   More memory is required than is available. For example, there may not be
   enough memory to allocate a file buffer. Try reducing the size of your DOS
   buffers, getting rid of any terminate-and-stay resident programs, or
   eliminating some device drivers. If you have large arrays, try placing a
   $DYNAMIC metacommand at the top of your program. If you have documents
   loaded, then unloading them will free some memory. (Run-time error)

 EXIT DO not within DO...LOOP

   An EXIT DO statement is used outside of a DO...LOOP statement.
   (Compile-time error)

 EXIT not within FOR...NEXT

   An EXIT FOR statement is used outside of a FOR...NEXT statement.
   (Compile-time error)

 Expected: item

   This is a syntax error. The cursor is positioned at the unexpected item.
   (Compile-time error)

 Expression too complex

   This error is caused when certain internal limitations are exceeded. For
   example, during expression evaluation, strings that are not associated
   with variables are assigned temporary locations. A large number of such
   strings can cause this error to occur. Try simplifying expressions, and
   assigning strings to variables. (Compile-time error)

 Extra file name ignored

   You specified too many files on the command line; the last file name on
   the line is ignored. (BC invocation error)

 Far heap corrupt

   The far-heap memory has been corrupted by one of the following:

   ■ The QB compiler does not support a terminate-and-stay-resident program
     resident in DOS.

   ■ The POKE statement modified areas of memory used by QuickBASIC. (This
     may modify the descriptor for a dynamic array of numbers or fixed-length
     strings.)

   ■ The program called an other-language routine that modified areas of
     memory used by QuickBASIC. (This may modify the descriptor for a dynamic
     array of numbers or fixed-length strings.

   (Compile-time error)

 FIELD overflow

   A FIELD statement is attempting to allocate more bytes than were specified
   for the record length of a random file. (Run-time error)

   ERR code: 50

 FIELD statement active

   A GET or PUT statement referred to a record variable used in a a file with
   space previously allocated by the FIELD statement. GET or PUT with a
   record variable argument may only be used on files where no FIELD
   statements have been executed. (Run-time error)

   ERR code: 56

 File already exists

   The file name specified in a NAME statement is identical to a file name
   already in use on the disk. (Run-time error)

   ERR code: 58

 File already open

   A sequential-output-mode OPEN statement is issued for a file that is
   already open, or a KILL statement is given for a file that is open.
   (Run-time error)

   ERR code: 55

 File not found

   A FILES, KILL, NAME, OPEN or RUN statement references a file that does not
   exist. (Run-time error)

   ERR code: 53

 File not found in module module-name at address segment:offset

   A FILES, KILL, NAME, OPEN or RUN statement references a file that does not
   exist. This error message is equivalent to the File not found message, but
   it occurs during execution of compiled programs. The module-name is the
   name of the calling module. The address is the location of the error in
   the code. (Run-time error)

   ERR code: 53

 File previously loaded

   You are attempting to load a file that is already in memory. (Compile-time
   error)

 Fixed-length string illegal

   You are attempting to use a fixed-length string as a formal parameter.
   (Compile-time error)

 FOR index variable already in use

   This error occurs when an index variable is used more than once in nested
   FOR loops. (Compile-time error)

 FOR index variable illegal

   This error is usually caused when an incorrect variable type is used in a
   FOR-loop index. A FOR-loop index variable must be a simple numeric
   variable. (Compile-time error)

 FOR without NEXT

   Each FOR statement must have a matching NEXT statement. (Compile-time
   error)

 Formal parameter specification illegal

   There is an error in a function or subprogram parameter list.
   (Compile-time error)

 Formal parameters not unique

   A FUNCTION or SUB declaration contains duplicate parameters, as in this
   example: SUB GetName(A,B,C,A) STATIC. (Compile-time error)

 Function already defined

   This error occurs when a previously defined FUNCTION is redefined.
   (Compile-time error)

 Function name illegal

   A BASIC reserved word is used as a user-defined FUNCTION name.
   (Compile-time error)

 Function not defined

   You must declare or define a FUNCTION before using it. (Compile-time
   error)

 GOSUB missing

   The GOSUB is missing from an ON event statement. (Compile-time error)

 GOTO missing

   The GOTO is missing from an ON ERROR statement. (Compile-time error)

 GOTO or GOSUB expected

   QuickBASIC expects a GOTO or GOSUB statement. (Compile-time error)

 Help not found

   Help was requested but not found, and the program contains errors
   prohibiting QuickBASIC from building a variable table. Press F5 to view
   the line that caused the error.

 Identifier cannot end with %, &, !, #, or $

   The above suffixes are not allowed in type identifiers, subprogram names,
   or names appearing in COMMON statements. (Compile-time error)

 Identifier cannot include period

   User-defined type identifier and record element names cannot contain
   periods. The period should only be used as a record variable separator. In
   addition, a variable name cannot contain a period if the part of the name
   before the period has been used in an identifier AS usertype clause
   anywhere in the program. If you have programs that use the period in
   variable names, it is recommended that you change them to use mixed case
   instead. For example, variable ALPHA.BETA would become AlphaBeta.
   (Compile-time error)

 Identifier expected

   You are attempting to use a number or a BASIC reserved word where an
   identifier is expected. (Compile-time error)

 Identifier too long

   Identifiers must not be longer than 40 characters. (Compile-time error)

 Illegal function call

   A parameter that is out of range is passed to a math or string function. A
   function-call error can also occur for the following reasons:

   ■ A negative or unreasonably large subscript is used.

   ■ A negative number is raised to a power that is not an integer.

   ■ A negative record number is given when using GET file or PUT file.

   ■ An improper or out-of-range argument is given to a function.

   ■ A BLOAD or BSAVE operation is directed to a nondisk device.

   ■ An I/O function or statement (LOC or LOF, for example) is performed on a
     device that does not support it.

   ■ Strings are concatenated to create a string greater than 32,767
     characters in length.

   (Run-time error)

   ERR code: 5

 Illegal in direct mode

   The statement is valid only within a program and cannot be used in the
   Immediate window. (Compile-time error)

 Illegal in procedure or DEF FN

   The statement is not allowed inside a procedure. (Compile-time error)

 Illegal number

   The format of the number does not correspond to a valid number format. You
   have probably made a typographical error. For example, the number 2p3 will
   produce this error. (Compile-time error)

 Illegal outside of SUB, FUNCTION, or DEF FN

   This statement is not allowed in module-level code. (Compile-time error)

 Illegal outside of SUB/FUNCTION

   The statement is not allowed in module-level code or DEF FN functions.
   (Compile-time error)

 Illegal outside of TYPE block

   The element AS type clause is permitted only within a TYPE...END TYPE
   block. (Compile-time error)

 Illegal type character in numeric constant

   A numeric constant contains an inappropriate type-declaration character.
   (Compile-time error)

 $INCLUDE-file access error

   The include file named in the $INCLUDE metacommand cannot be located.
   (Compile-time error)

 Include file too large

   Your include file exceeds QuickBASIC's internal limit. Break the file into
   separate files. (Compile-time error)

 Input file not found

   The source file you gave on the command line is not in the specified
   location. (BC invocation error)

 INPUT missing

   The compiler expects the keyword INPUT. (Compile-time error)

 Input past end of file

   An INPUT statement reads from a null (empty) file or from a file in which
   all data have already been read. To avoid this error, use the EOF function
   to detect the end of file. (Run-time error)

   ERR code: 62

 Input runtime module path:

   This prompt appears if the run-time module BRUN45.EXE is not found. Enter
   the correct path specification. This error is severe and cannot be
   trapped. (Run-time error)

 Integer between 1 and 32767 required

   The statement requires an integer argument. (Compile-time error)

 Internal error

   An internal malfunction occurred in QuickBASIC. Use the Product Assistance
   Request form included with your documentation to report to Microsoft the
   conditions under which the message appeared. (Run-time error)

   ERR code: 51

 Internal error near xxxx

   An internal malfunction occurred in QuickBASIC at location xxxx. Use the
   Product Assistance Request form included with your documentation to report
   the conditions under which the message appeared. (Compile-time error)

 Invalid character

   QuickBASIC found an invalid character, such as a control character, in the
   source file. (Compile-time error)

 Invalid constant

   An invalid expression is used to assign a value to a constant. Remember
   that expressions assigned to constants may contain numeric constants,
   symbolic constants, and any of the arithmetic or logical operators except
   exponentiation. A string expression assigned to a constant may consist
   only of a single literal string. (Compile-time error)

 Invalid DECLARE for BASIC procedure

   You are attempting to use the DECLARE statement keywords ALIAS, CDECL, or
   BYVAL with a BASIC procedure. ALIAS, CDECL, and BYVAL can only be used
   with non-BASIC procedures. (Compile-time error)

 Label not defined

   A line label is referenced (in a GOTO statement, for example), but does
   not occur in the program. (Compile-time error)

 Label not defined: label

   A GOTO linelabel statement refers to a nonexistent line label.
   (Compile-time error)

 Left parenthesis missing

   QuickBASIC expected a left parenthesis, or a REDIM statement tried to
   reallocate space for a scalar. (Compile-time error)

 Line invalid. Start again

   An invalid file-name character was used following the path characters "\"
   (backslash) or ":" (colon). (BC invocation error)

 Line number or label missing

   A line number or label is missing from a statement that requires one, for
   example, GOTO. (Compile-time error)

 Line too long

   Lines are limited to 255 characters. (Compile-time error)

 LOOP without DO

   The DO starting a DO...LOOP statement is missing or misspelled.
   (Compile-time error)

 Lower bound exceeds upper bound

   The lower bound exceeds the upper bound defined in a DIM statement.
   (Compile-time error)

 Math overflow

   The result of a calculation is too large to be represented in BASIC number
   format. (Compile-time error)

 $Metacommand error

   A metacommand is incorrect. If you are compiling the program with BC this
   error is not "fatal"; the program will execute, although the results may
   be incorrect. (Compile-time warning)

 Minus sign missing

   QuickBASIC expects a minus sign. (Compile-time error)

 Missing Event Trapping (/W) or Checking Between Statements (/V) option

   The program contains an ON event statement requiring one of these options.
   (Compile-time error)

 Missing On Error (/E) option

   When using the BC command, programs containing ON ERROR statements must be
   compiled with the On Error (/E) option. (Compile-time error)

 Missing Resume Next (/X) option

   When using the BC command, programs containing RESUME, RESUME NEXT, and
   RESUME 0 statements must be compiled with the Resume Next (/X) option.
   (Compile-time error)

 Module level code too large

   Your module-level code exceeds QuickBASIC's internal limit. Try moving
   some of the code into SUB or FUNCTION procedures. (Compile-time error)

 Module not found. Unload module from program?

   When loading the program, QuickBASIC did not find the file containing the
   indicated module. QuickBASIC created an empty module instead. You must
   delete the empty module before you can run the program.

 Must be first statement on the line

   In block IF...THEN...ELSE constructs, IF, ELSE, ELSEIF, and END IF can be
   preceded only by a line number or label. (Compile-time error)

 Name of subprogram illegal

   The error is caused when a subprogram name is a BASIC reserved word, or a
   subprogram name is used twice. (Compile-time error)

 Nested function definition

   A FUNCTION definition appears inside another FUNCTION definition, or
   inside an IF...THEN...ELSE clause. (Compile-time error)

 NEXT missing for variable

   A FOR statement is missing a corresponding NEXT statement. The variable is
   the FOR-loop index variable. (Compile-time error)

 NEXT without FOR

   Each NEXT statement must have a matching FOR statement. (Compile-time
   error)

 No line number in module-name at address segment:offset

   This error occurs when the error address cannot be found in the
   line-number table during error trapping. This happens if there are no
   integer line numbers between 0 and 65,527. It may also occur if the
   line-number table has been accidentally overwritten by the user program.
   This error is severe and cannot be trapped. (Run-time error)

 No main module. Choose Set Main Module from the Run menu to select one

   You are attempting to run the program after you have unloaded the main
   module. Every program must have a main module. (Compile-time error)

 No RESUME

   The end of the program was encountered while the program was in an
   error-handling routine. A RESUME statement is needed to remedy this
   situation. (Run-time error)

   ERR code: 19

 Not watchable

   This error occurs when you are specifying a variable in a watch
   expression. Make sure the module or procedure in the active View window
   has access to the variable you want to watch. For example, module-level
   code cannot access variables that are local to a SUB or FUNCTION.
   (Run-time error)

 Numeric array illegal

   Numeric arrays are not allowed as arguments to VARPTR$. Only simple
   variables and string array elements are permitted. (Compile-time error)

 Only simple variables allowed

   User-defined types and arrays are not permitted in READ and INPUT
   statements. Array elements that are not of a user-defined type are
   permitted. (Compile-time error)

 Operation requires disk

   You are attempting to load from, or save to, a nondisk device such as the
   printer or keyboard. (Compile-time error)

 Option unknown: option

   You have given an illegal option. (BC invocation error)

 Out of DATA

   A READ statement is executed when there are no DATA statements with unread
   data remaining in the program. (Run-time error)

   ERR code: 4

 Out of data space

   Try modifying your data space requirements as follows:

   ■ Use a smaller file buffer in the OPEN statement's LEN clause.

   ■ Use the $DYNAMIC metacommand to create dynamic arrays. Dynamic array
     data can usually be much larger than static array data.

   ■ Use fixed-length string arrays instead of variable-length string arrays.

   ■ Use the smallest data type that will accomplish your task. Use integers
     whenever possible.

   ■ Try not to use many small procedures. QuickBASIC must create several
     bytes of control information for each procedure.

   ■ Use CLEAR to modify the size of the stack. Use only enough stack space
     to accomplish your task.

   ■ Do not use source lines longer than 255 characters. Such lines require
     allocation of additional text buffer space.

   (Compile-time or run-time error)

 Out of memory

   More memory is required than is available. For example, there may not be
   enough memory to allocate a file buffer. Try reducing the size of your DOS
   buffers, or getting rid of any terminate-and-stay-resident programs, or
   eliminating some device drivers. If you have large arrays, try placing a
   $DYNAMIC metacommand at the top of your program. If you have documents
   loaded, unloading them will free some memory. (BC invocation,
   compile-time, or run-time error)

   ERR code: 7

 Out of paper

   The printer is out of paper or is not turned on. (Run-time error)

   ERR code: 27

 Out of stack space

   This error can occur when a recursive FUNCTION procedure nests too deeply,
   or there are too many active subroutine, FUNCTION, and SUB calls. You can
   use the CLEAR statement to increase the program's allotted stack space.
   This error cannot be trapped. (Run-time error)

 Out of string space

   String variables exceed the allocated amount of string space. (Run-time
   error)

   ERR code: 14

 Overflow

   The result of a calculation is too large to be represented within the
   range allowed for either floating-point or integer numbers. (Run-time
   error)

   ERR code: 6

 Overflow in numeric constant

   The numeric constant is too large. (Compile-time error)

 Parameter type mismatch

   A subprogram or FUNCTION parameter type does not match the DECLARE
   statement argument or the calling argument. (Compile-time error)

 Path not found

   During an OPEN, MKDIR, CHDIR, or RMDIR operation, DOS was unable to find
   the path specified. The operation is not completed. (Run-time error)

   ERR code: 76

 Path/File access error

   During an OPEN, MKDIR, CHDIR, or RMDIR operation, DOS was unable to make a
   correct connection between the path and file name. The operation is not
   completed. (Compile-time or run-time error)

   ERR code: 75

 Permission denied

   An attempt was made to write to a write-protected disk, or to access a
   locked file. (Run-time error)

   ERR code: 70

 Procedure already defined in Quick library

   A procedure in the Quick library has the same name as a procedure in your
   program. (Compile-time error)

 Procedure too large

   The procedure has exceeded QuickBASIC's internal limit. Make the procedure
   smaller by dividing it into several procedures. (Compile-time error)

 Program-memory overflow

   You are attempting to compile a program whose code segment is larger than
   64K. Try splitting the program into separate modules, or use the CHAIN
   statement. (Compile-time error)

 Read error on standard input

   A system error occurred while reading from the console or a redirected
   input file. (BC invocation error)

 Record/string assignment required

   The string or record variable assignment is missing from the LSET
   statement. (Compile-time error)

 Redo from start

   You have responded to an INPUT prompt with the wrong number or type of
   items. Retype your response in the correct form. (Run-time error)

 Rename across disks

   An attempt was made to rename a file with a new drive designation. This is
   not allowed. (Run-time prompt)

   ERR code: 74

 Requires DOS 2.10 or later

   You are attempting to use QuickBASIC with an incorrect version of DOS. (QB
   invocation or run-time error)

 RESUME without error

   A RESUME statement is encountered before an error-trapping routine is
   entered. (Run-time error)

   ERR code: 20

 RETURN without GOSUB

   A RETURN statement is encountered for which there is no previous,
   unmatched GOSUB statement. (Run-time error)

   ERR code: 3

 Right parenthesis missing

   QuickBASIC expects a right (closing) parenthesis. (Compile-time error)

 SEG or BYVAL not allowed in CALLS

   BYVAL and SEG are permitted only in a CALL statement. (Compile-time error)

 SELECT without END SELECT

   The end of a SELECT CASE statement is missing or misspelled. (Compile-time
   error)

 Semicolon missing

   QuickBASIC expects a semicolon. (Compile-time error)

 Separator illegal

   There is an illegal delimiting character in a PRINT USING or WRITE
   statement. Use a semicolon or a comma as a delimiter. (Compile-time error)

 Simple or array variable expected

   The compiler expects a variable argument. (Compile-time error)

 Skipping forward to END TYPE statement

   An error in the TYPE statement has caused QuickBASIC to ignore everything
   between the TYPE and END TYPE statement. (Compile-time error)

 Statement cannot occur within "CLUDE file

   SUB...END SUB and FUNCTION...END FUNCTION statement blocks are not
   permitted in include files. Use the Merge command from the File menu to
   insert the include file into the current module, or load the include file
   as a separate module. If you load the include file as a separate module,
   some restructuring may be necessary because shared variables are shared
   only within the scope of the module. (Compile-time error)

 Statement cannot precede SUB/FUNCTION definition

   The only statements allowed before a procedure definition are the
   statements REM and DEFtype. (Compile-time error)

 Statement ignored

   You are using the BC command to compile a program that contains TRON and
   TROFF statements without using the /D option. This error is not "fatal" ;
   the program will execute, although the results may be incorrect.
   (Compile-time warning)

 Statement illegal in TYPE block

   The only statements allowed between the TYPE and END TYPE statements are
   REM and element AS typename. (Compile-time error)

 Statement unrecognizable

   You have probably mistyped a BASIC statement. (Compile-time error)

 Statements/labels illegal between SELECT CASE and CASE

   Statements and line labels are not permitted between SELECT CASE and the
   first CASE statement. Comments and statement separators are permitted.
   (Compile-time error)

 STOP in module name at address segment:offset

   A STOP statement was encountered in the program. (Run-time error)

 String assignment required

   The string assignment is missing from an RSET statement. (Compile-time
   error)

 String constant required for ALIAS

   The DECLARE statement ALIAS keyword requires a string-constant argument.
   (Compile-time error)

 String expression required

   The statement requires a string-expression argument. (Compile-time error)

 String formula too complex

   Either a string formula is too long or an INPUT statement requests more
   than 15 string variables. Break the formula or INPUT statement into parts
   for correct execution. (Run-time error)

   ERR code: 16

 String space corrupt

   This error occurs when an invalid string in string space is being deleted
   during heap compaction. The probable causes of this error are as follows:

   ■ A string descriptor or string back pointer has been improperly modified.
     This may occur if you use an assembly-language subroutine to modify
     strings.

   ■ Out-of-range array subscripts are used and string space is inadvertently
     modified. The Produce Debug Code option can be used at compile time to
     check for array subscripts that exceed the array bounds.

   ■ Incorrect use of the POKE and/or DEF SEG statements may modify string
     space improperly.

   ■ Mismatched COMMON declarations may occur between two chained programs.

   (Run-time error)

 String variable required

   The statement requires a string-variable argument. (Compile-time error)

 SUB or FUNCTION missing

   A DECLARE statement has no corresponding procedure. (Compile-time error)

 SUB/FUNCTION without END SUB/FUNCTION

   The terminating statement is missing from a procedure. (Compile-time
   error)

 Subprogram error

   This is a SUB or FUNCTION definition error and is usually caused by one of
   the following:

   ■ The SUB or FUNCTION is already defined.

   ■ The program contains incorrectly nested FUNCTION or SUB statements.

   ■ The SUB or FUNCTION does not terminate with an END SUB or END FUNCTION
     statement.

   (Compile-time error)

 Subprogram not defined

   A subprogram is called but never defined. (Compile-time error)

 Subprograms not allowed in control statements

   Subprogram FUNCTION definitions are not permitted inside control
   constructs such as IF...THEN...ELSE and SELECT CASE. (Compile-time error)

 Subscript out of range

   An array element was referenced with a subscript that was outside the
   dimensions of the array, or an element of an undimensioned dynamic array
   was accessed. This message may be generated if the Debug (/D) option was
   specified at compile time. You may also get this error if the array size
   exceeds 64K, the array is not dynamic, and the /AH option was not used.
   Reduce the size of the array, or make the array dynamic and use the /AH
   command-line option. (Run-time error)

   ERR code: 9

 Subscript syntax illegal

   An array subscript contains a syntax error: for example, an array
   subscript contains both string and integer data types. (Compile-time
   error)

 Syntax error

   Several conditions can cause this error. The most common cause at compile
   time is a mistyped BASIC keyword or argument. At run-time, it is often
   caused by an improperly formatted DATA statement. (Compile-time or
   run-time error)

   ERR code: 2

 Syntax error in numeric constant

   A numeric constant is not properly formed. (Compile-time error)

 THEN missing

   QuickBASIC expects a THEN keyword. (Compile-time error)

 TO missing

   QuickBASIC expects a TO keyword. (Compile-time error)

 Too many arguments in function call

   Function calls are limited to 60 arguments. (Compile-time error)

 Too many dimensions

   Arrays are limited to 60 dimensions. (Compile-time error)

 Too many files

   At compile time, this error occurs when include files are nested more than
   five levels deep. It occurs at run time when the 255-file directory
   maximum is exceeded by an attempt to create a new file with a SAVE or OPEN
   statement. (Compile-time or run-time error)

   ERR code: 67

 Too many labels

   The number of lines in the line list following an ON...GOTOor ON...GOSUB
   statement exceeds 255 (Compile-time error) or 59 (Run-time error in
   compiled applications).

 Too many named COMMON blocks

   The maximum number of named COMMON blocks permitted is 126. (Compile-time
   error)

 Too many TYPE definitions

   The maximum number of user-defined types permitted is 240. (Compile-time
   error)

 Too many variables for INPUT

   An INPUT statement is limited to 60 variables. (Compile-time error)

 Too many variables for LINE INPUT

   Only one variable is allowed in a LINE INPUT statement. (Compile-time
   error)

 Type mismatch

   The variable is not of the required type. For example, you are trying to
   use the SWAP statement with a string variable and a numeric variable.
   (Compile-time or run-time error)

   ERR code: 13

 TYPE missing

   The TYPE keyword is missing from an END TYPE statement. (Compile-time
   error)

 Type more than 65535 bytes

   A user-defined type cannot exceed 64K. (Compile-time error)

 Type not defined

   The usertype argument to the TYPE statement is not defined. (Compile-time
   error)

 TYPE statement improperly nested

   User-defined type definitions are not allowed in procedures. (Compile-time
   error)

 TYPE without END TYPE

   There is no END TYPE statement associated with a TYPE statement.
   (Compile-time error)

 Typed variable not allowed in expression

   Variables that are user-defined types are not permitted in expressions
   such as CALL ALPHA((X)), where Xis a user-defined type. (Compile-time
   error)

 Unexpected end of file in TYPE declaration

   There is an end-of-file character inside a TYPE...END TYPE block.

 Unprintable error

   An error message is not available for the error condition that exists.
   This may be caused by an ERROR statement that doesn't have a defined error
   code. (Run-time error)

 Unrecognized switch error: "QU"

   You are attempting to create an .EXE file or Quick library with an
   incorrect version of the Microsoft Overlay Linker. You must use the linker
   supplied on the QuickBASIC distribution disks to create an .EXE file or
   Quick library. (Compile-time error)

 Valid options: [/RUN] file /AH /B /C:buf /G /NOHI /H /L [lib] /MBF /CMD
 string

   This message appears when you invoke QuickBASIC with an invalid option.
   (QB invocation error)

 Variable-length string required

   Only variable-length strings are permitted in a FIELD statement.
   (Compile-time error)

 Variable name not unique

   You are attempting to define the variable x as a user-defined type after
   x.y has been used. (Compile-time error)

 Variable required

   QuickBASIC encountered an INPUT, LET, READ, or SHARED statement without a
   variable argument. (Compile-time error)

 Variable required

   A GET or PUT statement didn't specify a variable when an operation is
   performed on a file opened in BINARY mode. (Run-time error)

   ERR code: 40

 WEND without WHILE

   This error is caused when a WEND statement has no corresponding WHILE
   statement. (Compile-time error)

 WHILE without WEND

   This error is caused when a WHILE statement has no corresponding WEND
   statement. (Compile-time error)

 Wrong number of dimensions

   An array reference contains the wrong number of dimensions. (Compile-time
   error)


 I.3  LINK Error Messages

   This section lists and describes error messages generated by the Microsoft
   Overlay Linker, LINK.

   Fatal errors cause the linker to stop execution. Fatal error messages have
   the following format:

   location : fatal error L1xxx:messagetext

   Nonfatal errors indicate problems in the executable file. LINK produces
   the executable file. Nonfatal error messages have the following format:

   location : error L2xxx: messagetext

   Warnings indicate possible problems in the executable file. LINK produces
   the executable file. Warnings have the following format:

   location : warning L4xxx: messagetext

   In these messages, location is the input file associated with the error,
   or LINK if there is no input file.

   The following error messages may appear when you link object files with
   LINK:

╓┌─┌──────────────┌──────────────────────────────────────────────────────────╖
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
   L1001          option : option name ambiguous

                  A unique option name did not appear after the option
                  indicator (/). For example, the command

                  LINK /N main;
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 LINK /N main;

                  generates this error, since LINK cannot tell which of the
                  three options beginning with the letter "N" was intended.

   L1002          option : unrecognized option name

                  An unrecognized character followed the option indicator
                  (/), as in the following example:

                  LINK /ABCDEF main;

   L1003          /QUICKLIB, /EXEPACK incompatible

                  You specified two options that cannot be used together:
                  /QUICKLIB and /EXEPACK.

   L1004          option : invalid numeric value

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

                  An incorrect value appeared for one of the LINK options.
                  For example, a character string was given for an option
                  that requires a numeric value.

   L1006          option : stack size exceeds 65535 bytes

                  The value given as a parameter to the /STACKSIZE option
                  exceeds the maximum allowed.

   L1007          option : interrupt number exceeds 255

                  For the /OVERLAYINTERRUPT option, a number greater than 255
                  was given as a value.

   L1008          option : segment limit set too high

                  The limit on the number of segments allowed was set to
                  greater than 3072 using the /SEGMENTS option.
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 greater than 3072 using the /SEGMENTS option.

   L1009          number : CPARMAXALLOC : illegal value

                  The number specified in the /CPARMAXALLOC option was not in
                  the range 1-65,535.

   L1020          no object modules specified

                  No object-file names were specified to LINK.

   L1021          cannot nest response files

                  A response file occurred within a response file.

   L1022          response line too long

                  A line in a response file was longer than 127 characters.

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

   L1023          terminated by user

                  You entered CTRL+C or CRTL+BREAK

   L1024          nested right parentheses

                  The contents of an overlay were typed incorrectly on the
                  command line.

   L1025          nested left parentheses

                  The contents of an overlay were typed incorrectly on the
                  command line.

   L1026          unmatched right parenthesis

                  A right parenthesis was missing from the contents
                  specification of an overlay on the command line.
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 specification of an overlay on the command line.

   L1027          unmatched left parenthesis

                  A left parenthesis was missing from the contents
                  specification of an overlay on the command line.

   L1043          relocation table overflow

                  More than 32,768 long calls, long jumps, or other long
                  pointers appeared in the program.

                  Try replacing long references with short references, where
                  possible, and recreate the object module.

   L1045          too many TYPDEF records

                  An object module contained more than 255 TYPDEF records.
                  These records describe communal variables. This error can
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 These records describe communal variables. This error can
                  appear only with programs produced by the Microsoft FORTRAN
                  Compiler or other compilers that support communal
                  variables. (TYPDEF is a DOS term. It is explained in the
                  Microsoft MS-DOS Programmer's Reference and in other
                  reference books on DOS.)

   L1046          too many external symbols in one module

                  An object module specified more than the limit of 1023
                  external symbols.

                  Break the module into smaller parts.

   L1047          too many group, segment, and class names in one module

                  The program contained too many group, segment, and class
                  names.

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

                  Reduce the number of groups, segments, or classes, and
                  recreate the object file.

   L1048          too many segments in one module

                  An object module had more than 255 segments.

                  Split the module or combine segments

   L1049          too many segments

                  The program had more than the maximum number of segments.
                  Use the /SEGMENTS option, which has a default value of 128,
                  to specify the maximum legal number of segments. The
                  default is 128 in the /SEGMENTS option, which specifies the
                  maximum legal number.

                  Relink using the /SEGMENTS option with an appropriate
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 Relink using the /SEGMENTS option with an appropriate
                  number of segments.

   L1050          too many groups in one module

                  LINK encountered over 21 group definitions (GRPDEF) in a
                  single module.

                  Reduce the number of group definitions or split the module.
                  (Group definitions are explained in the Microsoft MS-DOS
                  Programmer's Reference and in other reference books on
                  DOS.)

   L1051          too many groups

                  The program defined more than 20 groups, not counting
                  DGROUP.

                  Reduce the number of groups.
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 Reduce the number of groups.

   L1052          too many libraries

                  An attempt was made to link with more than 32 libraries.

                  Combine libraries, or use modules that require fewer
                  libraries.

   L1053          out of memory for symbol table

                  There is no fixed limit to the size of the symbol table.
                  However, it is limited by the amount of available memory.

                  Combine modules or segments and recreate the object files.
                  Eliminate as many public symbols as possible.

   L1054          requested segment limit too high

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

                  LINK did not have enough memory to allocate tables
                  describing the number of segments requested. (The default
                  is 128 or the value specified with the /SEGMENTS option.)

                  Try linking again using the /SEGMENTS option to select a
                  smaller number of segments (for example, use 64 if the
                  default was used previously), or free some memory by
                  eliminating resident programs or shells.

   L1056          too many overlays

                  The program defined more than 63 overlays.

   L1057          data record too large

                  A LEDATA record (in an object module) contained more than
                  1024 bytes of data. This is a translator error. (LEDATA is
                  a DOS term, which is explained in the Microsoft MS-DOS
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 a DOS term, which is explained in the Microsoft MS-DOS
                  Programmer's Reference and in other DOS reference books.)

                  Note which translator (compiler or assembler) produced the
                  incorrect object module and the circumstances. Please
                  report this error to Microsoft Corporation using the
                  Product Assistance Request form included with the
                  documentation.

   L1063          out of memory for CodeView information

                  Too many linked object (".OBJ") files contain debugging
                  information. Turn off the Produce Debug Code option in the
                  Make EXE file dialog box.

   L1070          segment size exceeds 64K

                  A single segment contained more than 64K of code or data.

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

                  Try compiling and linking using the large model.

   L1071          segment _TEXT larger than 65520 bytes

                  This error is likely to occur only in small-model C
                  programs, but it can occur when any program with a segment
                  named _TEXT is linked using the /DOSSEG option. Small-model
                  C programs must reserve code addresses 0 and 1; this range
                  is increased to 16 for alignment purposes.

   L1072          common area longer than 65536 bytes

                  The program had more than 64K of communal variables. This
                  error occurs only with programs produced by compilers that
                  support communal variables.

   L1080          cannot open list file

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

                  The disk or the root directory was full.

                  Delete or move files to make space.

   L1081          out of space for run file

                  The disk on which the executable file was being written was
                  full.

                  Free more space on the disk and restart LINK.

   L1083          cannot open run file

                  The disk or the root directory was full.

                  Delete or move files to make space.

   L1084          cannot create temporary file
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
  L1084          cannot create temporary file

                  The disk or root directory was full.

                  Free more space in the directory and restart LINK.

   L1085          cannot open temporary file

                  The disk or the root directory was full.

                  Delete or move files to make space.

   L1086          scratch file missing

                  An internal error has occurred.

                  Note the circumstances of the problem and contact Microsoft
                  Corporation using the Product Assistance Request form
                  included with the documentation.
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 included with the documentation.

   L1087          unexpected end-of-file on scratch file

                  The disk with the temporary output file from LINK was
                  removed.

   L1088          out of space for list file

                  The disk where the listing file is being written is full.

                  Free more space on the disk and restart LINK.

   L1089          filename : cannot open response file

                  LINK could not find the specified response file.

                  This usually indicates a typing error.

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

   L1090          cannot reopen list file

                  The original disk was not replaced at the prompt.

                  Restart LINK.

   L1091          unexpected end-of-file on library

                  The disk containing the library probably was removed.

                  Replace the disk containing the library and run LINK again.

   L1093          object not found

                  One of the object files specified in the input to LINK was
                  not found.

                  Restart LINK and specify the object file.
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 Restart LINK and specify the object file.

   L1101          invalid object module

                  One of the object modules was invalid.

                  If the error persists after recompiling, please contact
                  Microsoft Corporation using the Product Assistance Request
                  form included with the documentation.

   L1102          unexpected end-of-file

                  An invalid format for a library was encountered.

   L1103          attempt to access data outside segment bounds

                  A data record in an object module specified data extending
                  beyond the end of a segment. This is a translator error.

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

                  Note which translator (compiler or assembler) produced the
                  incorrect object module and the circumstances in which it
                  was produced. Please report this error to Microsoft
                  Corporation using the Product Assistance Request form
                  included with the documentation.

   L1104          filename : not valid library

                  The specified file was not a valid library file. This error
                  causes LINK to abort.

   L1113          unresolved COMDEF; internal error

                  Note the circumstances of the failure and contact Microsoft
                  Corporation using the Product Assistance Request form
                  included with the documentation.

   L1114          file not suitable for /EXEPACK; relink without
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
  L1114          file not suitable for /EXEPACK; relink without

                  For the linked program, the size of the packed load image
                  plus packing overhead was larger than that of the unpacked
                  load image.

                  Relink without the /EXEPACK option.

   L1115          /QUICKLIB, overlays incompatible

                  You specified overlays and used the /QUICKLIB option. These
                  cannot be used together.

   L2001          fixup(s) without data

                  A FIXUPP record occurred without a data record immediately
                  preceding it. This is probably a compiler error. (See the
                  Microsoft MS-DOS Programmer's Reference for more
                  information on FIXUPP.)
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 information on FIXUPP.)

   L2002          fixup overflow near number in frame seg segname target seg
                  segname target offset number

                  The following conditions can cause this error:

                  ■ A group is larger than 64K.

                  ■ The program contains an intersegment short jump or
                  intersegment short call.

                  ■ The name of a data item in the program conflicts with the
                  name of a library subroutine included in the link.

                  ■ An EXTRN declaration in an assembly-language source file
                  appeared inside the body of a segment, as in the following
                  example:

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

                  code   SEGMENT public 'CODE'
                         EXTRN   main:far
                  start  PROC    far
                         call    main
                         ret
                  start  ENDP
                  code   ENDS

                  The following construction is preferred:

                  EXTRN   main:far
                  code   SEGMENT public 'CODE'
                  start  PROC    far
                         call    main
                         ret
                  start  ENDP
                  code   ENDS

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

                  Revise the source file and recreate the object file. (See
                  the Microsoft MS-DOS Programmer's Reference for information
                  about frame and target segments.

   L2003          intersegment self-relative fixup at offset in segment
                  segname

                  You tried to make a near call or jump to a far entry in
                  segment segname at offset.

                  Change the call or jump to far or make the entry near.

   L2004          LOBYTE-type fixup overflow

                  A LOBYTE fixup generated an address overflow. (See the
                  Microsoft MS-DOS Programmer's Reference for more
                  information.)

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

   L2005          fixup type unsupported

                  A fixup type occurred that is not supported by the
                  Microsoft linker. This is probably a compiler error.

                  Note the circumstances of the failure and contact Microsoft
                  Corporation using the Product Assistance Request form
                  included with the documentation.

   L2011          name : NEAR/HUGE conflict

                  Conflicting NEAR and HUGE attributes were given for a
                  communal variable. This error can occur only with programs
                  produced by compilers that support communal variables.

   L2012          name : array-element size mismatch

                  A far communal array was declared with two or more
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 A far communal array was declared with two or more
                  different array-element sizes (for instance, an array was
                  declared once as an array of characters and once as an
                  array of real numbers). This error occurs only with
                  compilers that support far communal arrays.

   L2013          LIDATA record too large

                  A LIDATA record contains more than 512 bytes. This error is
                  usually caused by a compiler error.

   L2024          name : symbol already defined

                  LINK has found a public-symbol redefinition. Remove extra
                  definition(s).

   L2025          name : symbol defined more than once

                  Remove the extra symbol definition from the object file.
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 Remove the extra symbol definition from the object file.

   L2029          unresolved externals

                  One or more symbols were declared to be external in one or
                  more modules, but they were not publicly defined in any of
                  the modules or libraries. A list of the unresolved external
                  references appears after the message, as shown in the
                  following example:

                  unresolved externals
                  EXIT in file(s):
                   MAIN.OBJ (main.for)
                  OPEN in file(s):
                   MAIN.OBJ (main.for)

                  The name that comes before in file(s) is the unresolved
                  external symbol. On the next line is a list of object
                  modules that have made references to this symbol. This
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 modules that have made references to this symbol. This
                  message and the list are also written to the map file, if
                  one exists.

   L2041          stack plus data exceed 64K

                  The total size of near data and the stack exceeds 64K.
                  Reduce the stack size to control the error.

                  LINK tests for this condition only if the /DOSSEG option is
                  enabled. This option is automatically enabled by the
                  library startup module.

   L2043          Quick library support module missing

                  You did not specify, or LINK could not find, the object
                  module or library required for creating a Quick library. In
                  the case of QuickBASIC, the library provided is BQLB45.LIB.

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

   L2044          name : symbol multiply defined, use /NOE

                  LINK has found a possible public-symbol redefinition. This
                  error is often caused by redefining a symbol defined in a
                  library.

                  Relink using the /NOEXTDICTIONARY option.

                  This error in combination with error L2025 for the same
                  symbol indicates a real redefinition error.

   L4011          PACKCODE value exceeding 65500 unreliable

                  Packcode segment sizes that exceed 65,500 bytes may be
                  unreliable on the Intel(R) 80286 processor.

   L4012          load-high disables EXEPACK

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

                  The /HIGH and /EXEPACK options cannot be used at the same
                  time.

   L4015          /CODEVIEW disables /DSALLOCATE

                  The /CODEVIEW and /DSALLOCATE options cannot be used at the
                  same time.

   L4016          /CODEVIEW disables /EXEPACK

                  The /CODEVIEW and /EXEPACK options cannot be used at the
                  same time.

   L4020          name : code-segment size exceeds 65500

                  Code segments of 65,501-65,536 bytes in length may be
                  unreliable on the Intel 80286 processor.

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

   L4021          no stack segment

                  The program did not contain a stack segment defined with
                  STACK combine type. This message should not appear for
                  modules compiled with Microsoft QuickBASIC, but it could
                  appear for an assembly-language module.

                  Normally, every program should have a stack segment with
                  the combine type specified as STACK. You can ignore this
                  message if you have a specific reason for not defining a
                  stack or for defining one without the STACK combine type.
                  Linking with versions of LINK earlier than Version 2.40
                  might cause this message, since these linkers search
                  libraries only once.

   L4031          name : segment declared in more than one group

                  A segment was declared to be a member of two different
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
                 A segment was declared to be a member of two different
                  groups.

                  Correct the source file and recreate the object files.

   L4034          more than 239 overlay segments; extra put in root

                  The program designates more than 239 segments to go in
                  overlays. When this error occurs, segments beginning with
                  number 234 are placed in the root, the permanently resident
                  portion.

   L4045          name of output file is name

                  The prompt for the run-file field gave an inaccurate
                  default because the /QUICKLIB option was not used early
                  enough. The output will be a Quick library with the name
                  given in the error message.

   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────

   L4050          too many public symbols for sorting

                  The number of public symbols exceeds the space available
                  for sorting the symbols as requested by the /MAP option.
                  The symbols are left unsorted.

   L4051          filename : cannot find library

                  LINK could not find the specified file.

                  Enter a new file name, a new path specification, or both.

   L4053          VM.TMP : illegal file name; ignored

                  VM.TMP appeared as an object-file name. Rename the file and
                  rerun LINK.

   L4054          filename : cannot find file
   Number         LINK Error Message
   ──────────────────────────────────────────────────────────────────────────
  L4054          filename : cannot find file

                  LINK could not find the specified file. Enter a new file
                  name, a new path specification, or both.
   ──────────────────────────────────────────────────────────────────────────



 I.4  LIB Error Messages

   Error messages generated by the Microsoft Library Manager, LIB, have one
   of the following formats:

   {filename| LIB} : fatal error U1xxx: messagetext
   {filename| LIB} : error U2xxx: messagetext
   {filename| LIB} : warning U4xxx: messagetext

   The message begins with the input-file name (filename), if one exists, or
   with the name of the utility. If possible, LIB prints a warning and
   continues operation. In some cases errors are fatal, and LIB terminates
   processing.

   LIB may display the following error messages:


   Number                   LIB Error Message
   ──────────────────────────────────────────────────────────────────────────
   U1150                    page size too small

                            The page size of an input library was too small,
                            which indicates an invalid input .LIB file.

   U1151                    syntax error : illegal file specification

                            A command operator such as a minus sign (-) was
                            given without a following module name.

   U1152                    syntax error : option name missing

                            A forward slash (/) was given without an option
                            after it.

   U1153                    syntax error : option value missing

                            The /PAGESIZE option was given without a value
                            following it.

   U1154                    option unknown

                            An unknown option was given. Currently, LIB
                            recognizes only the /PAGESIZE option.

   U1155                    syntax error : illegal input

                            The given command did not follow correct LIB
                            syntax as specified in Appendix G, "Compiling
                            and Linking from DOS."

   U1156                    syntax error

                            The given command did not follow correct LIB
                            syntax as specified in Appendix G, "Compiling
                            and Linking from DOS."

   U1157                    comma or new line missing

                            A comma or carriage return was expected in the
                            command line but did not appear. This may
                            indicate an inappropriately placed comma, as in
                            the line that follows:

                            LIB math.lib,-mod1+mod2;

                            The line should have been entered as follows:

                            LIB math.lib -mod1+mod2;

   U1158                    terminator missing

                            Either the response to the "Output library"
                            prompt or the last line of the response file used
                            to start LIB did not end with a carriage return.

   U1161                    cannot rename old library

                            LIB could not rename the old library to have a
                            .BAK extension because the .BAK version already
                            existed with read-only protection.

                            Change the protection on the old .BAK version.

   U1162                    cannot reopen library

                            The old library could not be reopened after it
                            was renamed to have a .BAK extension.

   U1163                    error writing to cross-reference file

                            The disk or root directory was full.

                            Delete or move files to make space.

   U1170                    too many symbols

                            More than 4609 symbols appeared in the library
                            file.

   U1171                    insufficient memory

                            LIB did not have enough memory to run.

                            Remove any shells or resident programs and try
                            again, or add more memory.

   U1172                    no more virtual memory

                            Note the circumstances of the failure and notify
                            Microsoft Corporation using the Product Assistant
                            Request form included with the documentation.

   U1173                    internal failure

                            Note the circumstances of the failure and notify
                            Microsoft Corporation using the Product Assistant
                            Request form included with the documentation.

   U1174                    mark: not allocated

                            Note the circumstances of the failure and notify
                            Microsoft Corporation using the Product
                            Assistance Request form included with the
                            documentation.

   U1175                    free: not allocated

                            Note the circumstances of the failure and notify
                            Microsoft Corporation using the Product
                            Assistance Request form included with the
                            documentation.

   U1180                    write to extract file failed

                            The disk or root directory was full.

                            Delete or move files to make space.

   U1181                    write to library file failed

                            The disk or root directory was full.

                            Delete or move files to make space.

   U1182                    filename : cannot create extract file

                            The disk or root directory was full, or the
                            specified extract file already existed with
                            read-only protection.

                            Make space on the disk or change the protection
                            of the extract file.

   U1183                    cannot open response file

                            The response file was not found.

   U1184                    unexpected end-of-file on command input

                            An end-of-file character was received prematurely
                            in response to a prompt.

   U1185                    cannot create new library

                            The disk or root directory was full, or the
                            library file already existed with read-only
                            protection.

                            Make space on the disk or change the protection
                            of the library file.

   U1186                    error writing to new library

                            The disk or root directory was full.

                            Delete or move files to make space.

   U1187                    cannot open VM.TMP

                            The disk or root directory was full.

                            Delete or move files to make space.

   U1188                    cannot write to VM

                            Note the circumstances of the failure and notify
                            Microsoft Corporation using the Product
                            Assistance Request form.

   U1189                    cannot read from VM

                            Note the circumstances of the failure and notify
                            Microsoft Corporation using the Product
                            Assistance Request form.

   U1190                    interrupted by user

                            The user pressed CTRL+C or CTRL+BREAK.

   U1200                    name : invalid library header

                            The input library file had an invalid format. It
                            was either not a library file, or it had been
                            corrupted.

   U1203                    name : invalid object module near location

                            The module specified by name was not a valid
                            object module.

   U2152                    filename : cannot create listing

                            The directory or disk was full, or the
                            cross-reference-listing file already existed with
                            read-only protection.

                            Either make space on the disk or change the
                            protection of the cross-reference-listing file.

   U2155                    modulename : module not in library; ignored

                            The specified module was not found in the input
                            library.

   U2157                    filename : cannot access file

                            LIB was unable to open the specified file.

   U2158                    libraryname : invalid library header; file
                            ignored

                            The input library had an incorrect format.

   U2159                    filename : invalid format hexnumber; file ignored

                            The signature byte or word hexnumber of the given
                            file was not one of the following recognized
                            types: Microsoft library, Intel library,
                            Microsoft object, or XENIX(R) archive.

   U4150                    modulename : module redefinition ignored

                            A module was specified to be added to a library
                            but a module with the same name was already in
                            the library. Or, a module with the same name was
                            found more than once in the library.

   U4151                    symbol : symbol redefined in module modulename,
                            redefinition ignored

                            The specified symbol was defined in more than one
                            module.

   U4153                    number : page size too small; ignored

                            The value specified in the /PAGESIZE option was
                            less than 16.

   U4155                    modulename: module not in library

                            A module to be replaced is not in the library.
                            LIB adds the module to the library.

   U4156                    libraryname : output-library specification
                            ignored

                            An output library was specified in addition to a
                            new library name. For example, specifying

                            LIB new.lib+one.obj,new.lst,new.lib

                            where new.lib does not already exist causes this
                            error.

   U4157                    Insufficient memory, extended dictionary not
                            created.

                            LIB was unable to create the extended dictionary.
                            The library is still valid, but LINK cannot take
                            advantage of extended dictionaries to link
                            faster.

   U4158                    Internal error, extended dictionary not created.

                            LIB was unable to create the extended dictionary.
                            The library is still valid, but LINK cannot take
                            advantage of extended dictionaries to link
                            faster.



 ────────────────────────────────────────────────────────────────────────────
 Index


 Symbols

 #
 (+)
   operator, combining strings
 '
 *
 * (asterisk)
   AS,
   LIB command symbol
 , (comma)
   fields, ending
   variable separator
 $ (dollar sign), string-type suffix
 " (double quotes), ending
 / (forward slash), LINK option character
 (/), LINK option character
 - (minus sign)
 - (minus sign), LIB command symbol
 -* (minus sign-asterisk, LIB
 -+ (minus sign-plus sign), LIB command symbol
 "" (null string)
 + (plus)
   operator, combining strings
   sign, LIB command
 ; (semicolon)
   LIB
 ; (semicolon),
 ; (semicolon), LIB command symbol
 # USING

 A

 ,A option
   BASICA
   #INCLUDE files
 /A option (BC)
 ABS function
 ABSOLUTE
 Absolute
 ABSOLUTE statement
 access, contrasted with
 after input
 /AH option
 ALIAS, DECLARE
 aliasing
 Aliasing, variable
 all in a module
 allowable
 allowed
 Alphabetizing
 alternative
 among versions
 AND
   operator
 and functions. See individual statement and function names
   FIELD
   GET
   INPUT #
   PUT
   WRITE #
 and GW-BASIC
 AND option
   PUT
 and replacing
 Angle measurements
 Animate mode
 Animation
   GET and PUT
   graphics statements, simple
   image flicker,
   PALETTE USING
   screen pages
 Apostrophe (')
   entering
   introducing comments
 (apostrophe), introducing comments
 Arc
 Arctangent,
 Arguments
   correct type and number, checking for
   LINK options
   parameters
     agreement
     distinguished from
   passing
     by
     by value
     described
     limits on
   SUB procedures,
 arguments by reference
 Array-bound
 Array-bound functions
 Arrays
   dynamic
     ERASE
     REDIM statement
   elements, passing
   format
     argument list
     FUNCTION statement
     parameter
     parameter list
     SHARED statement
     SUB statement
   LBOUND function
   limits (table)
   lower-bound function
   memory allocation
   procedures
     passing
     passing to
     sharing
   row-order option
   static, ERASE statement
   subscripts,
   subscripts, specifying
     lower
   UBOUND (upper-bound) function
   variables
 arrays
   limits
 Arrow keys. See DIRECTION keys
 ASC function
 ASCII
   character
   character codes
     CHR$
     determining
     (table)
   files, reading as sequential
 Aspect ratio
   CIRCLE
   correction for
   defined
   screen size, computing for
   squares,
 Assembly-language listings
 Assignment statements
 (asterisk)
   AS, fixed-length string with
 Asterisk (*)
   fixed-length
 Asterisk (*)
 ATN function
 attribute
   described
   DIM
     described
     sharing
   REDIM
   variables, making global
 Attributes
   colors, assigning
   screen
   screen modes, EGA and VGA
   STATIC
 attributes. See Attributes
 automatic
 Automatic
 Automatic variables
 AUX (device name)

 B

 Background color default
 Background music
 .BAS file, execution by QuickBASIC
 BASIC
   error codes
   reserved words
   run-time errors
 BASIC, compatibility
 BASICA
   compatibility
   QuickBASIC, converting to
 /BATCH option (LINK)
 Batch file, when to use
 Baud rate
 BC command
   options
     /V
 BC
 BC command
   command line, invoking from
   file-name usage
   options
     /A
     /AH
     /C
     /D
     /E
     (list)
     /MBF
     new (table)
     not used (table)
     /O
     /R
     /S
     /V
     /W
     /X
     /ZD
     /ZI
   versions, differences among
 BC.EXE
 BEEP statement
 Binary
   file access
     OPEN statement syntax
     random
     versions, differences among
   input
   numbers, converting to hexadecimal
 Binary, differences from
 Binary format
   IEEE format, differences from
 Binary-access
 Binary-access files
   creating
   opening
   reading
   writing to
 Bit
 Bitwise operators. See Logical operators
 Blank COMMON block
 BLOAD statement
 block
 Block IF...THEN...ELSE
 Bold text, indicating keywords
 B_OnExit routine
 Boolean
   constants
   expressions
     definition
     logical operators
     other
     relational operators (table)
 bound
 bound for
 Boxes,
 Boxes, LINE statement
 BRUN40.LIB, default for linker
 BSAVE statement
 buffer
 BUILDLIB utility
 by QuickBASIC
 by value
   defined

 C

 /C option (BC)
 CALL
 CALL ABSOLUTE
 CALL INT86OLD statement
 CALL INT86XOLD statement
 CALL INTERRUPT
 CALL INTERRUPT statement
 CALL INTERRUPTX statement
 CALL statement
   DECLARE, used with
   described
   optional
   QuickBASIC/interpreter differences
   SUB procedure, calling
 calls
 CALLS statement
 CALLS statement (non-BASIC)
 Carriage-return-line-feed
 Cartesian coordinates. See View coordinates
 Case
   sensitivity
   significance,
 CASE clause. See SELECT CASE statement
 CASE$ function
 CDBL function
 CDECL, use in DECLARE statement
 CGA
   palette, changing
   screen modes supported by
 CHAIN
 CHAIN statement
   described
   QuickBASIC/interpreter differences
 Chaining programs,
 Chaining programs, statements used. See individual
 changing number of
 changing with
 Characters
   how stored
   limits
 CHDIR statement
 Checking between statements option
 Choosing
   commands,
   options, differences among versions
 CHR$ function
 CINT function
 CIRCLE
 CIRCLE statement
   arcs
   circles
   described
   ellipses
   pie shapes
 Circles, drawing
 clause
 CLEAR
 CLEAR statement
 CLNG function
 CLOSE statement
 CLS statement
 /CODEVIEW option (LINK)
 codes
   determining with the ASC function
   storing characters in memory
 CodeView
 COLOR
 Color
 Color Graphics Adapter. See CGA
 COLOR statement
   background color, controlling
   described
   foreground color, controlling
   palette, changing with
   screen mode 1, syntax in
 Colors
   background,
   CGA, using with
   clarity, tradeoff with
   foreground,
   foreground, controlling
   graphics statements, specifying in
   PALETTE
   PALETTE,
 Columns
   changing
   skipping
 COM
 COM devices
 COM statements
 Comma (,)
   ending fields
   variable separator
 command
   option
     /MBF
   /RUN option
 COMMAND$
 command, DRAW
 COMMAND$ function
   limits
 Command line
   BASIC program passing to
   Quick
 command line
 command symbol
 command-line
 Commands
   BC. See BC command
   Linker. See LINK
   versions,
 commands
 Commands QB. See QB command
 Comments
   REM statement
 Comments, introducing with apostrophe
 COMMON
 COMMON block
   blank
   named
 COMMON statement
   AS clause
   chaining programs
   QuickBASIC/interpreter differences
   SHARED
   SHARED attribute
     defined
     described
     variables, sharing across
   variables,
 compared with
 Comparing
 Comparing strings
   relational operators, with
 Compatibility
   BASICA
   versions,
 compatibility among
 Compile options
 Compile-time error messages
 Compiling from DOS
 Complex numbers, defined
 CON (device name)
 Concatenation, defined
 CONS
 CONST statement
 Constants
   input list
   procedures, passing to
   string, literal and symbolic
   symbolic
 constants
   format in program examples
   string
 contrasted with
 Control-flow
 Control-flow statements. See individual
   CALL
   CALL ABSOLUTE
   CALLS
   CHAIN
   DO...LOOP
   FUNCTION
   GOSUB...RETURN
   GOTO
   IF...THEN...ELSE
   ON GOTO
   ON...GOTO
   RETURN
   SELECT CASE
 Control-flow structures
   BASIC, used in (table)
   decision
   defined
   indenting
   new
 Controlling
   linker
   segments
   stack size
 controlling
 conventions
   BASIC programs
 Converting
   BASICA and GW-BASIC programs
   data
   IEEE format, program for
 converting to QuickBASIC
 Coordinates
   absolute
     STEP, specifying
     VIEW SCREEN, specifying
   physical
     GET
     pixels,
     view
   pixels, locating
   relative
     defined
     STEP
     VIEW
   view
     GET statement
     physical coordinates, translating
     WINDOW,
   viewport,
 coordinates. See Coordinates, absolute
   WINDOW statement
 coordinates, translating to
 COS
 (/CP)
 /CPARMAXALLOC option (LINK)
 creating outside QuickBASIC environment
 Cross-reference-file
 CSNG function
 CSRLIN function
 Cursor
   graphics
   text
     defined
     LOCATE, positioning
     location, finding
     shape, changing
 cursor
 CVD function
 CVDMBF
 CVDMBF function
 CVI function
 CVL
 CVL function
 CVS
 CVSMBF function
 CVtype statement

 D

 /D option (BC)
 Data
 Data files
   closing
   creating
   defined
   file numbers
   file-access errors,
   opening
   organization
   random-access
   reading
   records, adding
   sequential
 data, preventing
 DATA statement
 Data types
   TYPE statement
 Data-file buffer
 DATE$
 Date and time
   functions
     DATE$
     TIME$
   statements
     DATE$
     TIME$
 DATE$ statement
 Debug option
 debugger, debugging with
 debugger, LINK option for
 Debugging
   /CODEVIEW (LINK) option
   statements
   versions, differences among
 Decision
 Decision structures
   defined
   IF...THEN...ELSE
     block
     single-line
   SELECT CASE
 Declarations. See individual statement names
   CONST
   DECLARE statement (BASIC procedures)
   DECLARE statement (non-BASIC
   DEFtype
   DIM statement
 DECLARE
 DECLARE statement
   described
   include
   QuickBASIC,
   versions, differences among
   where required
 Declaring arrays
   limits
 DEF FN functions
   exit from, alternative
   FUNCTION procedure, contrasted with
   local
 DEF FN statement
 DEF SEG statement
 DEFDBL statement
 defining with
 definitions
 DEFINT statement
 DEFLNG statement
 DEFSNG statement
 DEFSTR
 DEFtype
   QuickBASIC/interpreter differences
 DEFtype
 Degrees
   compared with
   converting to radians
 deleting from, including, and replacing
 Device I/O, contrasted with file I/O
 (device name)
 Devices
   COM
   CONS
   function
   function handling
     IOCTL$
     PEN
   I/O modes, valid
   KEYBD
   LPT
   names
   SCRN
   statement handling
     IOCTL
     OPEN
     OUT
     WAIT
 Device-status information
 differences among
 Differences among versions
   file compatibility
   (table)
 differences among versions
 DIM
 DIM statement
   AS
   described
   QuickBASIC/interpreter differences
   SHARED attribute
     defined
     example,
     variables,
   TO clause
 Dimensioning
 DIRECTION
 keys, trapping
 Directory
 Directory statements
   CHDIR
   FILES
   MKDIR
   RMDIR
 Display memory, PCOPY statement
 displaying
 DO UNTIL statement
 DO WHILE statement
 Document conventions
 Dollar
 DO...LOOP
 DO...LOOP statement
   described
   exit from,
   exit from, alternative
   keyword
     UNTIL
     WHILE
   loop test, location of
   syntax
   WHILE...WEND,
 DOS
 DOS-level
 option (LINK)
 /DOSSEG
 Dotted lines, drawing
 Double quotes ("), ending fields
 Double-precision
 Double-precision numbers
   size limits
 DRAW statement
   described
   figures
     rotating
     scaling
   macro commands in
   QuickBASIC/interpreter differences
   VARPTR$
 drawing
 Dumb terminal, defined
 Dummy arguments, POS function
 #DYNAMIC metacommand
 Dynamic arrays
   #DYNAMIC metacommand
   ERASE
   REDIM

 E

 /E option
   BC
   QB
 /E option
   BC
 Editing, differences
 EGA, changing palette
 elements
 Ellipses, drawing
 ELSE clause
 ELSEIF clause
 END
 END DEF
 END FUNCTION statement
 END IF statement
 END SELECT
 END statement
 END SUB statement
 END TYPE statement
 End-of-line markers
 Enhanced Graphics Adapter. See EGA
 key, equivalent to SPACEBAR
 ENTER
 ENVIRON$ function
 ENVIRON statement
 environment variable
 Environment variables
   described
   LIB
   LINK
   TMP, used by LINK
 Environment-string
 EOF
 EOF function
 EQV
 ERASE statement
 Erasing
 ERDEV$
 ERDEV$ function
 ERL function
 ERR
   code
   function
 ERR
 ERRDEV function
 ERRDEV$ function
 Error
 Error codes
 Error messages
   compile-time
   described
   invocation
   LIB
   LINK
   numbers, limits (table)
   redirection
   run-time
 ERROR statement
 Error trapping
   ERR, identifying errors with
   ERROR statement
   error-handling routine
   file-access errors
   multiple modules
   Quick libraries
   screen modes, inappropriate
   SUB or FUNCTION procedures
   syntax,
 Error-handling
 Error-handling routines
   parts
   specifying
 Error-handling statements
   ERDEV
   ERR, ERL
 Error-message window
 event
 Event polling, event trapping, contrasted with
 Event trapping. See specific
   activating
   background music
   described
   disabling
   keystrokes
   multiple modules
   options,
   polling, contrasted with
   routines, event-handling
   statements and functions, summary of (table)
   SUB
   suspending
   syntax, error-trapping
   trappable events
   types
   types of
     COM
     KEY
     PEN
     PLAY
     TIMER
 event trapping
   PLAY ON statement
 Event trapping, Quick library
 Event-handling
 Event-handling routine
 Event-trapping
 Event-trapping option
 Event-trapping statements. See individual
   COM
   KEY LIST
   KEY OFF
   ON
   ON event
   PEN ON, OFF, and STOP
   PLAY ON, OFF, and STOP
   TIMER ON, OFF, and STOP
   UEVENT
 event-trapping syntax, contrasted with
 examples
 Executable
 /EXEPACK option (LINK)
 EXIT
 EXIT DEF statement
 EXIT DO statement
 EXIT FOR statement
 EXIT FUNCTION statement
 EXIT statement
 EXIT SUB statement
 Exiting, functions and procedures
 EXP function
 Expressions
   Boolean
   false
   lists
   procedures, passing to
   true
 expressions, comparing with
 Expressions, string. See Strings
 Extensions, file-name
 Extra files produced
 extracting and deleting

 F

 Factorial function
 False expressions
 FIELD
 FIELD statement
   described
   random-access
   TYPE...END
 Fields
   defined
   records
     random-access
     sequential
   sequential files, delimited
 fields
 fields, delimiting
 figures with DRAW
 File
   names
     characters,
     OPEN statement
   numbers
     CLOSE, freeing with
     FREEFILE, getting with
     freeing
     OPEN statement
     values, allowable
   pointers
 file
   LIB
 File
 File access
   LOCK statement
   UNLOCK
   UNLOCK statement
 File conversion
 File handling. See statements;individual statement names
   functions
     EOF
     FILEATTR
     FREEFILE
     LOC
     LOF
     SEEK
   statements
     CHDIR
     CLOSE
     FIELD
     GET
     INPUT #
     KILL
     LOCK
     NAME
     OPEN
     RESET
     SEEK
 File I/O
   defined
   device I/O contrasted
 File names
   case sensitivity
   described
   restrictions
   truncation
 file, temporary
 File-access
 File-access modes
   APPEND
   BINARY
   INPUT
   OUTPUT
   RANDOM
 FILEATTR function
 File-name extensions
 File-naming
 File-naming conventions
   BC command
   DOS
   LINK
   Quick libraries
 Files
   ASCII format
   attributes
   extra, produced by QuickBASIC
   #INCLUDE
   length,
   limits (table)
   map
   map (LINK)
   random-access,
   random-access, statements
   random-access, statements and functions. See individual statement and
   function names
   sequential,
   sequential, statements and functions. See individual
     INPUT
     WRITE
   versions,
 files
   adding to
   advantages of
   appending
   compact
   creating
   format
   number storage
   opening
   packing
   random-access files, contrasted with
   records
   statements and functions
     FIELD
     PRINT #
     PUT
     RSET
   statements not allowed
 FILES
 files, closing
 files, contrasted with
 files (LINK)
 files, placing in
 FILES statement
 Filling. See Painting
 filling
 FIX function
 fixed-length string with
 Fixed-length strings
   parameter lists
   record
   variable length, contrasted with
   variables, stand-alone
 Floating-point
   precision, within Quick libraries
 FOR statement
 Foreground color
   default
   screen mode 1
 form
 format
   numbers
     converting from
 Formatting text output
 FOR...NEXT
 FOR...NEXT loops
   described
   execution,
   exit from, alternative
   STEP keyword
 FOR...NEXT statement
 Forward reference problem
 Forward reference problem, DECLARE,
 Forward slash
 Fractal
 FRE function
 FRE statement
 FREEFILE
 FREEFILE function
 from, alternative
 FUNCTION
 function
 function
   data, reading
     files
   described
   DRAW, use with
   PLAY, use with
 FUNCTION
 function, arguments to
 function (cosine)
 Function keys, trapping
 function name
 function name
 function names
 FUNCTION procedures
   calling
   DECLARE statements
   described
   error
   event trapping
 FUNCTION statement
   AS
   described
   include files,
   include files, restrictions with
 function, using
 FUNCTION...END FUNCTION statements. See FUNCTION procedures
 Functions. See individual
   user defined
 functions
   CDBL
   CVL
   INPUT$
   INT
   SIN

 G

 GET
 GET statement
   described
   file I/O
     binary-access
     random-access
   graphics
     array, calculating size of
     syntax
   records, user-defined
 Global variables
   DEF FN function
   FUNCTION procedure
   GOSUB routine
   SHARED attribute
   variable aliasing
 GOSUB
 GOSUB, contrasted with
 GOSUB statement
 GOSUB subroutines
   SUB procedures,
 GOTO statement
   described
   #INCLUDE metacommand
 Graphics. See statements;individual statement names
   functions. See individual statement names
     PALETTE
     PMAP
     POINT
     VIEW
     WINDOW
   statements
     BLOAD
     BSAVE
     CIRCLE
     COLOR
     DRAW
     GET
     LINE
     PAINT
     PALETTE
     PALETTE
     PRESET
     PSET
     PUT
     VIEW
     WINDOW
 graphics
 Graphics Adapter), changing palette
 Graphics cursor. See Cursor, graphics
 Graphics screen modes. See Screen modes
 graphics statement, with
 Graphics statements and functions, summary (table)
 Graphics viewport. See Viewport,
 GW-BASIC

 H

 /H option (QB)
 handling
   functions. See individual function names
   LPOS
   statements. See individual statement names
     UNLOCK
 /HELP option (LINK)
 HEX$ function
 Hexadecimal
 High-resolution-display

 I

 IEEE
 IEEE format
   accuracy
   converting to
   /MBF
   numbers
     converting
     exponential,
     Microsoft
     printing
     ranges
 IF...THEN...ELSE
 IF...THEN...ELSE statement
   described
   SELECT CASE
 IF...THEN...ELSE statement, block
 IF...THEN...ELSE statement, block form
 (IGN)
 /IGNORECASE option (LIB)
 Ignore case
   LIB
   LINK
 ignoring
 Images
   GET, saving to memory with
   PUT, copying to screen with
 Immediate window, limits
 IMP operator
 in
 in map files
 #INCLUDE metacommand
   COMMON
   description
   procedure declarations
   restrictions
 Include
 Include files
   COMMON
   procedures
     declaring
     not allowed
 /INFORMATION option (LINK)
 INKEY$ function
 INP function
 INPUT
 input
   reading
 INPUT
 INPUT #
 INPUT$
 Input
 INPUT$ function
   data, reading
     communications device
     standard input
   described
   example
   INPUT #, contrasted with
   LINE INPUT #, contrasted with
   modem, communicating with
 Input functions. See individual
   COMMAND$
   INKEY$
   INP
 Input past end error
 INPUT # statement
   described
   example
   INPUT$,
   LINE INPUT #, contrasted with
 INPUT statement
   carriage-return-line-feed sequence, suppressing
   defined
   described
   error
   example
   LINE INPUT,
   variable
 Input statements. See individual
   DATA
   INPUT
   LINE
   READ
   RESTORE
 Input/Output. See I/O
 Insert mode, differences
 INSTR function
 INT function
 INT86, INT86X replacements
   CALL
   CALL INT86OLD statements
 INT86OLD
 Integers
   converting
   converting to
   FIX function
   limits, (table)
 Interpreted
 INTERRUPT
 Interrupt
 INTERRUPT statements
 Invocation error
 I/O
   binary-access
   defined
   devices, from and to
   files, from and to
   ports
   standard
 IOCTL$ function
 IOCTL statement
 Italic text, showing placeholders
 items

 J

 Joysticks

 K

 Key
 KEY LIST
 KEY OFF statement
 KEY ON statement
 KEY statement
 Key trapping
   activating
   keys
     DIRECTION
     user-defined
 key trapping
 KEYBD
 Keyboard, reading input from
 Keyboard scan codes
 KEY(n) statements
 Keys
   debugging, differences among versions
   DIRECTION,
   editing, differences among versions
   ENTER
   SPACEBAR
 Keywords, format in program examples
 KILL statement

 L

 (QB)
 /L option
 Labels
 Language differences among
 Last
 Last point referenced
 LBOUND function
 LCASE$
 LCASE$ function
 leading blank
 LEFT$
 LEFT$ function
 LEN
 LEN function
   described
   sample
   sample program application
   use of
 LET statement
 letters
   file names
 .LIB files. See Libraries, stand-alone
 LIB
   case sensitivity
   command
   command symbols
     plus
     plus sign (+)
   default responses
   described
   invoking
   libraries, combining
   library
   library modules
   listing files
   options
     case sensitivity
     dictionary, no extended
     /IGNORECASE (/P)
     /NOEXTDICTIONARY
     /NOIGNORECASE
     page size, specifying
     /PAGESIZE
   response file
   search path
 LIB command symbol
 LIB error messages
 LIB.EXE
 Libraries. See Quick libraries
   default,
   default, ignoring
   described
   LINK, specifying for
   search
   stand-alone
     combining
     defined
     described
     LIB
     listing
     modules,
     object
     object modules,
     object modules, deleting from, including,
     parallel
   types, contrasted
   user.
 libraries. See Quick Libraries
   CALL INT86OLD statement
   compatibility among versions
   compilation
   contents
     described
   use of
 libraries, creating
 library, creating from
 Library Manager. See LIB
 Limits, file size and complexity (table)
 /LINENUMBERS option (LINK)
 Line
 LINE INPUT
 LINE INPUT # statement
   described
   INPUT #, contrasted
   INPUT$, contrasted
 LINE INPUT statement
   described
 Line printer
 LINE statement
   coordinate pairs, order of
   described
   lines and boxes, drawing
   sample applications
   syntax
 Lines, drawing
 (LINK)
 LINK. See Libraries
   command line, invoking from
   defaults
   libraries, specifying
   options
     abbreviations
     arguments, numerical
     /BATCH (/B)
     BC, unsuitable for
     case sensitivity
     CodeView
     /CODEVIEW (/CO)
     command line, order
     /CPARMAXALLOC
     default libraries, ignoring
     displaying
     /DOSSEG (/DO)
     /EXEPACK (/E)
     /HELP (/HE)
     /IGNORECASE
     information,
     /INFORMATION (/I)
     line
     /LINENUMBERS (/LI)
     LINK
     linker
     map
     /MAP (/M)
     /NODEFAULTLIBRARYSEARCH
     /NOIGNORECASE
     /NOPACKCODE (/NOP)
     /PACKCODE (/PAC)
     paragraph space, allocating
     /PAUSE
     pausing
     Quick
     /QUICKLIB (/Q)
     segments
     /SEGMENTS
     segments,
     stack
     /STACK (/ST)
   output
   output file, temporary
   Quick libraries, other language routines
   response file
 LINK environment variable
 LINK error messages
 LINK options
 Linker. See LINK
 LINK.EXE
 Linking. See LINK
 Linking from DOS
 list
 list, format of
 listing
 Listing files, cross-reference (LIB)
 Literal constants,
 Loading Quick libraries
 LOC function
   described
   devices, with
   modem, communicating with
   SEEK,
 local
 Local variables
 LOCATE statement
   cursor
     changing
     positioning
   described
   example
 locating
 LOCK statement
 LOF
 LOF function
   described
   devices
   example
   files
 LOG function
 Logical
 Logical coordinates
   physical coordinates,
 Logical operators
 Long integers
   advantages of
   converting
   converting to
   limits (table)
 Looping
 Looping structures
   defined
   DO...LOOP
   WHILE...WEND
 loops
   nesting
 Lowercase
 Lowercase letters
   uppercase, converting to
 LPOS function
 LPRINT statement, SPC function
 LPRINT USING statement
 LPT devices
 LSET
 LSET statement
 .LST files. See Listing files
 LTRIM$ function
   blanks, leading, printing numbers without
   described
   spaces, leading, stripping
   spaces, leading, stripping

 M

 Macro
 Main module
 libraries, use with
 .MAK files, Quick
 Make Library command
 making global
 Mandelbrot set
 .MAP files. See Map files
 /MAP option (LINK)
 Map
 Map files
 Map files (LINK)
 mapping to
 Math functions
   ABS
   ATN
   COS
   CVSMBF
   EXP
   LOG
   MKSMBF$, MKDMBF$
   SIN
   SQR
   TAN
 /MBF option
   BC
   QB
 option, using with old programs
 Memory
   available, calculating
   requirements, Quick libraries
 Memory functions
 Memory management
   functions. See individual
     FRE
     SETMEM
   statements
     CLEAR
     DEF
     ERASE
     individual
     PCOPY
 Menu commands, differences among versions
 message, invalid-input
 messages
 Metacommands
   described
   #DYNAMIC
   #INCLUDE See also #INCLUDE metacommand
   #STATIC
 Microsoft
 Microsoft Binary format
   numbers
 Microsoft Library Manager. See LIB
 MID$
   function
 MID$
 MID$ function
 MID$ statement
 Minimize String Data option
 Mixed-language
 Mixed-language programming
   ALIAS, use of
   CALL,
   CDECL,
   DECLARE
   Quick libraries
 MKD$ function
 MKDIR statement
 MKDMBF$ function
 MKI$ function
 MKL$
 MKS$ function
 MKSMBF$ function
 MKtype statement
 MKtype$ statement
 MKtypeMBF$ statement
 mode 1
 Modem, communicating with
 modes
   BINARY
   INPUT
   OUTPUT
 modes, EGA and VGA
 Module-level code
 Modules. See Multiple
 modules
   event trapping
 modules
 modules, deleting from, including, and replacing
 monochrome
 Monochrome screen mode
 Moving images with PUT
 Multiple
 Multiple modules
   advantages
   error
   error trapping
   event trapping
   loading
   main module
   programming style
   Quick libraries
   size limits (table)
   variables,
   variables, sharing
   versions, differences among
 Music
   background
   statements
 Music
 Music event trapping
   ON PLAY GOSUB statement
 music option

 N

 NAME statement
 Named COMMON
 Named COMMON block
 names
 Names, devices
 nclude files
   nesting limits (table)
 New line. See Carriage-return-line-feed sequence
 NEXT statement
 No extended dictionary, library
 NOCOM.OBJ file
 (/NOD)
 /NODEFAULTLIBRARYSEARCH option (LINK)
 /NOEXTDICTIONARY option (LIB)
 (/NOI)
 /NOIGNORECASE option (LIB)
 /NOIGNORECASE option (LINK)
 non-BASIC procedures
 /NOPACKCODE option (LINK)
 NOT
 not generated by
 NOT operator
 notation
   placeholders
 Notational
 NUL (device name)
 Null
 NUL.MAP file
 number, displaying
 number of on screen
 Numbers
   positive, printing without leading blank
   random-access files, storage in
   screen,
   screen, printing on
   strings, representing as
 numbers
   converting to
 Numeric
 Numeric conversions
   CVD
   CVI
   CVL function
   CVS function
   double-precision
   integer
   single-precision
 Numeric functions. See individual function names
   CINT
   CLNG
   CSNG
   CVD
   CVI
   CVS
   FIX
   RND
   SGN

 O

 /O option (BC)
 Object
   files
   modules
 OCT$ function
 Octal conversion
 of
   STRIG
 of, printing
 on
 ON
 ON COM statement
 ON ERROR
 ON ERROR GOTO statement
   described
   example
   syntax
 ON event
 ON event GOSUB statements
 ON event statements
 ON expression statement
 ON PEN statement
 ON PLAY GOSUB statement
 ON PLAY statement
 ON statement
 ON STRIG
 ON TIMER statement
 ON UEVENT statement
 ON...GOSUB statement
 ON...GOTO statement
 OPEN
 OPEN COM statement
 OPEN statement
   described
   file names in
   file-access
   file-access modes
     APPEND
     INPUT
     OUTPUT
   LEN
 opening for I/O
 operator
 Operators
   logical
   relational
   relational,
 operators
   string comparisons
 option
 OPTION BASE statement
 option (QB)
 option required
 Options, BC. See BC command
 Options, LIB. See LIB
 Options, LINK. See LINK
 or FUNCTION procedures, within
 OR operator
 ordering
 OUT statement
 Output. See statements;individual function names
   functions. See individual function names
     LPOS
     POS
     TAB
   line
   statements
     BEEP
     CLS
     LPRINT
     OUT
     PRINT
     PRINT
     PRINT #
     PRINT USING
     PUT
     WRITE
     WRITE #
 Overlay linker. See LINK
 Overtype mode, differences among versions

 P

 (/P)
 /PACKCODE option (LINK)
 /PAGESIZE option (LIB)
 Page size, library
 Pages. See Screen
 pages
 pages
 PAINT
 PAINT statement
   argument
     background
     border
   described
   numeric expression
   shapes, filling
     colored
     patterned
   string expression
   tiling
     monochrome, defining
     multicolor, defining
 Painting
   colors
   exterior
   interior
     patterns,
   patterns
     described
     multicolor
 PALETTE
 PALETTE statement
 PALETTE USING statement
 Palettes
   COLOR, changing with
   PALETTE, changing with
   screen
 Paragraph space
 Parameter list, defined
 Parameters
   arguments
     agreement with
     distinguished from
   DECLARE, format in
   number and
 Passing
 Passing by reference
 Passing by value
   DEF FN, used in
 passing to
 path
 Path names, limits (table)
 Pattern tiles, editing on screen
 Patterns
   monochrome
   multicolor
   shapes,
   tile size
 (/PAU)
 /PAUSE option (LINK)
 pausing
 Pausing program execution, FOR...NEXT statement
 PCOPY
 PCOPY statement
 PEEK function
 PEN function
 PEN OFF statement
 PEN ON statement
 PEN STOP
 Peripheral devices
 Physical coordinates
 Pie shapes, drawing
 Pixels
   coordinates, locating with
   defined
   PRESET,
   PSET, plotting with
   text
 Place markers, limits (table)
 planes
 PLAY
 PLAY function
 PLAY OFF statement
 PLAY statement
   background
   described
   QuickBASIC/interpreter differences
   VARPTR$ function, using
 PLAY STOP
 plotting with
 Plus
 Plus (+)
   sign, LIB command symbol
 PMAP function
 PMAP statement
 POINT function
 point referenced
 POKE statement
 Polling
 POS function
 Positive numbers, printing without
 PRESET
 PRESET option, with PUT graphics statement
 PRESET statement
   color option, using with
   described
 previous
 PRINT
 PRINT # statement
   described
   record
   WRITE #, contrasted with
 PRINT statement
   described
   example
   text, wrapping
 PRINT # USING statement
 PRINT USING # statement
 PRINT USING statement
 Print zone
 Printing
   numbers
     negative
     positive
   text
     printer,
     screen, to
 printing
 printing on
 PRN
 Procedures
   arguments
     passing by reference
     passing by value
   arrays
   benefits
   calling
   constants
   defining
   described
   expressions
   format
     argument-list
     parameter-list
   include files, declarations in
   libraries, user
   limits (table)
   modules, multiple
   moving
   passing
   Quick
   records
   recursive
   statements
     FUNCTION...END
     FUNCTION...END FUNCTION
     SUB...END
     SUB...END SUB
     summary (table)
   statements not allowed
   STATIC variables
   variables
     global
     local
     sharing
   variables,
   variables, automatic
 procedures
   DEF FN function, contrasted with
   exit from, alternative
 procedures)
 procedures
 Procedures-only module
 Program
   suspension
   termination
 program application
 programming
   Quick libraries
 Programming environment, differences in versions
 Programming style
   multiple
 Programs
   BASICA, GW-BASIC,
 ProKey, using QuickBASIC with
 prompting, preventing
 PSET
 PSET statement
   described
   example
   STEP option
 PUT
 PUT statement
   described
   file
   file I/O
     binary-access
     random-access
   graphics
     animation
     interaction with background, controlling
     syntax
   records,

 Q

 QB
 QB command
   /AH
   /H option
   /L option
   /MBF
   /MBF option
   /RUN option
   versions, differences among
 QB.QLB
   library
   loading, automatic
 QLBDUMP.BAS
 Quick
 Quick libraries
   advantages
   CALL ABSOLUTE statement
   CALL INTERRUPT
   contents
     described
     listing
     reading
   creating
     command line, from
     described
     files needed
     LINK, using
     QuickBASIC, from within
   default
   described
   end user, delivery to
   errors, trapping in
   executable files, making compact
   files
     needed to create
     produced by
   floating-point precision
   include files, declaring procedures with
   loading
   .MAK file, updating
   memory
   mixed languages
   naming
   object code, linking
   routines, other languages
   search
   updating
 option (LINK)
 /QUICKLIB

 R

 /R option (BC)
 Radians
 radians
 Random access, contrasted with binary access
 Random numbers
 Random-access
 Random-access files
   opening
   records
     adding
     organizing
     reading
   sequential
   sequential files, contrasted with
   statements
 RANDOMIZE statement
 READ statement
 Record numbers
   limits (table)
   random-access files, indexing in
 Record numbers, random-access files
   indexing in
 Records
   binary-access files, writing
   data, overwriting
   defined
   defining
   described
   fixed-length
   procedures,
   procedures, passing to
   random-access
   random-access files
     reading
     storing
     writing
   sequential
   sequential files
     appending
     reading
     storing
   variable length
 records, defining
 Rectangles, specifying coordinates
 Recursive
 Recursive procedures
 REDIM
 REDIM statement
   described
   SHARED
   SHARED attribute
 reducing
 reference
 Relational
 Relational operators
   Boolean expressions
   SELECT CASE statement
 relative
 Relative coordinates. See Coordinates,
 REM statement
 representing as
 requirements
 RESET statement
 Response
 Response file
   example
   LINK
 RESTORE statement
 restrictions with
 RESUME
 Resume Next option
 RESUME NEXT statement
   described
   example
   RESUME,
 RESUME statement
   compiler
   compiler option required
   described
   example
   QuickBASIC/interpreter differences
   RESUME NEXT, contrasted with
 retrieving
   right side
 RETURN statement
 RIGHT$ function
 RMDIR statement
 RND function
 Rotating
 Rotating figures with DRAW
 routine
 Routine, B_OnExit
 routines
   ERR, identifying errors with
 Rows, changing number of
 RSET
 RSET statement
 RTRIM$
 RTRIM$ function
 /RUN option (QB)
 Run menu, Make Library command
 RUN statement
   data
 Run-time error messages

 S

 /S option (BC)
 SADD function
 SAVE statement (BASICA)
 Saving
   images, with GET
   programs, ASCII format
 Scan codes
   keyboard
   trapping keys, use
 Screen
   configuration
     graphics mode
     text mode
   functions
     CSRLIN
     individual function
     POS
     SCREEN
   resolution,
   statements. See individual statement names
     CLS
     COLOR
     LOCATE
     PCOPY
     SCREEN
     VIEW PRINT
     WIDTH
 Screen
 SCREEN function
 Screen modes
 Screen pages
 SCREEN statement
   aspect ratio, effect on
   described
   example
   screen
     page
     resolution, adjusting
   text mode, rows in
 SCRN
 Scrolling
 (/SE)
 Search paths
   libraries
   Quick libraries
 Searching
   strings
 See Quick libraries
 SEEK function
 SEEK statement
 SEG
 /SEGMENTS option (LINK)
 Segments
   lists, map files
   number
   order
   packing
 SELECT CASE
 SELECT CASE statement
   CASE clause
   CASE ELSE clause
   described
   END SELECT
   IF...THEN...ELSE
   ON expression
   routine, error-handling
   syntax
   versions, differences among
 Semicolon (;), LIB command symbol
 Separate-compilation method. See BC command
 sequence
 Sequential
 Sequential files
   creating
   fields
   opening
   random-access files, contrasted
   records
   statements
   statements and functions
     LINE INPUT #
 Serial communication
   defined
   input
   input buffer
 Serial ports,
 Set Main Module command, differences among versions
 SETMEM function
 setting
 SGN function
 shape of
 SHARED
 SHARED attribute
   COMMON
   DIM
     described
     example
     prohibited
   REDIM
 SHARED statement
 Shared variables, between modules
 sharing
 Shell escape (SHELL statement)
 Shifted keys, trapping
 SideKick,
 sign (+)
 sign ($), string-type suffix
 SIN function
 Sine, SIN function
 Sine wave, graphing
 Single-precision
 Single-precision numbers
   size limits (table)
 size
 size, setting
 Skipping
   columns
   spaces
 SLEEP statement
 Sorting,
 Sorting, examples
 SOUND statement
 Source
 Source files
   versions, compatibility among
 SPACE$
 SPACE$ function
 Spaces
   skipping
   trimming
 SPC
 SPC function
 SPC statement
 specifying
   maximum value
   number of
 specifying values outside
 SQR function
 Squares, drawing
 /STACK option (LINK)
 Stack size,
 Stack size, recursive procedures, adjusting for
 Stand-alone programs,
 Standard
 Standard input
   defined
   reading
   redirecting
 Standard I/O
   statements
 Standard output
 Standard places, libraries
 Statement
   modification required
 statement
 statement
 statement. See Painting
   arcs
   arguments, checking with
   AS clause
   BASIC procedures
   buffer allocation, FIELD statement
   CASE clause
   color option
   coordinates
   described
   exit from, alternative
   FIELD statement
   file numbers in
   file-access modes
     APPEND
     BINARY
     RANDOM
   flow control
   foreground color, controlling
   graphics
     animation
     images, copying to screen
     memory, copying images to
   #INCLUDE metacommand, used with
   INPUT, contrasted with INPUT
   prompting
   SHARED attribute
     prohibited
   single-line form
   SPC function
   STATIC attribute
   SUB procedure, calling
   TYPE...END TYPE, contrasted with
 statement and function names
 Statement block
 statement, block form
 statement, contrasted with
 statement names
 statement (non-BASIC)
 statement, use in
 Statements. See individual statement names
 statements. See Individual statement names; individual statement names
   DEF FN
   described
   ERROR
   FOR...NEXT
   INPUT #
   KEY ON
   KEY(n)
   NAME
   ON ERROR
   ON GOSUB
   ON...GOSUB
   RESUME
   STRIG
   WAIT
   WHILE...WEND
 statements and functions
   LINE INPUT #
   LSET
   PRINT #
   RSET
 statements used
   CHAIN
   COMMON
 #STATIC
   statement
   variables
 #STATIC metacommand
   arrays, dimensioned, implicitly
   arrays, memory allocation
 STATIC
   attribute
   statement
 Static arrays
   ERASE statement
   #STATIC metacommand
 STEP
   option
 STICK function
 Stop bits
 STOP statement
 STR$ function
 STRIG function
 STRIG OFF
 STRIG ON statement
 STRIG(n) statements
 STRING
 String
   expressions
     defined
     sequential files, delimiting in
   functions. See individual function names
     ASC
     CHR$
     DATE$
     HEX$
     INPUT$
     INSTR
     LCASE$
     LEFT$
     LEN
     LTRIM$
     MID$
     RIGHT$
     RTRIM$
     SADD
     SPACE$
     STR$
     STRING$
     UCASE$
     VAL
   statements. See individual statement names
     LSET
     MID$
     RSET
   variables. See Strings
 string
 STRING$
 string ("")
 STRING$ function
 String, processing. See Strings
 string with AS
 String-handling functions, new
 Strings
   alphabetizing
   characters,
   characters, retrieving
     left side
     middle
   combining
   comparing
   constants
   defined
   expressions
   fixed-length
     AS STRING
     record elements
     variable length, contrasted
   generating
   limits (table)
   numbers,
   replacing
   spaces,
   spaces, trimming
     right side
   statements and functions, summary of (table)
   substring, searching for
   variable-length
     AS
     defined
     fixed-length,
     maximum
   variables
 strings
   fixed- and variable-length
 structures
   FOR...NEXT
   IF...THEN...ELSE
     single-line
   looping
   SELECT CASE
 styling
 SUB
   procedures
     CALL
     DECLARE
     error trapping in
     event trapping in
     exit
     GOSUB, compared
     include
     #INCLUDE metacommand
     variables,
   statement
     AS clause
     described
     include files, not allowed in
     STATIC attribute
 SUB procedure. See SUB procedures
 SUB statement
 SUB...END
 Subprograms. See SUB
   CALL statement
   CALLS
   SUB statement
   variables
 Subroutines. See GOSUB...RETURN subroutine
 subroutines
   drawbacks in using
 Subscripts
   arrays, limits (table)
   lower bound, specifying
   maximum value, specifying
   number, specifying
   upper
 SuperKey,
 support routines
 SWAP statement
 symbol
 Symbol tables,
 Symbolic
 Symbolic constants
   CONST
   defined
   string
 symbols
   asterisk (*)
   minus sign-plus sign (-+)
 Syntax
 Syntax Checking command, differences
 syntax, contrasted with
 Syntax notation
   choices
   optional
 System
 System calls
 SYSTEM statement

 T

 TAB function
 TAB statement
 (table)
 table
 Text
   screen, printing on
   wrapping
 Text
 Text boxes, limits (table)
 Tiling. See Painting
 Time and date functions. See Date and time, functions
 TIME$ function
 TIME$ statement
 TIMER
 TIMER function
 TIMER OFF statement
 TIMER STOP statement
 Timing function
 TMP environment variable, LINK, used by
 to
 translating to
 Trapping. See Error trapping, Event trapping
   errors
   events
   multiple modules
   options, command-line, required by compiler
 trapping
   activating
   keys
     function
   statements and functions (table)
 trapping in
 Trigonometric
 Trigonometric functions
   ATN
   COS
   TAN
 trimming
   left side
 TROFF statement
 TRON statement
 True expressions
 TYPE command (DOS)
 TYPE, contrasted with
 type, declaring
 TYPE statement
   described
   FIELD, contrasted with
   versions, differences among
 TYPE...END
 TYPE...END TYPE statement
   example
   fixed-length strings in
   random-access records, defining
 Typeface
   key names
   keywords
   placeholders
   program
 types
   specifying
 Typographic conventions

 U

 UBOUND
 UBOUND function
 UCASE$
 UCASE$ function
 UEVENT
 UEVENT statement
 UNLOCK statement
 Uppercase letters
   file names
   lowercase, converting
 use of
 used in BASIC (table)
 User
 User libraries
 User-defined
   data
   events
   types
 user-defined
 USING
 USING, changing with
 using QuickBASIC with
 using to circumvent
 Utility, BUILDLIB

 V

 /V compiler option
   described
 /V option (BC)
   described
   versions, differences among
 VAL function
 Variable aliasing
 variable aliasing
 Variable-length strings
   defined
   fixed-length, compared with
   GET statement
   maximum size
   PUT
 Variables
   arrays
     described
     elements of, passing
     entire, passing
   automatic
   data type
   global
     described
     function
     sharing
     subprograms
     variable
   local
     described
     function definitions
     subprograms
   multiple modules, sharing
   names
     limits (table)
     program examples, format in
   procedures
     sharing
     sharing all in a module
   procedures, passing to
   programs, sharing
   simple, passing
   STATIC
   string. See Strings
   type, declaring
   values, exchanging, SWAP
 variables
 variables in
 VARPTR$
 VARPTR function
   described
   versions, differences among
 VARPTR$ function
   described
 VARSEG function
   described
   versions, differences among
 Version differences, file compatibility
 versions
 VGA (Video
 VIEW
 View coordinates
   physical coordinates,
   WINDOW, defining with
 VIEW PRINT statement
 VIEW SCREEN statement
 VIEW statement
 Viewport
   graphics
     advantages
     VIEW,
     VIEW SCREEN, defining with
   text
 viewport. See Viewport
 VM.TMP file

 W

 /W option (BC)
   described
   versions, differences among
 WAIT statement
 Watch expressions, limits
 Watchpoints, limits (table)
 WEND statement
   described
   versions, differences among
 WHILE statement
 WHILE...WEND
 WHILE...WEND statement
   DO...LOOP, contrasted with
   syntax
 width
 WIDTH
 WIDTH statement
   columns, changing number of
   described
   rows,
 WINDOW
 WINDOW SCREEN statement, WINDOW contrasted with
 WINDOW statement
   example
   GET, effect on
 Windows
   error-message
   Immediate, limits (table)
   versions, differences among
 with
 with CLOSE
 with the ASC function
 WordStar keys, similarity to
 Wrapping text
 WRITE # statement
   described
   PRINT #, contrasted
 WRITE statement

 X

 /X option
   described
 /X option (BC)
   described
   differences among versions
 XOR operator
 XOR option, PUT graphics

 Z

 /ZD option (BC)
 /ZI option (BC)